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

ConsistentReadOption Core::Collection::WithLimitAndNextToken

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

@api private

Attributes

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

Public Class methods

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

Public Instance methods

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

_limit(*args)

Alias for limit

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:

@example

  domain.items.create('shirt', {
    'colors' => ['red', 'blue'],
    'category' => 'clearance'})

@overload create(item_name, attributes)

  @param [String] item_name The name of the item as you want it stored
    in SimpleDB.
  @param [Hash] attributes 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 default 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 expensive 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 attributes) 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 [Symbol, String, or Array] attributes The attributes to

  retrieve.  This can be:

  * `:all` or '*' to request all attributes for each item

  * A list or array of attribute names as strings 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.
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

Applies standard scope options (e.g. :where => ‘foo’) and removes them from the options hash by calling their method (e.g. by calling where(‘foo’)). Yields only if there were scope options to apply. @api private

@api private

@api private

@api private

[Validate]