mongoid 3.1.5 → 8.0.2

data/lib/mongoid/contextual/mongo.rb

@@ -1,62 +1,81 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 require "mongoid/contextual/atomic"
 require "mongoid/contextual/aggregable/mongo"
 require "mongoid/contextual/command"
-require "mongoid/contextual/eager"
-require "mongoid/contextual/find_and_modify"
 require "mongoid/contextual/geo_near"
 require "mongoid/contextual/map_reduce"
+require "mongoid/association/eager_loadable"
 
 module Mongoid
   module Contextual
     class Mongo
+      extend Forwardable
       include Enumerable
       include Aggregable::Mongo
       include Atomic
-      include Eager
+      include Association::EagerLoadable
       include Queryable
 
-      # @attribute [r] query The Moped query.
-      attr_reader :query
-
-      # Is the context cached?
-      #
-      # @example Is the context cached?
-      #   context.cached?
-      #
-      # @return [ true, false ] If the context is cached.
-      #
-      # @since 3.0.0
-      def cached?
-        !!@cache
-      end
+      Mongoid.deprecate(self, :geo_near)
+
+      # Options constant.
+      OPTIONS = [ :hint,
+                  :limit,
+                  :skip,
+                  :sort,
+                  :batch_size,
+                  :max_scan,
+                  :max_time_ms,
+                  :snapshot,
+                  :comment,
+                  :read,
+                  :cursor_type,
+                  :collation
+                ].freeze
+
+      # @attribute [r] view The Mongo collection view.
+      attr_reader :view
 
       # Get the number of documents matching the query.
       #
       # @example Get the number of matching documents.
       #   context.count
       #
-      # @example Get the count of documents matching the provided.
-      #   context.count(document)
+      # @example Get the count of documents with the provided options.
+      #   context.count(limit: 1)
       #
       # @example Get the count for where the provided block is true.
       #   context.count do |doc|
       #     doc.likes > 1
       #   end
       #
-      # @param [ Document ] document A document to match or true if wanting
-      #   skip and limit to be factored into the count.
+      # @param [ Hash ] options The options, such as skip and limit to be factored
+      #   into the count.
       #
       # @return [ Integer ] The number of matches.
-      #
-      # @since 3.0.0
-      def count(document = false, &block)
+      def count(options = {}, &block)
         return super(&block) if block_given?
-        if document.is_a?(Document)
-          return collection.find(criteria.and(_id: document.id).selector).count
+        view.count_documents(options)
+      end
+
+      # Get the estimated number of documents matching the query.
+      #
+      # Unlike count, estimated_count does not take a block because it is not
+      # traditionally defined (with a block) on Enumarable like count is.
+      #
+      # @example Get the estimated number of matching documents.
+      #   context.estimated_count
+      #
+      # @param [ Hash ] options The options, such as maxTimeMS to be factored
+      #   into the count.
+      #
+      # @return [ Integer ] The number of matches.
+      def estimated_count(options = {})
+        unless self.criteria.selector.empty?
+          raise Mongoid::Errors::InvalidEstimatedCountCriteria.new(self.klass)
         end
-        return query.count(document) if document
-        cached? ? @count ||= query.count : query.count
+        view.estimated_document_count(options)
       end
 
       # Delete all documents in the database that match the selector.
@@ -65,12 +84,8 @@ module Mongoid
       #   context.delete
       #
       # @return [ nil ] Nil.
-      #
-      # @since 3.0.0
       def delete
-        self.count.tap do
-          query.remove_all
-        end
+        view.delete_many.deleted_count
       end
       alias :delete_all :delete
 
@@ -80,14 +95,12 @@ module Mongoid
       #   context.destroy
       #
       # @return [ nil ] Nil.
-      #
-      # @since 3.0.0
       def destroy
-        destroyed = self.count
-        each do |doc|
+        each.inject(0) do |count, doc|
           doc.destroy
+          count += 1 if acknowledged_write?
+          count
         end
-        destroyed
       end
       alias :destroy_all :destroy
 
@@ -96,13 +109,24 @@ module Mongoid
       # @example Get the distinct values.
       #   context.distinct(:name)
       #
