mongoid 2.4.10 → 3.0.0

data/lib/mongoid/criteria.rb

@@ -1,15 +1,8 @@
 # encoding: utf-8
-require "mongoid/criterion/builder"
-require "mongoid/criterion/creational"
-require "mongoid/criterion/complex"
-require "mongoid/criterion/exclusion"
-require "mongoid/criterion/inclusion"
 require "mongoid/criterion/inspection"
-require "mongoid/criterion/optional"
 require "mongoid/criterion/scoping"
-require "mongoid/criterion/selector"
 
-module Mongoid #:nodoc:
+module Mongoid
 
   # 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
@@ -17,78 +10,14 @@ module Mongoid #:nodoc:
   # 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 Create and execute a criteria.
-  #   criteria = Criteria.new
-  #   criteria.only(:field).where(:field => "value").skip(20).limit(20)
-  #   criteria.execute
   class Criteria
     include Enumerable
-    include Criterion::Builder
-    include Criterion::Creational
-    include Criterion::Exclusion
-    include Criterion::Inclusion
+    include Contextual
+    include Origin::Queryable
     include Criterion::Inspection
-    include Criterion::Optional
     include Criterion::Scoping
 
-    attr_accessor \
-      :documents,
-      :embedded,
-      :ids,
-      :klass,
-      :options,
-      :selector,
-      :field_list
-
-    delegate \
-      :add_to_set,
-      :aggregate,
-      :avg,
-      :blank?,
-      :count,
-      :size,
-      :length,
-      :delete,
-      :delete_all,
-      :destroy,
-      :destroy_all,
-      :distinct,
-      :empty?,
-      :execute,
-      :first,
-      :group,
-      :last,
-      :max,
-      :min,
-      :one,
-      :pull,
-      :shift,
-      :sum,
-      :update,
-      :update_all, :to => :context
-
-    # Concatinate the criteria with another enumerable. If the other is a
-    # +Criteria+ then it needs to get the collection from it.
-    #
-    # @example Concat 2 criteria.
-    #   criteria + criteria
-    #
-    # @param [ Criteria ] other The other criteria.
-    def +(other)
-      entries + comparable(other)
-    end
-
-    # Returns the difference between the criteria and another enumerable. If
-    # the other is a +Criteria+ then it needs to get the collection from it.
-    #
-    # @example Get the difference of 2 criteria.
-    #   criteria - criteria
-    #
-    # @param [ Criteria ] other The other criteria.
-    def -(other)
-      entries - comparable(other)
-    end
+    attr_accessor :embedded, :klass
 
     # Returns true if the supplied +Enumerable+ or +Criteria+ is equal to the results
     # of this +Criteria+ or the criteria itself.
@@ -98,51 +27,155 @@ module Mongoid #:nodoc:
     # @param [ Object ] other The other +Enumerable+ or +Criteria+ to compare to.
     #
     # @return [ true, false ] If the objects are equal.
+    #
+    # @since 1.0.0
     def ==(other)
-      case other
-      when Criteria
-        self.selector == other.selector && self.options == other.options
-      when Enumerable
-        return (execute.entries == other)
-      else
-        return false
-      end
+      return super if other.respond_to?(:selector)
+      entries == other
     end
 
-    # Get the collection associated with the criteria.
+    # Needed to properly get a criteria back as json
     #
-    # @example Get the collection.
-    #   criteria.collection
+    # @example Get the criteria as json.
+    #   Person.where(:title => "Sir").as_json
     #
-    # @return [ Collection ] The collection.
+    # @param [ Hash ] options Options to pass through to the serializer.
     #
