Class AWS::Record::Scope
In: lib/aws/record/scope.rb
Parent: Object

The primary interface for finding records with AWS::Record.

Getting a Scope Object

You should normally never need to construct a Scope object directly. Scope objects are returned from the AWS::Record::Base finder methods (e.g. find all, where, order, limit, etc).

  books = Book.where(:author => 'John Doe')
  books.class #=> AWS::Record::Scope, not Array

Scopes are also returned from methods defined with the scope method.

Delayed Execution

Scope objects represent a select expression, but do not actually cause a request to be made until enumerated.

  # no request made yet
  books = Book.where(:author => 'John Doe')

  # a request is made now
  books.each {|book| ... }

You can refine a scope object by calling other scope methods on it.

  # refine the previous books Scope, no request
  top_10 = books.order(:popularity, :desc).limit(10)

  # another request is made now
  top_10.first

Methods

count   each   find   limit   new   order   size   where  

Included Modules

Enumerable

Attributes

base_class  [R]  @return [Class] Returns the AWS::Record::Base extending class that
  this scope will find records for.

Public Class methods

@param [Record::Base] base_class A class that extends

  {AWS::Record::Base}.

@param [Hash] options @option options : @private

Public Instance methods

@return [Integer] Returns the number of records that match the

  current scoped finder.

Yields once for each record matching the request made by this scope.

  books = Book.where(:author => 'me').order(:price, :asc).limit(10)

  books.each do |book|
    puts book.attributes.to_yaml
  end

@yieldparam [Object] record

@overload find(id)

  Finds and returns a single record by id.  If no record is found
  with the given +id+, then a RecordNotFound error will be raised.
  @param [String] id ID of the record to find.
  @return [Record::Base] Returns the record.

@overload find(:first, options = {})

  Returns the first record found.  If no records were matched then
  nil will be returned (raises no exceptions).
  @param [Symbol] mode (:first)
  @return [Object,nil] Returns the first record or nil if no
    records matched the conditions.

@overload find(:all, options = {})

  Returns an enumerable Scope object that represents all matching
  records.  No request is made to AWS until the scope is enumerated.

    Book.find(:all, :limit => 100).each do |book|
      # ...
    end

  @param [Symbol] mode (:all)
  @return [Scope] Returns an enumerable scope object.

Limits the maximum number of total records to return when finding or counting. Returns a scope, does not make a request.

  books = Book.limit(100)

@param [Integer] limit The maximum number of records to return. @return [Scope] Returns a new scope that has the applied limit.

Specifies how to sort records returned.

  # enumerate books, starting with the most recently published ones
  Book.order(:published_at, :desc).each do |book|
    # ...
  end

Only one order may be applied. If order is specified more than once the last one in the chain takes precedence:

  # books returned by this scope will be ordered by :published_at
  # and not :author.
  Book.where(:read => false).order(:author).order(:published_at)

@param [String,Symbol] attribute_name The attribute to sort by. @param [:asc, :desc] order (:asc) The direct to sort.

size(options = {})

Alias for count

Applies conditions to the scope that limit which records are returned. Only those matching all given conditions will be returned.

@overload where(conditions_hash)

  Specify a hash of conditions to query with.  Multiple conditions
  are joined together with AND.

    Book.where(:author => 'John Doe', :softcover => true)
    # where `author` = `John Doe` AND `softcover` = `1`

  @param [Hash] conditions

@overload where(conditions_string, *values)

  A sql-like query fragment with optional placeholders and values.
  Placeholders are replaced with properly quoted values.

    Book.where('author = ?', 'John Doe')

  @param [String] conditions_string A sql-like where string with
    question mark placeholders.  For each placeholder there should
    be a value that will be quoted into that position.
  @param [String] *values A value that should be quoted into the
    corresponding (by position) placeholder.

@return [Scope] Returns a new scope with the passed conditions applied.

[Validate]