Module: Aws::Record::Attributes::ClassMethods

Included in:
Aws::Record
Defined in:
lib/aws-record/record/attributes.rb

Instance Method Summary collapse

Instance Method Details

#atomic_counter(name, opts = {}) ⇒ Object

Define an atomic counter attribute for your model.

Atomic counter are an integer-type attribute that is incremented, unconditionally, without interfering with other write requests. The numeric value increments each time you call increment_<attr>!. If a specific numeric value are passed in the call, the attribute will increment by that value.

To use increment_<attr>! method, the following condition must be true:

  • None of the attributes have dirty changes.

  • If there is a value passed in, it must be an integer.

For more information, see Atomic counter in the Amazon DynamoDB Developer Guide.

Examples:

Usage Example

class MyRecord
  include Aws::Record
  integer_attr :id, hash_key: true
  atomic_counter :counter
end

record = MyRecord.find(id: 1)
record.counter #=> 0
record.increment_counter! #=> 1
record.increment_counter!(2) #=> 3

Parameters:

  • name (Symbol) —

    Name of this attribute. It should be a name that is safe to use as a method.

  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • :default_value (Object) —

    Optional attribute used to define a “default value” to be used if the attribute’s value on an item is nil or not set at persistence time. The “default value” of the attribute starts at 0.

See Also:



475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
 
# File 'lib/aws-record/record/attributes.rb', line 475

def atomic_counter(name, opts = {})
  opts[:dynamodb_type] = 'N'
  opts[:default_value] ||= 0
  attr(name, Marshalers::IntegerMarshaler.new(opts), opts)

  define_method("increment_#{name}!") do |increment = 1|
    if dirty?
      msg = 'Attributes need to be saved before atomic counter can be incremented'
      raise Errors::RecordError, msg
    end

    unless increment.is_a?(Integer)
      msg = "expected an Integer value, got #{increment.class}"
      raise ArgumentError, msg
    end

    resp = dynamodb_client.update_item(
      table_name: self.class.table_name,
      key: key_values,
      expression_attribute_values: {
        ':i' => increment
      },
      expression_attribute_names: {
        '#n' => name
      },
      update_expression: 'SET #n = #n + :i',
      return_values: 'UPDATED_NEW'
    )
    assign_attributes(resp[:attributes])
    @data.clean!
    @data.get_attribute(name)
  end
end

#attr(name, marshaler, opts = {}) ⇒ Object

Define an attribute for your model, providing your own attribute type.