-    # @since 2.2.0
-    def collection
-      klass.collection
+    # @return [ String ] The JSON string.
+    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
+    def build(attrs = {})
+      create_document(:new, attrs)
+    end
+    alias :new :build
+
+    # 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.
+    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.
+    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
+    def create(attrs = {})
+      create_document(:create, attrs)
+    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
+    def create!(attrs = {})
+      create_document(:create!, attrs)
+    end
+
+    # Get the documents from the embedded criteria.
+    #
+    # @example Get the documents.
+    #   criteria.documents
+    #
+    # @return [ Array<Document> ] The documents.
+    #
+    # @since 3.0.0
+    def documents
+      @documents ||= []
     end
 
-    # Return or create the context in which this criteria should be executed.
+    # Set the embedded documents on the criteria.
     #
-    # This will return an Enumerable context if the class is embedded,
-    # otherwise it will return a Mongo context for root classes.
+    # @example Set the documents.
     #
-    # @example Get the appropriate context.
-    #   criteria.context
+    # @param [ Array<Document> ] docs The embedded documents.
     #
-    # @return [ Mongo, Enumerable ] The appropriate context.
-    def context
-      @context ||= Contexts.context_for(self, embedded)
+    # @return [ Array<Document> ] The embedded documents.
+    #
+    # @since 3.0.0
+    def documents=(docs)
+      @documents = docs
     end
 
-    # Iterate over each +Document+ in the results. This can take an optional
-    # block to pass to each argument in the results.
+    # 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
+    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.
     #
-    # @example Iterate over the criteria results.
-    #   criteria.each { |doc| p doc }
+    # @return [ Document, Array<Document> ] The document(s).
     #
-    # @return [ Criteria ] The criteria itself.
-    def each(&block)
-      tap { context.iterate(&block) }
+    # @since 2.0.0
+    def execute_or_raise(ids, multi)
+      result = multiple_from_map_or_db(ids)
+      check_for_missing_documents!(result, ids)
+      multi ? result : result.first
     end
 
     # Return true if the criteria has some Document or not.
@@ -151,6 +184,8 @@ module Mongoid #:nodoc:
     #   criteria.exists?
     #
     # @return [ true, false ] If documents match.
+    #
+    # @since 1.0.0
     def exists?
       context.count > 0
     end
@@ -165,7 +200,80 @@ module Mongoid #:nodoc:
     #
     # @since 2.3.0
     def extract_id
