Class Aws::SdbInterface
In: lib/sdb/sdb_interface.rb
Parent: AwsBase

Methods

Included Modules

AwsBaseInterface

Classes and Modules

Class Aws::SdbInterface::Item

Constants

DEFAULT_HOST = 'sdb.amazonaws.com'
DEFAULT_PORT = 443
DEFAULT_PROTOCOL = 'https'
DEFAULT_SERVICE = '/'
API_VERSION = '2009-04-15'
DEFAULT_NIL_REPRESENTATION = 'nil'

Attributes

last_query_expression  [R] 

Public Class methods

Creates new RightSdb instance.

Params:

   { :server       => 'sdb.amazonaws.com'  # Amazon service host: 'sdb.amazonaws.com'(default)
     :port         => 443                  # Amazon service port: 80(default) or 443
     :protocol     => 'https'              # Amazon service protocol: 'http'(default) or 'https'
     :signature_version => '2'             # The signature version : '0', '1' or '2' (default)
     DEPRECATED :multi_thread => true|false           # Multi-threaded (connection per each thread): true or false(default)
     :connection_mode  => :default         # options are :default (will use best known option, may change in the future)
                                                 :per_request (opens and closes a connection on every request to SDB)
                                                 :single - one connection shared across app (same as old multi_thread=>false)
                                                 :per_thread - one connection per ruby thread (same as old multi_thread=>true)
                                                 :pool (uses a connection pool with a maximum number of connections - NOT IMPLEMENTED YET)
     :logger       => Logger Object        # Logger instance: logs to STDOUT if omitted
     :nil_representation => 'mynil'}       # interpret Ruby nil as this string value; i.e. use this string in SDB to represent Ruby nils (default is the string 'nil')
     :service      => '/'                  # Set this to /mdb/request.mgwsi for usage with M/DB #

Example:

 sdb = Aws::SdbInterface.new('1E3GDYEOGFJPIT7XXXXXX','hgTHt68JY07JKUY08ftHYtERkjgtfERn57XXXXXX', {:connection_mode => :per_request, :logger => Logger.new('/tmp/x.log')}) #=> #<RightSdb:0xa6b8c27c>

see: docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/

Public Instance methods

items is an array item_name‘s or Aws::SdbInterface::Item.new(o.id, o.attributes, true)

Create new SDB domain at Amazon.

Returns a hash: { :box_usage, :request_id } on success or an exception on error. (Amazon raises no errors if the domain already exists).

Example:

 sdb = Aws::SdbInterface.new
 sdb.create_domain('toys') # => { :box_usage  => "0.0000071759",
                                  :request_id => "976709f9-0111-2345-92cb-9ce90acd0982" }

see: docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/SDB_API_CreateDomain.html

Delete value, attribute or item.

Example:

 # delete 'vodka' and 'girls' from 'Jon' and 'mice' from 'cat'.
 sdb.delete_attributes 'family', 'toys', { 'Jon' => ['vodka', 'girls'], 'cat' => ['mice'] }

 # delete the all the values from attributes (i.e. delete the attributes)
 sdb.delete_attributes 'family', 'toys', { 'Jon' => [], 'cat' => [] }
 # or
 sdb.delete_attributes 'family', 'toys', [ 'Jon', 'cat' ]

 # delete all the attributes from item 'toys' (i.e. delete the item)
 sdb.delete_attributes 'family', 'toys'

see docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/SDB_API_DeleteAttributes.html

Delete SDB domain at Amazon.

Returns a hash: { :box_usage, :request_id } on success or an exception on error. (Amazon raises no errors if the domain does not exist).

Example:

 sdb = Aws::SdbInterface.new
 sdb.delete_domain('toys') # => { :box_usage  => "0.0000071759",
                                  :request_id => "976709f9-0111-2345-92cb-9ce90acd0982" }

see: docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/SDB_API_DeleteDomain.html

Retrieve a list of SDB domains from Amazon.

Returns a hash:

  { :domains     => [domain1, ..., domainN],
    :next_token => string || nil,
    :box_usage   => string,
    :request_id  => string }

Example:

 sdb = Aws::SdbInterface.new
 sdb.list_domains  #=> { :box_usage  => "0.0000071759",
                         :request_id => "976709f9-0111-2345-92cb-9ce90acd0982",
                         :domains    => ["toys", "dolls"]}

If a block is given, this method yields to it. If the block returns true, list_domains will continue looping the request. If the block returns false, list_domains will end.

  sdb.list_domains(10) do |result|   # list by 10 domains per iteration
    puts result.inspect
    true
  end

see: docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/SDB_API_ListDomains.html

Use this helper to manually escape the fields in the query expressions. To escape the single quotes and backslashes and to wrap the string into the single quotes.

see: docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/SDB_API.html

Retrieve SDB item‘s attribute(s).

