activerecord 6.0.0

data/lib/active_record/associations/preloader.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Associations
+    # Implements the details of eager loading of Active Record associations.
+    #
+    # Suppose that you have the following two Active Record models:
+    #
+    #   class Author < ActiveRecord::Base
+    #     # columns: name, age
+    #     has_many :books
+    #   end
+    #
+    #   class Book < ActiveRecord::Base
+    #     # columns: title, sales, author_id
+    #   end
+    #
+    # When you load an author with all associated books Active Record will make
+    # multiple queries like this:
+    #
+    #   Author.includes(:books).where(name: ['bell hooks', 'Homer']).to_a
+    #
+    #   => SELECT `authors`.* FROM `authors` WHERE `name` IN ('bell hooks', 'Homer')
+    #   => SELECT `books`.* FROM `books` WHERE `author_id` IN (2, 5)
+    #
+    # Active Record saves the ids of the records from the first query to use in
+    # the second. Depending on the number of associations involved there can be
+    # arbitrarily many SQL queries made.
+    #
+    # However, if there is a WHERE clause that spans across tables Active
+    # Record will fall back to a slightly more resource-intensive single query:
+    #
+    #   Author.includes(:books).where(books: {title: 'Illiad'}).to_a
+    #   => SELECT `authors`.`id` AS t0_r0, `authors`.`name` AS t0_r1, `authors`.`age` AS t0_r2,
+    #             `books`.`id`   AS t1_r0, `books`.`title`  AS t1_r1, `books`.`sales` AS t1_r2
+    #      FROM `authors`
+    #      LEFT OUTER JOIN `books` ON `authors`.`id` =  `books`.`author_id`
+    #      WHERE `books`.`title` = 'Illiad'
+    #
+    # This could result in many rows that contain redundant data and it performs poorly at scale
+    # and is therefore only used when necessary.
+    #
+    class Preloader #:nodoc:
+      extend ActiveSupport::Autoload
+
+      eager_autoload do
+        autoload :Association,        "active_record/associations/preloader/association"
+        autoload :ThroughAssociation, "active_record/associations/preloader/through_association"
+      end
+
+      # Eager loads the named associations for the given Active Record record(s).
+      #
+      # In this description, 'association name' shall refer to the name passed
+      # to an association creation method. For example, a model that specifies
+      # <tt>belongs_to :author</tt>, <tt>has_many :buyers</tt> has association
+      # names +:author+ and +:buyers+.
+      #
+      # == Parameters
+      # +records+ is an array of ActiveRecord::Base. This array needs not be flat,
+      # i.e. +records+ itself may also contain arrays of records. In any case,
+      # +preload_associations+ will preload the all associations records by
+      # flattening +records+.
+      #
+      # +associations+ specifies one or more associations that you want to
+      # preload. It may be:
+      # - a Symbol or a String which specifies a single association name. For
+      #   example, specifying +:books+ allows this method to preload all books
+      #   for an Author.
+      # - an Array which specifies multiple association names. This array
+      #   is processed recursively. For example, specifying <tt>[:avatar, :books]</tt>
+      #   allows this method to preload an author's avatar as well as all of his
+      #   books.
+      # - a Hash which specifies multiple association names, as well as
+      #   association names for the to-be-preloaded association objects. For
+      #   example, specifying <tt>{ author: :avatar }</tt> will preload a
+      #   book's author, as well as that author's avatar.
+      #
+      # +:associations+ has the same format as the +:include+ option for
+      # <tt>ActiveRecord::Base.find</tt>. So +associations+ could look like this:
+      #
+      #   :books
+      #   [ :books, :author ]
+      #   { author: :avatar }
+      #   [ :books, { author: :avatar } ]
+      def preload(records, associations, preload_scope = nil)
+        records = Array.wrap(records).compact
+
+        if records.empty?
+          []
+        else
+          Array.wrap(associations).flat_map { |association|
+            preloaders_on association, records, preload_scope
+          }
+        end
+      end
+
+      private
+
+        # Loads all the given data into +records+ for the +association+.
+        def preloaders_on(association, records, scope, polymorphic_parent = false)
+          case association
+          when Hash
+            preloaders_for_hash(association, records, scope, polymorphic_parent)
+          when Symbol, String
+            preloaders_for_one(association, records, scope, polymorphic_parent)
+          else
+            raise ArgumentError, "#{association.inspect} was not recognized for preload"
+          end
+        end
+
+        def preloaders_for_hash(association, records, scope, polymorphic_parent)
+          association.flat_map { |parent, child|
+            grouped_records(parent, records, polymorphic_parent).flat_map do |reflection, reflection_records|
+              loaders = preloaders_for_reflection(reflection, reflection_records, scope)
+              recs = loaders.flat_map(&:preloaded_records)
+              child_polymorphic_parent = reflection && reflection.options[:polymorphic]
+              loaders.concat Array.wrap(child).flat_map { |assoc|
+                preloaders_on assoc, recs, scope, child_polymorphic_parent
+              }
+              loaders
+            end
+          }
+        end
+
+        # Loads all the given data into +records+ for a singular +association+.
+        #
+        # Functions by instantiating a preloader class such as Preloader::Association and
+        # call the +run+ method for each passed in class in the +records+ argument.
+        #
+        # Not all records have the same class, so group then preload group on the reflection
+        # itself so that if various subclass share the same association then we do not split
+        # them unnecessarily
+        #
+        # Additionally, polymorphic belongs_to associations can have multiple associated
+        # classes, depending on the polymorphic_type field. So we group by the classes as
+        # well.
+        def preloaders_for_one(association, records, scope, polymorphic_parent)
+          grouped_records(association, records, polymorphic_parent)
+            .flat_map do |reflection, reflection_records|
+              preloaders_for_reflection reflection, reflection_records, scope
+            end
+        end
+
+        def preloaders_for_reflection(reflection, records, scope)
+          records.group_by { |record| record.association(reflection.name).klass }.map do |rhs_klass, rs|
+            preloader_for(reflection, rs).new(rhs_klass, rs, reflection, scope).run
+          end
+        end
+
+        def grouped_records(association, records, polymorphic_parent)
+          h = {}
+          records.each do |record|
+            reflection = record.class._reflect_on_association(association)
+            next if polymorphic_parent && !reflection || !record.association(association).klass
+            (h[reflection] ||= []) << record
+          end
+          h
+        end
+
+        class AlreadyLoaded # :nodoc:
+          def initialize(klass, owners, reflection, preload_scope)
+            @owners = owners
+            @reflection = reflection
+          end
+
+          def run
+            self
+          end
+
+          def preloaded_records
+            @preloaded_records ||= records_by_owner.flat_map(&:last)
+          end
+
+          def records_by_owner
+            @records_by_owner ||= owners.each_with_object({}) do |owner, result|
+              result[owner] = Array(owner.association(reflection.name).target)
+            end
+          end
+
+          private
+            attr_reader :owners, :reflection
+        end
+
+        # Returns a class containing the logic needed to load preload the data
+        # and attach it to a relation. The class returned implements a `run` method
+        # that accepts a preloader.
+        def preloader_for(reflection, owners)
+          if owners.first.association(reflection.name).loaded?
+            return AlreadyLoaded
+          end
+          reflection.check_preloadable!
+
+          if reflection.options[:through]
+            ThroughAssociation
+          else
+            Association
+          end
+        end
+    end
+  end
+end