-      selector[:_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
+    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
+    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
+    def find(*args)
+      ids = args.__find_args__
+      raise_invalid if ids.any?(&:nil?)
+      for_ids(ids).execute_or_raise(ids, args.multi_arged?)
+    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.
+    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
@@ -182,31 +290,107 @@ module Mongoid #:nodoc:
       context and inclusions and super
     end
 
-    # Merges the supplied argument hash into a single criteria
+    # Get the document from the identity map, and if not found hit the
+    # database.
     #
-    # @example Fuse the criteria and the object.
-    #   criteria.fuse(:where => { :field => "value"}, :limit => 20)
+    # @example Get the document from the map or criteria.
+    #   criteria.from_map_or_db
     #
-    # @param [ Hash ] criteria_conditions Criteria keys and values.
+    # @return [ Document ] The found document.
     #
-    # @return [ Criteria ] self.
-    def fuse(criteria_conditions = {})
-      criteria_conditions.inject(self) do |criteria, (key, value)|
-        criteria.send(key, value)
+    # @since 2.2.1
+    def from_map_or_db
+      id = extract_id
+      id = klass.fields["_id"].mongoize(id) if id
+      doc = IdentityMap.get(klass, id || selector.except("_type"))
+      doc && doc.matches?(selector) ? doc : first
+    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.
+    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
+
+    # Initialize the new criteria.
+    #
+    # @example Init the new criteria.
+    #   Criteria.new(Band)
+    #
+    # @param [ Class ] klass The model class.
+    #
+    # @since 1.0.0
+    def initialize(klass)
+      @klass = klass
+      super(klass.aliased_fields, klass.fields)
+    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
+    def includes(*relations)
+      relations.each do |name|
+        metadata = klass.reflect_on_association(name)
+        inclusions.push(metadata) unless inclusions.include?(metadata)
       end
+      clone
     end
 
-    # Create the new +Criteria+ object. This will initialize the selector
-    # and options hashes, as well as the type of criteria.
+    # Get a list of criteria that are to be executed for eager loading.
+    #
+    # @example Get the eager loading inclusions.
+    #   Person.includes(:game).inclusions
     #
-    # @example Instantiate a new criteria.
-    #   Criteria.new(Model, true)
+    # @return [ Array<Metadata> ] The inclusions.
     #
-    # @param [ Class ] klass The model the criteria is for.
-    # @param [ true, false ] embedded Is the criteria for embedded docs.
-    def initialize(klass, embedded = false)
-      @selector = Criterion::Selector.new(klass)
-      @options, @klass, @documents, @embedded = {}, klass, [], embedded
+    # @since 2.2.0
+    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
+    def inclusions=(value)
+      @inclusions = value
     end
 
     # Merges another object with this +Criteria+ and returns a new criteria.
@@ -214,26 +398,55 @@ module Mongoid #:nodoc:
     # combine multiple scopes together, where a chained scope situation
     # may be desired.
     #
-    # @example Merge the criteria with a conditions hash.
-    #   criteria.merge({ :conditions => { :title => "Sir" } })
-    #
     # @example Merge the criteria with another criteria.
     #   criteri.merge(other_criteria)
     #
-    # @param [ Criteria, Hash ] other The other criterion to merge with.
+    # @param [ Criteria ] other The other criterion to merge with.
     #
     # @return [ Criteria ] A cloned self.
     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
+      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
+    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
+
+    # 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
+    def only(*args)
+      return clone if args.empty?
+      args = args.flatten
+      if klass.hereditary?
+        super(*args.push(:_type))
+      else
+        super(*args)
       end
     end
 
@@ -247,117 +460,127 @@ module Mongoid #:nodoc:
     #
     # @return [ true, false ] If the criteria responds to the method.
     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)
+      super || klass.respond_to?(name) || entries.respond_to?(name, include_private)
     end
 
-    # Returns the selector and options as a +Hash+ that would be passed to a
-    # scope for use with named scopes.
+    alias :to_ary :to_a
+
+    # Convenience for objects that want to be merged into a criteria.
     #
-    # @example Get the criteria as a scoped hash.
-    #   criteria.as_conditions
+    # @example Convert to a criteria.
+    #   criteria.to_criteria
+    #
+    # @return [ Criteria ] self.
     #
-    # @return [ Hash ] The criteria as a scoped hash.
-    def as_conditions
-      scope_options = @options.dup
-      sorting = scope_options.delete(:sort)
-      scope_options[:order_by] = sorting if sorting
-      scope_options[:includes] = inclusions.map(&:name) if inclusions.any?
-      { :where => @selector }.merge(scope_options)
+    # @since 3.0.0
+    def to_criteria
+      self
     end
-    alias :to_ary :to_a
 
-    # Needed to properly get a criteria back as json
+    # Convert the criteria to a proc.
     #
-    # @example Get the criteria as json.
-    #   Person.where(:title => "Sir").as_json
+    # @example Convert the criteria to a proc.
+    #   criteria.to_proc
     #
-    # @param [ Hash ] options Options to pass through to the serializer.
+    # @return [ Proc ] The wrapped criteria.
     #
-    # @return [ String ] The JSON string.
-    def as_json(options = nil)
-      entries.as_json(options)
+    # @since 3.0.0
+    def to_proc
+      ->{ self }
     end
 
-    # Search for documents based on a variety of args.
+    # Adds a criterion to the +Criteria+ that specifies a type or an Array of
+    # types that must be matched.
     #
-    # @example Find by an id.
-    #   criteria.search(BSON::ObjectId.new)
+    # @example Match only specific models.
+    #   criteria.type('Browser')
+    #   criteria.type(['Firefox', 'Browser'])
     #
