Method: ActiveRecord::Associations::Preloader#initialize

Defined in:
activerecord/lib/active_record/associations/preloader.rb

#initialize(records:, associations:, scope: nil, available_records: [], associate_by_default: true) ⇒ Preloader

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 belongs_to :author, has_many :buyers 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 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 [:avatar, :books] allows this method to preload an author’s avatar as well as all of their books.

  • a Hash which specifies multiple association names, as well as association names for the to-be-preloaded association objects. For example, specifying { author: :avatar } will preload a book’s author, as well as that author’s avatar.

:associations has the same format as the arguments to ActiveRecord::QueryMethods#includes. So associations could look like this:

:books
[ :books, :author ]
{ author: :avatar }
[ :books, { author: :avatar } ]

available_records is an array of ActiveRecord::Base. The Preloader will try to use the objects in this array to preload the requested associations before querying the database. This can save database queries by reusing in-memory objects. The optimization is only applied to single associations (i.e. :belongs_to, :has_one) with no scopes.



99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'activerecord/lib/active_record/associations/preloader.rb', line 99

def initialize(records:, associations:, scope: nil, available_records: [], associate_by_default: true)
  @records = records
  @associations = associations
  @scope = scope
  @available_records = available_records || []
  @associate_by_default = associate_by_default

  @tree = Branch.new(
    parent: nil,
    association: nil,
    children: @associations,
    associate_by_default: @associate_by_default,
    scope: @scope
  )
  @tree.preloaded_records = @records
end