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

Class: AWS::DynamoDB

Inherits:
Object
  • Object
show all
Includes:
Core::ServiceInterface
Defined in:
lib/aws/dynamo_db.rb,
lib/aws/dynamo_db/item.rb,
lib/aws/dynamo_db/keys.rb,
lib/aws/dynamo_db/table.rb,
lib/aws/dynamo_db/types.rb,
lib/aws/dynamo_db/errors.rb,
lib/aws/dynamo_db/client.rb,
lib/aws/dynamo_db/binary.rb,
lib/aws/dynamo_db/resource.rb,
lib/aws/dynamo_db/item_data.rb,
lib/aws/dynamo_db/client_v2.rb,
lib/aws/dynamo_db/batch_get.rb,
lib/aws/dynamo_db/batch_write.rb,
lib/aws/dynamo_db/expectations.rb,
lib/aws/dynamo_db/item_collection.rb,
lib/aws/dynamo_db/table_collection.rb,
lib/aws/dynamo_db/primary_key_element.rb,
lib/aws/dynamo_db/attribute_collection.rb

Overview

Provides a high-level interface for using DynamoDB.

dynamo_db = AWS::DynamoDB.new(
  :access_key_id => '...',
  :secret_access_key => '...')

Supported API Version

Please note, the AWS::DynamoDB classes have been built against the 2011-12-05 API version. Constructing a AWS::DynamoDB object with a newer API version will emit a warning and then ignore the specified version.

If you would like to use features of the newer 2012-08-10 API version, then please construct a DynamoDB client and use the client API directly.

# supports the latest API version
ddb = AWS::DynamoDB::Client.new(api_verison:'2012-08-10')

Tables

Tables contain items, and organize information into discrete areas. All items in the table have the same primary key scheme. You designate the attribute name (or names) to use for the primary key when you create a table, and the table requires each item in the table to have a unique primary key value. The first step in writing data to DynamoDB is to create a table and designate a table name with a primary key.

table = dynamo_db.tables.create(
  "MyTable", 10, 5,
  :hash_key => { :id => :string }
)
sleep 1 while table.status == :creating

See Table and TableCollection for more information on creating and managing tables.

Items and Attributes

An item is a collection of one or more attributes, where each attribute has a string name and a string, number, string set or number set value.

The identity of an item consists of its hash key value and -- if the table's schema includes a range key -- its range key value.

item = table.items.put(:id => "abc123")
item.hash_value # => "abc123"
item.attributes.set(
  :colors => ["red", "blue"],
  :numbers => [12, 24]
)

See Item and ItemCollection for more information on creating and managing items. For more information on managing attributes, see AttributeCollection.

Examples

# create a table (10 read and 5 write capacity units) with the
# default schema (id string hash key)
dynamo_db = AWS::DynamoDB.new
table = dynamo_db.tables.create('my-table', 10, 5)

sleep 1 while table.status == :creating
table.status #=> :active

# get an existing table by name and specify its hash key
table = dynamo_db.tables['another-table']
table.hash_key = [:id, :number]

# add an item
item = table.items.create('id' => 12345, 'foo' => 'bar')

# add attributes to an item
item.attributes.add 'category' => %w(demo), 'tags' => %w(sample item)

# update an item with mixed add, delete, update
item.attributes.update do |u|
  u.add 'colors' => %w(red)
  u.set 'category' => 'demo-category'
  u.delete 'foo'
end

# delete attributes
item.attributes.delete 'colors', 'category'

# get attributes
item.attributes.to_h
#=> {"id"=>#<BigDecimal:10155f5d0,'0.12345E5',9(18)>, "tags"=>#<Set: {"item", "sample"}>}

# delete an item and all of its attributes
item.delete

Defined Under Namespace

Modules: Errors, Expectations Classes: AttributeCollection, BatchGet, BatchWrite, Binary, Client, ClientV2, Item, ItemCollection, ItemData, PrimaryKeyElement, Resource, Table, TableCollection

Constant Summary

IGNORING_API_SPECIFIED_MSG = 
"WARNING: Ignoring DynamoDB API version specified because only '2011-12-05' is supported by this class.  To use another version of the API, invoke the lower level AWS::DynamoDB::Client explicitly."

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Core::ServiceInterface

included, #inspect

Constructor Details

#initialize(options = {}) ⇒ DynamoDB

Returns a new instance of DynamoDB



143
144
145
146
147
148
149
 
# File 'lib/aws/dynamo_db.rb', line 143

def initialize options = {}
  options = options.dup
  options[:dynamo_db] ||= {}
  warn(IGNORING_API_SPECIFIED_MSG) if options[:dynamo_db][:api_version]
  options[:dynamo_db][:api_version] = '2011-12-05'
  super(options)
end

Instance Attribute Details

#client ⇒ Client (readonly)

Returns the low-level DynamoDB client object

Returns:

  • (Client) —

    the low-level DynamoDB client object



117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
 
# File 'lib/aws/dynamo_db.rb', line 117