-    # @example Find by multiple ids.
-    #   criteria.search([ BSON::ObjectId.new, BSON::ObjectId.new ])
+    # @param [ Array<String> ] types The types to match against.
     #
-    # @example Conditionally find all matching documents.
-    #   criteria.search(:all, :conditions => { :title => "Sir" })
+    # @return [ Criteria ] The cloned criteria.
+    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 Conditionally find the first document.
-    #   criteria.search(:first, :conditions => { :title => "Sir" })
+    # @example Add a standard selection.
+    #   criteria.where(name: "syd")
     #
-    # @example Conditionally find the last document.
-    #   criteria.search(:last, :conditions => { :title => "Sir" })
+    # @example Add a javascript selection.
+    #   criteria.where("this.name == 'syd'")
     #
-    # @param [ Symbol, BSON::ObjectId, Array<BSON::ObjectId> ] arg The
-    #   argument to search with.
-    # @param [ Hash ] options The options to search with.
+    # @param [ String, Hash ] criterion The javascript or standard selection.
     #
-    # @return [ Array<Symbol, Criteria> ] The type and criteria.
+    # @raise [ UnsupportedJavascript ] If provided a string and the criteria
+    #   is embedded.
     #
-    # @since 2.0.0
-    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)
+    # @return [ Criteria ] The cloned selectable.
+    #
+    # @since 1.0.0
+    def where(expression)
+      if expression.is_a?(::String) && embedded?
+        raise Errors::UnsupportedJavascript.new(klass, expression)
       end
-      return [ type, where(conditions).extras(params) ]
+      super
     end
 
-    # Convenience method of raising an invalid options error.
+    private
+
+    # Are documents in the query missing, and are we configured to raise an
+    # error?
     #
-    # @example Raise the error.
-    #   criteria.raise_invalid
+    # @api private
     #
-    # @raise [ Errors::InvalidOptions ] The error.
+    # @example Check for missing documents.
+    #   criteria.check_for_missing_documents!([], [ 1 ])
     #
-    # @since 2.0.0
-    def raise_invalid
-      raise Errors::InvalidFind.new
-    end
-
-    protected
-
-    # Return the entries of the other criteria or the object. Used for
-    # comparing criteria or an enumerable.
-    #
-    # @example Get the comparable version.
-    #   criteria.comparable(other)
+    # @param [ Array<Document> ] result The result.
+    # @param [ Array<Object> ] ids The ids.
     #
-    # @param [ Criteria ] other Another criteria.
+    # @raise [ Errors::DocumentNotFound ] If none are found and raising an
+    #   error.
     #
-    # @return [ Array ] The array to compare with.
-    def comparable(other)
-      other.is_a?(Criteria) ? other.entries : other
+    # @since 3.0.0
+    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
 
-    # Get the raw driver collection from the criteria.
+    # Create a document given the provided method and attributes from the
+    # existing selector.
     #
-    # @example Get the raw driver collection.
-    #   criteria.driver
+    # @api private
     #
-    # @return [ Mongo::Collection ] The driver collection.
+    # @example Create a new document.
+    #   criteria.create_document(:new, {})
     #
-    # @since 2.2.0
-    def driver
-      collection.driver
+    # @param [ Symbol ] method Either :new or :create.
+    # @param [ Hash ] attrs Additional attributes to use.
+    #
+    # @return [ Document ] The new or saved document.
+    #
+    # @since 3.0.0
+    def create_document(method, attrs = {})
+      klass.__send__(method,
+        selector.reduce(attrs) do |hash, (key, value)|
+          unless key.to_s =~ /\$/ || value.is_a?(Hash)
+            hash[key] = value
+          end
+          hash
+        end
+      )
     end
 
     # Clone or dup the current +Criteria+. This will return a new criteria with
     # the selector, options, klass, embedded options, etc intact.
     #
+    # @api private
+    #
     # @example Clone a criteria.
     #   criteria.clone
     #
