preload_associations

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 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 [:avatar, :books] 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 { :author => :avatar } will preload a book’s author, as well as that author’s avatar.

:associations has the same format as the :include option for ActiveRecord::Base.find. So associations could look like this:

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

preload_options contains options that will be passed to ActiveRecord::Base#find (which is called under the hood for preloading records). But it is passed only one level deep in the associations argument, i.e. it’s not passed to the child associations when associations is a Hash.

# File activerecord/lib/active_record/association_preload.rb, line 87
      def preload_associations(records, associations, preload_options={})
        records = Array.wrap(records).compact
        return if records.empty?
        case associations
        when Array then associations.each {|association| preload_associations(records, association, preload_options)}
        when Symbol, String then preload_one_association(records, associations.to_sym, preload_options)
        when Hash then
          associations.each do |parent, child|
            raise "parent must be an association name" unless parent.is_a?(String) || parent.is_a?(Symbol)
            preload_associations(records, parent, preload_options)
            reflection = reflections[parent]
            parents = records.sum { |record| Array.wrap(record.send(reflection.name)) }
            unless parents.empty?
              parents = parents.uniq if reflection.macro == :belongs_to
              parents.first.class.preload_associations(parents, child)
            end
          end
        end
      end