data/lib/active_record/associations/preloader/association.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Associations
+    class Preloader
+      class Association #:nodoc:
+        def initialize(klass, owners, reflection, preload_scope)
+          @klass         = klass
+          @owners        = owners
+          @reflection    = reflection
+          @preload_scope = preload_scope
+          @model         = owners.first && owners.first.class
+        end
+
+        def run
+          if !preload_scope || preload_scope.empty_scope?
+            owners.each do |owner|
+              associate_records_to_owner(owner, records_by_owner[owner] || [])
+            end
+          else
+            # Custom preload scope is used and
+            # the association can not be marked as loaded
+            # Loading into a Hash instead
+            records_by_owner
+          end
+          self
+        end
+
+        def records_by_owner
+          # owners can be duplicated when a relation has a collection association join
+          # #compare_by_identity makes such owners different hash keys
+          @records_by_owner ||= preloaded_records.each_with_object({}.compare_by_identity) do |record, result|
+            owners_by_key[convert_key(record[association_key_name])].each do |owner|
+              (result[owner] ||= []) << record
+            end
+          end
+        end
+
+        def preloaded_records
+          return @preloaded_records if defined?(@preloaded_records)
+          @preloaded_records = owner_keys.empty? ? [] : records_for(owner_keys)
+        end
+
+        private
+          attr_reader :owners, :reflection, :preload_scope, :model, :klass
+
+          # The name of the key on the associated records
+          def association_key_name
+            reflection.join_primary_key(klass)
+          end
+
+          # The name of the key on the model which declares the association
+          def owner_key_name
+            reflection.join_foreign_key
+          end
+
+          def associate_records_to_owner(owner, records)
+            association = owner.association(reflection.name)
+            if reflection.collection?
+              association.target = records
+            else
+              association.target = records.first
+            end
+          end
+
+          def owner_keys
+            @owner_keys ||= owners_by_key.keys
+          end
+
+          def owners_by_key
+            @owners_by_key ||= owners.each_with_object({}) do |owner, result|
+              key = convert_key(owner[owner_key_name])
+              (result[key] ||= []) << owner if key
+            end
+          end
+
+          def key_conversion_required?
+            unless defined?(@key_conversion_required)
+              @key_conversion_required = (association_key_type != owner_key_type)
+            end
+
+            @key_conversion_required
+          end
+
+          def convert_key(key)
+            if key_conversion_required?
+              key.to_s
+            else
+              key
+            end
+          end
+
+          def association_key_type
+            @klass.type_for_attribute(association_key_name).type
+          end
+
+          def owner_key_type
+            @model.type_for_attribute(owner_key_name).type
+          end
+
+          def records_for(ids)
+            scope.where(association_key_name => ids).load do |record|
+              # Processing only the first owner
+              # because the record is modified but not an owner
+              owner = owners_by_key[convert_key(record[association_key_name])].first
+              association = owner.association(reflection.name)
+              association.set_inverse_instance(record)
+            end
+          end
+
+          def scope
+            @scope ||= build_scope
+          end
+
+          def reflection_scope
+            @reflection_scope ||= reflection.scope ? reflection.scope_for(klass.unscoped) : klass.unscoped
+          end
+
+          def build_scope
+            scope = klass.scope_for_association
+
+            if reflection.type && !reflection.through_reflection?
+              scope.where!(reflection.type => model.polymorphic_name)
+            end
+
+            scope.merge!(reflection_scope) if reflection.scope
+            scope.merge!(preload_scope) if preload_scope
+            scope
+          end
+      end
+    end
+  end
+end

