Mongoid::Criteria

Initialize the new criteria.

@example Init the new criteria.

Criteria.new(Band)

@param [ Class ] klass The model class.

@since 1.0.0

# File lib/mongoid/criteria.rb, line 349
def initialize(klass)
  @klass = klass
  klass ? super(klass.aliased_fields, klass.fields) : super({}, {})
end

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

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

@param [ Object ] other The other Enumerable or Criteria to compare to.

@return [ true, false ] If the objects are equal.

@since 1.0.0

# File lib/mongoid/criteria.rb, line 33
def ==(other)
  return super if other.respond_to?(:selector)
  entries == other
end

Needed to properly get a criteria back as json

@example Get the criteria as json.

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

@param [ Hash ] options Options to pass through to the serializer.

@return [ String ] The JSON string.

# File lib/mongoid/criteria.rb, line 46
def as_json(options = nil)
  entries.as_json(options)
end

Build a document given the selector and return it. Complex criteria, such as $in and $or operations will get ignored.

@example build the document.

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

@example Build with selectors getting ignored.

Person.where(:age.gt => 5).build

@return [ Document ] A non-persisted document.

@since 2.0.0

# File lib/mongoid/criteria.rb, line 62
def build(attrs = {}, &block)
  create_document(:new, attrs, &block)
end

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.

@example Flag the criteria as cached.

criteria.cache

@return [ Criteria ] The cloned criteria.

# File lib/mongoid/criteria.rb, line 76
def cache
  crit = clone
  crit.options.merge!(cache: true)
  crit
end

Will return true if the cache option has been set.

@example Is the criteria cached?

criteria.cached?

@return [ true, false ] If the criteria is flagged as cached.

# File lib/mongoid/criteria.rb, line 88
def cached?
  options[:cache] == true
end

Create a document in the database given the selector and return it. Complex criteria, such as $in and $or operations will get ignored.

@example Create the document.

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

@example Create with selectors getting ignored.

Person.where(:age.gt => 5).create

@return [ Document ] A newly created document.

@since 2.0.0.rc.1

# File lib/mongoid/criteria.rb, line 104
def create(attrs = {}, &block)
  create_document(:create, attrs, &block)
end

Create a document in the database given the selector and return it. Complex criteria, such as $in and $or operations will get ignored. If validation fails, an error will be raised.

@example Create the document.

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

@example Create with selectors getting ignored.

Person.where(:age.gt => 5).create

@raise [ Errors::Validations ] on a validation error.

@return [ Document ] A newly created document.

@since 3.0.0

# File lib/mongoid/criteria.rb, line 123
def create!(attrs = {}, &block)
  create_document(:create!, attrs, &block)
end

Get the documents from the embedded criteria.

@example Get the documents.

criteria.documents

@return [ Array<Document> ] The documents.

@since 3.0.0

# File lib/mongoid/criteria.rb, line 135
def documents
  @documents ||= []
end

Set the embedded documents on the criteria.

@example Set the documents.

@param [ Array<Document> ] docs The embedded documents.

@return [ Array<Document> ] The embedded documents.

@since 3.0.0

# File lib/mongoid/criteria.rb, line 148
def documents=(docs)
  @documents = docs
end

Is the criteria for embedded documents?

@example Is the criteria for embedded documents?

criteria.embedded?

@return [ true, false ] If the criteria is embedded.

@since 3.0.0

# File lib/mongoid/criteria.rb, line 160
def embedded?
  !!@embedded
end

Execute the criteria or raise an error if no documents found.

@example Execute or raise

criteria.execute_or_raise(id)

@param [ Object ] args The arguments passed.

@raise [ Errors::DocumentNotFound ] If nothing returned.

@return [ Document, Array<Document> ] The document(s).

@since 2.0.0

# File lib/mongoid/criteria.rb, line 176
def execute_or_raise(ids, multi)
  result = multiple_from_map_or_db(ids)
  check_for_missing_documents!(result, ids)
  multi ? result : result.first
end

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

@example Extract the id.

criteria.extract_id

@return [ Object ] The id.

@since 2.3.0

# File lib/mongoid/criteria.rb, line 191
def extract_id
  selector.extract_id
end

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

@example Add extra params to the criteria. criteria.extras(:limit => 20, :skip => 40)

@param [ Hash ] extras The extra driver options.

@return [ Criteria ] The cloned criteria.

@since 2.0.0

