Class | RightAws::SdbInterface |
In: |
lib/sdb/right_sdb_interface.rb
|
Parent: | RightAwsBase |
DEFAULT_HOST | = | 'sdb.amazonaws.com' |
DEFAULT_PORT | = | 443 |
DEFAULT_PROTOCOL | = | 'https' |
API_VERSION | = | '2007-11-07' |
DEFAULT_NIL_REPRESENTATION | = | 'nil' |
last_query_expression | [R] |
Creates new RightSdb instance.
Params:
{ :server => 'sdb.amazonaws.com' # Amazon service host: 'sdb.amazonaws.com'(default) :port => 443 # Amazon service port: 80 or 443(default) :protocol => 'https' # Amazon service protocol: 'http' or 'https'(default) :signature_version => '0' # The signature version : '0' or '1'(default) :multi_thread => true|false # Multi-threaded (connection per each thread): true or false(default) :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')
Example:
sdb = RightAws::SdbInterface.new('1E3GDYEOGFJPIT7XXXXXX','hgTHt68JY07JKUY08ftHYtERkjgtfERn57XXXXXX', {:multi_thread => true, :logger => Logger.new('/tmp/x.log')}) #=> #<RightSdb:0xa6b8c27c>
see: docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/
# File lib/sdb/right_sdb_interface.rb, line 61 61: def initialize(aws_access_key_id=nil, aws_secret_access_key=nil, params={}) 62: @nil_rep = params[:nil_representation] ? params[:nil_representation] : DEFAULT_NIL_REPRESENTATION 63: params.delete(:nil_representation) 64: init({ :name => 'SDB', 65: :default_host => ENV['SDB_URL'] ? URI.parse(ENV['SDB_URL']).host : DEFAULT_HOST, 66: :default_port => ENV['SDB_URL'] ? URI.parse(ENV['SDB_URL']).port : DEFAULT_PORT, 67: :default_protocol => ENV['SDB_URL'] ? URI.parse(ENV['SDB_URL']).scheme : DEFAULT_PROTOCOL }, 68: aws_access_key_id || ENV['AWS_ACCESS_KEY_ID'], 69: aws_secret_access_key || ENV['AWS_SECRET_ACCESS_KEY'], 70: params) 71: end
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 = RightAws::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
# File lib/sdb/right_sdb_interface.rb, line 258 258: def create_domain(domain_name) 259: link = generate_request("CreateDomain", 260: 'DomainName' => domain_name) 261: request_info(link, QSdbSimpleParser.new) 262: rescue Exception 263: on_exception 264: end
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
# File lib/sdb/right_sdb_interface.rb, line 390 390: def delete_attributes(domain_name, item_name, attributes = nil) 391: params = { 'DomainName' => domain_name, 392: 'ItemName' => item_name }.merge(pack_attributes(attributes)) 393: link = generate_request("DeleteAttributes", params) 394: request_info( link, QSdbSimpleParser.new ) 395: rescue Exception 396: on_exception 397: end
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 = RightAws::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
# File lib/sdb/right_sdb_interface.rb, line 279 279: def delete_domain(domain_name) 280: link = generate_request("DeleteDomain", 281: 'DomainName' => domain_name) 282: request_info(link, QSdbSimpleParser.new) 283: rescue Exception 284: on_exception 285: end
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
# File lib/sdb/right_sdb_interface.rb, line 148 148: def escape(value) 149: %Q{'#{value.to_s.gsub(/(['\\])/){ "\\#{$1}" }}'} if value 150: end
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
# File lib/sdb/right_sdb_interface.rb, line 361 361: def get_attributes(domain_name, item_name, attribute_name=nil) 362: link = generate_request("GetAttributes", 'DomainName' => domain_name, 363: 'ItemName' => item_name, 364: 'AttributeName' => attribute_name ) 365: res = request_info(link, QSdbGetAttributesParser.new) 366: res[:attributes].each_value do |values| 367: values.collect! { |e| sdb_to_ruby(e) } 368: end 369: res 370: rescue Exception 371: on_exception 372: end
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 = RightAws::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
# File lib/sdb/right_sdb_interface.rb, line 226 226: def list_domains(max_number_of_domains = nil, next_token = nil ) 227: request_params = { 'MaxNumberOfDomains' => max_number_of_domains, 228: 'NextToken' => next_token } 229: link = generate_request("ListDomains", request_params) 230: result = request_info(link, QSdbListDomainParser.new) 231: # return result if no block given 232: return result unless block_given? 233: # loop if block if given 234: begin 235: # the block must return true if it wanna continue 236: break unless yield(result) && result[:next_token] 237: # make new request 238: request_params['NextToken'] = result[:next_token] 239: link = generate_request("ListDomains", request_params) 240: result = request_info(link, QSdbListDomainParser.new) 241: end while true 242: rescue Exception 243: on_exception 244: end
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
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 = RightAws::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
# File lib/sdb/right_sdb_interface.rb, line 328 328: def put_attributes(domain_name, item_name, attributes, replace = false) 329: params = { 'DomainName' => domain_name, 330: 'ItemName' => item_name }.merge(pack_attributes(attributes, replace)) 331: link = generate_request("PutAttributes", params) 332: request_info( link, QSdbSimpleParser.new ) 333: rescue Exception 334: on_exception 335: end
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
# File lib/sdb/right_sdb_interface.rb, line 436 436: def query(domain_name, query_expression = nil, max_number_of_items = nil, next_token = nil) 437: query_expression = query_expression_from_array(query_expression) if query_expression.is_a?(Array) 438: @last_query_expression = query_expression 439: # 440: request_params = { 'DomainName' => domain_name, 441: 'QueryExpression' => query_expression, 442: 'MaxNumberOfItems' => max_number_of_items, 443: 'NextToken' => next_token } 444: link = generate_request("Query", request_params) 445: result = request_info( link, QSdbQueryParser.new ) 446: # return result if no block given 447: return result unless block_given? 448: # loop if block if given 449: begin 450: # the block must return true if it wanna continue 451: break unless yield(result) && result[:next_token] 452: # make new request 453: request_params['NextToken'] = result[:next_token] 454: link = generate_request("Query", request_params) 455: result = request_info( link, QSdbQueryParser.new ) 456: end while true 457: rescue Exception 458: on_exception 459: end
# File lib/sdb/right_sdb_interface.rb, line 192 192: def query_expression_from_hash(hash) 193: return '' if hash.blank? 194: expression = [] 195: hash.each do |key, value| 196: expression << "#{key}=#{escape(value)}" 197: end 198: expression.join(' AND ') 199: end
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"}
# File lib/sdb/right_sdb_interface.rb, line 504 504: def query_with_attributes(domain_name, attributes=[], query_expression = nil, max_number_of_items = nil, next_token = nil) 505: attributes = attributes.to_a 506: query_expression = query_expression_from_array(query_expression) if query_expression.is_a?(Array) 507: @last_query_expression = query_expression 508: # 509: request_params = { 'DomainName' => domain_name, 510: 'QueryExpression' => query_expression, 511: 'MaxNumberOfItems' => max_number_of_items, 512: 'NextToken' => next_token } 513: attributes.each_with_index do |attribute, idx| 514: request_params["AttributeName.#{idx+1}"] = attribute 515: end 516: link = generate_request("QueryWithAttributes", request_params) 517: result = select_response_to_ruby(request_info( link, QSdbQueryWithAttributesParser.new )) 518: # return result if no block given 519: return result unless block_given? 520: # loop if block if given 521: begin 522: # the block must return true if it wanna continue 523: break unless yield(result) && result[:next_token] 524: # make new request 525: request_params['NextToken'] = result[:next_token] 526: link = generate_request("QueryWithAttributes", request_params) 527: result = select_response_to_ruby(request_info( link, QSdbQueryWithAttributesParser.new )) 528: end while true 529: rescue Exception 530: on_exception 531: end
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.
# File lib/sdb/right_sdb_interface.rb, line 154 154: def ruby_to_sdb(value) 155: value.nil? ? @nil_rep : value 156: end
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.
# File lib/sdb/right_sdb_interface.rb, line 160 160: def sdb_to_ruby(value) 161: value.eql?(@nil_rep) ? nil : value 162: end
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"}
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
# File lib/sdb/right_sdb_interface.rb, line 570 570: def select(select_expression, next_token = nil) 571: select_expression = query_expression_from_array(select_expression) if select_expression.is_a?(Array) 572: @last_query_expression = select_expression 573: # 574: request_params = { 'SelectExpression' => select_expression, 575: 'NextToken' => next_token } 576: link = generate_request("Select", request_params) 577: result = select_response_to_ruby(request_info( link, QSdbSelectParser.new )) 578: return result unless block_given? 579: # loop if block if given 580: begin 581: # the block must return true if it wanna continue 582: break unless yield(result) && result[:next_token] 583: # make new request 584: request_params['NextToken'] = result[:next_token] 585: link = generate_request("Select", request_params) 586: result = select_response_to_ruby(request_info( link, QSdbSelectParser.new )) 587: end while true 588: rescue Exception 589: on_exception 590: end