Class: Mongoid::Criteria

Relationships & Source Files
Namespace Children
Modules: `Findable`, `Includable`, `Inspectable`, `Marshalable`, `Modifiable`, `Options`, `Permission`, `Queryable`, `Scopable`, `Translator`
Super Chains via Extension / Inclusion / Inheritance
Instance Chain: self, `Options`, `Clients::Sessions`, `Clients::Options`, `Scopable`, `Modifiable`, `Marshalable`, `Includable`, `Inspectable`, `Findable`, `Queryable`, `Criteria::Queryable::Optional`, `Selectable`, `Criteria::Queryable::Aggregable`, `Criteria::Queryable::Mergeable`, `Criteria::Queryable::Expandable`, `Criteria::Queryable::Storable`, `Contextual`, Enumerable
Inherits:	Object
Defined in:	lib/mongoid/criteria.rb, lib/mongoid/criteria/findable.rb, lib/mongoid/criteria/includable.rb, lib/mongoid/criteria/inspectable.rb, lib/mongoid/criteria/marshalable.rb, lib/mongoid/criteria/modifiable.rb, lib/mongoid/criteria/options.rb, lib/mongoid/criteria/permission.rb, lib/mongoid/criteria/queryable.rb, lib/mongoid/criteria/scopable.rb, lib/mongoid/criteria/translator.rb, lib/mongoid/criteria/queryable/aggregable.rb, lib/mongoid/criteria/queryable/expandable.rb, lib/mongoid/criteria/queryable/key.rb, lib/mongoid/criteria/queryable/macroable.rb, lib/mongoid/criteria/queryable/mergeable.rb, lib/mongoid/criteria/queryable/optional.rb, lib/mongoid/criteria/queryable/options.rb, lib/mongoid/criteria/queryable/pipeline.rb, lib/mongoid/criteria/queryable/selectable.rb, lib/mongoid/criteria/queryable/selector.rb, lib/mongoid/criteria/queryable/smash.rb, lib/mongoid/criteria/queryable/storable.rb, lib/mongoid/criteria/queryable/extensions/array.rb, lib/mongoid/criteria/queryable/extensions/big_decimal.rb, lib/mongoid/criteria/queryable/extensions/boolean.rb, lib/mongoid/criteria/queryable/extensions/date.rb, lib/mongoid/criteria/queryable/extensions/date_time.rb, lib/mongoid/criteria/queryable/extensions/hash.rb, lib/mongoid/criteria/queryable/extensions/nil_class.rb, lib/mongoid/criteria/queryable/extensions/numeric.rb, lib/mongoid/criteria/queryable/extensions/object.rb, lib/mongoid/criteria/queryable/extensions/range.rb, lib/mongoid/criteria/queryable/extensions/regexp.rb, lib/mongoid/criteria/queryable/extensions/set.rb, lib/mongoid/criteria/queryable/extensions/string.rb, lib/mongoid/criteria/queryable/extensions/symbol.rb, lib/mongoid/criteria/queryable/extensions/time.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.

Constant Summary

CHECK =

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

# File 'lib/mongoid/criteria.rb', line 66
```
[]
```

Class Method Summary

.from_hash(hash) ⇒ Criteria

Convert the given hash to a criteria.
.new(klass) ⇒ Criteria constructor

Initialize the new criteria.

Instance Attribute Summary

#association rw
#documents ⇒ Array<Document> rw

Get the documents from the embedded criteria.
#documents=(docs) ⇒ Array<Document> rw

::Set the embedded documents on the criteria.
#embedded rw
#embedded? ⇒ true | false rw

Is the criteria for embedded documents?
#empty_and_chainable? ⇒ true | false readonly

Is the criteria an empty but chainable criteria?
#klass rw
#parent_document rw
#type_selectable? ⇒ true | false readonly private Internal use only Internal use only

Is the criteria type selectable?

`Clients::Options` - Included

#persistence_context	Get the document’s current persistence context.
#persistence_context?	Returns whether a persistence context is set for the document or the document’s class.

