class AWS::DynamoDB::Table

Represents a DynamoDB table.

## Working with Tables

Dynamo DB allows you to organize data into tables. Tables have a unique name and a key schema. A key schema is comprised of a hash key and an optional range key.

Dynamo DB automatically partitions the data contained in a table across multiple nodes so that the data throughput is not constrained by the scale of a single box. You can reserve the required throughput by specifying a number of reads and writes per second to support.

## Creating a Table

To get started you can create a table by supplying a name and the read/write capacity. A default schema with a hash_key of :id => :string will be provided.

dynamo_db = AWS::DynamoDB.new
dynamo_db.tables.create('mytable', 10, 5)

You can provide your own hash key and optional range key.

dynamo_db.tables.create('comments', 10, 5,
  :hash_key => { :blog_post_id => :number },
  :range_key => { :comment_id => :number }
)

## Provisioning Throughput

You must specify the desired read and write capacity when creating a table. After a table is created you can see what has been provisioned.

table.read_capacity_units #=> 10
table.write_capacity_units #=> 5

To change these values, call {#provision_throughput}:

table.provision_throughput :read_capacity_units => 100, :write_capacity_units => 100

Please note that provisioned throughput can be decreased only once within a 24 hour period.

## Table Status

When you create or update a table the changes can take some time to apply. You can query the status of your table at any time:

# creating a table can be a *very* slow operation
table = dynamo_db.tables.create('mytable')
sleep 1 while table.status == :creating
table.status #=> :active

@attr_reader [Time] created_at When the table was first creatd.

@attr_reader [Symbol] status

@attr [Integer] read_capacity_units

@attr [Integer] write_capacity_units

@attr [Time] throughput_last_increased_at

@attr [Time] throughput_last_decreased_at

@attr [Integer] size_bytes

@attr [Integer] item_count

@attr [PrimaryKeyElement] hash_key Returns the hash key element

for this table.

@attr [PrimaryKeyElement,nil] #range_key Returns the range key

element for this table, or nil if the table does not have a range
key.

Attributes

name[R]

@return [String] The name of this table.

Public Class Methods

new(name, options = {}) click to toggle source

@api private

Calls superclass method AWS::Core::Resource.new
# File lib/aws/dynamo_db/table.rb, line 98
def initialize name, options = {}
  @name = name
  super
end

Public Instance Methods

assert_schema!() click to toggle source

Raises an exception unless the table schema is loaded.

@return [nil]

# File lib/aws/dynamo_db/table.rb, line 222
def assert_schema!
  raise "table schema not loaded" unless schema_loaded?
end
batch_delete(items) click to toggle source

Delete up to 25 items in a single batch.

table.batch_delete(%w(id1 id2 id3 id4 id5))

@param [Array<String>,Array<Array>] items A list of item keys to

delete.  For tables without a range key, items should be an array
of hash key strings.

    batch.delete('table-name', ['hk1', 'hk2', 'hk3'])

For tables with a range key, items should be an array of
hash key and range key pairs.

    batch.delete('table-name', [['hk1', 'rk1'], ['hk1', 'rk2']])

@return (see AWS::DynamoDB::BatchWrite#process!)

# File lib/aws/dynamo_db/table.rb, line 480
def batch_delete items
  batch = BatchWrite.new(:config => config)
  batch.delete(self, items)
  batch.process!
end
batch_get(attributes, items, options = {}) click to toggle source

Requets a list of attributes for a list of items in the same table.

If you want to request a list of attributes for items that span multiple tables, see {DynamoDB#batch_get}.

You can call this method in two forms:

# block form
table.batch_get(:all, items) do |attributes|
  # yeilds one hash of attribute names/values for each item
  puts attributes.to_yaml
end

# enumerable return value
attribute_hashes = table.batch_get(:all, items)
attribute_hashes.each do |attributes|
  # ...
end

@note This method does not require the table schema to be loaded.

## Attributes

You can specify the list of attributes to request in 3 ways:

  • The symbol `:all` (to recieve all attributes)

  • A single attribute name (e.g. 'size')

  • An array of attribute names (e.g. ['size', 'color'])

A few exmaples:

# get all attributes
table.batch_get(:all, items)

# only get the 'color' attribute
table.batch_get('color', items)

# get 'color' and 'size' attributes
table.batch_get(['color', size'], items)

## Items

You must specify an array of items to fetch attributes for. The `items` param should always be an array with:

  • String hash key values

  • Arrays of string hash key and range key values

  • Item objects

Here are a few examples:

# items as a list of hash key values
items = %w(hashkey1 hashkey2 hashkey3)
table.batch_get(:all, items)

# items as a list of hash and range key values
items = [['hashkey1', 'rangekey2'], ['hashkey1', 'rangekey2']]
table.batch_get(:all, items)

# items as a list of Item objects
items = []
items << Item.new(table, 'hashkey1')
items << Item.new(table, 'hashkey2')
table.batch_get(:all, items)

Please note that you must provide both hash and range keys for tables that include a range key in the schema.

@param [:all, String, Array<String>] attributes The list of

attributes you want to fetch for each item.  `attributes` may be:

  * the symbol `:all`
  * a single attribute name string
  * an array of attribute name strings

@param [Mixed] items A list of 2 or more items to fetch attributes

for.  You may provide `items` as:

  * an array of hash key value strings
  * an array of hash and range key value pairs (nested arrays)
  * an array of {Item} objects

@param [Hash] options

@option options [Boolean] :consistent_read (false) When `true`, items

are read from this table with consistent reads.  When `false`, reads
are eventually consistent.

@yield [Hash] Yields a hash of attributes for each item.

@return [Enumerable] Returns an enumerable object that yields

hashes of attributes.
# File lib/aws/dynamo_db/table.rb, line 412
def batch_get attributes, items, options = {}, &block
  batch = BatchGet.new(:config => config)
  batch.table(name, attributes, items, options)
  enum = batch.to_enum(:each_attributes)
  block_given? ? enum.each(&block) : enum
end
batch_put(items) click to toggle source

Batch puts up to 25 items to this table.

table.batch_put([
  { :id => 'id1', :color => 'red' },
  { :id => 'id2', :color => 'blue' },
  { :id => 'id3', :color => 'green' },
])

@param [Array<Hash>] items A list of item attributes to put.

The hash must contain the table hash key element and range key
element (if one is defined).

@return (see AWS::DynamoDB::BatchWrite#process!)

# File lib/aws/dynamo_db/table.rb, line 433
def batch_put items
  batch = BatchWrite.new(:config => config)
  batch.put(self, items)
  batch.process!
end
batch_write(options = {}) click to toggle source

Batch writes up to 25 items to this table. A batch may contain a mix of items to put and items to delete.

table.batch_write(
  :put => [
    { :id => 'id1', :color => 'red' },
    { :id => 'id2', :color => 'blue' },
    { :id => 'id3', :color => 'green' },
  ],
  :delete => ['id4', 'id5']
)

@param [Hash] options

@option options (BatchWrite#write)

@return (see AWS::DynamoDB::BatchWrite#process!)

# File lib/aws/dynamo_db/table.rb, line 457
def batch_write options = {}
  batch = BatchWrite.new(:config => config)
  batch.write(self, options)
  batch.process!
end
composite_key?() click to toggle source

@return [Boolean] Returns true if the table has both a hash key and

a range key.
# File lib/aws/dynamo_db/table.rb, line 201
def composite_key?
  !simple_key?
end
Also aliased as: has_range_key?
delete() click to toggle source

Deletes a table and all of its items. The table must be in an `:active` state (see {#status}).

@return [nil]

# File lib/aws/dynamo_db/table.rb, line 297
def delete
  client.delete_table(:table_name => name)
  nil
end
exists?() click to toggle source

@return [Boolean] Returns true if the table exists. Note that a table

exists even when it is in a `:deleting` state; this method
only returns false when DynamoDB no longer returns any
information about the table.
# File lib/aws/dynamo_db/table.rb, line 312
def exists?
  get_resource
  true
rescue Errors::ResourceNotFoundException
  false
end
has_range_key?()
Alias for: composite_key?
hash_key=(description) click to toggle source

Configures the hash key element of the table's key schema. This is the preferred way to load the table schema so that it can be used to work with DynamoDB items.

# these are equivalent:
table.hash_key = [:id, :string]
table.hash_key = { :id => :string }

@note For tables with composite primary keys, you must call

this method first followed by {#range_key=} to configure the
table schema.

@param description A description of the hash key element. If

this is a hash, it may contain a single mapping; the key is
the name of the hash key attribute and the value is the type
(`:string`, `:number` or `:binary`).  If it is an array, the first
element is the name and the second element is the type.
# File lib/aws/dynamo_db/table.rb, line 261
def hash_key= description
  static_attributes[:hash_key] =
    PrimaryKeyElement.from_description(description)
end
items() click to toggle source

@return [ItemCollection] Returns an object representing all the

items in the table.
# File lib/aws/dynamo_db/table.rb, line 304
def items
  ItemCollection.new(self)
end
load_schema() click to toggle source

Loads the table's schema information into memory. This method should not be used in a high-volume code path, and is intended only as a convenience for exploring the API. In general you should configure a schema with {#hash_key=} and {#range_key=} before using the table.

@note You must load the the table schema using {#load_schema},

{#hash_key} or {#range_key} or configure it using
{#hash_key=} and optionally {#range_key=} in order to work
with DynamoDB items.

@return self

# File lib/aws/dynamo_db/table.rb, line 238
def load_schema
  hash_key
  self
end
provision_throughput(options = {}) click to toggle source

@param [Hash] options

@option options [Integer] :read_capacity_units

@option options [Integer] :write_capacity_units

@return [Hash] Returns a hash with the current throughput

provisioning (`:read_capacity_units` and `:write_capacity_units`).
# File lib/aws/dynamo_db/table.rb, line 169
def provision_throughput options = {}

  options[:read_capacity_units] ||= read_capacity_units
  options[:write_capacity_units] ||= write_capacity_units

  client_opts = {}
  client_opts[:table_name] = name
  client_opts[:provisioned_throughput] = options
  client.update_table(client_opts)

  options

end
range_key() click to toggle source

@return [PrimaryKeyElement]

# File lib/aws/dynamo_db/table.rb, line 152
def range_key
  if schema_loaded?
    static_attributes[:range_key]
  else
    range_key_without_schema_override
  end
end
range_key=(description) click to toggle source

Configures the range key element of the table's key schema. This is the preferred way to load the table schema so that it can be used to work with DynamoDB items. This method is only valid if the table has a composite key schema, and it may only be called after {#hash_key=} has been used to configure the hash key element.

# these are equivalent:
table.range_key = [:id, :string]
table.range_key = { :id => :string }

@param description A description of the range key element. If

this is a hash, it may contain a single mapping; the key is
the name of the hash key attribute and the value is the type
(`:string`, `:number` or `:binary`).  If it is an array, the first
element is the name and the second element is the type.
# File lib/aws/dynamo_db/table.rb, line 283
def range_key= description
  raise "attempted to set a range key without configuring a hash key first" unless
    schema_loaded?

  static_attributes[:range_key] =
    PrimaryKeyElement.from_description(description)

end
range_key_without_schema_override()
Alias for: range_key
read_capacity_units=(read_capacity_units) click to toggle source

@param [Integer] read_capacity_units

# File lib/aws/dynamo_db/table.rb, line 184
def read_capacity_units= read_capacity_units
  provision_throughput(:read_capacity_units => read_capacity_units)
end
schema_loaded?() click to toggle source

@return [Boolean] True if the table's schema information is

loaded into memory.

@note You must load the the table schema using {#load_schema},

{#hash_key} or {#range_key} or configure it using
{#hash_key=} and optionally {#range_key=} in order to work
with DynamoDB items.
# File lib/aws/dynamo_db/table.rb, line 214
def schema_loaded?
  static_attributes.include?(:hash_key)
end
simple_key?() click to toggle source

@return [Boolean] Returns true if the table has a hash key and no

range key.
# File lib/aws/dynamo_db/table.rb, line 195
def simple_key?
  range_key.nil?
end
write_capacity_units=(write_capacity_units) click to toggle source

@param [Integer] write_capacity_units

# File lib/aws/dynamo_db/table.rb, line 189
def write_capacity_units= write_capacity_units
  provision_throughput(:write_capacity_units => write_capacity_units)
end

Protected Instance Methods

get_resource(attribute_name = nil) click to toggle source
# File lib/aws/dynamo_db/table.rb, line 487
def get_resource attribute_name = nil
  client.describe_table(resource_options)
end
resource_identifiers() click to toggle source
# File lib/aws/dynamo_db/table.rb, line 492
def resource_identifiers
  [[:table_name, name]]
end