-      # @param [ String, Symbol ] field The name of the field.
+      # @param [ String | Symbol ] field The name of the field.
       #
       # @return [ Array<Object> ] The distinct values for the field.
-      #
-      # @since 3.0.0
       def distinct(field)
-        query.distinct(klass.database_field_name(field))
+        name = if Mongoid.legacy_pluck_distinct
+          klass.database_field_name(field)
+        else
+          klass.cleanse_localized_field_names(field)
+        end
+
+        view.distinct(name).map do |value|
+          if Mongoid.legacy_pluck_distinct
+            value.class.demongoize(value)
+          else
+            is_translation = "#{name}_translations" == field.to_s
+            recursive_demongoize(name, value, is_translation)
+          end
+        end
       end
 
       # Iterate over the context. If provided a block, yield to a Mongoid
@@ -114,17 +138,12 @@ module Mongoid
       #   end
       #
       # @return [ Enumerator ] The enumerator.
-      #
-      # @since 3.0.0
       def each(&block)
         if block_given?
-          selecting do
-            documents_for_iteration.each do |doc|
-              yield_document(doc, &block)
-            end
-            @cache_loaded = true
-            eager_loadable? ? docs : self
+          documents_for_iteration.each do |doc|
+            yield_document(doc, &block)
           end
+          self
         else
           to_enum
         end
@@ -136,14 +155,11 @@ module Mongoid
       #   context.exists?
       #
       # @note We don't use count here since Mongo does not use counted
-      #   b-tree indexes, unless a count is already cached then that is
-      #   used to determine the value.
+      #   b-tree indexes.
       #
-      # @return [ true, false ] If the count is more than zero.
-      #
-      # @since 3.0.0
+      # @return [ true | false ] If the count is more than zero.
       def exists?
-        @exists ||= check_existence
+        !!(view.projection(_id: 1).limit(1).first)
       end
 
       # Run an explain on the criteria.
@@ -152,30 +168,59 @@ module Mongoid
       #   Band.where(name: "Depeche Mode").explain
       #
       # @return [ Hash ] The explain result.
-      #
-      # @since 3.0.0
       def explain
-        query.explain
+        view.explain
       end
 
       # Execute the find and modify command, used for MongoDB's
       # $findAndModify.
       #
       # @example Execute the command.
-      #   context.find_and_modify({ "$inc" => { likes: 1 }}, new: true)
+      #   context.find_one_and_update({ "$inc" => { likes: 1 }})
       #
       # @param [ Hash ] update The updates.
       # @param [ Hash ] options The command options.
       #
-      # @option options [ true, false ] :new Return the updated document.
-      # @option options [ true, false ] :remove Delete the first document.
-      # @option options [ true, false ] :upsert Create the document if it doesn't exist.
+      # @option options [ :before | :after ] :return_document Return the updated document
+      #   from before or after update.
+      # @option options [ true | false ] :upsert Create the document if it doesn't exist.
       #
       # @return [ Document ] The result of the command.
+      def find_one_and_update(update, options = {})
+        if doc = view.find_one_and_update(update, options)
+          Factory.from_db(klass, doc)
+        end
+      end
+
+      # Execute the find and modify command, used for MongoDB's
+      # $findAndModify.
+      #
+      # @example Execute the command.
+      #   context.find_one_and_update({ likes: 1 })
       #
-      # @since 3.0.0
-      def find_and_modify(update, options = {})
-        if doc = FindAndModify.new(collection, criteria, update, options).result
+      # @param [ Hash ] replacement The replacement.
+      # @param [ Hash ] options The command options.
+      #
+      # @option options [ :before | :after ] :return_document Return the updated document
+      #   from before or after update.
+      # @option options [ true | false ] :upsert Create the document if it doesn't exist.
+      #
+      # @return [ Document ] The result of the command.
+      def find_one_and_replace(replacement, options = {})
+        if doc = view.find_one_and_replace(replacement, options)
+          Factory.from_db(klass, doc)
+        end
+      end
+
+      # Execute the find and modify command, used for MongoDB's
+      # $findAndModify. This deletes the found document.
+      #
+      # @example Execute the command.
+      #   context.find_one_and_delete
+      #
+      # @return [ Document ] The result of the command.
+      def find_one_and_delete
+        if doc = view.find_one_and_delete
           Factory.from_db(klass, doc)
         end
       end