Returns a hash:

 { :box_usage  => string,
   :request_id => string,
   :attributes => { 'nameA' => [valueA1,..., valueAN],
                    ... ,
                    'nameZ' => [valueZ1,..., valueZN] } }

Example:

 # request all attributes
 sdb.get_attributes('family', 'toys') # => { :attributes => {"cat"    => ["clew", "Jons_socks", "mouse"] },
                                                             "Silvia" => ["beetle", "rolling_pin", "kids"],
                                                             "Jon"    => ["vacuum_cleaner", "hammer", "spade"]},
                                             :box_usage  => "0.0000093222",
                                             :request_id => "81273d21-000-1111-b3f9-512d91d29ac8" }

 # request cat's attributes only
 sdb.get_attributes('family', 'toys', 'cat') # => { :attributes => {"cat" => ["clew", "Jons_socks", "mouse"] },
                                                    :box_usage  => "0.0000093222",
                                                    :request_id => "81273d21-001-1111-b3f9-512d91d29ac8" }

see: docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/SDB_API_GetAttributes.html

Retrieve a list of SDB domains from Amazon.

Returns a hash:

  { :domains     => [domain1, ..., domainN],
    :next_token => string || nil,
    :box_usage   => string,
    :request_id  => string }

Example:

 sdb = Aws::SdbInterface.new
 sdb.list_domains  #=> { :box_usage  => "0.0000071759",
                         :request_id => "976709f9-0111-2345-92cb-9ce90acd0982",
                         :domains    => ["toys", "dolls"]}

If a block is given, this method yields to it. If the block returns true, list_domains will continue looping the request. If the block returns false, list_domains will end.

  sdb.list_domains(10) do |result|   # list by 10 domains per iteration
    puts result.inspect
    true
  end

see: docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/SDB_API_ListDomains.html

Add/Replace item attributes.

Params:

 domain_name = DomainName
 item_name   = ItemName
 attributes  = {
   'nameA' => [valueA1,..., valueAN],
   ...
   'nameZ' => [valueZ1,..., valueZN]
 }
 replace = :replace | any other value to skip replacement
 options:
   :create_domain => If true and domain does not exist, it will be created. Default is false.

Returns a hash: { :box_usage, :request_id } on success or an exception on error. (Amazon raises no errors if the attribute was not overridden, as when the :replace param is unset).

Example:

 sdb = Aws::SdbInterface.new
 sdb.create_domain 'family'

 attributes = {}
 # create attributes for Jon and Silvia
 attributes['Jon']    = %w{ car beer }
 attributes['Silvia'] = %w{ beetle rolling_pin kids }
 sdb.put_attributes 'family', 'toys', attributes   #=> ok
 # now: Jon=>[car, beer], Silvia=>[beetle, rolling_pin, kids]

 # add attributes to Jon
 attributes.delete('Silvia')
 attributes['Jon'] = %w{ girls pub }
 sdb.put_attributes 'family', 'toys', attributes   #=> ok
 # now: Jon=>[car, beer, girls, pub], Silvia=>[beetle, rolling_pin, kids]

 # replace attributes for Jon and add to a cat (the cat had no attributes before)
 attributes['Jon'] = %w{ vacuum_cleaner hammer spade }
 attributes['cat'] = %w{ mouse clew Jons_socks }
 sdb.put_attributes 'family', 'toys', attributes, :replace #=> ok
 # now: Jon=>[vacuum_cleaner, hammer, spade], Silvia=>[beetle, rolling_pin, kids], cat=>[mouse, clew, Jons_socks]

see: docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/SDB_API_PutAttributes.html

Perform a query on SDB.

Returns a hash:

  { :box_usage  => string,
    :request_id => string,
    :next_token => string,
    :items      => [ItemName1,..., ItemNameN] }

Example:

  query = "['cat' = 'clew']"
  sdb.query('family', query)     #=> hash of data
  sdb.query('family', query, 10) #=> hash of data with max of 10 items

If a block is given, query will iteratively yield results to it as long as the block continues to return true.

  # List 10 items per iteration. Don't
  # forget to escape single quotes and backslashes and wrap all the items in single quotes.
  query = "['cat'='clew'] union ['dog'='Jon\\'s boot']"
  sdb.query('family', query, 10) do |result|
    puts result.inspect
    true
  end

  # Same query using automatic escaping...to use the auto escape, pass the query and its params as an array:
  query = [ "['cat'=?] union ['dog'=?]", "clew", "Jon's boot" ]
  sdb.query('family', query)

  query = [ "['cat'=?] union ['dog'=?] sort 'cat' desc", "clew", "Jon's boot" ]
  sdb.query('family', query)

see: docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/SDB_API_Query.html

     http://docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/index.html?SortingData.html

Perform a query and fetch specified attributes. If attributes are not specified then fetches the whole list of attributes.

