Class: Mongoid::Criteria

Inherits:
Object
  • Object
show all
Includes:
Enumerable, Mongoid::Clients::Options, Mongoid::Clients::Sessions, Contextual, Findable, Includable, Inspectable, Marshalable, Modifiable, Options, Queryable, Scopable
Defined in:
lib/mongoid/criteria.rb,
lib/mongoid/criteria/options.rb,
lib/mongoid/criteria/findable.rb,
lib/mongoid/criteria/scopable.rb,
lib/mongoid/criteria/queryable.rb,
lib/mongoid/criteria/includable.rb,
lib/mongoid/criteria/modifiable.rb,
lib/mongoid/criteria/permission.rb,
lib/mongoid/criteria/inspectable.rb,
lib/mongoid/criteria/marshalable.rb,
lib/mongoid/criteria/queryable/key.rb,
lib/mongoid/criteria/queryable/smash.rb,
lib/mongoid/criteria/queryable/options.rb,
lib/mongoid/criteria/queryable/optional.rb,
lib/mongoid/criteria/queryable/pipeline.rb,
lib/mongoid/criteria/queryable/selector.rb,
lib/mongoid/criteria/queryable/storable.rb,
lib/mongoid/criteria/queryable/macroable.rb,
lib/mongoid/criteria/queryable/mergeable.rb,
lib/mongoid/criteria/queryable/aggregable.rb,
lib/mongoid/criteria/queryable/expandable.rb,
lib/mongoid/criteria/queryable/selectable.rb,
lib/mongoid/criteria/queryable/extensions/set.rb,
lib/mongoid/criteria/queryable/extensions/date.rb,
lib/mongoid/criteria/queryable/extensions/hash.rb,
lib/mongoid/criteria/queryable/extensions/time.rb,
lib/mongoid/criteria/queryable/extensions/array.rb,
lib/mongoid/criteria/queryable/extensions/range.rb,
lib/mongoid/criteria/queryable/extensions/object.rb,
lib/mongoid/criteria/queryable/extensions/regexp.rb,
lib/mongoid/criteria/queryable/extensions/string.rb,
lib/mongoid/criteria/queryable/extensions/symbol.rb,
lib/mongoid/criteria/queryable/extensions/boolean.rb,
lib/mongoid/criteria/queryable/extensions/numeric.rb,
lib/mongoid/criteria/queryable/extensions/date_time.rb,
lib/mongoid/criteria/queryable/extensions/nil_class.rb,
lib/mongoid/criteria/queryable/extensions/big_decimal.rb,
lib/mongoid/criteria/queryable/extensions/time_with_zone.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.

Defined Under Namespace

Modules: Findable, Includable, Inspectable, Marshalable, Modifiable, Options, Permission, Queryable, Scopable

Constant Summary collapse

CHECK =

Static array used to check with method missing - we only need to ever instantiate once.

Since:

  • 4.0.0

[]

Instance Attribute Summary collapse

Attributes included from Modifiable

#create_attrs, #create_attrs Additional attributes to add to the Document upon creation.

Attributes included from Queryable

#aliases, #aliases The aliases., #driver, #driver The Mongo driver being used., #serializers, #serializers The serializers.

Attributes included from Queryable::Optional

#options, #options The query options.

Attributes included from Queryable::Aggregable

#aggregating, #aggregating Flag for whether or not we are aggregating., #pipeline, #pipeline The aggregation pipeline.

Attributes included from Queryable::Mergeable

#strategy, #strategy The name of the current strategy.

Instance Method Summary collapse

Methods included from Mongoid::Clients::Sessions

#with_session

Methods included from Mongoid::Clients::Options

#collection, #collection_name, #mongo_client, #persistence_context, #with

Methods included from Scopable

#apply_default_scope, #remove_scoping, #scoped, #scoped?, #scoping_options, #scoping_options=, #unscoped, #unscoped?, #with_default_scope

Methods included from Modifiable

#build, #create, #create!, #create_with, #find_or_create_by, #find_or_create_by!, #find_or_initialize_by, #first_or_create, #first_or_create!, #first_or_initialize

Methods included from Marshalable

#marshal_dump, #marshal_load

Methods included from Includable

#includes, #inclusions, #inclusions=

Methods included from Inspectable

#inspect

Methods included from Findable

#execute_or_raise, #for_ids, #multiple_from_db

Methods included from Queryable::Optional

#ascending, #batch_size, #collation, #comment, #cursor_type, #descending, forwardables, #hint, #limit, #max_scan, #max_time_ms, #no_timeout, #order_by, #reorder, #skip, #slice, #snapshot