# File lib/mongoid/criteria.rb, line 206
def extras(extras)
  crit = clone
  crit.options.merge!(extras)
  crit
end

Get the list of included fields.

@example Get the field list.

criteria.field_list

@return [ Array<String> ] The fields.

@since 2.0.0

# File lib/mongoid/criteria.rb, line 220
def field_list
  if options[:fields]
    options[:fields].keys.reject{ |key| key == "_type" }
  else
    []
  end
end

Find the matchind document(s) in the criteria for the provided ids.

@example Find by an id.

criteria.find(Moped::BSON::ObjectId.new)

@example Find by multiple ids.

criteria.find([ Moped::BSON::ObjectId.new, Moped::BSON::ObjectId.new ])

@param [ Array<Moped::BSON::ObjectId> ] args The ids to search for.

@return [ Array<Document>, Document ] The matching document(s).

@since 1.0.0

# File lib/mongoid/criteria.rb, line 241
def find(*args)
  ids = args.__find_args__
  raise_invalid if ids.any?(&:nil?)
  for_ids(ids).execute_or_raise(ids, args.multi_arged?)
end

Find the first Document given the conditions, or creates a new document with the conditions that were supplied.

@example Find or create the document.

Person.find_or_create_by(:attribute => "value")

@param [ Hash ] attrs The attributes to check.

@return [ Document ] A matching or newly created document.

# File lib/mongoid/criteria.rb, line 256
def find_or_create_by(attrs = {}, &block)
  find_or(:create, attrs, &block)
end

Find the first Document given the conditions, or initializes a new document with the conditions that were supplied.

@example Find or initialize the document.

Person.find_or_initialize_by(:attribute => "value")

@param [ Hash ] attrs The attributes to check.

@return [ Document ] A matching or newly initialized document.

# File lib/mongoid/criteria.rb, line 269
def find_or_initialize_by(attrs = {}, &block)
  find_or(:new, attrs, &block)
end

Adds a criterion to the Criteria that specifies an id that must be matched.

@example Add a single id criteria.

criteria.for_ids([ 1 ])

@example Add multiple id criteria.

criteria.for_ids([ 1, 2 ])

@param [ Array ] ids The array of ids.

@return [ Criteria ] The cloned criteria.

# File lib/mongoid/criteria.rb, line 284
def for_ids(ids)
  ids = mongoize_ids(ids)
  method = extract_id ? :all_of : :where
  if ids.size > 1
    send(method, { _id: { "$in" => ids }})
  else
    send(method, { _id: ids.first })
  end
end

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.

@example Freeze the criteria.

criteria.freeze

@return [ Criteria ] The frozen criteria.

@since 2.0.0

# File lib/mongoid/criteria.rb, line 304
def freeze
  context and inclusions and super
end

Get the document from the identity map, and if not found hit the database.

@example Get the document from the map or criteria.

criteria.from_map_or_db

@return [ Document ] The found document.

@since 2.2.1

# File lib/mongoid/criteria.rb, line 317
def from_map_or_db
  id = extract_id
  id = klass.fields["_id"].mongoize(id) if id
  doc = IdentityMap.get(klass, id || selector.except("_type"))
  return nil if doc == {}
  doc && doc.matches?(selector) ? doc : first
end

Eager loads all the provided relations. Will load all the documents into the identity map who's ids match based on the extra query for the ids.

@note This will only work if Mongoid's identity map is enabled. To do

so set identity_map_enabled: true in your mongoid.yml

@note This will work for embedded relations that reference another

collection via belongs_to as well.

@note Eager loading brings all the documents into memory, so there is a

sweet spot on the performance gains. Internal benchmarks show that
eager loading becomes slower around 100k documents, but this will
naturally depend on the specific application.

@example Eager load the provided relations.

Person.includes(:posts, :game)

@param [ Array<Symbol> ] relations The names of the relations to eager

load.

@return [ Criteria ] The cloned criteria.

@since 2.2.0

# File lib/mongoid/criteria.rb, line 378
def includes(*relations)
  relations.flatten.each do |name|
    metadata = klass.reflect_on_association(name)
    raise Errors::InvalidIncludes.new(klass, relations) unless metadata
    inclusions.push(metadata) unless inclusions.include?(metadata)
  end
  clone
end

Get a list of criteria that are to be executed for eager loading.

@example Get the eager loading inclusions.

Person.includes(:game).inclusions

@return [ Array<Metadata> ] The inclusions.

