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?'", " ?"]] @private |
conditions | [R] | @private |
domain | [R] | @return [Domain] The domain the items belong to. |
output_list | [R] | @private |
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 specify what items to count with {where}:
domain.items.where(:color => "red").count
You can also limit the number of items to count:
# count up to 500 items and then stop 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 when +true+.
@option options :where Restricts the item collection using
{#where} before querying.
@option options :limit [Integer] The maximum number of
items to count in SimpleDB.
@return [Integer] The number of items counted.
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 collection. This method can yield two type of objects:
The defualt mode of an ItemCollection is to yield Item objects with no populated attributes.
# only receives item names from SimpleDB domain.items.each do |item| puts item.name puts item.class.name # => AWS::SimpleDB::Item end
You can switch a collection into yielded {ItemData} objects by specifying what attributes to request:
domain.items.select(:all).each do |item_data| puts item_data.class.name # => AWS::SimpleDB::ItemData puts item_data.attributes # => { 'attr-name' => 'attr-value', ... } end
You can also pass the standard scope options to each as well:
# output the item names of the 10 most expesive items domain.items.each(:order => [:price, :desc], :limit => 10).each do |item| puts item.name end
@yield [item] Yields once for every item in the {domain}.
@yieldparam [Item,ItemData] item If the item collection has been
scoped by chaining +#select+ or by passing the +:select+ option then {ItemData} objects (that contain a hash of attrbiutes) are yielded. If no list of attributes has been provided, then# {Item} objects (with no populated data) are yielded.
@param options [Hash]
@option options [Boolean] :consistent_read (false) Causes this
method to yield the most current data in the domain.
@option options [Mixed] :select If select is provided, then each
will yield {ItemData} objects instead of empty {Item}. The +:select+ option may be: * +:all+ - Specifies that all attributes should requested. * A single or array of attribute names (as strings or symbols). This causes the named attribute(s) to be requested.
@option options :where Restricts the item collection using
{#where} before querying (see {#where}).
@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.
@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. Generally you should not need to specify this option.
@return [String,nil] Returns a next token that can be used with
the exact same SimpleDB select expression to get more results. A next token is returned ONLY if there was a limit on the expression, otherwise all items will be enumerated and nil is returned.
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.
Specifies a list of attributes select from SimpleDB.
domain.items.select('size', 'color').each do |item_data| puts item_data.attributes # => { 'size' => ..., :color => ... } end
You can select all attributes by passing +:all+ or ’*’:
domain.items.select('*').each {|item_data| ... } domain.items.select(:all).each {|item_data| ... }
Calling select causes each to yield {ItemData} objects with attribute hashes, instead of {Item} objects with an item name.
@param *attributes [Symbol, String, or Array] The attributes to
retrieve. This can be: * +:all+ or '*' to request all attributes for each item * A list or array of attribute names as strinsg or symbols Attribute names 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.
@return [ItemCollection] Returns a new item collection with the
specified list of attributes to select.
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.