Methods included from Queryable::Macroable

#key

Methods included from Selectable

#atomic_selector

Methods included from Queryable::Aggregable

#aggregating?, #group, #project, #unwind

Methods included from Queryable::Mergeable

#intersect, #override, #reset_strategies!, #union

Methods included from Queryable::Storable

#add_field_expression, #add_logical_operator_expression, #add_one_expression, #add_operator_expression

Methods included from Contextual

#context

Constructor Details

#initialize(klass) ⇒ Criteria

Initialize the new criteria.

Examples:

Init the new criteria.

Criteria.new(Band)

Parameters:

  • klass (Class) —

    The model class.

Since:

  • 1.0.0



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

def initialize(klass)
  @klass = klass
  @embedded = nil
  @none = nil
  klass ? super(klass.aliased_fields, klass.fields) : super({}, {})
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing ⇒ Object (private)

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

Examples:

Handle method missing.

criteria.method_missing(:name)

Parameters:

  • name (Symbol) —

    The method name.

  • args (Array) —

    The arguments.

Returns:

  • (Object) —

    The result of the method call.

Since:

  • 1.0.0



570
571
572
573
574
575
576
577
578
579
580
 
# File 'lib/mongoid/criteria.rb', line 570

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

Instance Attribute Details

#association ⇒ Object

Returns the value of attribute association.



49
50
51
 
# File 'lib/mongoid/criteria.rb', line 49

def association
  @association
end

#embedded ⇒ Object

Returns the value of attribute embedded.



49
50
51
 
# File 'lib/mongoid/criteria.rb', line 49

def embedded
  @embedded
end

#klass ⇒ Object

Returns the value of attribute klass.



49
50
51
 
# File 'lib/mongoid/criteria.rb', line 49

def klass
  @klass
end

#parent_document ⇒ Object

Returns the value of attribute parent_document.



49
50
51
 
# File 'lib/mongoid/criteria.rb', line 49

def parent_document
  @parent_document
end

Instance Method Details

#==(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.

Since:

  • 1.0.0



61
62
63
64
 
# File 'lib/mongoid/criteria.rb', line 61

def ==(other)
  return super if other.respond_to?(:selector)
  entries == other
end

#_enumerable_find ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



25
 
# File 'lib/mongoid/criteria.rb', line 25

alias :_enumerable_find :find

#_findable_find ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



32
 
# File 'lib/mongoid/criteria.rb', line 32

alias :_findable_find :find

#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.



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

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

#cache ⇒ Criteria

Tells the criteria that the cursor that gets returned needs to be cached. This is so multiple iterations don’t hit the database multiple times, however this is not advisable when working with large data sets as the entire results will get stored in memory.

Examples:

Flag the criteria as cached.

criteria.cache

Returns:



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

def cache
  crit = clone
  crit.options.merge!(cache: true)
  crit
end

#cached? ⇒ true, false

Will return true if the cache option has been set.

Examples:

Is the criteria cached?

criteria.cached?

Returns:

  • (true, false) —

    If the criteria is flagged as cached.



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

def cached?
  options[:cache] == true
end

#documents ⇒ Array<Document>

Get the documents from the embedded criteria.

Examples:

Get the documents.

criteria.documents

Returns:

Since:

  • 3.0.0



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

def documents
  @documents ||= []
end

#documents=(docs) ⇒ Array<Document>

Set the embedded documents on the criteria.

Examples:

Set the documents.

Parameters:

  • docs (Array<Document>) —

    The embedded documents.

Returns:

  • (Array<Document>) —

    The embedded documents.

Since:

  • 3.0.0



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

def documents=(docs)
  @documents = docs
end

#embedded? ⇒ true, false

Is the criteria for embedded documents?

Examples:

Is the criteria for embedded documents?

criteria.embedded?

Returns:

  • (true, false) —

    If the criteria is embedded.

Since:

  • 3.0.0



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

def embedded?
  !!@embedded
end

#empty_and_chainable? ⇒ true, false

Is the criteria an empty but chainable criteria?

Examples:

Is the criteria a none criteria?

criteria.empty_and_chainable?

Returns:

  • (true, false) —

    If the criteria is a none.

Since:

  • 4.0.0



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

def empty_and_chainable?
  !!@none
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:

  • (Object) —

    The id.

Since:

  • 2.3.0



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

def extract_id
  selector.extract_id
end

#extras(extras) ⇒ Criteria

Adds a criterion to the Criteria that specifies additional options to be passed to the Ruby driver, in the exact format for the driver.

