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/client.rb,
lib/aws/dynamo_db/errors.rb,
lib/aws/dynamo_db/request.rb,
lib/aws/dynamo_db/resource.rb,
lib/aws/dynamo_db/batch_get.rb,
lib/aws/dynamo_db/item_data.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

Note:

If you make a request using AWS::DynamoDB with long-term credentials a request is made to Amazon STS for temproary session credentials. These will be cached in the process and re-used.

Provides a high-level interface for using DynamoDB.

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

Credentials

Amazon DynamoDB requires that all requests are made with short-term credentials (e.g. requires a session token).

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",
  :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, Keys, Types Classes: AttributeCollection, BatchGet, BatchWrite, Client, Item, ItemCollection, ItemData, PrimaryKeyElement, Request, Resource, Table, TableCollection

Instance Method Summary collapse

Methods included from Core::ServiceInterface

included, #initialize, #inspect

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)

167
168
169
170
171
# File 'lib/aws/dynamo_db.rb', line 167

def batch_get &block 
  batch = BatchGet.new(:config => config)
  yield(batch)
  batch.enumerator
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:


206
207
208
209
210
# File 'lib/aws/dynamo_db.rb', line 206

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

#tablesTableCollection

Returns a collection representing all the tables in your account.

Returns:


137
138
139
# File 'lib/aws/dynamo_db.rb', line 137

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