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.

Examples:

Create and execute a criteria.

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, #extras, #for_ids, #limit, #offset, #order_by, #skip, #type

Methods included from Mongoid::Criterion::Inspection

#inspect

Methods included from Mongoid::Criterion::Inclusion

#all, #all_of, #also_in, #and, #any_of, #execute_or_raise, #find, #from_map_or_db, #in, #includes, #inclusions, #load_ids, #near, #where

Methods included from Mongoid::Criterion::Exclusion

#excludes, #fields, #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.

Examples:

Instantiate a new criteria.

Criteria.new(Model, true)

Parameters:

  • klass (Class) —

    The model the criteria is for.

  • embedded (true, false) (defaults to: false) —

    Is the criteria for embedded docs.



205
206
207
208
 
# File 'lib/mongoid/criteria.rb', line 205

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, &block) ⇒ Object (protected)

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



376
377
378
379
380
381
382
383
384
 
# File 'lib/mongoid/criteria.rb', line 376

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

Instance Attribute Details

#documents ⇒ Object

Returns the value of attribute documents.



33
34
35
 
# File 'lib/mongoid/criteria.rb', line 33

def documents
  @documents
end

#embedded ⇒ Object

Returns the value of attribute embedded.



33
34
35
 
# File 'lib/mongoid/criteria.rb', line 33

def embedded
  @embedded
end

#field_list ⇒ Object

Returns the value of attribute field_list.



33
34
35
 
# File 'lib/mongoid/criteria.rb', line 33

def field_list
  @field_list
end

#ids ⇒ Object

Returns the value of attribute ids.



33
34
35
 
# File 'lib/mongoid/criteria.rb', line 33

def ids
  @ids
end

#klass ⇒ Object

Returns the value of attribute klass.



33
34
35
 
# File 'lib/mongoid/criteria.rb', line 33

def klass
  @klass
end

#options ⇒ Object

Returns the value of attribute options.



33
34
35
 
# File 'lib/mongoid/criteria.rb', line 33

def options
  @options
end

#selector ⇒ Object

Returns the value of attribute selector.



33
34
35
 
# File 'lib/mongoid/criteria.rb', line 33

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.

Examples:

Concat 2 criteria.

criteria + criteria

Parameters:

  • other (Criteria) —

    The other criteria.



76
77
78
 
# File 'lib/mongoid/criteria.rb', line 76

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.

Examples:

Get the difference of 2 criteria.

criteria - criteria

Parameters:

  • other (Criteria) —

    The other criteria.



87
88
89
 
# File 'lib/mongoid/criteria.rb', line 87

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

#==(other) ⇒ true, false

Note:

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

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

Parameters:

  • other (Object) —

    The other Enumerable or Criteria to compare to.

Returns:

  • (true, false) —

    If the objects are equal.



99
100
101
102
103
104
105
106
107
108
 
# File 'lib/mongoid/criteria.rb', line 99

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.



275
276
277
 
# File 'lib/mongoid/criteria.rb', line 275

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

#collection ⇒ Collection

Get the collection associated with the criteria.

Examples:

Get the collection.

criteria.collection

Returns:

Since:

  • 2.2.0



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

def collection
  klass.collection
end

#context ⇒ Mongo, Enumerable

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.

Examples:

Get the appropriate context.

criteria.context

Returns:

  • (Mongo, Enumerable) —

    The appropriate context.



131
132
133
 
# File 'lib/mongoid/criteria.rb', line 131

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

#each(&block) ⇒ Criteria

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

Examples:

Iterate over the criteria results.

criteria.each { |doc| p doc }

Returns:



142
143
144
 
# File 'lib/mongoid/criteria.rb', line 142

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

#exists? ⇒ true, false

Return true if the criteria has some Document or not.

Examples:

Are there any documents for the criteria?

criteria.exists?

Returns:

  • (true, false) —

    If documents match.



152
153
154
 
# File 'lib/mongoid/criteria.rb', line 152

def exists?
  context.count > 0
end

#extract_id ⇒ Object

Extract a single id from the provided criteria. Could be in an $and query or a straight _id query.

Examples:

Extract the id.

criteria.extract_id

Returns:

Since:

  • 2.3.0



165
166
167
 
# File 'lib/mongoid/criteria.rb', line 165

def extract_id
  selector[:_id]
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



179
180
181
 
# File 'lib/mongoid/criteria.rb', line 179

def freeze
  context and inclusions and super
end

#fuse(criteria_conditions = {}) ⇒ Criteria

Merges the supplied argument hash into a single criteria

Examples:

Fuse the criteria and the object.

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

Parameters:

  • criteria_conditions (Hash) (defaults to: {}) —

    Criteria keys and values.

Returns:



191
192
193
194
195
 
# File 'lib/mongoid/criteria.rb', line 191

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

#merge(other) ⇒ Criteria

Merges another object with this Criteria and returns a new 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.

Examples:

Merge the criteria with a conditions hash.

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

Merge the criteria with another criteria.

criteri.merge(other_criteria)

Parameters:

  • other (Criteria, Hash) —

    The other criterion to merge with.

Returns:



224
225
226
227
228
229
230
231
232
233
234
235
236
 
# File 'lib/mongoid/criteria.rb', line 224

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



324
325
326
 
# File 'lib/mongoid/criteria.rb', line 324

def raise_invalid
  raise Errors::InvalidFind.new
end

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

Returns true if criteria responds to the given method.

Examples:

Does the criteria respond to the method?

crtiteria.respond_to?(:each)

Parameters:

  • name (Symbol) —

    The name of the class method on the Document.

  • include_private (true, false) (defaults to: false) —

    Whether to include privates.

Returns:

  • (true, false) —

    If the criteria responds to the method.



247
248
249
250
 
# File 'lib/mongoid/criteria.rb', line 247

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 ⇒ Hash

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

Examples:

Get the criteria as a scoped hash.

criteria.scoped

Returns:

  • (Hash) —

    The criteria as a scoped hash.



259
260
261
262
263
264
 
# File 'lib/mongoid/criteria.rb', line 259

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



303
304
305
306
307
308
309
310
311
312
313
314
 
# File 'lib/mongoid/criteria.rb', line 303

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