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

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

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#hash_key ⇒ PrimaryKeyElement

Returns the hash key element for this table.

Returns:



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

def hash_key
  @hash_key
end

#name ⇒ String (readonly)

Returns The name of this table.

Returns:

  • (String) —

    The name of this table.



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

def name
  @name
end

#range_key ⇒ PrimaryKeyElement

Returns:



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

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



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

def read_capacity_units
  @read_capacity_units
end

#status ⇒ Symbol (readonly)

Returns the current value of status.

Returns:

  • (Symbol) —

    the current value of status



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

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



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

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



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

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



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

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) 


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

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) 


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

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.



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

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) 


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

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) 


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

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.



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

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) 


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

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.



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

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.



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

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



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

def load_schema
  hash_key
  self
end

#provision_throughput(options = {}) ⇒ Hash

Returns a hash with the current throughput provisioning (:read_capacity_units and :write_capacity_units).

Parameters:

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

Options Hash (options):

  • :read_capacity_units (Integer)
  • :write_capacity_units (Integer)

Returns:

  • (Hash) —

    Returns a hash with the current throughput provisioning (:read_capacity_units and :write_capacity_units).



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

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 ⇒ PrimaryKeyElement?

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

Returns:



123
124
125
 
# File 'lib/aws/dynamo_db/table.rb', line 123

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.



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

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.



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

def simple_key?
  range_key.nil?
end