Parameters:

  • name (Symbol) —

    Name of this attribute. It should be a name that is safe to use as a method.

  • marshaler (Marshaler) —

    The marshaler for this attribute. So long as you provide a marshaler which implements #type_cast and #serialize that consume raw values as expected, you can bring your own marshaler type. Convenience methods will provide this for you.

  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • :database_attribute_name (String) —

    Optional attribute used to specify a different name for database persistence than the ‘name` parameter. Must be unique (you can’t have overlap between database attribute names and the names of other attributes).

  • :dynamodb_type (String) —

    Generally used for keys and index attributes, one of “S”, “N”, “B”, “BOOL”, “SS”, “NS”, “BS”, “M”, “L”. Optional if this attribute will never be used for a key or secondary index, but most convenience methods for setting attributes will provide this.

  • :persist_nil (Boolean) —

    Optional attribute used to indicate whether nil values should be persisted. If true, explicitly set nil values will be saved to DynamoDB as a “null” type. If false, nil values will be ignored and not persisted. By default, is false.

  • :default_value (Object) —

    Optional attribute used to define a “default value” to be used if the attribute’s value on an item is nil or not set at persistence time. Additionally, lambda can be used as a default value.

  • :hash_key (Boolean) —

    Set to true if this attribute is the hash key for the table.

  • :range_key (Boolean) —

    Set to true if this attribute is the range key for the table.



133
134
135
136
137
 
# File 'lib/aws-record/record/attributes.rb', line 133

def attr(name, marshaler, opts = {})
  @attributes.register_attribute(name, marshaler, opts)
  _define_attr_methods(name)
  _key_attributes(name, opts)
end

#attribute_names ⇒ Array

Returns List of attribute names.

Returns:

  • (Array) —

    List of attribute names.



525
526
527
 
# File 'lib/aws-record/record/attributes.rb', line 525

def attribute_names
  @attributes.attributes.keys
end

#attributes ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



520
521
522
 
# File 'lib/aws-record/record/attributes.rb', line 520

def attributes
  @attributes
end

#boolean_attr(name, opts = {}) ⇒ Object

Define a boolean-type attribute for your model.

Parameters:

  • name (Symbol) —

    Name of this attribute. It should be a name that is safe to use as a method.

  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • :hash_key (Boolean) —

    Set to true if this attribute is the hash key for the table.

  • :range_key (Boolean) —

    Set to true if this attribute is the range key for the table.

  • :persist_nil (Boolean) —

    Optional attribute used to indicate whether nil values should be persisted. If true, explicitly set nil values will be saved to DynamoDB as a “null” type. If false, nil values will be ignored and not persisted. By default, is false.

  • :default_value (Object) —

    Optional attribute used to define a “default value” to be used if the attribute’s value on an item is nil or not set at persistence time. Additionally, lambda can be used as a default value.



178
179
180
181
 
# File 'lib/aws-record/record/attributes.rb', line 178

def boolean_attr(name, opts = {})
  opts[:dynamodb_type] = 'BOOL'
  attr(name, Marshalers::BooleanMarshaler.new(opts), opts)
end

#date_attr(name, opts = {}) ⇒ Object

Define a date-type attribute for your model.

Parameters:

  • name (Symbol) —

    Name of this attribute. It should be a name that is safe to use as a method.

  • opts (Hash) (defaults to: {})
  • options (Hash) —

    a customizable set of options

Options Hash (opts):

  • :hash_key (Boolean) —

    Set to true if this attribute is the hash key for the table.

  • :range_key (Boolean) —

    Set to true if this attribute is the range key for the table.

  • :persist_nil (Boolean) —

    Optional attribute used to indicate whether nil values should be persisted. If true, explicitly set nil values will be saved to DynamoDB as a “null” type. If false, nil values will be ignored and not persisted. By default, is false.



244
245
246
247
 
# File 'lib/aws-record/record/attributes.rb', line 244

def date_attr(name, opts = {})
  opts[:dynamodb_type] = 'S'
  attr(name, Marshalers::DateMarshaler.new(opts), opts)
end

#datetime_attr(name, opts = {}) ⇒ Object

Define a datetime-type attribute for your model.

Parameters:

  • name (Symbol) —

    Name of this attribute. It should be a name that is safe to use as a method.

  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • :hash_key (Boolean) —

    Set to true if this attribute is the hash key for the table.

  • :range_key (Boolean) —

    Set to true if this attribute is the range key for the table.

  • :persist_nil (Boolean) —

    Optional attribute used to indicate whether nil values should be persisted. If true, explicitly set nil values will be saved to DynamoDB as a “null” type. If false, nil values will be ignored and not persisted. By default, is false.

  • :default_value (Object) —

    Optional attribute used to define a “default value” to be used if the attribute’s value on an item is nil or not set at persistence time. Additionally, lambda can be used as a default value.



266
267
268
269
 
# File 'lib/aws-record/record/attributes.rb', line 266

def datetime_attr(name, opts = {})
  opts[:dynamodb_type] = 'S'
  attr(name, Marshalers::DateTimeMarshaler.new(opts), opts)
end

#epoch_time_attr(name, opts = {}) ⇒ Object

Define a time-type attribute for your model which persists as epoch-seconds.

Parameters:

  • name (Symbol) —

    Name of this attribute. It should be a name that is safe to use as a method.

  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • :hash_key (Boolean) —

    Set to true if this attribute is the hash key for the table.

  • :range_key (Boolean) —

    Set to true if this attribute is the range key for the table.

  • :persist_nil (Boolean) —

    Optional attribute used to indicate whether nil values should be persisted. If true, explicitly set nil values will be saved to DynamoDB as a “null” type. If false, nil values will be ignored and not persisted. By default, is false.

  • :default_value (Object) —

    Optional attribute used to define a “default value” to be used if the attribute’s value on an item is nil or not set at persistence time. Additionally, lambda can be used as a default value.



311
312
313
314
 
# File 'lib/aws-record/record/attributes.rb', line 311

def epoch_time_attr(name, opts = {})
  opts[:dynamodb_type] = 'N'
  attr(name, Marshalers::EpochTimeMarshaler.new(opts), opts)
end

#float_attr(name, opts = {}) ⇒ Object

Define a float-type attribute for your model.

Parameters:

  • name (Symbol) —

    Name of this attribute. It should be a name that is safe to use as a method.

  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • :hash_key (Boolean) —

    Set to true if this attribute is the hash key for the table.

  • :range_key (Boolean) —

    Set to true if this attribute is the range key for the table.

  • :persist_nil (Boolean) —

    Optional attribute used to indicate whether nil values should be persisted. If true, explicitly set nil values will be saved to DynamoDB as a “null” type. If false, nil values will be ignored and not persisted. By default, is false.

  • :default_value (Object) —

    Optional attribute used to define a “default value” to be used if the attribute’s value on an item is nil or not set at persistence time. Additionally, lambda can be used as a default value.



222
223
224
225
 
# File 'lib/aws-record/record/attributes.rb', line 222

def float_attr(name, opts = {})
  opts[:dynamodb_type] = 'N'
  attr(name, Marshalers::FloatMarshaler.new(opts), opts)
end

#hash_key ⇒ Symbol?

Returns The symbolic name of the table’s hash key.

Returns:

  • (Symbol, nil) —

    The symbolic name of the table’s hash key.



510
511
512
 
# File 'lib/aws-record/record/attributes.rb', line 510

def hash_key
  @keys.hash_key
end

#integer_attr(name, opts = {}) ⇒ Object

Define a integer-type attribute for your model.

Parameters:

  • name (Symbol) —

    Name of this attribute. It should be a name that is safe to use as a method.

  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • :hash_key (Boolean) —

    Set to true if this attribute is the hash key for the table.

  • :range_key (Boolean) —

    Set to true if this attribute is the range key for the table.

  • :persist_nil (Boolean) —

    Optional attribute used to indicate whether nil values should be persisted. If true, explicitly set nil values will be saved to DynamoDB as a “null” type. If false, nil values will be ignored and not persisted. By default, is false.

  • :default_value (Object) —

    Optional attribute used to define a “default value” to be used if the attribute’s value on an item is nil or not set at persistence time. Additionally, lambda can be used as a default value.



200
201
202
203
 
# File 'lib/aws-record/record/attributes.rb', line 200

def integer_attr(name, opts = {})
  opts[:dynamodb_type] = 'N'
  attr(name, Marshalers::IntegerMarshaler.new(opts), opts)
end

#keys ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



530
531
532
 
# File 'lib/aws-record/record/attributes.rb', line 530

def keys
  @keys.keys
end

#list_attr(name, opts = {}) ⇒ Object

Define a list-type attribute for your model.

Lists do not have to be homogeneous, but they do have to be types that the AWS SDK for Ruby V3’s DynamoDB client knows how to marshal and unmarshal. Those types are:

  • Hash

  • Array

  • String

  • Numeric

  • Boolean

  • IO

  • Set

  • nil

Also note that, since lists are heterogeneous, you may lose some precision when marshaling and unmarshaling. For example, symbols will be stringified, but there is no way to return those strings to symbols when the object is read back from DynamoDB.

Parameters:

  • name (Symbol) —

    Name of this attribute. It should be a name that is safe to use as a method.

  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • :hash_key (Boolean) —

    Set to true if this attribute is the hash key for the table.

  • :range_key (Boolean) —

    Set to true if this attribute is the range key for the table.

  • :default_value (Object) —

    Optional attribute used to define a “default value” to be used if the attribute’s value on an item is nil or not set at persistence time. Additionally, lambda can be used as a default value.



347
348
349
350
 
# File 'lib/aws-record/record/attributes.rb', line 347

def list_attr(name, opts = {})
  opts[:dynamodb_type] = 'L'
  attr(name, Marshalers::ListMarshaler.new(opts), opts)
end

#map_attr(name, opts = {}) ⇒ Object

Define a map-type attribute for your model.

Maps do not have to be homogeneous, but they do have to use types that the AWS SDK for Ruby V3’s DynamoDB client knows how to marshal and unmarshal. Those types are:

  • Hash

  • Array

  • String

  • Numeric

  • Boolean

  • IO

  • Set

  • nil

Also note that, since maps are heterogeneous, you may lose some precision when marshaling and unmarshaling. For example, symbols will be stringified, but there is no way to return those strings to symbols when the object is read back from DynamoDB.

Parameters:

  • name (Symbol) —

    Name of this attribute. It should be a name that is safe to use as a method.

  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • :hash_key (Boolean) —

    Set to true if this attribute is the hash key for the table.

  • :range_key (Boolean) —

    Set to true if this attribute is the range key for the table.

  • :default_value (Object) —

    Optional attribute used to define a “default value” to be used if the attribute’s value on an item is nil or not set at persistence time. Additionally, lambda can be used as a default value.



383
384
385
386
 
# File 'lib/aws-record/record/attributes.rb', line 383

def map_attr(name, opts = {})
  opts[:dynamodb_type] = 'M'
  attr(name, Marshalers::MapMarshaler.new(opts), opts)
end

#numeric_set_attr(name, opts = {}) ⇒ Object

Define a numeric set attribute for your model.

Numeric sets are homogeneous sets, containing only numbers. Note that empty sets cannot be persisted to DynamoDB. Empty sets are valid for aws-record items, but they will not be persisted as sets. nil values from your table, or a lack of value from your table, will be treated as an empty set for item instances. At persistence time, the marshaler will attempt to marshal any non-numerics within the set to be Numeric objects.

Parameters:

  • name (Symbol) —

    Name of this attribute. It should be a name that is safe to use as a method.

  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • :hash_key (Boolean) —

    Set to true if this attribute is the hash key for the table.

  • :range_key (Boolean) —

    Set to true if this attribute is the range key for the table.

  • :default_value (Object) —

    Optional attribute used to define a “default value” to be used if the attribute’s value on an item is nil or not set at persistence time. Additionally, lambda can be used as a default value.



435
436
437
438
 
# File 'lib/aws-record/record/attributes.rb', line 435

def numeric_set_attr(name, opts = {})
  opts[:dynamodb_type] = 'NS'
  attr(name, Marshalers::NumericSetMarshaler.new(opts), opts)
end

#range_key ⇒ Symbol?

Returns The symbolic name of the table’s range key, or nil if there is no range key.

Returns:

  • (Symbol, nil) —

    The symbolic name of the table’s range key, or nil if there is no range key.



515
516
517
 
# File 'lib/aws-record/record/attributes.rb', line 515

def range_key
  @keys.range_key
end

#string_attr(name, opts = {}) ⇒ Object

Define a string-type attribute for your model.

Parameters:

  • name (Symbol) —

    Name of this attribute. It should be a name that is safe to use as a method.

  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • :hash_key (Boolean) —

    Set to true if this attribute is the hash key for the table.

  • :range_key (Boolean) —

    Set to true if this attribute is the range key for the table.

  • :persist_nil (Boolean) —

    Optional attribute used to indicate whether nil values should be persisted. If true, explicitly set nil values will be saved to DynamoDB as a “null” type. If false, nil values will be ignored and not persisted. By default, is false.

  • :default_value (Object) —

    Optional attribute used to define a “default value” to be used if the attribute’s value on an item is nil or not set at persistence time. Additionally, lambda can be used as a default value.



156
157
158
159
 
# File 'lib/aws-record/record/attributes.rb', line 156

def string_attr(name, opts = {})
  opts[:dynamodb_type] = 'S'
  attr(name, Marshalers::StringMarshaler.new(opts), opts)
end

#string_set_attr(name, opts = {}) ⇒ Object

Define a string set attribute for your model.

String sets are homogeneous sets, containing only strings. Note that empty sets cannot be persisted to DynamoDB. Empty sets are valid for aws-record items, but they will not be persisted as sets. nil values from your table, or a lack of value from your table, will be treated as an empty set for item instances. At persistence time, the marshaler will attempt to marshal any non-strings within the set to be String objects.

Parameters:

  • name (Symbol) —

    Name of this attribute. It should be a name that is safe to use as a method.

  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • :hash_key (Boolean) —

    Set to true if this attribute is the hash key for the table.

  • :range_key (Boolean) —

    Set to true if this attribute is the range key for the table.

  • :default_value (Object) —

    Optional attribute used to define a “default value” to be used if the attribute’s value on an item is nil or not set at persistence time. Additionally, lambda can be used as a default value.



409
410
411
412
 
# File 'lib/aws-record/record/attributes.rb', line 409

def string_set_attr(name, opts = {})
  opts[:dynamodb_type] = 'SS'
  attr(name, Marshalers::StringSetMarshaler.new(opts), opts)
end

#time_attr(name, opts = {}) ⇒ Object

Define a time-type attribute for your model.

Parameters:

  • name (Symbol) —

    Name of this attribute. It should be a name that is safe to use as a method.

  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • :hash_key (Boolean) —

    Set to true if this attribute is the hash key for the table.

  • :range_key (Boolean) —

    Set to true if this attribute is the range key for the table.

  • :persist_nil (Boolean) —

    Optional attribute used to indicate whether nil values should be persisted. If true, explicitly set nil values will be saved to DynamoDB as a “null” type. If false, nil values will be ignored and not persisted. By default, is false.

  • :default_value (Object) —

    Optional attribute used to define a “default value” to be used if the attribute’s value on an item is nil or not set at persistence time. Additionally, lambda can be used as a default value.



288
289
290
291
 
# File 'lib/aws-record/record/attributes.rb', line 288

def time_attr(name, opts = {})
  opts[:dynamodb_type] = 'S'
  attr(name, Marshalers::TimeMarshaler.new(opts), opts)
end