Class | AWS::SimpleDB::ItemCollection |
In: |
lib/aws/simple_db/item_collection.rb
|
Parent: | Object |
Represents a collection of items in a SimpleDB domain.
OUTSIDE_QUOTES_REGEX | = | Regexp.compile('([^\'"`]*)(`(?:[^`]*(?:``))*[^`]*`|'+ '\'(?:[^\']*(?:\'\'))*[^\']*\'|'+ '"(?:[^"]*(?:""))*[^"]*")([^\'`"]*)') |
Identifies quoted regions in the string, giving access to the regions
before and after each quoted
region, for example:
"? ? `foo?``bar?` ? 'foo?' ?".scan(OUTSIDE_QUOTES_REGEX) # => [["? ? ", "`foo?``bar?`", " ? "], ["", "'foo?'", " ?"]] |
conditions | [R] | @private |
domain | [R] | @return [Domain] The domain the items belong to. |
sort_instructions | [R] | @private |
@param [Domain] domain The domain that you want an item collection for. @return [ItemCollection]
Retuns an item with the given name.
@note This does not make a request to SimpleDB.
You can ask for any item. The named item may or may not actually exist in SimpleDB.
@example Get an item by symbol or string name
item = domain.items[:itemname] item = domain.items['itemname']
@param [String, Symbol] item_name name of the item to get. @return [Item] Returns an item with the given name.
Counts the items in the collection.
domain.items.count
You can use this method to get the total number of items in the domain, or you can use it with {where} to count a subset of items. For example, to count the items where the "color" attribute is "red":
domain.items.where("color" => "red").count
You can also limit the number of items searched using the {limit} method. For example, to count the number of items up to 500:
domain.items.limit(500).count
@param [Hash] options Options for counting items.
@option options [Boolean] :consistent_read (false) Causes this
method to yield the most current data in the domain.
@option options :where Restricts the item collection using
{#where} before querying.
@option options :limit [Integer] The maximum number of
items to fetch from SimpleDB. More than one request may be required to satisfy the limit.
Creates a new item in SimpleDB with the given attributes:
domain.items.create('shirt', { 'colors' => ['red', 'blue'], 'category' => 'clearance'})
@overload create(item_name, attribute_hash) @param [String] item_name The name of the item as you want it stored
in SimpleDB.
@param [Hash] attribute_hash A hash of attribute names and values
you want to store in SimpleDB.
@return [Item] Returns a reference to the object that was created.
Yields to the block once for each item in the domain.
@example using each to fetch every item in the domain.
domain.items.each do |item| puts item.name end
@yield [item] Yields once for every item in the {domain}. @yieldparam [Item] item @param options (see select) @option options (see select) @option options [Symbol or Array] :select Causes this method
to behave like {#select} and yield {ItemData} instead of {Item} instances.
@option options :batch_size Specifies a maximum number of records
to fetch from SimpleDB in a single request. SimpleDB may return fewer items than :batch_size per request, but never more.
@return [nil]
Limits the number of items that are returned or yielded. For example, to get the 100 most popular item names:
domain.items. order(:popularity, :desc). limit(100). map(&:name)
@overload limit
@return [Integer] Returns the current limit for the collection.
@overload limit(value)
@return [ItemCollection] Returns a collection with the given limit.
Changes the order in which results are returned or yielded. For example, to get item names in descending order of popularity, you can do:
domain.items.order(:popularity, :desc).map(&:name)
@param attribute [String or Symbol] The attribute name to
order by.
@param order [String or Symbol] The desired order, which may be:
* +asc+ or +ascending+ (the default) * +desc+ or +descending+
@return [ItemCollection] Returns a new item collection with the
given ordering logic.
Retrieves data from each item in the domain.
domain.items.select('size', 'color')
You may optionally filter by a set of conditions. For example, to retrieve the attributes of each of the top 100 items in order of descending popularity as an array of hashes, you could do:
items.order(:popularity, :desc).limit(100).select do |data| puts data.to_yaml end
You can select specific attributes; for example, to get all the unique colors in the collection you could do:
colors = Set.new items.select(:color) {|data| colors += data.attributes["color"] }
Finally, you can specify conditions, sort instructions, and a limit in the same method call:
items.select(:color, :where => "rating > 4", :order => [:popularity, :desc], :limit => 100) do |data| puts "Data for #{data.name}: #{data.attributes.inspect}" end
@overload select(*attribute_names, options = {}) &block
@param *attributes [Symbol, String, or Array] The attributes to retrieve. This can be: * +:all+ to retrieve all attributes (the default). * a Symbol or String to retrieve a single attribute. * an array of Symbols or Strings to retrieve multiple attributes. For single attributes or arrays of attributes, the attribute name may contain any characters that are valid in a SimpleDB attribute name; this method will handle escaping them for inclusion in the query. Note that you cannot use this method to select the number of items; use {#count} instead. @param [Hash] options Options for querying the domain. @option options [Boolean] :consistent_read (false) Causes this method to yield the most current data in the domain. @option options :where Restricts the item collection using {#where} before querying. @option options :order Changes the order in which the items will be yielded (see {#order}). @option options :limit [Integer] The maximum number of items to fetch from SimpleDB. More than one request may be required to satisfy the limit. @option options :batch_size Specifies a maximum number of records to fetch from SimpleDB in a single request. SimpleDB may return fewer items than :batch_size per request, but never more. @return If no block is given, an enumerator is returned. If a block was passed then nil is returned.
Returns an item collection defined by the given conditions in addition to any conditions defined on this collection. For example:
items = domain.items.where(:color => 'blue'). where('engine_type is not null') # does SELECT itemName() FROM `mydomain` # WHERE color = "blue" AND engine_type is not null items.each { |i| ... }
When conditions is a hash, each entry produces a condition on the attribute named in the hash key. For example:
# produces "WHERE `foo` = 'bar'" domain.items.where(:foo => 'bar')
You can pass an array value to use an "IN" operator instead of "=":
# produces "WHERE `foo` IN ('bar', 'baz')" domain.items.where(:foo => ['bar', 'baz'])
You can also pass a range value to use a "BETWEEN" operator:
# produces "WHERE `foo` BETWEEN 'bar' AND 'baz' domain.items.where(:foo => 'bar'..'baz') # produces "WHERE (`foo` >= 'bar' AND `foo` < 'baz')" domain.items.where(:foo => 'bar'...'baz')
If conditions is a string and "?" appears outside of any quoted part of the expression, placeholers is expected to contain a value for each of the "?" characters in the expression. For example:
# produces "WHERE foo like 'fred''s % value'" domain.items.where("foo like ?", "fred's % value")
Array values are surrounded with parentheses when they are substituted for a placeholder:
# produces "WHERE foo in ('1', '2')" domain.items.where("foo in ?", [1, 2])
Note that no substitutions are made within a quoted region of the query:
# produces "WHERE `foo?` = 'red'" domain.items.where("`foo?` = ?", "red") # produces "WHERE foo = 'fuzz?' AND bar = 'zap'" domain.items.where("foo = 'fuzz?' AND bar = ?", "zap")
Also note that no attempt is made to correct for syntax:
# produces "WHERE 'foo' = 'bar'", which is invalid domain.items.where("? = 'bar'", "foo")
@return [ItemCollection] Returns a new item collection with the
additional conditions.