mongoid 9.0.12 → 9.1.0

data/lib/mongoid/association/builders.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
-# rubocop:todo all
 
 module Mongoid
   module Association
-
     # This module is responsible for defining the build and create methods used
     # in one to one associations.
     #
@@ -22,17 +20,20 @@ module Mongoid
 
       private
 
-      # Parse out the attributes and the options from the args passed to a
-      # build_ or create_ methods.
-      #
-      # @example Parse the args.
-      #   doc.parse_args(:name => "Joe")
+      # Parses the arguments passed to the build and create methods. The first
+      # argument is always the attributes (defaulting to {} if not given). The
+      # last argument is always the options hash, if the last argument is a
+      # hash. The first of any remaining arguments is the type.
       #
-      # @param [ Hash... ] *args The arguments.
+      # @param [ Array ] args The arguments passed to the method.
       #
-      # @return [ Array<Hash> ] The attributes and options.
-      def parse_args(*args)
-        [ args.first || {}, args.size > 1 ? args[1] : {} ]
+      # @return [ Array ] An array containing the attributes, type, and options.
+      def parse_args(args)
+        attributes = args.shift || {}
+        opts = args.last.is_a?(Hash) ? args.pop : {}
+        type = args.shift
+
+        [ attributes, type, opts ]
       end
 
       # Defines a builder method. This is defined as #build_name.
@@ -46,8 +47,9 @@ module Mongoid
       def self.define_builder!(association)
         association.inverse_class.tap do |klass|
           klass.re_define_method("build_#{association.name}") do |*args|
-            attributes, _options = parse_args(*args)
-            document = Factory.execute_build(association.relation_class, attributes, execute_callbacks: false)
+            attributes, type, _opts = parse_args(args)
+
+            document = Factory.execute_build(type || association.relation_class, attributes, execute_callbacks: false)
             _building do
               child = send("#{association.name}=", document)
               child.run_pending_callbacks
@@ -70,8 +72,9 @@ module Mongoid
       def self.define_creator!(association)
         association.inverse_class.tap do |klass|
           klass.re_define_method("create_#{association.name}") do |*args|
-            attributes, _options = parse_args(*args)
-            document = Factory.execute_build(association.relation_class, attributes, execute_callbacks: false)
+            attributes, type, _opts = parse_args(args)
+
+            document = Factory.execute_build(type || association.relation_class, attributes, execute_callbacks: false)
             doc = _assigning do
               send("#{association.name}=", document)
             end

data/lib/mongoid/association/constrainable.rb

@@ -1,13 +1,10 @@
 # frozen_string_literal: true
-# rubocop:todo all
 
 module Mongoid
   module Association
-
     # Used for converting foreign key values to the correct type based on the
     # types of ids that the document stores.
     module Constrainable
-
       # Convert the supplied object to the appropriate type to set as the
       # foreign key for an association.
       #
@@ -19,11 +16,12 @@ module Mongoid
       # @return [ Object ] The object cast to the correct type.
       def convert_to_foreign_key(object)
         return convert_polymorphic(object) if polymorphic?
-        field = relation_class.fields["_id"]
+
+        field = relation_class.fields['_id']
         if relation_class.using_object_ids?
           BSON::ObjectId.mongoize(object)
         elsif object.is_a?(::Array)
-          object.map!{ |obj| field.mongoize(obj) }
+          object.map! { |obj| field.mongoize(obj) }
         else
           field.mongoize(object)
         end

data/lib/mongoid/association/depending.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
-# rubocop:todo all
 
 module Mongoid
   module Association
-
     # This module defines the behavior for setting up cascading deletes and
     # nullifies for associations, and how to delegate to the appropriate strategy.
     module Depending
@@ -12,19 +10,14 @@ module Mongoid
       included do
         class_attribute :dependents
 
-        # Note the leading underscore: without it, ActiveSupport's
-        # class_attribute would generate a helper method for this attribute
-        # that collides with one it generates for :dependents.
-        #
         # @api private
