MONGOID-5391 - Add #pluck_each, extract out PluckEnumerator

docs/reference/queries.txt

@@ -1522,6 +1522,41 @@ Mongoid also has some helpful methods on criteria.
           Band.all.pluck(:name, :likes)
             #=> [ ["Daft Punk", 342], ["Aphex Twin", 98], ["Ween", 227] ]
 
+   * - ``Criteria#pluck_each``
+
+       *This method returns an Enumerator for the results of ``pluck``.
+       A block may optionally be given, which will be called once for
+       each result.*
+
+       *Similar to the ``each`` method, this method will use the
+       `MongoDB getMore command
+       <https://mongodb.com/docs/manual/reference/command/getMore/>`_
+       to load results in batches. This is useful for working with
+       large query results.*
+
+       *The method arguments and field normalization behavior are
+       otherwise identical to ``pluck``.*
+
+     -
+       .. code-block:: ruby
+
+         Band.all.pluck_each(:name)
+           #=> #<Enumerator: ... >
+
+         Band.all.pluck_each(:name, 'address.city', :founded) do |name, city, founded|
+           puts "#{name} from #{city} started in #{founded}"
+         end
+           # =>
+           # The Rolling Stones from London started in 1962
+           # The Beatles from Liverpool started in 1960
+           # The Monkees from Los Angeles started in 1966
+            #=> [ ["Berry Gordy", "Tommy Mottola"], [], ["Quincy Jones"] ]
+
+          # Accepts multiple field arguments, in which case
+          # the result will be returned as an Array of Arrays.
+          Band.all.pluck(:name, :likes)
+            #=> [ ["Daft Punk", 342], ["Aphex Twin", 98], ["Ween", 227] ]
+
    * - ``Criteria#read``
 
        *Sets the read preference for the criteria.*

docs/release-notes/mongoid-9.0.txt

@@ -386,6 +386,35 @@ defaults to ``true``.
 When set to false, the older, inconsistent behavior is restored.
 
 
+``Criteria#pluck_each`` Method Added
+----------------------------------------
+
+The newly introduced ``Criteria#pluck_each`` method returns
+an Enumerator for the results of ``pluck``, or if a block is given,
+calls the block once for each pluck result in a progressively-loaded
+fashion.
+
+Previously, calling ``criteria.pluck(:name).each`` would load the
+entire result set into Ruby's memory before iterating over the results.
+In contrast, ``criteria.pluck_each(:name)`` uses the `MongoDB getMore command
+<https://mongodb.com/docs/manual/reference/command/getMore/>`_
+to load results in batches, similar to how ``criteria.each`` behaves.
+This is useful for working with large query results.
+
+The method arguments and behavior of ``pluck_each`` are otherwise
+identical to ``pluck``.
+
+.. code-block:: ruby
+
+  Band.all.pluck_each(:name, 'address.city', :founded) do |name, city, founded|
+    puts "#{name} from #{city} started in #{founded}"
+  end
+  # =>
+  # The Rolling Stones from London started in 1962
+  # The Beatles from Liverpool started in 1960
+  # The Monkees from Los Angeles started in 1966
+
+
 Support Field Aliases on Index Options
 --------------------------------------
 

lib/mongoid/contextual/memory.rb

@@ -263,6 +263,22 @@ def pluck(*fields)
         end
       end
 
+      # Iterate through plucked field values in memory.
+      #
+      # @example Iterate through the values for null context.
+      #   context.pluck_each(:name) { |name| puts name }
+      #
+      # @param [ [ String | Symbol ]... ] *fields Field(s) to pluck.
+      # @param [ Proc ] &block The block to call once for each plucked
+      #   result.
+      #
+      # @return [ Enumerator | Memory ] An enumerator, or the context
+      #   if a block was given.
+      def pluck_each(*fields, &block)
+        enum = pluck(*fields).each(&block)
+        block_given? ? self : enum
+      end
+
       # Pick the field values in memory.
       #
       # @example Get the values in memory.

lib/mongoid/contextual/mongo.rb

@@ -8,6 +8,7 @@
 require "mongoid/contextual/command"
 require "mongoid/contextual/geo_near"
 require "mongoid/contextual/map_reduce"
+require "mongoid/contextual/mongo/pluck_enumerator"
 require "mongoid/association/eager_loadable"
 
 module Mongoid
@@ -357,23 +358,27 @@ def map_reduce(map, reduce)
       #   in the array will be a single value. Otherwise, each
       #   result in the array will be an array of 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)
-          hash[klass.cleanse_localized_field_names(f)] = true
-          hash
-        end
+        pluck_each(*fields).to_a
+      end
 