@@ -367,55 +590,102 @@ module Mongoid #:nodoc:
     # @param [ Criteria ] other The criteria getting cloned.
     #
     # @return [ nil ] nil.
+    #
+    # @since 1.0.0
     def initialize_copy(other)
       @selector = other.selector.dup
       @options = other.options.dup
-      @includes = other.inclusions.dup
+      @inclusions = other.inclusions.dup
+      @scoping_options = other.scoping_options
+      @documents = other.documents.dup
       @context = nil
     end
 
+    # Get documents from the database only.
+    #
+    # @api private
+    #
+    # @example Get documents from the database.
+    #   criteria.from_database(ids)
+    #
+    # @param [ Array<Object> ] ids The ids to fetch with.
+    #
+    # @return [ Array<Document> ] The matching documents.
+    #
+    # @since 3.0.0
+    def from_database(ids)
+      (ids.size > 1 ? any_in(id: ids) : where(id: ids.first)).entries
+    end
+
+    # Get documents from the identity map only.
+    #
+    # @api private
+    #
+    # @example Get documents from the identity map.
+    #   criteria.from_identity_map(ids)
+    #
+    # @param [ Array<Object> ] ids The ids to fetch with.
+    #
+    # @return [ Array<Document> ] The matching documents.
+    #
+    # @since 3.0.0
+    def from_identity_map(ids)
+      result = []
+      ids.reject! do |id|
+        doc = IdentityMap.get(klass, id)
+        doc && doc.matches?(selector) ? result.push(doc) : false
+      end
+      result
+    end
+
     # Used for chaining +Criteria+ scopes together in the for of class methods
     # on the +Document+ the criteria is for.
+    #
+    # @example Handle method missing.
+    #   criteria.method_missing(:name)
+    #
+    # @param [ Symbol ] name The method name.
+    # @param [ Array ] args The arguments.
+    #
+    # @return [ Object ] The result of the method call.
+    #
+    # @since 1.0.0
     def method_missing(name, *args, &block)
-      if @klass.respond_to?(name)
-        @klass.send(:with_scope, self) do
-          @klass.send(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
 
-    # Update the selector setting the operator on the value for each key in the
-    # supplied attributes +Hash+.
-    #
-    # @example Update the selector.
-    #   criteria.update_selector({ :field => "value" }, "$in")
-    #
-    # @param [ Hash, Array ] attributes The values to convert and apply.
-    # @param [ String ] operator The MongoDB operator.
-    # @param [ Symbol ] combine The operator to use when combining sets.
-    def update_selector(attributes, operator, combine = :+)
-      clone.tap do |crit|
-        converted = BSON::ObjectId.convert(klass, attributes || {})
-        converted.each_pair do |key, value|
-          existing = crit.selector[key]
-          unless existing
-            crit.selector[key] = { operator => value }
-          else
-            if existing.respond_to?(:merge)
-              if existing.has_key?(operator)
-                new_value = existing.values.first.send(combine, value)
-                crit.selector[key] = { operator => new_value }
-              else
-                crit.selector[key][operator] = value
-              end
-            else
-              crit.selector[key] = { operator => value }
-            end
-          end
-        end
-      end
+    # Convert all the ids to their proper types.
+    #
+    # @api private
+    #
+    # @example Convert the ids.
+    #   criteria.mongoize_ids(ids)
+    #
+    # @param [ Array<Object> ] ids The ids to convert.
+    #
+    # @return [ Array<Object> ] The converted ids.
+    #
+    # @since 3.0.0
+    def mongoize_ids(ids)
+      ids.map{ |id| klass.fields["_id"].mongoize(id) }
+    end
+
+    # Convenience method of raising an invalid options error.
+    #
+    # @example Raise the error.
+    #   criteria.raise_invalid
+    #
+    # @raise [ Errors::InvalidOptions ] The error.
+    #
+    # @since 2.0.0
+    def raise_invalid
+      raise Errors::InvalidFind.new
     end
   end
 end