@@ -185,20 +230,33 @@ module Mongoid
       # @example Get the first document.
       #   context.first
       #
-      # @return [ Document ] The first document.
+      # @note Automatically adding a sort on _id when no other sort is
+      #   defined on the criteria has the potential to cause bad performance issues.
+      #   If you experience unexpected poor performance when using #first or #last
+      #   and have no sort defined on the criteria, use #take instead.
+      #   Be aware that #take won't guarantee order.
       #
-      # @since 3.0.0
-      def first
-        if cached? && cache_loaded?
-          documents.first
-        else
-          with_sorting do
-            with_eager_loading(query.first)
-          end
+      # @param [ Integer ] limit The number of documents to return.
+      #
+      # @return [ Document ] The first document.
+      def first(limit = nil)
+        sort = view.sort || { _id: 1 }
+        if raw_docs = view.sort(sort).limit(limit || 1).to_a
+          process_raw_docs(raw_docs, limit)
         end
       end
       alias :one :first
 
+      # Return the first result without applying sort
+      #
+      # @api private
+      def find_first
+        if raw_doc = view.first
+          doc = Factory.from_db(klass, raw_doc, criteria)
+          eager_load([doc]).first
+        end
+      end
+
       # Execute a $geoNear command against the database.
       #
       # @example Find documents close to 10, 10.
@@ -217,78 +275,56 @@ module Mongoid
       #
       # @return [ GeoNear ] The GeoNear command.
       #
-      # @since 3.1.0
+      # @deprecated
       def geo_near(coordinates)
         GeoNear.new(collection, criteria, coordinates)
       end
 
-      # Invoke the block for each element of Contextual. Create a new array
-      # containing the values returned by the block.
-      #
-      # If the symbol field name is passed instead of the block, additional
-      # optimizations would be used.
-      #
-      # @example Map by some field.
-      #   context.map(:field1)
-      #
-      # @exmaple Map with block.
-      #   context.map(&:field1)
-      #
-      # @param [ Symbol ] field The field name.
-      #
-      # @return [ Array ] The result of mapping.
-      def map(field = nil, &block)
-        if block_given?
-          super(&block)
-        else
-          field = field.to_sym
-          criteria.only(field).map(&field.to_proc)
-        end
-      end
-
       # Create the new Mongo context. This delegates operations to the
-      # underlying driver - in Mongoid's case Moped.
+      # underlying driver.
       #
       # @example Create the new context.
       #   Mongo.new(criteria)
       #
       # @param [ Criteria ] criteria The criteria.
-      #
-      # @since 3.0.0
       def initialize(criteria)
-        @criteria, @klass, @cache = criteria, criteria.klass, criteria.options[:cache]
-        @collection = klass.collection
+        @criteria, @klass = criteria, criteria.klass
+        @collection = @klass.collection
         criteria.send(:merge_type_selection)
-        @query = collection.find(criteria.selector)
+        @view = collection.find(criteria.selector, session: _session)
         apply_options
       end
 
-      delegate(:database_field_name, to: :@klass)
+      def_delegator :@klass, :database_field_name
 
       # Get the last document in the database for the criteria's selector.
       #
       # @example Get the last document.
       #   context.last
       #
-      # @return [ Document ] The last document.
+      # @note Automatically adding a sort on _id when no other sort is
+      #   defined on the criteria has the potential to cause bad performance issues.
+      #   If you experience unexpected poor performance when using #first or #last
+      #   and have no sort defined on the criteria, use #take instead.
+      #   Be aware that #take won't guarantee order.
       #
-      # @since 3.0.0
-      def last
-        with_inverse_sorting do
-          with_eager_loading(query.first)
-        end
+      # @param [ Integer ] limit The number of documents to return.
+      #
+      # @return [ Document ] The last document.
+      def last(limit = nil)
+        raw_docs = view.sort(inverse_sorting).limit(limit || 1).to_a.reverse
+        process_raw_docs(raw_docs, limit)
       end
 