-        view.projection(normalized_select).reduce([]) do |plucked, doc|
-          values = normalized_field_names.map do |n|
-            extract_value(doc, n)
-          end
-          plucked << (values.size == 1 ? values.first : values)
-        end
+      # Iterate through plucked field value(s) from the database
+      # for the context. Yields result values progressively as they are
+      # read from the database. The yielded results are normalized
+      # according to their Mongoid field types.
+      #
+      # @example Iterate through the plucked values from the database.
+      #   context.pluck_each(:name) { |name| puts name }
+      #
+      # @param [ [ String | Symbol ]... ] *fields Field(s) to pluck,
+      #   which may include nested fields using dot-notation.
+      # @param [ Proc ] &block The block to call once for each plucked
+      #   result.
+      #
+      # @return [ Enumerator | Mongoid::Contextual::Mongo ] The enumerator,
+      #   or the context if a block was given.
+      def pluck_each(*fields, &block)
+        enum = PluckEnumerator.new(klass, view, fields).each(&block)
+        block_given? ? self : enum
       end
 
       # Pick the single field values from the database.
@@ -919,78 +924,6 @@ 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.
-      #
-      # @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 [ Object ] The demongoized value.
-      #
-      # @api private
-      def fetch_and_demongoize(obj, meth, field)
-        if obj.is_a?(Array)
-          obj.map { |doc| fetch_and_demongoize(doc, meth, field) }
-        else
-          res = obj.try(:fetch, meth, nil)
-          field ? field.demongoize(res) : res.class.demongoize(res)
-        end
-      end
-
-      # Extracts the value for the given field name from the given attribute
-      # hash.
-      #
-      # @param [ Hash ] attrs The attributes hash.
-      # @param [ String ] field_name The name of the field to extract.
-      #
-      # @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
-
       # Recursively demongoize the given value. This method recursively traverses
       # the class tree to find the correct field to use to demongoize the value.
       #

lib/mongoid/contextual/mongo/pluck_enumerator.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Contextual
+    class Mongo
+
+      # Utility class to add enumerable behavior for Criteria#pluck_each.
+      #
+      # @api private
+      class PluckEnumerator
+        include Enumerable
+
+        # Create the new PluckEnumerator.
+        #
+        # @api private
+        #
+        # @example Initialize a PluckEnumerator.
+        #   PluckEnumerator.new(klass, view, fields)
+        #
+        # @param [ Class ] klass The base of the binding.
+        # @param [ Mongo::Collection::View ] view The Mongo view context.
+        # @param [ String | Symbol ] *fields Field(s) to pluck,
+        #   which may include nested fields using dot-notation.
+        def initialize(klass, view, fields)
+          @klass = klass
+          @view = view
+          @fields = fields
+        end
+
+        # Iterate through plucked field value(s) from the database
+        # for the view context. Yields result values progressively as
+        # they are read from the database. The yielded results are
+        # normalized according to their Mongoid field types.
+        #
+        # @api private
+        #
+        # @example Iterate through the plucked values from the database.
+        #   context.pluck_each(:name) { |name| puts name }
+        #
+        # @param [ Proc ] &block The block to call once for each plucked
+        #   result.
+        #
+        # @return [ Enumerator | PluckEnumerator ] The enumerator, or
+        #   self if a block was given.
+        def each(&block)
+          return to_enum unless block_given?
+
+          @view.projection(normalized_field_names.index_with(true)).each do |doc|
+            yield_result(doc, &block)
+          end
+
+          self
+        end
+
+        private
+
+        def database_field_names
+          @database_field_names ||= @fields.map {|f| @klass.database_field_name(f) }
+        end
+
+        def normalized_field_names
+          @normalized_field_names ||= @fields.map {|f| @klass.cleanse_localized_field_names(f) }
+        end
+
+        def yield_result(doc)
+          values = database_field_names.map {|n| extract_value(doc, n) }
+          yield(values.size == 1 ? values.first : values)
+        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.
+        #
+        # @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 [ Object ] The demongoized value.
+        #
+        # @api private
+        def fetch_and_demongoize(obj, meth, field)
+          if obj.is_a?(Array)
+            obj.map { |doc| fetch_and_demongoize(doc, meth, field) }
+          else
+            res = obj.try(:fetch, meth, nil)
+            field ? field.demongoize(res) : res.class.demongoize(res)
+          end
+        end
+
+        # Extracts the value for the given field name from the given attribute
+        # hash.
+        #
+        # @param [ Hash ] attrs The attributes hash.
+        # @param [ String ] field_name The name of the field to extract.
+        #
+        # @return [ Object ] The value for the given field name
+        #
+        # @api private
+        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
+      end
+    end
+  end
+end