`Scopable` - Included

#scoped?	Has the criteria had the default scope applied?
#scoping_options	Get the criteria scoping options, as a pair (scoped, unscoped).
#scoping_options=	`::Set` the criteria scoping options, as a pair (scoped, unscoped).
#unscoped	Clears all scoping from the criteria.
#unscoped?	Is the criteria unscoped?

`Modifiable` - Included

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

`Includable` - Included

#inclusions	Get a list of criteria that are to be executed for eager loading.
#inclusions=	`::Set` the inclusions for the criteria.

`Queryable` - Included

#aliases, #aliases The aliases., #serializers, #serializers The serializers.

`Criteria::Queryable::Optional` - Included

#options, #options The query options.

`Criteria::Queryable::Aggregable` - Included

#aggregating Flag for whether or not we are aggregating., #aggregating=,
#aggregating?	Has the aggregable enter an aggregation state.
#pipeline, #pipeline The aggregation pipeline.

`Criteria::Queryable::Mergeable` - Included

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

Instance Method Summary

#==(other) ⇒ true | false

Returns true if the supplied Enumerable or Criteria is equal to the results of this Criteria or the criteria itself.
#_enumerable_find Internal use only Internal use only
#_findable_find Internal use only Internal use only
#as_json(options = nil) ⇒ String

Needed to properly get a criteria back as json.
#extract_id ⇒ Object

Extract a single id from the provided criteria.
#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.
#field_list ⇒ Array<String>

Get the list of included fields.
#find(*args) {|Object| ... } ⇒ 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.
#for_js(javascript, scope = {}) ⇒ Criteria deprecated Deprecated.
#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.
#merge(other) ⇒ Criteria

Merges another object with this Criteria and returns a new criteria.
#merge!(other) ⇒ Criteria

Merge the other criteria into this one.
#none ⇒ Criteria

Returns a criteria that will always contain zero results and never hits the database.
#only(*args) ⇒ Criteria

Overriden to include _type in the fields.
#read(value = nil) ⇒ Criteria

::Set the read preference for the criteria.
#respond_to?(name, include_private = false) ⇒ true | false

Returns true if criteria responds to the given method.
#to_ary
#to_criteria ⇒ Criteria deprecated Deprecated.
#to_proc ⇒ Proc

Convert the criteria to a proc.
#type(types) ⇒ Criteria

Adds a criterion to the Criteria that specifies a type or an ::Array of types that must be matched.
#where(*args) ⇒ Criteria

This is the general entry point for most MongoDB queries.
#without(*args) ⇒ Criteria

Overriden to exclude _id from the fields.
#without_options ⇒ Criteria

Get a version of this criteria without the options.
#check_for_missing_documents!(result, ids) private Internal use only Internal use only

Are documents in the query missing, and are we configured to raise an error?
#initialize_copy(other) ⇒ nil private Internal use only Internal use only

Clone or dup the current Criteria.
#merge_type_selection ⇒ true | false private

For models where inheritance is at play we need to add the type selection.
#method_missing ⇒ Object private

Used for chaining Criteria scopes together in the for of class methods on the Document the criteria is for.
#selector_with_type_selection ⇒ Hash private Internal use only Internal use only

Get a new selector with type selection in it.
#type_selection ⇒ Hash private Internal use only Internal use only

Get the selector for type selection.

`Options` - Included

#clear_persistence_context, #persistence_context, #set_persistence_context

`Clients::Sessions` - Included

#ensure_client_compatibility!

If at least one session is active, this ensures that the current model’s client is compatible with one of them.

`Clients::Options` - Included

#collection	Get the collection for the document’s current persistence context.
#collection_name	Get the collection name for the document’s current persistence context.
#mongo_client	Get the database client for the document’s current persistence context.
#with	Change the persistence context for this object during the block.
#clear_persistence_context, #set_persistence_context

`Scopable` - Included