@since 2.2.0

# File lib/mongoid/criteria.rb, line 395
def inclusions
  @inclusions ||= []
end

Set the inclusions for the criteria.

@example Set the inclusions.

criteria.inclusions = [ meta ]

@param [ Array<Metadata> ] The inclusions.

@return [ Array<Metadata> ] The new inclusions.

@since 3.0.0

# File lib/mongoid/criteria.rb, line 409
def inclusions=(value)
  @inclusions = value
end

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

@param [ Criteria ] other The other criterion to merge with.

@return [ Criteria ] A cloned self.

# File lib/mongoid/criteria.rb, line 433
def merge(other)
  crit = clone
  crit.merge!(other)
  crit
end

Merge the other criteria into this one.

@example Merge another criteria into this criteria.

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

@param [ Criteria ] other The criteria to merge in.

@return [ Criteria ] The merged criteria.

@since 3.0.0

# File lib/mongoid/criteria.rb, line 449
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.dup).uniq
  self
end

Get the documents from the identity map, and if not found hit the database.

@example Get the documents from the map or criteria.

criteria.multiple_from_map_or_db(ids)

@param [ ids ] The searched ids.

@return [ Array<Document> ] The found documents.

# File lib/mongoid/criteria.rb, line 334
def multiple_from_map_or_db(ids)
  return entries if embedded?
  ids = mongoize_ids(ids)
  result = from_identity_map(ids)
  ids.empty? ? result : result + from_database(ids)
end

Overriden to include _type in the fields.

@example Limit the fields returned from the database.

Band.only(:name)

@param [ Array<Symbol> ] args The names of the fields.

@return [ Criteria ] The cloned criteria.

@since 1.0.0

# File lib/mongoid/criteria.rb, line 469
def only(*args)
  return clone if args.empty?
  args = args.flatten
  if klass.hereditary?
    super(*args.push(:_type))
  else
    super(*args)
  end
end

Returns true if criteria responds to the given method.

@example Does the criteria respond to the method?

crtiteria.respond_to?(:each)

@param [ Symbol ] name The name of the class method on the Document. @param [ true, false ] include_private Whether to include privates.

@return [ true, false ] If the criteria responds to the method.

# File lib/mongoid/criteria.rb, line 488
def respond_to?(name, include_private = false)
  super || klass.respond_to?(name) || entries.respond_to?(name, include_private)
end

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

@example Convert to a criteria.

criteria.to_criteria

@return [ Criteria ] self.

@since 3.0.0

# File lib/mongoid/criteria.rb, line 502
def to_criteria
  self
end

Convert the criteria to a proc.

@example Convert the criteria to a proc.

criteria.to_proc

@return [ Proc ] The wrapped criteria.

@since 3.0.0

# File lib/mongoid/criteria.rb, line 514
def to_proc
  ->{ self }
end

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

@example Match only specific models.

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

@param [ Array<String> ] types The types to match against.

@return [ Criteria ] The cloned criteria.

# File lib/mongoid/criteria.rb, line 528
def type(types)
  any_in(_type: Array(types))
end

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.

@example Add a standard selection.

criteria.where(name: "syd")

@example Add a javascript selection.

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

@param [ String, Hash ] criterion The javascript or standard selection.

@raise [ UnsupportedJavascript ] If provided a string and the criteria

is embedded.

@return [ Criteria ] The cloned selectable.

@since 1.0.0

# File lib/mongoid/criteria.rb, line 550
def where(expression)
  if expression.is_a?(::String) && embedded?
    raise Errors::UnsupportedJavascript.new(klass, expression)
  end
  super
end

Tell the next persistance operation to query from a specific collection, database or session.

@example Send the criteria to another collection.

Band.where(name: "Depeche Mode").with(collection: "artists")

@param [ Hash ] options The storage options.

@option options [ String, Symbol ] :collection The collection name. @option options [ String, Symbol ] :database The database name. @option options [ String, Symbol ] :session The session name.

@return [ Criteria ] The criteria.

@since 3.0.0

# File lib/mongoid/criteria.rb, line 572
def with(options)
  Threaded.set_persistence_options(klass, options)
  self
end

Get a version of this criteria without the options.

@example Get the criteria without options.

criteria.without_options

@return [ Criteria ] The cloned criteria.

@since 3.0.4

# File lib/mongoid/criteria.rb, line 585
def without_options
  crit = clone
  crit.options.clear
  crit
end