-      # Get's the number of documents matching the query selector.
+      # Returns the number of documents in the database matching
+      # the query selector.
       #
       # @example Get the length.
       #   context.length
       #
       # @return [ Integer ] The number of documents.
-      #
-      # @since 3.0.0
       def length
-        @length ||= self.count
+        self.count
       end
       alias :size :length
 
@@ -300,10 +336,46 @@ module Mongoid
       # @param [ Integer ] value The number of documents to return.
       #
       # @return [ Mongo ] The context.
-      #
-      # @since 3.0.0
       def limit(value)
-        query.limit(value) and self
+        @view = view.limit(value) and self
+      end
+
+      # Take the given number of documents from the database.
+      #
+      # @example Take 10 documents
+      #   context.take(10)
+      #
+      # @param [ Integer | nil ] limit The number of documents to return or nil.
+      #
+      # @return [ Document | Array<Document> ] The list of documents, or one
+      #   document if no value was given.
+      def take(limit = nil)
+        if limit
+          limit(limit).to_a
+        else
+          # Do to_a first so that the Mongo#first method is not used and the
+          # result is not sorted.
+          limit(1).to_a.first
+        end
+      end
+
+      # Take one document from the database and raise an error if there are none.
+      #
+      # @example Take a document
+      #   context.take!
+      #
+      # @return [ Document ] The document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents to take.
+      def take!
+        # Do to_a first so that the Mongo#first method is not used and the
+        # result is not sorted.
+        if fst = limit(1).to_a.first
+          fst
+        else
+          raise Errors::DocumentNotFound.new(klass, nil, nil)
+        end
       end
 
       # Initiate a map/reduce operation from the context.
@@ -315,8 +387,6 @@ module Mongoid
       # @param [ String ] reduce The reduce js function.
       #
       # @return [ MapReduce ] The map/reduce lazy wrapper.
-      #
-      # @since 3.0.0
       def map_reduce(map, reduce)
         MapReduce.new(collection, criteria, map, reduce)
       end
@@ -327,17 +397,117 @@ module Mongoid
       # @example Pluck a field.
       #   context.pluck(:_id)
       #
-      # @note This method will return the raw db values - it performs no custom
-      #   serialization.
+      # @param [ String | Symbol ] *fields Field(s) to pluck.
+      #
+      # @return [ Array<Object> | Array<Array<Object>> ] The plucked values.
+      def pluck(*fields)
+        # Multiple fields can map to the same field name. For example, plucking
+        # a field and its _translations field map to the same field in the database.
+        # because of this, we need to keep track of the fields requested.
+        normalized_field_names = []
+        normalized_select = fields.inject({}) do |hash, f|
+          db_fn = klass.database_field_name(f)
+          normalized_field_names.push(db_fn)
+
+          if Mongoid.legacy_pluck_distinct
+            hash[db_fn] = true
+          else
+            hash[klass.cleanse_localized_field_names(f)] = true
+          end
+          hash
+        end
+
+        view.projection(normalized_select).reduce([]) do |plucked, doc|
+          values = normalized_field_names.map do |n|
+            if Mongoid.legacy_pluck_distinct
+              n.include?('.') ? doc[n.partition('.')[0]] : doc[n]
+            else
+              extract_value(doc, n)
+            end
+          end
+          plucked << (values.size == 1 ? values.first : values)
+        end
+      end
+
+      # Pick the single field values from the database.
+      #
+      # @example Pick a field.
+      #   context.pick(:_id)
+      #
+      # @param [ String | Symbol ] *fields Field(s) to pick.
+      #
+      # @return [ Object | Array<Object> ] The picked values.
+      def pick(*fields)
+        limit(1).pluck(*fields).first
+      end
+
+      # Get a hash of counts for the values of a single field. For example,
+      # if the following documents were in the database:
+      #
+      #   { _id: 1, age: 21 }
+      #   { _id: 2, age: 21 }
+      #   { _id: 3, age: 22 }
+      #
+      #   Model.tally("age")
+      #
+      # would yield the following result:
+      #
+      #   { 21 => 2, 22 => 1 }
+      #
+      # When tallying a field inside an array or embeds_many association:
+      #
+      #   { _id: 1, array: [ { x: 1 }, { x: 2 } ] }
+      #   { _id: 2, array: [ { x: 1 }, { x: 2 } ] }
+      #   { _id: 3, array: [ { x: 1 }, { x: 3 } ] }
+      #
+      #   Model.tally("array.x")
+      #
+      # The keys of the resulting hash are arrays:
+      #
+      #   { [ 1, 2 ] => 2, [ 1, 3 ] => 1 }
       #
