Class AWS::DynamoDB::AttributeCollection
In: lib/aws/dynamo_db/attribute_collection.rb
Parent: Object

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.

@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.

@example Retrieving specific attributes of an item

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

@example Retrieving all attributes in hash form

  item.attributes.to_h

@example Replacing the value of an attribute

  item.attributes[:title] = "Automobiles"

@example 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

@example Returning overwritten values

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

@example Performing a conditional update

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

Methods

[]   []=   add   delete   each   each_key   each_value   merge!   new   put   set   to_h   update   values_at  

Included Modules

Core::Model Enumerable Types Keys Expectations

Classes and Modules

Class AWS::DynamoDB::AttributeCollection::UpdateBuilder

Attributes

item  [R]  @return [Item] The item to which these attributes belong.

Public Class methods

Public Instance methods

Retrieves the value of a single attribute.

@param [String, Symbol] attribute The name of the attribute to

  get.

@return The value of the specified attribute, which may be a

  String, BigDecimal, Set<String> or Set<BigDecimal>.

Replaces the value of a single attribute.

@param [String, Symbol] attribute The name of the attribute to

  replace.

@param 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.

@return The new value of the attribute.

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 }

@param [Hash] attributes 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.

@param [Hash] options Options for updating the item.

@option options (see update)

@overload delete *attributes

  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.

@overload delete attributes, options = {}

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

  @param [Hash] attributes 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.

  @param [Hash] options Options for updating the item.

  @option options (see #update)

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}" }

@param (see to_h)

@option options (see to_h)

@yieldparam [String] name Each attribute name.

@yieldparam value Each attribute value belonging to the item.

  Values will be of type String, BigDecimal, Set<String> or
  Set<BigDecimal>.
merge!(attributes, options = {})

Alias for set

put(attributes, options = {})

Alias for set

Replaces the values of one or more attributes.

@param [Hash] attributes 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.

@param [Hash] options Options for updating the item.

@option options (see update)

@param [Hash] options Options for retrieving attributes from

  the item.

@option options [Boolean] :consistent_read If set to true,

  then a consistent read is issued, otherwise an eventually
  consistent read is used.

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

@param [Hash] options Options for updating the item.

@option options [Hash] :if 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

@option options [String, Symbol, Array] :unless_exists 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

@option options [Symbol] :return (+: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.

@yieldparam [UpdateBuilder] builder A handle for describing

  the update.

@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.

@return [nil] See the documentation for the +:return+ option

  above.

Retrieves the values of the specified attributes.

@param [Array<String, Symbol>] attributes 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.

@return [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+.

[Validate]