#apply_default_scope	Applies the default scope to the criteria.
#apply_scope	Applies a scope to the current criteria.
#remove_scoping	Given another criteria, remove the other criteria’s scoping from this criteria.
#scoped	Forces the criteria to be scoped, unless its inside an unscoped block.
#with_default_scope	Get the criteria with the default scope applied, if the default scope is able to be applied.
#reject_matching

`Modifiable` - Included

#build	Build a document given the selector and return it.
#create	Create a document in the database given the selector and return it.
#create!	Create a document in the database given the selector and return it.
#create_with	Define attributes with which new documents will be created.
#find_or_create_by	Find the first `Document` given the conditions, or creates a new document with the conditions that were supplied.
#find_or_create_by!	Find the first `Document` given the conditions, or creates a new document with the conditions that were supplied.
#find_or_initialize_by	Find the first `Document` given the conditions, or initializes a new document with the conditions that were supplied.
#first_or_create	Find the first `Document`, or creates a new document with the conditions that were supplied plus attributes.
#first_or_create!	Find the first `Document`, or creates a new document with the conditions that were supplied plus attributes and will raise an error if validation fails.
#first_or_initialize	Find the first `Document`, or initializes a new document with the conditions that were supplied plus attributes.
#new	Alias for Modifiable#build.
#create_document	Create a document given the provided method and attributes from the existing selector.
#find_or	Find the first object or create/initialize it.
#first_or	Find the first document or create/initialize it.
#invalid_embedded_doc?, #invalid_key?

`Marshalable` - Included

#marshal_dump	Provides the data needed to Marshal.dump a criteria.
#marshal_load	Resets the criteria object after a Marshal.load.
#dump_hash, #load_hash

`Includable` - Included

#includes	Eager loads all the provided associations.
#add_inclusion	Add an inclusion definition to the list of inclusions for the criteria.
#extract_includes_list	Iterate through the list of relations and create the inclusions list.

`Inspectable` - Included

#inspect

Get a pretty string representation of the criteria, including the selector, options, matching count and documents for inspection.

`Findable` - Included

#execute_or_raise	Execute the criteria or raise an error if no documents found.
#find	Find the matching document(s) in the criteria for the provided id(s).
#for_ids	Adds a criterion to the `Criteria` that specifies an id that must be matched.
#multiple_from_db	Get the documents from the identity map, and if not found hit the database.
#from_database	Get documents from the database only.
#from_database_selector,
#id_finder	Get the finder used to generate the id query.
#mongoize_ids	Convert all the ids to their proper types.
#multi_args?	Indicates whether the given arguments array is a list of values.
#prepare_ids_for_find	Convert args to the `#find` method into a flat array of ids.
#raise_invalid	Convenience method of raising an invalid options error.

`Queryable` - Included

#==	Is this queryable equal to another object? Is true if the selector and options are equal.
#initialize	Initialize the new queryable.
#initialize_copy	Handle the creation of a copy via #clone or #dup.

`Criteria::Queryable::Optional` - Included

#asc	Alias for Queryable::Optional#ascending.
#ascending	Add ascending sorting options for all the provided fields.
#batch_size	Adds the option for telling MongoDB how many documents to retrieve in it’s batching.
#collation	`::Set` the collation.
#comment	Associate a comment with the query.
#cursor_type	`::Set` the cursor type.
#desc	Alias for Queryable::Optional#descending.
#descending	Add descending sorting options for all the provided fields.
#hint	Add an index hint to the query options.
#limit	Add the number of documents to limit in the returned results.
#max_scan	Adds the option to limit the number of documents scanned in the collection.
#max_time_ms	Adds a cumulative time limit in milliseconds for processing operations on a cursor.
#no_timeout	Tell the query not to timeout.
#offset	Alias for Queryable::Optional#skip.
#only	Limits the results to only contain the fields provided.
#order	Alias for Queryable::Optional#order_by.
#order_by	Adds sorting criterion to the options.
#reorder	Instead of merging the order criteria, use this method to completely replace the existing ordering with the provided.
#skip	Add the number of documents to skip.
#slice	Limit the returned results via slicing embedded arrays.
#snapshot	Tell the query to operate in snapshot mode.
#without	Limits the results to only contain the fields not provided.
#add_sort_option	Add a single sort option.
#option	Take the provided criterion and store it as an option in the query options.
#sort_with_list	Add multiple sort options at once.