criteria.extras(:limit => 20, :skip => 40)

Examples:

Add extra params to the criteria.

Parameters:

  • extras (Hash) —

    The extra driver options.

Returns:

Since:

  • 2.0.0



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

def extras(extras)
  crit = clone
  crit.options.merge!(extras)
  crit
end

#field_list ⇒ Array<String>

Get the list of included fields.

Examples:

Get the field list.

criteria.field_list

Returns:

  • (Array<String>) —

    The fields.

Since:

  • 2.0.0



220
221
222
223
224
225
226
 
# File 'lib/mongoid/criteria.rb', line 220

def field_list
  if options[:fields]
    options[:fields].keys.reject{ |key| key == klass.discriminator_key }
  else
    []
  end
end

#find(*args, &block) ⇒ Document | Array<Document> | nil

Finds one or many documents given the provided _id values, or filters the documents in the current scope in the application process space after loading them if needed.

If this method is not given a block, it delegates to Findable#find and finds one or many documents for the provided _id values.

If this method is given a block, it delegates to Enumerable#find and returns the first document of those found by the current Crieria object for which the block returns a truthy value.

Note that the “default proc” argument of Enumerable is not specially treated by Mongoid - the decision between delegating to Findable vs Enumerable is made solely based on whether find is passed a block.

Examples:

Finds a document by its _id, invokes Findable#find.

critera.find("1234")

Finds the first matching document using a block, invokes Enumerable#find.

criteria.find { |item| item.name == "Depeche Mode" }

Finds the first matching document using a block using the default Proc, invokes Enumerable#find.

criteria.find(-> { "Default Band" }) { |item| item.name == "Milwaukee Mode" }

Tries to find a document whose _id is the stringification of the provided Proc, typically failing.

enumerator = criteria.find(-> { "Default Band" })

Returns:

Raises:

  • Errors::DocumentNotFound If the parameters were _id values and not all documents are found and the raise_not_found_error Mongoid configuration option is truthy.

See Also:



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

def find(*args, &block)
  if block_given?
    _enumerable_find(*args, &block)
  else
    _findable_find(*args)
  end
end

#for_js(javascript, scope = {}) ⇒ Criteria

Find documents by the provided javascript and scope. Uses a $where but is different from Criteria#where in that it will pass a code object to the query instead of a pure string. Safe against Javascript injection attacks.

Examples:

Find by javascript.

Band.for_js("this.name = param", param: "Tool")

Parameters:

  • javascript (String) —

    The javascript to execute in the $where.

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

    The scope for the code.

Returns:

Since:

  • 3.1.0



501
502
503
504
505
506
507
508
509
 
# File 'lib/mongoid/criteria.rb', line 501

def for_js(javascript, scope = {})
  code = if scope.empty?
    # CodeWithScope is not supported for $where as of MongoDB 4.4
    BSON::Code.new(javascript)
  else
    BSON::CodeWithScope.new(javascript, scope)
  end
  js_query(code)
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



238
239
240
 
# File 'lib/mongoid/criteria.rb', line 238

def freeze
  context and inclusions and super
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 another criteria.

criteri.merge(other_criteria)

Merge the criteria with a hash. The hash must contain a klass

key and the key/value pairs correspond to method names/args.

criteria.merge({
  klass: Band,
  where: { name: "Depeche Mode" },
  order_by: { name: 1 }
})

Parameters:

  • other (Criteria) —

    The other criterion to merge with.

Returns:



277
278
279
280
281
 
# File 'lib/mongoid/criteria.rb', line 277

def merge(other)
  crit = clone
  crit.merge!(other)
  crit
end

#merge!(other) ⇒ Criteria

Merge the other criteria into this one.

Examples:

Merge another criteria into this criteria.

criteria.merge(Person.where(name: "bob"))

Parameters:

  • other (Criteria) —

    The criteria to merge in.

Returns:

Since:

  • 3.0.0



293
294
295
296
297
298
299
300
301
 
# File 'lib/mongoid/criteria.rb', line 293

def merge!(other)
  criteria = other.to_criteria
  selector.merge!(criteria.selector)
  options.merge!(criteria.options)
  self.documents = criteria.documents.dup unless criteria.documents.empty?
  self.scoping_options = criteria.scoping_options
  self.inclusions = (inclusions + criteria.inclusions).uniq
  self
end

#none ⇒ Criteria

Returns a criteria that will always contain zero results and never hits the database.

Examples:

Return a none criteria.

criteria.none

Returns:

Since:

  • 4.0.0