data/lib/active_record/associations/preloader/through_association.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Associations
+    class Preloader
+      class ThroughAssociation < Association # :nodoc:
+        PRELOADER = ActiveRecord::Associations::Preloader.new
+
+        def initialize(*)
+          super
+          @already_loaded = owners.first.association(through_reflection.name).loaded?
+        end
+
+        def preloaded_records
+          @preloaded_records ||= source_preloaders.flat_map(&:preloaded_records)
+        end
+
+        def records_by_owner
+          return @records_by_owner if defined?(@records_by_owner)
+          source_records_by_owner = source_preloaders.map(&:records_by_owner).reduce(:merge)
+          through_records_by_owner = through_preloaders.map(&:records_by_owner).reduce(:merge)
+
+          @records_by_owner = owners.each_with_object({}) do |owner, result|
+            through_records = through_records_by_owner[owner] || []
+
+            if @already_loaded
+              if source_type = reflection.options[:source_type]
+                through_records = through_records.select do |record|
+                  record[reflection.foreign_type] == source_type
+                end
+              end
+            end
+
+            records = through_records.flat_map do |record|
+              source_records_by_owner[record]
+            end
+
+            records.compact!
+            records.sort_by! { |rhs| preload_index[rhs] } if scope.order_values.any?
+            records.uniq! if scope.distinct_value
+            result[owner] = records
+          end
+        end
+
+        private
+          def source_preloaders
+            @source_preloaders ||= PRELOADER.preload(middle_records, source_reflection.name, scope)
+          end
+
+          def middle_records
+            through_preloaders.flat_map(&:preloaded_records)
+          end
+
+          def through_preloaders
+            @through_preloaders ||= PRELOADER.preload(owners, through_reflection.name, through_scope)
+          end
+
+          def through_reflection
+            reflection.through_reflection
+          end
+
+          def source_reflection
+            reflection.source_reflection
+          end
+
+          def preload_index
+            @preload_index ||= preloaded_records.each_with_object({}).with_index do |(record, result), index|
+              result[record] = index
+            end
+          end
+
+          def through_scope
+            scope = through_reflection.klass.unscoped
+            options = reflection.options
+
+            values = reflection_scope.values
+            if annotations = values[:annotate]
+              scope.annotate!(*annotations)
+            end
+
+            if options[:source_type]
+              scope.where! reflection.foreign_type => options[:source_type]
+            elsif !reflection_scope.where_clause.empty?
+              scope.where_clause = reflection_scope.where_clause
+
+              if includes = values[:includes]
+                scope.includes!(source_reflection.name => includes)
+              else
+                scope.includes!(source_reflection.name)
+              end
+
+              if values[:references] && !values[:references].empty?
+                scope.references!(values[:references])
+              else
+                scope.references!(source_reflection.table_name)
+              end
+
+              if joins = values[:joins]
+                scope.joins!(source_reflection.name => joins)
+              end
+
+              if left_outer_joins = values[:left_outer_joins]
+                scope.left_outer_joins!(source_reflection.name => left_outer_joins)
+              end
+
+              if scope.eager_loading? && order_values = values[:order]
+                scope = scope.order(order_values)
+              end
+            end
+
+            scope
+          end
+      end
+    end
+  end
+end