-      # @param [ String, Symbol ] field The field to pluck.
+      # Note that if tallying an element in an array of hashes, and the key
+      # doesn't exist in some of the hashes, tally will not include those
+      # nil keys in the resulting hash:
       #
-      # @return [ Array<Object> ] The plucked values.
+      #   { _id: 1, array: [ { x: 1 }, { x: 2 }, { y: 3 } ] }
       #
-      # @since 3.1.0
-      def pluck(field)
-        normalized = klass.database_field_name(field)
-        query.dup.select(normalized => 1).map{ |doc| doc[normalized] }.compact
+      #   Model.tally("array.x")
+      #   # => { [ 1, 2 ] => 1 }
+      #
+      # @param [ String | Symbol ] field The field name.
+      #
+      # @return [ Hash ] The hash of counts.
+      def tally(field)
+        name = klass.cleanse_localized_field_names(field)
+
+        fld = klass.traverse_association_tree(name)
+        pipeline = [ { "$group" => { _id: "$#{name}", counts: { "$sum": 1 } } } ]
+        pipeline.unshift("$match" => view.filter) unless view.filter.blank?
+
+        collection.aggregate(pipeline).reduce({}) do |tallies, doc|
+          is_translation = "#{name}_translations" == field.to_s
+          val = doc["_id"]
+
+          key = if val.is_a?(Array)
+            val.map do |v|
+              demongoize_with_field(fld, v, is_translation)
+            end
+          else
+            demongoize_with_field(fld, val, is_translation)
+          end
+
+          # The only time where a key will already exist in the tallies hash
+          # is when the values are stored differently in the database, but
+          # demongoize to the same value. A good example of when this happens
+          # is when using localized fields. While the server query won't group
+          # together hashes that have other values in different languages, the
+          # demongoized value is just the translation in the current locale,
+          # which can be the same across multiple of those unequal hashes.
+          tallies[key] ||= 0
+          tallies[key] += doc["counts"]
+          tallies
+        end
       end
 
       # Skips the provided number of documents.
@@ -348,10 +518,8 @@ module Mongoid
       # @param [ Integer ] value The number of documents to skip.
       #
       # @return [ Mongo ] The context.
-      #
-      # @since 3.0.0
       def skip(value)
-        query.skip(value) and self
+        @view = view.skip(value) and self
       end
 
       # Sorts the documents by the provided spec.
@@ -363,8 +531,6 @@ module Mongoid
       #   pairs.
       #
       # @return [ Mongo ] The context.
-      #
-      # @since 3.0.0
       def sort(values = nil, &block)
         if block_given?
           super(&block)
@@ -382,48 +548,34 @@ module Mongoid
       #   context.update({ "$set" => { name: "Smiths" }})
       #
       # @param [ Hash ] attributes The new attributes for the document.
+      # @param [ Hash ] opts The update operation options.
       #
-      # @return [ nil, false ] False if no attributes were provided.
+      # @option opts [ Array ] :array_filters A set of filters specifying to which array elements
+      #   an update should apply.
       #
-      # @since 3.0.0
-      def update(attributes = nil)
-        update_documents(attributes)
+      # @return [ nil, false ] False if no attributes were provided.
+      def update(attributes = nil, opts = {})
+        update_documents(attributes, :update_one, opts)
       end
 
       # Update all the matching documents atomically.
       #
       # @example Update all the matching documents.
-      #   context.update({ "$set" => { name: "Smiths" }})
+      #   context.update_all({ "$set" => { name: "Smiths" }})
       #
       # @param [ Hash ] attributes The new attributes for each document.