312
313
314
 
# File 'lib/mongoid/criteria.rb', line 312

def none
  @none = true and self
end

#only(*args) ⇒ Criteria

Overriden to include _type in the fields.

Examples:

Limit the fields returned from the database.

Band.only(:name)

Parameters:

  • args (Array<Symbol>) —

    The names of the fields.

Returns:

Since:

  • 1.0.0



338
339
340
341
342
343
344
345
346
347
348
 
# File 'lib/mongoid/criteria.rb', line 338

def only(*args)
  args = args.flatten
  return clone if args.empty?
  if (args & Fields::IDS).empty?
    args.unshift(:_id)
  end
  if klass.hereditary?
    args.push(klass.discriminator_key.to_sym)
  end
  super(*args)
end

#read(value = nil) ⇒ Criteria

Set the read preference for the criteria.

Examples:

Set the read preference.

criteria.read(mode: :primary_preferred)

Parameters:

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

    The mode preference.

Returns:

Since:

  • 5.0.0



360
361
362
363
364
 
# File 'lib/mongoid/criteria.rb', line 360

def read(value = nil)
  clone.tap do |criteria|
    criteria.options.merge!(read: value)
  end
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.



390
391
392
 
# File 'lib/mongoid/criteria.rb', line 390

def respond_to?(name, include_private = false)
  super || klass.respond_to?(name) || CHECK.respond_to?(name, include_private)
end

#to_criteria ⇒ Criteria

Convenience for objects that want to be merged into a criteria.

Examples:

Convert to a criteria.

criteria.to_criteria

Returns:

Since:

  • 3.0.0



404
405
406
 
# File 'lib/mongoid/criteria.rb', line 404

def to_criteria
  self
end

#to_proc ⇒ Proc

Convert the criteria to a proc.

Examples:

Convert the criteria to a proc.

criteria.to_proc

Returns:

  • (Proc) —

    The wrapped criteria.

Since:

  • 3.0.0



416
417
418
 
# File 'lib/mongoid/criteria.rb', line 416

def to_proc
  ->{ self }
end

#type(types) ⇒ Criteria

Adds a criterion to the Criteria that specifies a type or an Array of types that must be matched.

Examples:

Match only specific models.

criteria.type('Browser')
criteria.type(['Firefox', 'Browser'])

Parameters:

  • types (Array<String>) —

    The types to match against.

Returns:



430
431
432
 
# File 'lib/mongoid/criteria.rb', line 430

def type(types)
  any_in(self.discriminator_key.to_sym => Array(types))
end

#where(*args) ⇒ Criteria

This is the general entry point for most MongoDB queries. This either creates a standard field: value selection, and expanded selection with the use of hash methods, or a $where selection if a string is provided.

Examples:

Add a standard selection.

criteria.where(name: "syd")

Add a javascript selection.

criteria.where("this.name == 'syd'")

Parameters:

  • expression (String, Hash) —

    The javascript or standard selection.

Returns:

Raises:

  • (UnsupportedJavascript) —

    If provided a string and the criteria is embedded.

Since:

  • 1.0.0



452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
 
# File 'lib/mongoid/criteria.rb', line 452

def where(*args)
  # Historically this method required exactly one argument.
  # As of https://jira.mongodb.org/browse/MONGOID-4804 it also accepts
  # zero arguments.
  # The underlying where implemetation that super invokes supports
  # any number of arguments, but we don't presently allow mutiple
  # arguments through this method. This API can be reconsidered in the
  # future.
  if args.length > 1
    raise ArgumentError, "Criteria#where requires zero or one arguments (given #{args.length})"
  end
  if args.length == 1
    expression = args.first
    if expression.is_a?(::String) && embedded?
      raise Errors::UnsupportedJavascript.new(klass, expression)
    end
  end
  super
end

#without(*args) ⇒ Criteria

Overriden to exclude _id from the fields.

Examples:

Exclude fields returned from the database.

Band.without(:name)

Parameters:

  • args (Array<Symbol>) —

    The names of the fields.

Returns:

Since:

  • 4.0.3



376
377
378
379
 
# File 'lib/mongoid/criteria.rb', line 376

def without(*args)
  args -= id_fields
  super(*args)
end

#without_options ⇒ Criteria

Get a version of this criteria without the options.

Examples:

Get the criteria without options.

criteria.without_options

Returns:

Since:

  • 3.0.4



481
482
483
484
485
 
# File 'lib/mongoid/criteria.rb', line 481

def without_options
  crit = clone
  crit.options.clear
  crit
end