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) 



258
259
260
261
 
# File 'lib/aws/record/scope.rb', line 258

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.



68
69
70
 
# File 'lib/aws/record/scope.rb', line 68

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.



135
136
137
138
139
140
141
 
# File 'lib/aws/record/scope.rb', line 135

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

#domain(name) ⇒ Scope

Returns a scope for restricting the domain of subsequent scope operations

Parameters:

  • domain (String)

Returns:

  • (Scope) —

    Returns a scope for restricting the domain of subsequent scope operations



92
93
94
 
# File 'lib/aws/record/scope.rb', line 92

def domain name
  _with(:domain => name)
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) 


223
224
225
226
227
228
229
 
# File 'lib/aws/record/scope.rb', line 223

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.



120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/aws/record/scope.rb', line 120

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).to_a.first
  else
    base_class.find_by_id(id_or_mode, :domain => scope._domain)
  end
  
end

#first(options = {}) ⇒ Record::Base?

Returns Gets the first record from the domain and returns it, or returns nil if the domain is empty.

Returns:

  • (Record::Base, nil) —

    Gets the first record from the domain and returns it, or returns nil if the domain is empty.



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

def first options = {}
  _handle_options(options).find(:first)
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.



210
211
212
 
# File 'lib/aws/record/scope.rb', line 210

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

#new(attributes = {}) ⇒ Object Also known as: build 



70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/aws/record/scope.rb', line 70

def new attributes = {}

  options = {}
  options.merge!(attributes)
  unless options.key?(:domain) or options.key?('domain')
    options[:domain] = _domain
  end

  @options[:where].each do |conditions|
    if conditions.size == 1 and conditions.first.is_a?(Hash)
      options.merge!(conditions.first)
    end
  end

  base_class.new(options)

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.



199
200
201
 
# File 'lib/aws/record/scope.rb', line 199

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.



175
176
177
178
179
180
 
# File 'lib/aws/record/scope.rb', line 175

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