Class: AWS::Record::Scope

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/aws/record/scope.rb

Overview

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

Instance Attribute Summary collapse

Instance Method Summary collapse

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(scope_name, *args) ⇒ Object (private) 



230
231
232
233
 
# File 'lib/aws/record/scope.rb', line 230

def method_missing scope_name, *args
  # @todo only proxy named scope methods
  _merge_scope(base_class.send(scope_name, *args))
end

Instance Attribute Details

#base_class ⇒ Class (readonly)

Returns the AWS::Record::Base extending class that this scope will find records for.

Returns:

  • (Class) —

    Returns the AWS::Record::Base extending class that this scope will find records for.



66
67
68
 
# File 'lib/aws/record/scope.rb', line 66

def base_class
  @base_class
end

Instance Method Details

#count(options = {}) ⇒ Integer Also known as: size

Returns the number of records that match the current scoped finder.

Returns:

  • (Integer) —

    Returns the number of records that match the current scoped finder.



112
113
114
115
116
117
118
 
# File 'lib/aws/record/scope.rb', line 112

def count options = {}
  if scope = _handle_options(options) and scope != self
    scope.count
  else
    _item_collection.count
  end
end

#each {|record| ... } ⇒ Object

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

Yield Parameters:

  • record (Object) 


194
195
196
197
198
199
200
 
# File 'lib/aws/record/scope.rb', line 194

def each &block
  if block_given?
    _each_object(&block)
  else
    Enumerator.new(self, :"_each_object")
  end
end

#find(id) ⇒ Record::Base #find(: first, options = {}) ⇒ Object? #find(: all, options = {}) ⇒ Scope

Overloads:

  • #find(id) ⇒ Record::Base

    Finds and returns a single record by id. If no record is found with the given id, then a RecordNotFound error will be raised.

    Parameters:

    • id (String) —

      ID of the record to find.

    Returns:

  • #find(: first, options = {}) ⇒ Object?

    Returns the first record found. If no records were matched then nil will be returned (raises no exceptions).

    Parameters:

    • mode (Symbol) —

      (:first)

    Returns:

    • (Object, nil) —

      Returns the first record or nil if no records matched the conditions.

  • #find(: all, options = {}) ⇒ Scope

    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

    Parameters:

    • mode (Symbol) —

      (:all)

    Returns:

    • (Scope) —

      Returns an enumerable scope object.



92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/aws/record/scope.rb', line 92

def find id_or_mode, options = {}

  scope = _handle_options(options)

  case
  when id_or_mode == :all   then scope
  when id_or_mode == :first then scope.limit(1).first
  when scope.send(:_empty?) then base_class[id_or_mode]
  else
    object = scope.where('itemName() = ?', id_or_mode).limit(1).first
    if object.nil?
      raise RecordNotFound, "no data found for record `#{id_or_mode}`"
    end
    object
  end
  
end

#limit(limit) ⇒ Scope

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)

Parameters:

  • limit (Integer) —

    The maximum number of records to return.

Returns:

  • (Scope) —

    Returns a new scope that has the applied limit.



181
182
183
 
# File 'lib/aws/record/scope.rb', line 181

def limit limit
  _with(:limit => limit)
end

#order(attribute_name, order = :asc) ⇒ Object

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)

Parameters:

  • attribute_name (String, Symbol) —

    The attribute to sort by.

  • order (:asc, :desc) (defaults to: :asc) —

    (:asc) The direct to sort.



170
171
172
 
# File 'lib/aws/record/scope.rb', line 170

def order attribute_name, order = :asc
  _with(:order => [attribute_name, order])
end

#where(conditions_hash) ⇒ Scope #where(conditions_string, *values) ⇒ Scope

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

Overloads:

  • #where(conditions_hash) ⇒ Scope

    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`

    Parameters:

    • conditions (Hash)
  • #where(conditions_string, *values) ⇒ Scope

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

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

    Parameters:

    • conditions_string (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.

    • *values (String) —

      A value that should be quoted into the corresponding (by position) placeholder.

Returns:

  • (Scope) —

    Returns a new scope with the passed conditions applied.



146
147
148
149
150
151
 
# File 'lib/aws/record/scope.rb', line 146

def where *conditions
  if conditions.empty?
    raise ArgumentError, 'missing required condition'
  end
  _with(:where => Record.as_array(@options[:where]) + [conditions])
end