+      # @param [ Hash ] opts The update operation options.
       #
-      # @return [ nil, false ] False if no attributes were provided.
+      # @option opts [ Array ] :array_filters A set of filters specifying to which array elements
+      #   an update should apply.
       #
-      # @since 3.0.0
-      def update_all(attributes = nil)
-        update_documents(attributes, :update_all)
+      # @return [ nil, false ] False if no attributes were provided.
+      def update_all(attributes = nil, opts = {})
+        update_documents(attributes, :update_many, opts)
       end
 
       private
 
-      # Checks if any documents exist in the database.
-      #
-      # @api private
-      #
-      # @example Check for document existsence.
-      #   context.check_existence
-      #
-      # @return [ true, false ] If documents exist.
-      #
-      # @since 3.1.0
-      def check_existence
-        if cached? && cache_loaded?
-          !documents.empty?
-        else
-          @count ? @count > 0 : !query.dup.select(_id: 1).limit(1).entries.first.nil?
-        end
-      end
-
       # Update the documents for the provided method.
       #
       # @api private
@@ -434,13 +586,11 @@ module Mongoid
       # @param [ Hash ] attributes The updates.
       # @param [ Symbol ] method The method to use.
       #
-      # @return [ true, false ] If the update succeeded.
-      #
-      # @since 3.0.4
-      def update_documents(attributes, method = :update)
+      # @return [ true | false ] If the update succeeded.
+      def update_documents(attributes, method = :update_one, opts = {})
         return false unless attributes
         attributes = Hash[attributes.map { |k, v| [klass.database_field_name(k.to_s), v] }]
-        query.send(method, attributes.__consolidate__(klass))
+        view.send(method, attributes.__consolidate__(klass), opts)
       end
 
       # Apply the field limitations.
@@ -449,11 +599,9 @@ module Mongoid
       #
       # @example Apply the field limitations.
       #   context.apply_fields
-      #
-      # @since 3.0.0
       def apply_fields
         if spec = criteria.options[:fields]
-          query.select(spec)
+          @view = view.projection(spec)
         end
       end
 
@@ -463,15 +611,13 @@ module Mongoid
       #
       # @example Apply all options.
       #   context.apply_options
-      #
-      # @since 3.1.0
       def apply_options
         apply_fields
-        [ :hint, :limit, :skip, :sort, :batch_size, :max_scan ].each do |name|
+        OPTIONS.each do |name|
           apply_option(name)
         end
         if criteria.options[:timeout] == false
-          query.no_timeout
+          @view = view.no_cursor_timeout
         end
       end
 
@@ -481,164 +627,191 @@ module Mongoid
       #
       # @example Apply the skip option.
       #   context.apply_option(:skip)
-      #
-      # @since 3.1.0
       def apply_option(name)
         if spec = criteria.options[name]
-          query.send(name, spec)
+          @view = view.send(name, spec)
         end
       end
 
-      # Apply an ascending id sort for use with #first queries, only if no
-      # other sorting is provided.
+      # Map the inverse sort symbols to the correct MongoDB values.
       #
       # @api private
-      #
-      # @example Apply the id sorting params to the given block
-      #   context.with_sorting
-      #
-      # @since 3.0.0
-      def with_sorting
-        begin
-          unless criteria.options.has_key?(:sort)
-            query.sort(_id: 1)
-          end
-          yield
-        ensure
-          apply_option(:sort)
-        end
+      def inverse_sorting
+        sort = view.sort || { _id: 1 }
+        Hash[sort.map{|k, v| [k, -1*v]}]
       end
 
-      # Map the inverse sort symbols to the correct MongoDB values.
-      #
-      #  @api private
-      #
-      # @example Apply the inverse sorting params to the given block
-      #   context.with_inverse_sorting
+      # Get the documents the context should iterate. This follows 3 rules:
       #
-      # @since 3.0.0
-      def with_inverse_sorting
-        begin
-          if spec = criteria.options[:sort]
-            query.sort(Hash[spec.map{|k, v| [k, -1*v]}])
-          else
-            query.sort(_id: -1)
-          end
-          yield
-        ensure
-          apply_option(:sort)
-        end
-      end
-
-      # Is the cache able to be added to?
+      # 1. If the query is cached, and we already have documents loaded, use
+      #   them.
+      # 2. If we are eager loading, then eager load the documents and use
+      #   those.
+      # 3. Use the query.
       #
       # @api private
       #
