You are viewing documentation for version 1 of the AWS SDK for Ruby. Version 2 documentation can be found here.

Class: AWS::DynamoDB::AttributeCollection

Inherits:
Object
  • Object
show all
Includes:
Expectations, Enumerable
Defined in:
lib/aws/dynamo_db/attribute_collection.rb

Overview

Note:

The SDK always returns numbers as BigDecimal objects and sets as Set objects; however, on input it accepts any numeric type for number attributes and either Arrays or Sets for set attributes.

Represents the attributes of a DynamoDB item. An attribute is a name-value pair. The name must be a string, but the value can be a string, number, string set, or number set. Attribute values cannot be null or empty.

Examples:

Retrieving specific attributes of an item

(title, description) =
  item.attributes.values_at(:title, :description)

Retrieving all attributes in hash form

item.attributes.to_hash

Replacing the value of an attribute

item.attributes[:title] = "Automobiles"

Doing a mixed update of item attributes in a single operation

item.attributes.update do |u|

  # add 12 to the (numeric) value of "views"
  u.add(:views => 12)

  # delete attributes
  u.delete(:foo, :bar)

  # delete values out of a set attribute
  u.delete(:colors => ["red", "blue"])

  # replace values
  u.set(:title => "More Automobiles")
end

Returning overwritten values

item.attributes.to_hash      # => { "foo" => "bar",
                                 "name" => "fred" }
item.attributes.set(
  { "foo" => "baz" },
  :return => :updated_old
)                         # => { "foo" => "bar" }

Performing a conditional update

item.set({ :version => 3 }, :if => { :version => 2 })

Defined Under Namespace

Classes: UpdateBuilder

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#item ⇒ Item (readonly)

Returns The item to which these attributes belong.

Returns:

  • (Item) —

    The item to which these attributes belong.



72
73
74
 
# File 'lib/aws/dynamo_db/attribute_collection.rb', line 72

def item
  @item
end

Instance Method Details

#[](attribute) ⇒ Object

Retrieves the value of a single attribute.

Parameters:

  • attribute (String, Symbol) —

    The name of the attribute to get.

Returns:

  • The value of the specified attribute, which may be a String, BigDecimal, Set or Set.



113
114
115
116
117
 
# File 'lib/aws/dynamo_db/attribute_collection.rb', line 113

def [] attribute
  attribute = attribute.to_s
  response_attributes = get_item(:attributes_to_get => [attribute])
  value_from_response(response_attributes[attribute])
end

#[]=(attribute, value) ⇒ Object

Replaces the value of a single attribute.

Parameters:

  • attribute (String, Symbol) —

    The name of the attribute to replace.

  • value —

    The new value to set. This may be a String, Numeric, Set or Array of String objects, or Set or Array of Numeric objects. Mixed types are not allowed in sets, and neither String values nor set values may be empty. Setting an attribute to nil is the same as deleting the attribute.

Returns:

  • The new value of the attribute.



131
132
133
134
 
# File 'lib/aws/dynamo_db/attribute_collection.rb', line 131

def []= attribute, value
  set(attribute => value)
  value
end

#add(attributes, options = {}) ⇒ Object

Adds to the values of one or more attributes. Each attribute must be a set or number in the original item, and each input value must have the same type as the value in the original item. For example, it is invalid to add a single number to a set of numbers, but it is valid to add a set containing a single number to another set of numbers.

When the original attribute is a set, the values provided to this method are added to that set. When the original attribute is a number, the original value is incremented by the numeric value provided to this method. For example:

item = table.items.put(
  :id => "abc123",
  :colors => ["red", "white"],
  :age => 3
)
item.attributes.add(
  { :colors => ["muave"],
    :age => 1 },
  :return => :updated_new
) # => { "colors" => Set["red", "white", "mauve"], "age" => 4 }

Parameters:

  • attributes (Hash) —

    The attribute values to add. The keys of the hash may be strings or symbols. The values may be of type Numeric, Set or Array of String objects, or Set or Array of Numeric objects. Mixed types are not allowed in sets, and neither String values nor set values may be empty. Single string values are not allowed for this method, since DynamoDB does not currently support adding a string to another string.

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

    Options for updating the item.

Options Hash (options):

  • :if (Hash) —

    Designates a conditional update. The operation will fail unless the item exists and has the attributes in the value for this option. For example:

    # throws DynamoDB::Errors::ConditionalCheckFailedException
# unless the item has "color" set to "red"
item.attributes.update(:if => { :color => "red" }) do |u|
  # ...
