Class: Mongoid::Criteria

Inherits:
Object show all
Includes:
Enumerable, Mongoid::Criterion::Builder, Mongoid::Criterion::Creational, Mongoid::Criterion::Exclusion, Mongoid::Criterion::Inclusion, Mongoid::Criterion::Inspection, Mongoid::Criterion::Optional
Defined in:
lib/mongoid/criteria.rb

Overview

The Criteria class is the core object needed in Mongoid to retrieve objects from the database. It is a DSL that essentially sets up the selector and options arguments that get passed on to a Mongo::Collection in the Ruby driver. Each method on the Criteria returns self to they can be chained in order to create a readable criterion to be executed against the database.

Example setup:

criteria = Criteria.new

criteria.only(:field).where(:field => "value").skip(20).limit(20)

criteria.execute

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Mongoid::Criterion::Optional

#ascending, #cache, #cached?, #descending, #enslave, #enslaved?, #extras, #for_ids, #limit, #offset, #order_by, #skip, #type

Methods included from Mongoid::Criterion::Inspection

#inspect

Methods included from Mongoid::Criterion::Inclusion

#all, #also_in, #and, #any_of, #find, #in, #near, #where

Methods included from Mongoid::Criterion::Exclusion

#excludes, #not_in, #only, #without

Methods included from Mongoid::Criterion::Creational

#create

Methods included from Mongoid::Criterion::Builder

#build

Constructor Details

#initialize(klass, embedded = false) ⇒ Criteria

Create the new Criteria object. This will initialize the selector and options hashes, as well as the type of criteria.

Options:

type: One of :all, :first:, or :last klass: The class to execute on.



168
169
170
171
 
# File 'lib/mongoid/criteria.rb', line 168

def initialize(klass, embedded = false)
  @selector = Criterion::Selector.new(klass)
  @options, @klass, @documents, @embedded = {}, klass, [], embedded
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(name, *args) ⇒ Object

Used for chaining Criteria scopes together in the for of class methods on the Document the criteria is for.

Options:

name: The name of the class method on the Document to chain. args: The arguments passed to the method.

Returns: Criteria



207
208
209
210
211
212
213
214
215
 
# File 'lib/mongoid/criteria.rb', line 207

def method_missing(name, *args)
  if @klass.respond_to?(name)
    @klass.send(:with_scope, self) do
      @klass.send(name, *args)
    end
  else
    return entries.send(name, *args)
  end
end

Instance Attribute Details

#collection ⇒ Object

Returns the value of attribute collection.



36
37
38
 
# File 'lib/mongoid/criteria.rb', line 36

def collection
  @collection
end

#documents ⇒ Object

Returns the value of attribute documents.



36
37
38
 
# File 'lib/mongoid/criteria.rb', line 36

def documents
  @documents
end

#embedded ⇒ Object

Returns the value of attribute embedded.



36
37
38
 
# File 'lib/mongoid/criteria.rb', line 36

def embedded
  @embedded
end

#field_list ⇒ Object

Returns the value of attribute field_list.



36
37
38
 
# File 'lib/mongoid/criteria.rb', line 36

def field_list
  @field_list
end

#ids ⇒ Object

Returns the value of attribute ids.



36
37
38
 
# File 'lib/mongoid/criteria.rb', line 36

def ids
  @ids
end

#klass ⇒ Object

Returns the value of attribute klass.



36
37
38
 
# File 'lib/mongoid/criteria.rb', line 36

def klass
  @klass
end

#options ⇒ Object

Returns the value of attribute options.



36
37
38
 
# File 'lib/mongoid/criteria.rb', line 36

def options
  @options
end

#selector ⇒ Object

Returns the value of attribute selector.



36
37
38
 
# File 'lib/mongoid/criteria.rb', line 36

def selector
  @selector
end

Instance Method Details

#+(other) ⇒ Object

Concatinate the criteria with another enumerable. If the other is a Criteria then it needs to get the collection from it.



74
75
76
 
# File 'lib/mongoid/criteria.rb', line 74

def +(other)
  entries + comparable(other)
end

#-(other) ⇒ Object

Returns the difference between the criteria and another enumerable. If the other is a Criteria then it needs to get the collection from it.



80
81
82
 
# File 'lib/mongoid/criteria.rb', line 80

def -(other)
  entries - comparable(other)
end

#==(other) ⇒ Object

Returns true if the supplied Enumerable or Criteria is equal to the results of this Criteria or the criteria itself.

This will force a database load when called if an enumerable is passed.

Options:

other: The other Enumerable or Criteria to compare to.



92
93
94
95
96
97
98
99
100
101
 
# File 'lib/mongoid/criteria.rb', line 92

def ==(other)
  case other
  when Criteria
    self.selector == other.selector && self.options == other.options
  when Enumerable
    return (execute.entries == other)
  else
    return false
  end
end

#as_json(options = nil) ⇒ String

Needed to properly get a criteria back as json

Examples:

Get the criteria as json.

Person.where(:title => "Sir").as_json

Parameters:

  • options (Hash) (defaults to: nil) —

    Options to pass through to the serializer.

