Class AWS::SimpleDB::ItemCollection
In: lib/aws/simple_db/item_collection.rb
Parent: Object

Represents a collection of items in a SimpleDB domain.

Methods

Included Modules

Model Enumerable ConsistentReadOption

Constants

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?'", " ?"]]

Attributes

conditions  [R]  @private
domain  [R]  @return [Domain] The domain the items belong to.
sort_instructions  [R]  @private

Public Class methods

@param [Domain] domain The domain that you want an item collection for. @return [ItemCollection]

Public Instance methods

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.
size(options = {})

Alias for count

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| ... }

Hash Conditions

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')

Placeholders

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.

Protected Instance methods

turns e.g. each(:where => ‘foo’, …) into where(‘foo’).each(…) @private

[Validate]