-        class_attribute :_dependents_owner
+        class_attribute :dependents_owner
 
         self.dependents = []
-        self._dependents_owner = self
+        self.dependents_owner = self
       end
 
       class_methods do
-
         # Returns all dependent association metadata objects.
         #
         # @return [ Array<Mongoid::Association::Relatable> ] The dependent
@@ -34,19 +27,20 @@ module Mongoid
         def _all_dependents
           superclass_dependents = superclass.respond_to?(:_all_dependents) ? superclass._all_dependents : []
           dependents + superclass_dependents.reject do |new_dep|
-            dependents.any? do |old_dep| old_dep.name == new_dep.name
+            dependents.any? do |old_dep|
+              old_dep.name == new_dep.name
             end
           end
         end
       end
 
       # The valid dependent strategies.
-      STRATEGIES = [
-          :delete_all,
-          :destroy,
-          :nullify,
-          :restrict_with_exception,
-          :restrict_with_error
+      STRATEGIES = %i[
+        delete_all
+        destroy
+        nullify
+        restrict_with_exception
+        restrict_with_error
       ]
 
       # Attempt to add the cascading information for the document to know how
@@ -61,14 +55,12 @@ module Mongoid
       def self.define_dependency!(association)
         validate!(association)
         association.inverse_class.tap do |klass|
-          if klass._dependents_owner != klass
+          if klass.dependents_owner != klass
             klass.dependents = []
-            klass._dependents_owner = klass
+            klass.dependents_owner = klass
           end
 
-          if association.dependent && !klass.dependents.include?(association)
-            klass.dependents.push(association)
-          end
+          klass.dependents.push(association) if association.dependent && !klass.dependents.include?(association)
         end
       end
 
@@ -81,11 +73,11 @@ module Mongoid
       # @raises [ Mongoid::Errors::InvalidDependentStrategy ]
       #   Error if invalid.
       def self.validate!(association)
-        unless STRATEGIES.include?(association.dependent)
-          raise Errors::InvalidDependentStrategy.new(association,
-                                                     association.dependent,
-                                                     STRATEGIES)
-        end
+        return if STRATEGIES.include?(association.dependent)
+
+        raise Errors::InvalidDependentStrategy.new(association,
+                                                   association.dependent,
+                                                   STRATEGIES)
       end
 
       # Perform all cascading deletes, destroys, or nullifies. Will delegate to
@@ -104,30 +96,30 @@ module Mongoid
       private
 
       def _dependent_delete_all!(association)
-        if relation = send(association.name)
-          if relation.respond_to?(:dependents) && relation.dependents.blank?
-            relation.clear
-          else
-            ::Array.wrap(send(association.name)).each { |rel| rel.delete }
-          end
+        return unless relation = send(association.name)
+
+        if relation.respond_to?(:dependents) && relation.dependents.blank?
+          relation.clear
+        else
+          ::Array.wrap(send(association.name)).each { |rel| rel.delete }
         end
       end
 
       def _dependent_destroy!(association)
-        if relation = send(association.name)
-          if relation.is_a?(Enumerable)
-            relation.entries
-            relation.each { |doc| doc.destroy }
-          else
-            relation.destroy
-          end
+        return unless relation = send(association.name)
+
+        if relation.is_a?(Enumerable)
+          relation.entries
+          relation.each { |doc| doc.destroy }
+        else
+          relation.destroy
         end
       end
 
       def _dependent_nullify!(association)
-        if relation = send(association.name)
-          relation.nullify
-        end
+        return unless relation = send(association.name)
+
+        relation.nullify
       end
 
       def _dependent_restrict_with_exception!(association)
@@ -137,10 +129,10 @@ module Mongoid
       end
 
       def _dependent_restrict_with_error!(association)
-        if (relation = send(association.name)) && !relation.blank?
-          errors.add(association.name, :destroy_restrict_with_error_dependencies_exist)
-          throw(:abort, false)
-        end
+        return unless (relation = send(association.name)) && !relation.blank?
+
+        errors.add(association.name, :destroy_restrict_with_error_dependencies_exist)
+        throw(:abort, false)
       end
     end
   end

data/lib/mongoid/association/eager.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
-# rubocop:todo all
 
 module Mongoid
   module Association
-
     # Base class for eager load preload functions.
     class Eager
       # Instantiate the eager load class.
@@ -14,12 +12,18 @@ module Mongoid
       # @param [ Array<Mongoid::Association::Relatable> ] associations
       #   Associations to eager load
       # @param [ Array<Document> ] docs Documents to preload the associations
+      # @param [ Boolean ] use_lookup Whether to use $lookup aggregation
+      #   for eager loading. This is used in Criteria#eager_load.
+      # @param [ Array<Hash> ] pipeline The aggregation pipeline to use
+      #   when using $lookup for eager loading.
       #
       # @return [ Base ] The eager load preloader
-      def initialize(associations, docs)
+      def initialize(associations, docs, use_lookup = false, pipeline = [])
         @associations = associations
         @docs = docs
         @grouped_docs = {}
+        @use_lookup = use_lookup
+        @pipeline = pipeline
       end
 
       # Run the preloader.
@@ -30,6 +34,13 @@ module Mongoid
       # @return [ Array ] The list of documents given.
       def run
         @loaded = []
+
+        if @use_lookup
+          preload_with_lookup
+          @loaded = @docs
+          return @loaded.flatten
+        end
+
         while shift_association
           preload
           @loaded << @docs.collect { |d| d.send(@association.name) if d.respond_to?(@association.name) }
@@ -49,6 +60,21 @@ module Mongoid
         raise NotImplementedError
       end
 
+      # Preload the current association using $lookup aggregation.
+      # This method executes the aggregation pipeline
+      # and instantiates the documents.
+      # @example Preload the current association using $lookup.
+      #   loader.preload_with_lookup
+      def preload_with_lookup
+        # For $lookup aggregation, execute pipeline and instantiate documents
+        owner_class = @associations.first.owner_class
+        aggregated_docs = owner_class.collection.aggregate(@pipeline)
+        aggregated_docs.each do |doc|
+          parsed_doc = Factory.from_db(owner_class, doc)
+          @docs << parsed_doc
+        end
+      end
+
       # Retrieves the documents referenced by the association, and
       # yields each one sequentially to the provided block. If the
       # association is not polymorphic, all documents are retrieved in
@@ -64,18 +90,13 @@ module Mongoid
       # When the documents are retrieved, the set of inclusions applied
       # is the set of inclusions applied to the host document minus the
       # association that is being eagerly loaded.
-      private def each_loaded_document_of_class(cls, keys)
-        # Note: keys should not include nil elements.
+      private def each_loaded_document_of_class(cls, keys, &block)
+        # NOTE: keys should not include nil elements.
         # Upstream code is responsible for eliminating nils from keys.
         return cls.none if keys.empty?
 
-        criteria = cls.criteria
-        criteria = criteria.apply_scope(@association.scope)
-        criteria = criteria.any_in(key => keys)
-        criteria.inclusions = criteria.inclusions - [@association]
-        criteria.each do |doc|
-          yield doc
-        end
+        criteria = prepare_criteria_for_loaded_documents(cls, keys)
+        criteria.each(&block)
       end
 
       # Set the pre-loaded document into its parent.
@@ -103,7 +124,7 @@ module Mongoid
       def grouped_docs
         @grouped_docs[@association.name] ||= @docs.group_by do |doc|
           doc.send(group_by_key) if doc.respond_to?(group_by_key)
-        end.reject do |k, v|
+        end.reject do |k, _v|
           k.nil?
         end
       end
@@ -155,6 +176,19 @@ module Mongoid
       def shift_association
         @association = @associations.shift
       end
+
+      # Prepares the criteria to retrieve the documents of the specified
+      # class, that have the foreign key included in the specified list of keys.
+      # When the documents are retrieved, the set of inclusions applied
+      # is the set of inclusions applied to the host document minus the
+      # association that is being eagerly loaded.
+      def prepare_criteria_for_loaded_documents(cls, keys)
+        criteria = cls.criteria
+        criteria = criteria.apply_scope(@association.scope)
+        criteria = criteria.any_in(key => keys)
+        criteria.inclusions = criteria.inclusions - [ @association ]
+        criteria
+      end
     end
   end
 end

data/lib/mongoid/association/eager_loadable.rb

@@ -1,14 +1,11 @@
 # frozen_string_literal: true
-# rubocop:todo all
 
-require "mongoid/association/eager"
+require 'mongoid/association/eager'
 
 module Mongoid
   module Association
-
     # This module defines the eager loading behavior for criteria.
     module EagerLoadable
-
       # Indicates whether the criteria has association
       # inclusions which should be eager loaded.
       #
@@ -24,10 +21,30 @@ module Mongoid
       # @return [ Array<Mongoid::Document> ] The given documents.
       def eager_load(docs)
         docs.tap do |d|
-          if eager_loadable?
-            preload(criteria.inclusions, d)
-          end
+          preload(criteria.inclusions, d) if eager_loadable?
+        end
+      end
+
+      # Load the associations for the given documents using $lookup.
+      #
+      # If any of the associated collections reside in a different cluster than
+      # the root class, falls back to the #includes behavior and logs a warning.
+      #
+      # @return [ Array<Mongoid::Document> ] The given documents.
+      def eager_load_with_lookup
+        offenders = cross_cluster_inclusions
+        if offenders.any?
+          root_client = klass.client_name
+          offender_list = offenders.map { |a| "#{a.name} (#{a.klass.client_name})" }.join(', ')
+          Mongoid.logger.warn(
+            'eager_load cannot use $lookup aggregation because the following associations ' \
+            "reside in a different cluster than #{klass} (client: #{root_client}): " \
+            "#{offender_list}. Falling back to #includes behavior."
+          )
+          return eager_load(docs_for_lookup_fallback)
         end
+
+        preload_for_lookup(criteria)
       end
 
       # Load the associations for the given documents. This will be done
@@ -46,25 +63,136 @@ module Mongoid
         queue.push(klass.root_class.to_s) if klass != klass.root_class
 
         while klass = queue.shift
-          if as = assoc_map.delete(klass)
-            as.each do |assoc|
-              queue << assoc.class_name
-
-              # If this class is nested in the inclusion tree, only load documents
-              # for the association above it. If there is no parent association,
-              # we will include documents from the documents passed to this method.
-              ds = docs
-              if assoc.parent_inclusions.length > 0
-                ds = assoc.parent_inclusions.map{ |p| docs_map[p].to_a }.flatten
-              end
-
-              res = assoc.relation.eager_loader([assoc], ds).run
-
-              docs_map[assoc.name] ||= [].to_set
-              docs_map[assoc.name].merge(res)
-            end
+          next unless as = assoc_map.delete(klass)
+
+          as.each do |assoc|
+            queue << assoc.class_name
+
+            # If this class is nested in the inclusion tree, only load documents
+            # for the association above it. If there is no parent association,
+            # we will include documents from the documents passed to this method.
+            ds = docs
+            ds = assoc.parent_inclusions.map { |p| docs_map[p].to_a }.flatten if assoc.parent_inclusions.length > 0
+
+            res = assoc.relation.eager_loader([ assoc ], ds).run
+
+            docs_map[assoc.name] ||= [].to_set
+            docs_map[assoc.name].merge(res)
+          end
+        end
+      end
+
+      # Load the associations for the given documents. This will be done
+      # recursively to load the associations of the given documents'
+      # associated documents.
+      #
+      # @param [ Array<Mongoid::Association::Relatable> ] associations
+      #   The associations to load.
+      # @param [ Array<Mongoid::Document> ] docs The documents.
+      def preload_for_lookup(criteria)
+        assoc_map = criteria.inclusions.group_by(&:inverse_class_name)
+
+        # match first
+        pipeline = criteria.selector.to_pipeline
+        # then sort, skip, limit
+        pipeline.concat(criteria.options.to_pipeline_for_lookup)
+
+        # account for single-collection inheritance
+        root_class = klass.root_class
+
+        if assoc_map[klass.to_s]
+          assoc_map[klass.to_s].each do |assoc|
+            # Create a copy of the mapping for each top-level association to avoid mutation issues
+            pipeline << create_pipeline(assoc, assoc_map.dup)
+          end
+        end
+
+        if klass != root_class && assoc_map[root_class.to_s]
+          assoc_map[root_class.to_s].each do |assoc|
+            # Create a copy of the mapping for each top-level association to avoid mutation issues
+            pipeline << create_pipeline(assoc, assoc_map.dup)
+          end
+        end
+
+        Eager.new(criteria.inclusions, [], true, pipeline).run
+      end
+
+      private
+
+      # Returns the materialized documents to use when falling back from
+      # $lookup to #includes-style preloading. Must be implemented by each
+      # concrete context class.
+      #
+      # @return [ Array<Mongoid::Document> ] The materialized documents.
+      def docs_for_lookup_fallback
+        raise NotImplementedError, "#{self.class} must implement #docs_for_lookup_fallback"
+      end
+
+      # Returns the inclusions whose target class resides in a different cluster
+      # than the root class.
+      #
+      # @return [ Array<Mongoid::Association::Relatable> ] The offending inclusions.
+      def cross_cluster_inclusions
+        root_client = klass.client_name
+        criteria.inclusions.reject { |assoc| assoc.klass.client_name == root_client }
+      end
+
+      public
+
+      def switch_local_and_foreign_fields?(association)
+        association.is_a?(Mongoid::Association::Referenced::BelongsTo) ||
+          association.is_a?(Mongoid::Association::Referenced::HasAndBelongsToMany)
+      end
+
+      def create_pipeline(current_assoc, mapping)
+        # Build nested pipeline for children and ordering
+        pipeline_stages = []
+
+        # For belongs_to and has_and_belongs_to_many, the foreign key is on the current document
+        # For has_many/has_one, the foreign key is on the related document
+        if switch_local_and_foreign_fields?(current_assoc)
+          local_field = current_assoc.foreign_key
+          foreign_field = current_assoc.primary_key
+        else
+          local_field = current_assoc.primary_key
+          foreign_field = current_assoc.foreign_key
+        end
+
+        # Build the 'as' field with embedded path prefix if needed
+        as_field = current_assoc.name.to_s
+
+        stage = {
+          '$lookup' => {
+            'from' => current_assoc.klass.collection.name,
+            'localField' => local_field,
+            'foreignField' => foreign_field,
+            'as' => as_field
+          }
+        }
+
+        # Add ordering if defined on the association, or default to _id for consistent order
+        if current_assoc.order
+          sort_spec = current_assoc.order.is_a?(Hash) ? current_assoc.order : { current_assoc.order => 1 }
+          pipeline_stages << { '$sort' => sort_spec }
+        else
+          # Default to sorting by _id to maintain insertion order consistency
+          pipeline_stages << { '$sort' => { '_id' => 1 } }
+        end
+
+        # Add nested lookups for child associations
+        # Child associations don't need the embedded_path prefix since they're referenced from the looked-up document
+        # Remove this class from the mapping to prevent infinite loops with circular references
+        class_name = current_assoc.klass.to_s
+        if child_assocs = mapping.delete(class_name)
+          child_assocs.each do |child|
+            pipeline_stages << create_pipeline(child, mapping)
           end
         end
+
+        # Always add pipeline since we always have at least $sort
+        stage['$lookup']['pipeline'] = pipeline_stages
+
+        stage
       end
     end
   end