-      # @example Is the context cacheable?
-      #   context.cacheable?
-      #
-      # @return [ true, false ] If caching, and the cache isn't loaded.
+      # @example Get the documents for iteration.
+      #   context.documents_for_iteration
       #
-      # @since 3.0.0
-      def cacheable?
-        cached? && !cache_loaded?
+      # @return [ Array<Document> | Mongo::Collection::View ] The docs to iterate.
+      def documents_for_iteration
+        return view unless eager_loadable?
+        docs = view.map{ |doc| Factory.from_db(klass, doc, criteria) }
+        eager_load(docs)
       end
 
-      # Is the cache fully loaded? Will be true if caching after one full
-      # iteration.
+      # Yield to the document.
       #
       # @api private
       #
-      # @example Is the cache loaded?
-      #   context.cache_loaded?
-      #
-      # @return [ true, false ] If the cache is loaded.
+      # @example Yield the document.
+      #   context.yield_document(doc) do |doc|
+      #     ...
+      #   end
       #
-      # @since 3.0.0
-      def cache_loaded?
-        !!@cache_loaded
+      # @param [ Document ] document The document to yield to.
+      def yield_document(document, &block)
+        doc = document.respond_to?(:_id) ?
+            document : Factory.from_db(klass, document, criteria)
+        yield(doc)
       end
 
-      # Get the documents for cached queries.
-      #
-      # @api private
-      #
-      # @example Get the cached documents.
-      #   context.documents
-      #
-      # @return [ Array<Document> ] The documents.
-      #
-      # @since 3.0.0
-      def documents
-        @documents ||= []
+      private
+
+      def _session
+        @criteria.send(:_session)
       end
 
-      # Get the documents the context should iterate. This follows 3 rules:
-      #
-      # 1. If the query is cached, and we already have documents loaded, use
-      #   them.
-      # 2. If we are eager loading, then eager load the documents and use
-      #   those.
-      # 3. Use the query.
-      #
-      # @api private
+      def acknowledged_write?
+        collection.write_concern.nil? || collection.write_concern.acknowledged?
+      end
+
+      # Fetch the element from the given hash and demongoize it using the
+      # given field. If the obj is an array, map over it and call this method
+      # on all of its elements.
       #
-      # @example Get the documents for iteration.
-      #   context.documents_for_iteration
+      # @param [ Hash | Array<Hash> ] obj The hash or array of hashes to fetch from.
+      # @param [ String ] meth The key to fetch from the hash.
+      # @param [ Field ] field The field to use for demongoization.
       #
-      # @return [ Array<Document>, Moped::Query ] The docs to iterate.
+      # @return [ Object ] The demongoized value.
       #
-      # @since 3.0.0
-      def documents_for_iteration
-        if cached? && !documents.empty?
-          documents
-        elsif eager_loadable?
-          docs = query.map{ |doc| Factory.from_db(klass, doc) }
-          eager_load(docs)
-          docs
+      # @api private
+      def fetch_and_demongoize(obj, meth, field)
+        if obj.is_a?(Array)
+          obj.map { |doc| fetch_and_demongoize(doc, meth, field) }
         else
-          query
+          res = obj.try(:fetch, meth, nil)
+          field ? field.demongoize(res) : res.class.demongoize(res)
         end
       end
 
-      # If we are limiting results, we need to set the field limitations on a
-      # thread local to avoid overriding the default values.
-      #
-      # @example Execute with selection.
-      #   context.selecting do
-      #     collection.find
-      #   end
+      # Extracts the value for the given field name from the given attribute
+      # hash.
       #
-      # @return [ Object ] The yielded value.
+      # @param [ Hash ] attrs The attributes hash.
+      # @param [ String ] field_name The name of the field to extract.
       #