`Selectable` - Included

#atomic_selector	Get the atomic selector for the document.
#embedded_atomic_selector	Get the atomic selector for an embedded document.
#root_atomic_selector_in_db	Get the atomic selector that would match the existing version of the root document.

`Criteria::Queryable::Aggregable` - Included

#group	Add a group ($group) operation to the aggregation pipeline.
#project	Add a projection ($project) to the aggregation pipeline.
#unwind	Add an unwind ($unwind) to the aggregation pipeline.
#aggregation	Add the aggregation operation.

`Criteria::Queryable::Mergeable` - Included

#and_with_operator	Merge criteria with operators using the and operator.
#intersect	Instruct the next mergeable call to use intersection.
#override	Instruct the next mergeable call to use override.
#reset_strategies!	Clear the current strategy and negating flag, used after cloning.
#union	Instruct the next mergeable call to use union.
#__add__	Adds the criterion to the existing selection.
#__expanded__	Adds the criterion to the existing selection.
#__intersect__	Adds the criterion to the existing selection.
#__merge__	Perform a straight merge of the criterion into the selection and let the symbol overrides do all the work.
#__multi__	Adds $and/$or/$nor criteria to a copy of this selection.
#__override__	Adds the criterion to the existing selection.
#__union__	Adds the criterion to the existing selection.
#_mongoid_add_top_level_operation	Combines criteria into a MongoDB selector.
#_mongoid_expand_keys	Takes a criteria hash and expands Key objects into hashes containing MQL corresponding to said key objects.
#_mongoid_flatten_arrays	Calling .flatten on an array which includes a `Criteria` instance evaluates the criteria, which we do not want.
#prepare	Prepare the value for merging.
#use	Use the named strategy for the next operation.
#with_strategy	Add criterion to the selection with the named strategy.

`Criteria::Queryable::Expandable` - Included

#expand_condition_to_array_values	Expand criterion values to arrays, to be used with operators that take an array as argument such as $in.
#expand_one_condition	Expands the specified condition to MongoDB syntax.

`Criteria::Queryable::Storable` - Included

#add_field_expression	Adds a field expression to the query.
#add_logical_operator_expression	Adds a logical operator expression to the selector.
#add_one_expression	Adds an arbitrary expression to the query.
#add_operator_expression	Adds an operator expression to the selector.

`Contextual` - Included

#context	Get the context in which criteria queries should execute.
#load_async	Instructs the context to schedule an asynchronous loading of documents specified by the criteria.
#create_context	Create the context for the queries to execute.

Constructor Details

.new(klass) ⇒ `Criteria`

Initialize the new criteria.

Examples:

Init the new criteria.

Criteria.new(Band)

Parameters:

klass (Class) —

The model class.

[ GitHub ]

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


def initialize(klass)
  @klass = klass
  @embedded = nil
  @none = nil
  klass ? super(klass.aliased_fields, klass.fields, klass.relations, klass.aliased_associations) : 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 (Object...) —

The arguments.

Returns:

(Object) —

The result of the method call.

[ GitHub ]

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


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

Class Method Details

.from_hash(hash) ⇒ `Criteria`

Convert the given hash to a criteria. Will iterate over each keys in the hash which must correspond to method on a criteria object. The hash must also include a “klass” key.

Examples:

Convert the hash to a criteria.