Returns:

  • (String) —

    The JSON string.



250
251
252
 
# File 'lib/mongoid/criteria.rb', line 250

def as_json(options = nil)
  entries.as_json(options)
end

#context ⇒ Object

Return or create the context in which this criteria should be executed.

This will return an Enumerable context if the class is embedded, otherwise it will return a Mongo context for root classes.



107
108
109
 
# File 'lib/mongoid/criteria.rb', line 107

def context
  @context ||= Contexts.context_for(self, embedded)
end

#each(&block) ⇒ Object

Iterate over each Document in the results. This can take an optional block to pass to each argument in the results.

Example:

criteria.each { |doc| p doc }



117
118
119
 
# File 'lib/mongoid/criteria.rb', line 117

def each(&block)
  tap { context.iterate(&block) }
end

#exists? ⇒ Boolean

Return true if the criteria has some Document or not

Example:

criteria.exists?

Returns:



126
127
128
 
# File 'lib/mongoid/criteria.rb', line 126

def exists?
  context.count > 0
end

#freeze ⇒ Criteria

When freezing a criteria we need to initialize the context first otherwise the setting of the context on attempted iteration will raise a runtime error.

Examples:

Freeze the criteria.

criteria.freeze

Returns:

Since:

  • 2.0.0



140
141
142
 
# File 'lib/mongoid/criteria.rb', line 140

def freeze
  context and super
end

#fuse(criteria_conditions = {}) ⇒ Object

Merges the supplied argument hash into a single criteria

Options:

criteria_conditions: Hash of criteria keys, and parameter values

Example:

criteria.fuse(:where => { :field => "value"}, :limit => 20)

Returns self



155
156
157
158
159
 
# File 'lib/mongoid/criteria.rb', line 155

def fuse(criteria_conditions = {})
  criteria_conditions.inject(self) do |criteria, (key, value)|
    criteria.send(key, value)
  end
end

#merge(other) ⇒ Object

Merges another object into this Criteria. The other object may be a Criteria or a Hash. This is used to combine multiple scopes together, where a chained scope situation may be desired.

Options:

other: The Criteria or Hash to merge with.

Example:

criteria.merge({ :conditions => { :title => "Sir" } })



184
185
186
187
188
189
190
191
192
193
194
195
196
 
# File 'lib/mongoid/criteria.rb', line 184

def merge(other)
  clone.tap do |crit|
    if other.is_a?(Criteria)
      crit.selector.update(other.selector)
      crit.options.update(other.options)
      crit.documents = other.documents
    else
      duped = other.dup
      crit.selector.update(duped.delete(:conditions) || {})
      crit.options.update(duped)
    end
  end
end

#raise_invalid ⇒ Object

Convenience method of raising an invalid options error.

Examples:

Raise the error.

criteria.raise_invalid

Raises:

Since:

  • 2.0.0



299
300
301
 
# File 'lib/mongoid/criteria.rb', line 299

def raise_invalid
  raise Errors::InvalidOptions.new(:calling_document_find_with_nil_is_invalid, {})
end

#respond_to?(name, include_private = false) ⇒ Boolean

Returns true if criteria responds to the given method.

Options:

name: The name of the class method on the Document. include_private: The arguments passed to the method.

Example:

criteria.respond_to?(:batch_update)

Returns:



227
228
229
230
 
# File 'lib/mongoid/criteria.rb', line 227

def respond_to?(name, include_private = false)
  # don't include klass private methods because method_missing won't call them
  super || @klass.respond_to?(name) || entries.respond_to?(name, include_private)
end

#scoped ⇒ Object

Returns the selector and options as a Hash that would be passed to a scope for use with named scopes.



234
235
236
237
238
239
 
# File 'lib/mongoid/criteria.rb', line 234

def scoped
  scope_options = @options.dup
  sorting = scope_options.delete(:sort)
  scope_options[:order_by] = sorting if sorting
  { :where => @selector }.merge(scope_options)
end

#search(*args) ⇒ Array<Symbol, Criteria>

Search for documents based on a variety of args.

Examples:

Find by an id.

criteria.search(BSON::ObjectId.new)

Find by multiple ids.

criteria.search([ BSON::ObjectId.new, BSON::ObjectId.new ])

Conditionally find all matching documents.

criteria.search(:all, :conditions => { :title => "Sir" })

Conditionally find the first document.

criteria.search(:first, :conditions => { :title => "Sir" })

Conditionally find the last document.

criteria.search(:last, :conditions => { :title => "Sir" })

Parameters:

Returns:

Since:

  • 2.0.0



278
279
280
281
282
283
284
285
286
287
288
289
 
# File 'lib/mongoid/criteria.rb', line 278

def search(*args)
  raise_invalid if args[0].nil?
  type = args[0]
  params = args[1] || {}
  return [ :ids, for_ids(type) ] unless type.is_a?(Symbol)
  conditions = params.delete(:conditions) || {}
  if conditions.include?(:id)
    conditions[:_id] = conditions[:id]
    conditions.delete(:id)
  end
  return [ type, where(conditions).extras(params) ]
end