end
  • :unless_exists (String, Symbol, Array) —

    A name or collection of attribute names; if the item already exists and has a value for any of these attributes, this method will raise DynamoDB::Errors::ConditionalCheckFailedException. For example:

    item.attributes.update(:unless_exists => :color) do |u|
  # ...
end
  • :return (Symbol) — default: `:none` —

    Changes the return value of the method. Valid values:

    • :none - Return nil
    • :all_old - Returns a hash containing all of the original values of the attributes before the update, or nil if the item did not exist at the time of the update.
    • :updated_old - Returns a hash containing the original values of the attributes that were modified as part of this operation. This includes attributes that were deleted, and set-valued attributes whose member values were deleted.
    • :updated_new - Returns a hash containing the new values of the attributes that were modified as part of this operation. This includes set-valued attributes whose member values were deleted.
    • :all_new - Returns a hash containing the new values of all of the attributes.


190
191
192
 
# File 'lib/aws/dynamo_db/attribute_collection.rb', line 190

def add attributes, options = {}
  update(options) { |u| u.add(attributes) }
end

#delete(*attributes) ⇒ Object #delete(attributes, options = {}) ⇒ Object

Overloads:

  • #delete(*attributes) ⇒ Object

    Deletes attributes from the item. Each argument must be a string or symbol specifying the name of the attribute to delete. The last argument may be a hash containing options for the update. See #update for more information about what options are accepted.

  • #delete(attributes, options = {}) ⇒ Object

    Deletes specific values from one or more attributes, whose original values must be sets.

    Parameters:

    • attributes (Hash) —

      The attribute values to delete. The keys of the hash may be strings or symbols. The values must be arrays or Sets of numbers or strings. Mixed types are not allowed in sets. The type of each member in a set must match the type of the members in the original attribute value.

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

      Options for updating the item.



217
218
219
220
221
222
223
224
225
 
# File 'lib/aws/dynamo_db/attribute_collection.rb', line 217

def delete *args
  if args.first.kind_of?(Hash)
    delete_args = [args.shift]
  else
    delete_args = args
  end
  options = args.pop if args.last.kind_of?(Hash)
  update(options || {}) { |u| u.delete(*delete_args) }
end

#each(options = {}, &block) ⇒ Object

Behaves like Hash#each; yields each attribute as a name/value pair.

attributes.each { |(name, value)| puts "#{name} = #{value}" }

attributes.each { |name, value| puts "#{name} = #{value}" }

Parameters:

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

    Options for retrieving attributes from the item.

Options Hash (options):

  • :consistent_read (Boolean) —

    If set to true, then a consistent read is issued, otherwise an eventually consistent read is used.



90
91
92
 
# File 'lib/aws/dynamo_db/attribute_collection.rb', line 90

def each(options = {}, &block)
  to_hash(options).each(&block)
end

#each_key(options = {}) {|name| ... } ⇒ Object

Yield Parameters:

  • name (String) —

    Each attribute name.



95
96
97
 
# File 'lib/aws/dynamo_db/attribute_collection.rb', line 95

def each_key(options = {})
  each(options) { |k, v| yield(k) if block_given? }
end

#each_value(options = {}) {|value| ... } ⇒ Object

Yield Parameters:

  • value —

    Each attribute value belonging to the item. Values will be of type String, BigDecimal, Set or Set.



102
103
104
 
# File 'lib/aws/dynamo_db/attribute_collection.rb', line 102

def each_value(options = {})
  each(options) { |k, v| yield(v) if block_given? }
end

#set(attributes, options = {}) ⇒ Object Also known as: merge!, put

Replaces the values of one or more attributes.

Parameters:

  • attributes (Hash) —

    The attributes to replace. The keys of the hash may be strings or symbols. The values may be of type String, Numeric, Set or Array of String objects, or Set or Array of Numeric objects. Mixed types are not allowed in sets, and neither String values nor set values may be empty. Setting an attribute to nil is the same as deleting the attribute.

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

    Options for updating the item.

Options Hash (options):

  • :if (Hash) —

    Designates a conditional update. The operation will fail unless the item exists and has the attributes in the value for this option. For example:

    # throws DynamoDB::Errors::ConditionalCheckFailedException
# unless the item has "color" set to "red"
item.attributes.update(:if => { :color => "red" }) do |u|
  # ...
end
  • :unless_exists (String, Symbol, Array) —

    A name or collection of attribute names; if the item already exists and has a value for any of these attributes, this method will raise DynamoDB::Errors::ConditionalCheckFailedException. For example:

    item.attributes.update(:unless_exists => :color) do |u|
  # ...