Criteria.from_hash({ klass: Band, where: { name: "Depeche Mode" })

Parameters:

hash (Hash) —

The hash to convert.

Returns:

(Criteria) —

The criteria.

[ GitHub ]

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


def from_hash(hash)
  criteria = Criteria.new(hash.delete(:klass) || hash.delete('klass'))
  hash.each_pair do |method, args|
    criteria = criteria.__send__(method, args)
  end
  criteria
end

Instance Attribute Details

#association (rw)

[ GitHub ]

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


attr_accessor :embedded, :klass, :parent_document, :association

#documents ⇒ Array<Document> (rw)

Get the documents from the embedded criteria.

Examples:

Get the documents.

criteria.documents

Returns:

(Array<Document>) —

The documents.

[ GitHub ]

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


def documents
  @documents ||= []
end

#documents=(docs) ⇒ Array<Document> (rw)

::Set the embedded documents on the criteria.

Examples:

::Set the documents.

Parameters:

docs (Array<Document>) —

The embedded documents.

Returns:

(Array<Document>) —

The embedded documents.

[ GitHub ]

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


def documents=(docs)
  @documents = docs
end

#embedded (rw)

[ GitHub ]

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


attr_accessor :embedded, :klass, :parent_document, :association

#embedded? ⇒ `true` | `false` (rw)

Is the criteria for embedded documents?

Examples:

Is the criteria for embedded documents?

criteria.embedded?

Returns:

(true | false) —

If the criteria is embedded.

[ GitHub ]

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


def embedded?
  !!@embedded
end

#empty_and_chainable? ⇒ `true` | `false` (readonly)

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.

[ GitHub ]

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


def empty_and_chainable?
  !!@none
end

#klass (rw)

[ GitHub ]

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


attr_accessor :embedded, :klass, :parent_document, :association

#parent_document (rw)

[ GitHub ]

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


attr_accessor :embedded, :klass, :parent_document, :association

#type_selectable? ⇒ `true` | `false` (readonly, private)

This method is for internal use only.

Is the criteria type selectable?

Examples:

If the criteria type selectable?

criteria.type_selectable?

Returns:

(true | false) —

If type selection should be added.

[ GitHub ]

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


def type_selectable?
  klass.hereditary? &&
    !selector.keys.include?(self.discriminator_key) &&
    !selector.keys.include?(self.discriminator_key.to_sym)
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.

[ GitHub ]

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


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

#_enumerable_find

This method is for internal use only.

[ GitHub ]

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


alias :_enumerable_find :find

#_findable_find

This method is for internal use only.

[ GitHub ]

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


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) —

Criteria::Options to pass through to the serializer.

Returns:

(String) —

The JSON string.

[ GitHub ]

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


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

#check_for_missing_documents!(result, ids) (private)

This method is for internal use only.

Are documents in the query missing, and are we configured to raise an error?

Examples:

Check for missing documents.

criteria.check_for_missing_documents!([], [ 1 ])

Parameters:

result (Array<Document>) —

The result.
ids (Array<Object>) —

The ids.

Raises:

(Errors::DocumentNotFound) —

If none are found and raising an error.

[ GitHub ]

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


def check_for_missing_documents!(result, ids)
  if (result.size < ids.size) && Mongoid.raise_not_found_error
    raise Errors::DocumentNotFound.new(klass, ids, ids - result.map(&:_id))
  end
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.

[ GitHub ]

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


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

(Criteria) —

The cloned criteria.

[ GitHub ]

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


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.

[ GitHub ]

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


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

#find(*args) {|Object| ... } ⇒ Document | Array<Document> | `nil`

Note:

Each argument can be an individual id, an array of ids or a nested array. Each array will be flattened.

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" })

Parameters:

*args ([ Object | Array<Object> ]...) —

The id(s).
&block —

Optional block to pass.

Yields:

(Object) —

Yields each enumerable element to the block.

Returns:

(Document | Array<Document> | nil) —

A document or matching documents.

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.

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

Deprecated.

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:

(Criteria) —

The criteria.

[ GitHub ]

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


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:

(Criteria) —

The frozen criteria.

[ GitHub ]

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


def freeze
  context and inclusions and super
end

#initialize_copy(other) ⇒ `nil` (private)

This method is for internal use only.

