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

Class: AWS::SimpleDB

Inherits:
Object
  • Object
show all
Includes:
Core::ServiceInterface
Defined in:
lib/aws/simple_db.rb,
lib/aws/simple_db/item.rb,
lib/aws/simple_db/errors.rb,
lib/aws/simple_db/domain.rb,
lib/aws/simple_db/client.rb,
lib/aws/simple_db/item_data.rb,
lib/aws/simple_db/attribute.rb,
lib/aws/simple_db/put_attributes.rb,
lib/aws/simple_db/item_collection.rb,
lib/aws/simple_db/domain_metadata.rb,
lib/aws/simple_db/delete_attributes.rb,
lib/aws/simple_db/domain_collection.rb,
lib/aws/simple_db/attribute_collection.rb,
lib/aws/simple_db/consistent_read_option.rb,
lib/aws/simple_db/expect_condition_option.rb

Overview

This class is the starting point for working with Amazon SimpleDB.

To use Amazon SimpleDB you must first sign up here.

For more information about Amazon SimpleDB:

Credentials

You can setup default credentials for all AWS services via AWS.config:

AWS.config(
  :access_key_id => 'YOUR_ACCESS_KEY_ID',
  :secret_access_key => 'YOUR_SECRET_ACCESS_KEY')

Or you can set them directly on the SimpleDB interface:

sdb = AWS::SimpleDB.new(
  :access_key_id => 'YOUR_ACCESS_KEY_ID',
  :secret_access_key => 'YOUR_SECRET_ACCESS_KEY')

Understanding the SimpleDB Interface

SimpleDB stores data in a hierarchy of:

Domains > Items > Attributes

These are modeled with the following classes:

The collection classes listed above make it easy to enumerate, the objects they represent. They also make it easy to perform bulk operations on all objects in that collection.

Domains

Domains are like database tables. A domain must exist before you can write to it. To create a domain:

sdb = SimpleDB.new
domain = sdb.domains.create('mydomain')

For more information about working with domains see DomainCollection and Domain.

Items & Attributes

Items exist in SimpleDB when they have attributes. You can delete an item by removing all of its attributes. You create an item by adding an attribute to it.

The following example illustrates how you can reference an item that does not exist yet:

sdb = SimpleDB.new

# this domain is empty, it has no items
domain = sdb.domains.create('newdomain')
domain.items.collect(&:name)
#=> []

# this item doesn't exist yet, so it has no attributes
item = domain.items['newitem']
item.attributes.collect(&:name)
#=> []

# the item has no attributes
tags = item.attributes['tags']
tags.values
#=> []

To create the item in SimpleDB you just need to add an attribute.

tags.add %w(first new)

domain.items.collect(&:name)
#=> ['newitem']

item.attributes.collect(&:name)
#=> ['tags']

tags.values
#=> ['first', 'new']

For more information about working with items and attributes, see:

Lazy Execution

Requests are not made until necessary. This means you can drill down all the way to an attribute, by name, without making any requests to SimpleDB.

# makes no request to SimpleDB
sdb = SimpleDB.new
colors = sdb.domains['mydomain'].items['car'].attributes['colors']

# one request to get the values for 'colors'
puts colors.values

# one request to add blue and green
colors.add 'blue', 'green'

# one request to delete the colors attribute
colors.delete

Defined Under Namespace

Classes: Attribute, AttributeCollection, Client, Domain, DomainCollection, DomainMetadata, Item, ItemCollection, ItemData

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Core::ServiceInterface

included, #initialize, #inspect

Instance Attribute Details

#client ⇒ Client (readonly)

Returns the low-level SimpleDB client object

Returns:

  • (Client) —

    the low-level SimpleDB client object



141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/aws/simple_db.rb', line 141