end
  • :return (Symbol) — default: `:none` —

    Changes the return value of the method. Valid values:

    • :none - Return nil
    • :all_old - Returns a hash containing all of the original values of the attributes before the update, or nil if the item did not exist at the time of the update.
    • :updated_old - Returns a hash containing the original values of the attributes that were modified as part of this operation. This includes attributes that were deleted, and set-valued attributes whose member values were deleted.
    • :updated_new - Returns a hash containing the new values of the attributes that were modified as part of this operation. This includes set-valued attributes whose member values were deleted.
    • :all_new - Returns a hash containing the new values of all of the attributes.


149
150
151
 
# File 'lib/aws/dynamo_db/attribute_collection.rb', line 149

def set attributes, options = {}
  update(options) { |u| u.set(attributes) }
end

#to_hash(options = {}) ⇒ Object Also known as: to_h

Parameters:

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

    Options for retrieving attributes from the item.

Options Hash (options):

  • :consistent_read (Boolean) —

    If set to true, then a consistent read is issued, otherwise an eventually consistent read is used.



420
421
422
 
# File 'lib/aws/dynamo_db/attribute_collection.rb', line 420

def to_hash options = {}
  values_from_response_hash(get_item(options))
end

#update(options = {}) {|builder| ... } ⇒ nil

Note:

DnamoDB allows only one update per attribute in a single operation. This method will raise an ArgumentError if multiple updates are described for a single attribute.

Updates multiple attributes in a single operation. This is more efficient than performing each type of update in sequence, and it also allows you to group different kinds of updates into an atomic operation.

item.attributes.update do |u|

  # add 12 to the (numeric) value of "views"
  u.add(:views => 12)

  # delete attributes
  u.delete(:foo, :bar)

  # delete values out of a set attribute
  u.delete(:colors => ["red", "blue"])

  # replace values
  u.set(:title => "More Automobiles")
end

Parameters:

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

    Options for updating the item.

Options Hash (options):

  • :if (Hash) —

    Designates a conditional update. The operation will fail unless the item exists and has the attributes in the value for this option. For example:

    # throws DynamoDB::Errors::ConditionalCheckFailedException
# unless the item has "color" set to "red"
item.attributes.update(:if => { :color => "red" }) do |u|
  # ...
end
  • :unless_exists (String, Symbol, Array) —

    A name or collection of attribute names; if the item already exists and has a value for any of these attributes, this method will raise DynamoDB::Errors::ConditionalCheckFailedException. For example:

    item.attributes.update(:unless_exists => :color) do |u|
  # ...
end
  • :return (Symbol) — default: `:none` —

    Changes the return value of the method. Valid values:

    • :none - Return nil
    • :all_old - Returns a hash containing all of the original values of the attributes before the update, or nil if the item did not exist at the time of the update.
    • :updated_old - Returns a hash containing the original values of the attributes that were modified as part of this operation. This includes attributes that were deleted, and set-valued attributes whose member values were deleted.
    • :updated_new - Returns a hash containing the new values of the attributes that were modified as part of this operation. This includes set-valued attributes whose member values were deleted.
    • :all_new - Returns a hash containing the new values of all of the attributes.

Yield Parameters:

  • builder (UpdateBuilder) —

    A handle for describing the update.

Returns:

  • (nil) —

    See the documentation for the :return option above.



379
380
381
382
383
384
 
# File 'lib/aws/dynamo_db/attribute_collection.rb', line 379

def update(options = {})
  builder = UpdateBuilder.new
  yield(builder)
  do_updates({ :attribute_updates => builder.updates },
             options)
end

#values_at(*attributes) ⇒ Array

Retrieves the values of the specified attributes.

Parameters:

  • attributes (Array<String, Symbol>) —

    The names of the attributes to retrieve. The last argument may be a hash of options for retrieving attributes from the item. Currently the only supported option is :consistent_read; If set to true, then a consistent read is issued, otherwise an eventually consistent read is used.

Returns:

  • (Array) —

    An array in which each member contains the value of the attribute at that index in the argument list. Values may be Strings, BigDecimals, Sets of Strings or Sets or BigDecimals. If a requested attribute does not exist, the corresponding member of the output array will be nil.



400
401
402
403
404
405
406
407
408
409
410
411
412
 
# File 'lib/aws/dynamo_db/attribute_collection.rb', line 400

def values_at(*attributes)
  options = {}
  options = attributes.pop if attributes.last.kind_of?(Hash)

  return [] if attributes.empty?

  attributes.map! { |a| a.to_s }
  response_attributes =
    get_item(options, :attributes_to_get => attributes)

  values_from_response_hash(response_attributes).
    values_at(*attributes)
end