Clone or dup the current Criteria. This will return a new criteria with the selector, options, klass, embedded options, etc intact.

Examples:

Clone a criteria.

criteria.clone

Dup a criteria.

criteria.dup

Parameters:

other (Criteria) —

The criteria getting cloned.

Returns:

(nil) —

nil.

[ GitHub ]

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


def initialize_copy(other)
  @inclusions = other.inclusions.dup
  @scoping_options = other.scoping_options
  @documents = other.documents.dup
  @context = nil
  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.

criteria.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:

(Criteria) —

A cloned self.

[ GitHub ]

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


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 | Hash) —

The criteria to merge in.

Returns:

(Criteria) —

The merged criteria.

[ GitHub ]

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


def merge!(other)
  other = self.class.from_hash(other) if other.is_a?(Hash)
  selector.merge!(other.selector)
  options.merge!(other.options)
  self.documents = other.documents.dup unless other.documents.empty?
  self.scoping_options = other.scoping_options
  self.inclusions = (inclusions + other.inclusions).uniq
  self
end

#merge_type_selection ⇒ `true` | `false` (private)

For models where inheritance is at play we need to add the type selection.

Examples:

Add the type selection.

criteria.merge_type_selection

Returns:

(true | false) —

If type selection was added.

[ GitHub ]

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


def merge_type_selection
  selector.merge!(type_selection) if type_selectable?
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:

(Criteria) —

The none criteria.

[ GitHub ]

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


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 ([ Symbol | Array<Symbol> ]...) —

The field name(s).

Returns:

(Criteria) —

The cloned criteria.

[ GitHub ]

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


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:

(Criteria) —

The cloned criteria.

[ GitHub ]

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


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.

[ GitHub ]

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


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

#selector_with_type_selection ⇒ Hash (private)

This method is for internal use only.

Get a new selector with type selection in it.

Examples:

Get a selector with type selection.

criteria.selector_with_type_selection

Returns:

(Hash) —

The selector.

[ GitHub ]

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


def selector_with_type_selection
  type_selectable? ? selector.merge(type_selection) : selector
end

#to_ary

[ GitHub ]

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


alias :to_ary :to_a

#to_criteria ⇒ `Criteria`

Deprecated.

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

Examples:

Convert to a criteria.

criteria.to_criteria

Returns:

(Criteria) —

self.

[ GitHub ]

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


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.

[ GitHub ]

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


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:

(Criteria) —

The cloned criteria.

[ GitHub ]

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


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

#type_selection ⇒ Hash (private)

This method is for internal use only.

Get the selector for type selection.

Examples:

Get a type selection hash.

criteria.type_selection

Returns:

(Hash) —

The type selection.

[ GitHub ]

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


def type_selection
  klasses = klass._types
  if klasses.size > 1
    { klass.discriminator_key.to_sym => { "$in" => klass._types }}
  else
    { klass.discriminator_key.to_sym => klass._types[0] }
  end
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:

*args ([ Hash | String ]...) —

The standard selection or javascript string.

Returns:

(Criteria) —

The cloned selectable.

Raises:

(UnsupportedJavascript) —

If provided a string and the criteria is embedded.

[ GitHub ]

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


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 (Symbol...) —

The field name(s).

Returns:

(Criteria) —

The cloned criteria.

[ GitHub ]

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


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:

(Criteria) —

The cloned criteria.

[ GitHub ]

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


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

Class: Mongoid::Criteria

Overview

Constant Summary

Class Method Summary

Instance Attribute Summary

Clients::Options - Included

Scopable - Included

Modifiable - Included

Includable - Included

Queryable - Included

Criteria::Queryable::Optional - Included

Criteria::Queryable::Aggregable - Included

Criteria::Queryable::Mergeable - Included

Instance Method Summary

Options - Included

Clients::Sessions - Included

Clients::Options - Included

Scopable - Included

Modifiable - Included

Marshalable - Included

Includable - Included

Inspectable - Included

Findable - Included

Queryable - Included