class SimpleDB

  autoload :Attribute, 'aws/simple_db/attribute'
  autoload :AttributeCollection, 'aws/simple_db/attribute_collection'
  autoload :Client, 'aws/simple_db/client'
  autoload :ConsistentReadOption, 'aws/simple_db/consistent_read_option'
  autoload :DeleteAttributes, 'aws/simple_db/delete_attributes'
  autoload :Domain, 'aws/simple_db/domain'
  autoload :DomainCollection, 'aws/simple_db/domain_collection'
  autoload :DomainMetadata, 'aws/simple_db/domain_metadata'
  autoload :Errors, 'aws/simple_db/errors'
  autoload :ExpectConditionOption, 'aws/simple_db/expect_condition_option'
  autoload :Item, 'aws/simple_db/item'
  autoload :ItemCollection, 'aws/simple_db/item_collection'
  autoload :ItemData, 'aws/simple_db/item_data'
  autoload :PutAttributes, 'aws/simple_db/put_attributes'

  include Core::ServiceInterface

  endpoint_prefix 'sdb'

  # Returns a collection object that represents the domains in your
  # account.
  #
  # @return [DomainCollection] Returns a collection representing all your
  #   domains.
  def domains
    DomainCollection.new(:config => config)
  end

  # Call this method with a block.  Code executed inside the block
  # make consistent reads until the block ends.
  #
  #     AWS::SimpleDB.consistent_reads do
  #       # ...
  #     end
  #
  # ### Other Modes
  #
  # You can also use this same function to disable consistent reads inside
  # a block.  This is useful if you have consistent reads enabled by
  # default:
  #
  #     AWS::SimpleDB.consistent_reads(false) do
  #       # ...
  #     end
  #
  # @param [Boolean] state (true) When true, all SimpleDB read operations
  #   will be consistent reads inside the block.  When false, all
  #   reads operations will not be consistent reads.  The previous state
  #   will be restored after the block executes.
  # @return Returns the final block value.
  def self.consistent_reads state = true, &block
    begin
      prev_state = Thread.current['_simple_db_consistent_reads_']
      Thread.current['_simple_db_consistent_reads_'] = state
      yield
    ensure
      Thread.current['_simple_db_consistent_reads_'] = prev_state
    end
  end

  # @return [Boolean] Returns true if we are inside an AWS::SimpleDB
  #   #consistent_reads method block.
  # @api private
  def self.in_consistent_reads_block?
    !Thread.current['_simple_db_consistent_reads_'].nil?
  end

  # @return [Boolean] Returns true if the consistent_reads block has
  #   a true state, false otherwise.
  # @api private
  def self.consistent_reads_state
    Thread.current['_simple_db_consistent_reads_']
  end

end

Class Method Details

.consistent_reads(state = true, &block) ⇒ Object

Call this method with a block. Code executed inside the block make consistent reads until the block ends.

AWS::SimpleDB.consistent_reads do
  # ...
end

Other Modes

You can also use this same function to disable consistent reads inside a block. This is useful if you have consistent reads enabled by default:

AWS::SimpleDB.consistent_reads(false) do
  # ...
end

Parameters:

  • state (Boolean) (defaults to: true) —

    (true) When true, all SimpleDB read operations will be consistent reads inside the block. When false, all reads operations will not be consistent reads. The previous state will be restored after the block executes.

Returns:

  • Returns the final block value.



193
194
195
196
197
198
199
200
201
 
# File 'lib/aws/simple_db.rb', line 193

def self.consistent_reads state = true, &block
  begin
    prev_state = Thread.current['_simple_db_consistent_reads_']
    Thread.current['_simple_db_consistent_reads_'] = state
    yield
  ensure
    Thread.current['_simple_db_consistent_reads_'] = prev_state
  end
end

Instance Method Details

#domains ⇒ DomainCollection

Returns a collection object that represents the domains in your account.

Returns:



167
168
169
 
# File 'lib/aws/simple_db.rb', line 167

def domains
  DomainCollection.new(:config => config)
end