class DynamoDB

  autoload :AttributeCollection, 'aws/dynamo_db/attribute_collection'
  autoload :BatchGet, 'aws/dynamo_db/batch_get'
  autoload :BatchWrite, 'aws/dynamo_db/batch_write'
  autoload :Binary, 'aws/dynamo_db/binary'
  autoload :Client, 'aws/dynamo_db/client'
  autoload :ClientV2, 'aws/dynamo_db/client_v2'
  autoload :Errors, 'aws/dynamo_db/errors'
  autoload :Expectations, 'aws/dynamo_db/expectations'
  autoload :Item, 'aws/dynamo_db/item'
  autoload :ItemData, 'aws/dynamo_db/item_data'
  autoload :ItemCollection, 'aws/dynamo_db/item_collection'
  autoload :Keys, 'aws/dynamo_db/keys'
  autoload :PrimaryKeyElement, 'aws/dynamo_db/primary_key_element'
  autoload :Resource, 'aws/dynamo_db/resource'
  autoload :Table, 'aws/dynamo_db/table'
  autoload :TableCollection, 'aws/dynamo_db/table_collection'
  autoload :Types, 'aws/dynamo_db/types'

  include Core::ServiceInterface

  endpoint_prefix 'dynamodb'

  IGNORING_API_SPECIFIED_MSG = "WARNING: Ignoring DynamoDB API version specified because only '2011-12-05' is supported by this class.  To use another version of the API, invoke the lower level AWS::DynamoDB::Client explicitly."

  def initialize options = {}
    options = options.dup
    options[:dynamo_db] ||= {}
    warn(IGNORING_API_SPECIFIED_MSG) if options[:dynamo_db][:api_version]
    options[:dynamo_db][:api_version] = '2011-12-05'
    super(options)
  end

  # Returns a collection representing all the tables in your account.
  #
  # @return [TableCollection]
  def tables
    TableCollection.new(:config => config)
  end

  # Request attributes for items spanning multiple tables.  You configure
  # you batch get request using a block:
  #
  #     attributes = dynamo_db.batch_get do |batch|
  #       # call methods on batch specify tables, attributes and items
  #       # ...
  #     end
  #
  # The value returned by #batch_get is an enumerable object that yields
  # the table name (as a string) and a hash of attributes.  The
  # enumerable yields once per item received in the batch get.
  #
  # ## Configuring the batch
  #
  # You can call two methods on the yielded batch object:
  #
  #   * {#table}
  #   * {#items}
  #
  # For more information on these methods, see {BatchGet}.
  #
  # @yield [String, Hash] Yields the table name as a string and a hash
  #   of attributes for each item received in the bach get request.
  #
  # @return [Enumerable]
  #
  def batch_get &block
    batch = BatchGet.new(:config => config)
    yield(batch)
    batch.to_enum(:each)
  end

  # Yields a batch for writing (put and delete) items across multiple
  # tables.  You can put and delete items in the same batch.
  #
  # @example Putting items across tables
  #
  #   # shard data across two tables with batch write
  #   items = [
  #     { :id => '123', :color => 'red' },
  #     { :id => '456', :color => 'blue' },
  #     { :id => '789', :color => 'green' },
  #   ]
  #
  #   ddb.batch_write do |batch|
  #     batch.put('table1', items)
  #     batch.put('table2', items)
  #   end
  #
  # @example Mixing puts and deletes
  #
  #   ddb.batch_write do |batch|
  #     batch.write('table1', :put => [...], :delete => [...])
  #     batch.write('table2', :put => [...], :delete => [...])
  #   end
  #
  # @yield [BatchWrite]
  #
  # @return (see BatchWrite#process!)
  #
  # @see BatchWrite
  # @see BatchWrite#put
  # @see BatchWrite#delete
  # @see BatchWrite#write
  #
  def batch_write &block
    batch = BatchWrite.new(:config => config)
    yield(batch)
    batch.process!
  end

end

Instance Method Details

#batch_get {|String, Hash| ... } ⇒ Enumerable

Request attributes for items spanning multiple tables. You configure you batch get request using a block:

attributes = dynamo_db.batch_get do |batch|
  # call methods on batch specify tables, attributes and items
  # ...
end

The value returned by #batch_get is an enumerable object that yields the table name (as a string) and a hash of attributes. The enumerable yields once per item received in the batch get.

Configuring the batch

You can call two methods on the yielded batch object:

  • #table
  • #items

For more information on these methods, see BatchGet.

Yields:

  • (String, Hash) —

    Yields the table name as a string and a hash of attributes for each item received in the bach get request.

Returns:

  • (Enumerable) 


184
185
186
187
188
 
# File 'lib/aws/dynamo_db.rb', line 184

def batch_get &block
  batch = BatchGet.new(:config => config)
  yield(batch)
  batch.to_enum(:each)
end

#batch_write {|BatchWrite| ... } ⇒ nil

Yields a batch for writing (put and delete) items across multiple tables. You can put and delete items in the same batch.

Examples:

Putting items across tables


# shard data across two tables with batch write
items = [
  { :id => '123', :color => 'red' },
  { :id => '456', :color => 'blue' },
  { :id => '789', :color => 'green' },
]

ddb.batch_write do |batch|
  batch.put('table1', items)
  batch.put('table2', items)
end

Mixing puts and deletes


ddb.batch_write do |batch|
  batch.write('table1', :put => [...], :delete => [...])
  batch.write('table2', :put => [...], :delete => [...])
end

Yields:

Returns:

  • (nil)

See Also:



223
224
225
226
227
 
# File 'lib/aws/dynamo_db.rb', line 223

def batch_write &block
  batch = BatchWrite.new(:config => config)
  yield(batch)
  batch.process!
end

#tables ⇒ TableCollection

Returns a collection representing all the tables in your account.

Returns:



154
155
156
 
# File 'lib/aws/dynamo_db.rb', line 154

def tables
  TableCollection.new(:config => config)
end