Criteria::Queryable::Optional - Included

Selectable - Included

Criteria::Queryable::Aggregable - Included

Criteria::Queryable::Mergeable - Included

Criteria::Queryable::Expandable - Included

Criteria::Queryable::Storable - Included

Contextual - Included

Constructor Details

.new(klass) ⇒ Criteria

Dynamic Method Handling

#method_missing ⇒ Object (private)

Class Method Details

.from_hash(hash) ⇒ Criteria

Instance Attribute Details

#association (rw)

#documents ⇒ Array<Document> (rw)

#documents=(docs) ⇒ Array<Document> (rw)

#embedded (rw)

#embedded? ⇒ true | false (rw)

#empty_and_chainable? ⇒ true | false (readonly)

#klass (rw)

#parent_document (rw)

#type_selectable? ⇒ true | false (readonly, private)

Instance Method Details

#==(other) ⇒ true | false

#_enumerable_find

#_findable_find

#as_json(options = nil) ⇒ String

#check_for_missing_documents!(result, ids) (private)

#extract_id ⇒ Object

#extras(extras) ⇒ Criteria

#field_list ⇒ Array<String>

#find(*args) {|Object| ... } ⇒ Document | Array<Document> | nil

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

#freeze ⇒ Criteria

#initialize_copy(other) ⇒ nil (private)

#merge(other) ⇒ Criteria

#merge!(other) ⇒ Criteria

#merge_type_selection ⇒ true | false (private)

#none ⇒ Criteria

#only(*args) ⇒ Criteria

#read(value = nil) ⇒ Criteria

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

#selector_with_type_selection ⇒ Hash (private)

#to_ary

#to_criteria ⇒ Criteria

#to_proc ⇒ Proc

#type(types) ⇒ Criteria

#type_selection ⇒ Hash (private)

#where(*args) ⇒ Criteria

#without(*args) ⇒ Criteria

#without_options ⇒ Criteria

`Clients::Options` - Included

`Scopable` - Included

`Modifiable` - Included

`Includable` - Included

`Queryable` - Included

`Criteria::Queryable::Optional` - Included

`Criteria::Queryable::Aggregable` - Included

`Criteria::Queryable::Mergeable` - Included

`Options` - Included

`Clients::Sessions` - Included

`Clients::Options` - Included

`Scopable` - Included

`Modifiable` - Included

`Marshalable` - Included

`Includable` - Included

`Inspectable` - Included

`Findable` - Included

`Queryable` - Included

`Criteria::Queryable::Optional` - Included

`Selectable` - Included

`Criteria::Queryable::Aggregable` - Included

`Criteria::Queryable::Mergeable` - Included

`Criteria::Queryable::Expandable` - Included

`Criteria::Queryable::Storable` - Included

`Contextual` - Included

.new(klass) ⇒ `Criteria`

#method_missing ⇒ `Object` (private)

.from_hash(hash) ⇒ `Criteria`

#embedded? ⇒ `true` | `false` (rw)

#empty_and_chainable? ⇒ `true` | `false` (readonly)

#type_selectable? ⇒ `true` | `false` (readonly, private)

#==(other) ⇒ `true` | `false`

#extract_id ⇒ `Object`

#extras(extras) ⇒ `Criteria`

#find(*args) {|Object| ... } ⇒ Document | Array<Document> | `nil`

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

#freeze ⇒ `Criteria`

#initialize_copy(other) ⇒ `nil` (private)

#merge(other) ⇒ `Criteria`

#merge!(other) ⇒ `Criteria`

#merge_type_selection ⇒ `true` | `false` (private)

#none ⇒ `Criteria`

#only(*args) ⇒ `Criteria`

#read(value = nil) ⇒ `Criteria`

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

#to_criteria ⇒ `Criteria`

#to_proc ⇒ `Proc`

#type(types) ⇒ `Criteria`

#where(*args) ⇒ `Criteria`

#without(*args) ⇒ `Criteria`

#without_options ⇒ `Criteria`