Class AWS::DynamoDB::Table
In: lib/aws/dynamo_db/table.rb
Parent: Resource

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

Methods

External Aliases

creation_date_time -> created_at
range_key -> range_key_without_schema_override

Attributes

name  [R]  @return [String] The name of this table.

Public Class methods

Public Instance methods

Raises an exception unless the table schema is loaded.

@return [nil]

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 BatchWrite#process!)

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.

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 BatchWrite#process!)

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 BatchWrite#process!)

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

  a range key.

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

@return [nil]

@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.
has_range_key?()

Alias for composite_key?

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.

@return [ItemCollection] Returns an object representing all the

  items in the table.

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

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

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.

@param [Integer] read_capacity_units

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

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

  range key.

@param [Integer] write_capacity_units

Protected Instance methods

[Validate]