Returns a hash:

  { :box_usage  => string,
    :request_id => string,
    :next_token => string,
    :items      => [ { ItemName1 => { attribute1 => value1, ...  attributeM => valueM } },
                     { ItemName2 => {...}}, ... ]

Example:

  sdb.query_with_attributes(domain, ['hobby', 'country'], "['gender'='female'] intersection ['name' starts-with ''] sort 'name'") #=>
    { :request_id => "06057228-70d0-4487-89fb-fd9c028580d3",
      :items =>
        [ { "035f1ba8-dbd8-11dd-80bd-001bfc466dd7"=>
            { "hobby"   => ["cooking", "flowers", "cats"],
              "country" => ["Russia"]}},
          { "0327614a-dbd8-11dd-80bd-001bfc466dd7"=>
            { "hobby"   => ["patchwork", "bundle jumping"],
              "country" => ["USA"]}}, ... ],
       :box_usage=>"0.0000504786"}

  sdb.query_with_attributes(domain, [], "['gender'='female'] intersection ['name' starts-with ''] sort 'name'") #=>
    { :request_id => "75bb19db-a529-4f69-b86f-5e3800f79a45",
      :items =>
      [ { "035f1ba8-dbd8-11dd-80bd-001bfc466dd7"=>
          { "hobby"   => ["cooking", "flowers", "cats"],
            "name"    => ["Mary"],
            "country" => ["Russia"],
            "gender"  => ["female"],
            "id"      => ["035f1ba8-dbd8-11dd-80bd-001bfc466dd7"]}},
        { "0327614a-dbd8-11dd-80bd-001bfc466dd7"=>
          { "hobby"   => ["patchwork", "bundle jumping"],
            "name"    => ["Mary"],
            "country" => ["USA"],
            "gender"  => ["female"],
            "id"      => ["0327614a-dbd8-11dd-80bd-001bfc466dd7"]}}, ... ],
     :box_usage=>"0.0000506668"}

see: docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/index.html?SDB_API_QueryWithAttributes.html

Convert a Ruby language value to a SDB value by replacing Ruby nil with the user‘s chosen string representation of nil. Non-nil values are unaffected by this filter.

Convert a SDB value to a Ruby language value by replacing the user‘s chosen string representation of nil with Ruby nil. Values are unaffected by this filter unless they match the nil representation exactly.

Perform SQL-like select and fetch attributes. Attribute values must be quoted with a single or double quote. If a quote appears within the attribute value, it must be escaped with the same quote symbol as shown in the following example. (Use array to pass select_expression params to avoid manual escaping).

 sdb.select(["select * from my_domain where gender=?", 'female']) #=>
   {:request_id =>"8241b843-0fb9-4d66-9100-effae12249ec",
    :items =>
     [ { "035f1ba8-dbd8-11dd-80bd-001bfc466dd7"=>
         {"hobby"   => ["cooking", "flowers", "cats"],
          "name"    => ["Mary"],
          "country" => ["Russia"],
          "gender"  => ["female"],
          "id"      => ["035f1ba8-dbd8-11dd-80bd-001bfc466dd7"]}},
       { "0327614a-dbd8-11dd-80bd-001bfc466dd7"=>
         {"hobby"   => ["patchwork", "bundle jumping"],
          "name"    => ["Mary"],
          "country" => ["USA"],
          "gender"  => ["female"],
          "id"      => ["0327614a-dbd8-11dd-80bd-001bfc466dd7"]}}, ... ]
    :box_usage =>"0.0000506197"}

  sdb.select('select country, name from my_domain') #=>
   {:request_id=>"b1600198-c317-413f-a8dc-4e7f864a940a",
    :items=>
     [ { "035f1ba8-dbd8-11dd-80bd-001bfc466dd7"=> {"name"=>["Mary"],     "country"=>["Russia"]} },
       { "376d2e00-75b0-11dd-9557-001bfc466dd7"=> {"name"=>["Putin"],    "country"=>["Russia"]} },
       { "0327614a-dbd8-11dd-80bd-001bfc466dd7"=> {"name"=>["Mary"],     "country"=>["USA"]}    },
       { "372ebbd4-75b0-11dd-9557-001bfc466dd7"=> {"name"=>["Bush"],     "country"=>["USA"]}    },
       { "37a4e552-75b0-11dd-9557-001bfc466dd7"=> {"name"=>["Medvedev"], "country"=>["Russia"]} },
       { "38278dfe-75b0-11dd-9557-001bfc466dd7"=> {"name"=>["Mary"],     "country"=>["Russia"]} },
       { "37df6c36-75b0-11dd-9557-001bfc466dd7"=> {"name"=>["Mary"],     "country"=>["USA"]}    } ],
    :box_usage=>"0.0000777663"}

options:

    :next_token
    :consistent_read
    :retries => maximum number of times to retry this query on an error response.

see: docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/index.html?SDB_API_Select.html

     http://docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/index.html?UsingSelect.html
     http://docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/index.html?SDBLimits.html

[Validate]