-      # @since 2.4.4
-      def selecting
-        begin
-          fields = criteria.options[:fields]
-          Threaded.set_selection(criteria.object_id, fields) unless fields.blank?
-          yield
-        ensure
-          Threaded.delete_selection(criteria.object_id)
+      # @param [ Object ] The value for the given field name
+      def extract_value(attrs, field_name)
+        i = 1
+        num_meths = field_name.count('.') + 1
+        curr = attrs.dup
+
+        klass.traverse_association_tree(field_name) do |meth, obj, is_field|
+          field = obj if is_field
+          is_translation = false
+          # If no association or field was found, check if the meth is an
+          # _translations field.
+          if obj.nil? & tr = meth.match(/(.*)_translations\z/)&.captures&.first
+            is_translation = true
+            meth = tr
+          end
+
+          # 1. If curr is an array fetch from all elements in the array.
+          # 2. If the field is localized, and is not an _translations field
+          #    (_translations fields don't show up in the fields hash).
+          #    - If this is the end of the methods, return the translation for
+          #      the current locale.
+          #    - Otherwise, return the whole translations hash so the next method
+          #      can select the language it wants.
+          # 3. If the meth is an _translations field, do not demongoize the
+          #    value so the full hash is returned.
+          # 4. Otherwise, fetch and demongoize the value for the key meth.
+          curr = if curr.is_a? Array
+            res = fetch_and_demongoize(curr, meth, field)
+            res.empty? ? nil : res
+          elsif !is_translation && field&.localized?
+            if i < num_meths
+              curr.try(:fetch, meth, nil)
+            else
+              fetch_and_demongoize(curr, meth, field)
+            end
+          elsif is_translation
+            curr.try(:fetch, meth, nil)
+          else
+            fetch_and_demongoize(curr, meth, field)
+          end
+
+          i += 1
         end
+        curr
       end
 
-      # Yield to the document.
+      # Recursively demongoize the given value. This method recursively traverses
+      # the class tree to find the correct field to use to demongoize the value.
       #
-      # @api private
+      # @param [ String ] field_name The name of the field to demongoize.
+      # @param [ Object ] value The value to demongoize.
+      # @param [ true | false ] is_translation The field we are retrieving is an
+      #   _translations field.
       #
-      # @example Yield the document.
-      #   context.yield_document(doc) do |doc|
-      #     ...
-      #   end
+      # @return [ Object ] The demongoized value.
+      def recursive_demongoize(field_name, value, is_translation)
+        field = klass.traverse_association_tree(field_name)
+        demongoize_with_field(field, value, is_translation)
+      end
+
+      # Demongoize the value for the given field. If the field is nil or the
+      # field is a translations field, the value is demongoized using its class.
       #
-      # @param [ Document ] document The document to yield to.
+      # @param [ Field ] field The field to use to demongoize.
+      # @param [ Object ] value The value to demongoize.
+      # @param [ true | false ] is_translation The field we are retrieving is an
+      #   _translations field.
       #
-      # @since 3.0.0
-      def yield_document(document, &block)
-        doc = document.respond_to?(:_id) ?
-          document : Factory.from_db(klass, document, criteria.object_id)
-        yield(doc)
-        documents.push(doc) if cacheable?
+      # @return [ Object ] The demongoized value.
+      #
+      # @api private
+      def demongoize_with_field(field, value, is_translation)
+        if field
+          # If it's a localized field that's not a hash, don't demongoize
+          # again, we already have the translation. If it's an _translations
+          # field, don't demongoize, we want the full hash not just a
+          # specific translation.
+          # If it is a hash, and it's not a translations field, we need to
+          # demongoize to get the correct translation.
+          if field.localized? && (!value.is_a?(Hash) || is_translation)
+            value.class.demongoize(value)
+          else
+            field.demongoize(value)
+          end
+        else
+          value.class.demongoize(value)
+        end
+      end
+
+      # Process the raw documents retrieved for #first/#last.
+      #
+      # @return [ Array<Document> | Document ] The list of documents or a
+      #   single document.
+      def process_raw_docs(raw_docs, limit)
+        docs = raw_docs.map do |d|
+          Factory.from_db(klass, d, criteria)
+        end
+        docs = eager_load(docs)
+        limit ? docs : docs.first
       end
     end
   end