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

Class: AWS::DynamoDB::Table

Inherits:
Resource
  • Object
show all
Defined in:
lib/aws/dynamo_db/table.rb

Overview

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

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

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#hash_key ⇒ PrimaryKeyElement

Returns the hash key element for this table.

Returns:



92
93
94
 
# File 'lib/aws/dynamo_db/table.rb', line 92

def hash_key
  @hash_key
end

#item_count ⇒ Integer

Returns the current value of item_count

Returns:

  • (Integer) —

    the current value of item_count



92
93
94
 
# File 'lib/aws/dynamo_db/table.rb', line 92

def item_count
  @item_count
end

#name ⇒ String (readonly)

Returns The name of this table.

Returns:

  • (String) —

    The name of this table.



101
102
103
 
# File 'lib/aws/dynamo_db/table.rb', line 101

def name
  @name
end

#range_key ⇒ PrimaryKeyElement

Returns:



92
93
94
 
# File 'lib/aws/dynamo_db/table.rb', line 92

def range_key
  @range_key
end

#read_capacity_units ⇒ Integer

Returns the current value of read_capacity_units

Returns:

  • (Integer) —

    the current value of read_capacity_units



92
93
94
 
# File 'lib/aws/dynamo_db/table.rb', line 92

def read_capacity_units
  @read_capacity_units
end

#size_bytes ⇒ Integer

Returns the current value of size_bytes

Returns:

  • (Integer) —

    the current value of size_bytes



92
93
94
 
# File 'lib/aws/dynamo_db/table.rb', line 92

def size_bytes
  @size_bytes
end

#status ⇒ Symbol (readonly)

Returns the current value of status

Returns:

  • (Symbol) —

    the current value of status



92
93
94
 
# File 'lib/aws/dynamo_db/table.rb', line 92

def status
  @status
end

#throughput_last_decreased_at ⇒ Time

Returns the current value of throughput_last_decreased_at

Returns:

  • (Time) —

    the current value of throughput_last_decreased_at



92
93
94
 
# File 'lib/aws/dynamo_db/table.rb', line 92

def throughput_last_decreased_at
  @throughput_last_decreased_at
end

#throughput_last_increased_at ⇒ Time

Returns the current value of throughput_last_increased_at

Returns:

  • (Time) —

    the current value of throughput_last_increased_at



92
93
94
 
# File 'lib/aws/dynamo_db/table.rb', line 92

def throughput_last_increased_at
  @throughput_last_increased_at
end

#write_capacity_units ⇒ Integer

Returns the current value of write_capacity_units

Returns:

  • (Integer) —

    the current value of write_capacity_units



92
93
94
 
# File 'lib/aws/dynamo_db/table.rb', line 92

def write_capacity_units
  @write_capacity_units
end

Instance Method Details

#assert_schema! ⇒ nil

Raises an exception unless the table schema is loaded.

Returns:

  • (nil) 


215
216
217
 
# File 'lib/aws/dynamo_db/table.rb', line 215

def assert_schema!
  raise "table schema not loaded" unless schema_loaded?
end

#batch_delete(items) ⇒ nil

Delete up to 25 items in a single batch.

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

Parameters:

  • items (Array<String>, Array<Array>) —

    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']])

Returns:

  • (nil) 


473
474
475
476
477
 
# File 'lib/aws/dynamo_db/table.rb', line 473

def batch_delete items
  batch = BatchWrite.new(:config => config)
  batch.delete(self, items)
  batch.process!
end

#batch_get(attributes, items, options = {}) {|Hash| ... } ⇒ Enumerable

Note:

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

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 AWS::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

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.

Parameters:

  • attributes (:all, String, Array<String>) —

    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
  • items (Mixed) —

    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
  • options (Hash) (defaults to: {})

Options Hash (options):

  • :consistent_read (Boolean) — default: false —

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

Yields:

  • (Hash) —

    Yields a hash of attributes for each item.

Returns:

  • (Enumerable) —

    Returns an enumerable object that yields hashes of attributes.



405
406
407
408
409
410
 
# File 'lib/aws/dynamo_db/table.rb', line 405

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) ⇒ nil

Batch puts up to 25 items to this table.

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

Parameters:

  • items (Array<Hash>) —

    A list of item attributes to put. The hash must contain the table hash key element and range key element (if one is defined).

Returns:

  • (nil) 


426
427
428
429
430
 
# File 'lib/aws/dynamo_db/table.rb', line 426

def batch_put items
  batch = BatchWrite.new(:config => config)
  batch.put(self, items)
  batch.process!
end

#batch_write(options = {}) ⇒ nil

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']
)

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • (BatchWrite#write) (Object)

Returns:

  • (nil) 


450
451
452
453
454
 
# File 'lib/aws/dynamo_db/table.rb', line 450

def batch_write options = {}
  batch = BatchWrite.new(:config => config)
  batch.write(self, options)
  batch.process!
end

#composite_key? ⇒ Boolean Also known as: has_range_key?

Returns true if the table has both a hash key and a range key.

Returns:

  • (Boolean) —

    Returns true if the table has both a hash key and a range key.



194
195
196
 
# File 'lib/aws/dynamo_db/table.rb', line 194

def composite_key?
  !simple_key?
end

#delete ⇒ nil

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

Returns:

  • (nil) 


290
291
292
293
 
# File 'lib/aws/dynamo_db/table.rb', line 290

def delete
  client.delete_table(:table_name => name)
  nil
end

#exists? ⇒ 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.

Returns:

  • (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.



305
306
307
308
309
310
 
# File 'lib/aws/dynamo_db/table.rb', line 305

def exists?
  get_resource
  true
rescue Errors::ResourceNotFoundException
  false
end

#items ⇒ ItemCollection

Returns an object representing all the items in the table.

Returns:

  • (ItemCollection) —

    Returns an object representing all the items in the table.



297
298
299
 
# File 'lib/aws/dynamo_db/table.rb', line 297

def items
  ItemCollection.new(self)
end

#load_schema ⇒ Object

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.

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.

Returns:

  • self



231
232
233
234
 
# File 'lib/aws/dynamo_db/table.rb', line 231

def load_schema
  hash_key
  self
end

#provision_throughput(options = {}) ⇒ Hash

Updates the provisioned throughput for this table.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :read_capacity_units (Integer) —

    The desired read capacity units.

  • :write_capacity_units (Integer) —

    The desired write capacity units.

Returns:

  • (Hash) —

    Returns the given options hash.



162
163
164
165
166
167
168
169
170
171
172
173
174
 
# File 'lib/aws/dynamo_db/table.rb', line 162

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_without_schema_override ⇒ Object

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



128
129
130
 
# File 'lib/aws/dynamo_db/table.rb', line 128

def range_key
  @range_key
end

#schema_loaded? ⇒ Boolean

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.

Returns True if the table's schema information is loaded into memory.

Returns:

  • (Boolean) —

    True if the table's schema information is loaded into memory.



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

def schema_loaded?
  static_attributes.include?(:hash_key)
end

#simple_key? ⇒ Boolean

Returns true if the table has a hash key and no range key.

Returns:

  • (Boolean) —

    Returns true if the table has a hash key and no range key.



188
189
190
 
# File 'lib/aws/dynamo_db/table.rb', line 188

def simple_key?
  range_key.nil?
end