vendor/rails/activerecord/lib/active_record/association_preload.rb

   1 module ActiveRecord
   2   # See ActiveRecord::AssociationPreload::ClassMethods for documentation.
   3   module AssociationPreload #:nodoc:
   4     def self.included(base)
   5       base.extend(ClassMethods)
   6     end
   7
   8     # Implements the details of eager loading of ActiveRecord associations.
   9     # Application developers should not use this module directly.
  10     #
  11     # ActiveRecord::Base is extended with this module. The source code in
  12     # ActiveRecord::Base references methods defined in this module.
  13     #
  14     # Note that 'eager loading' and 'preloading' are actually the same thing.
  15     # However, there are two different eager loading strategies.
  16     #
  17     # The first one is by using table joins. This was only strategy available
  18     # prior to Rails 2.1. Suppose that you have an Author model with columns
  19     # 'name' and 'age', and a Book model with columns 'name' and 'sales'. Using
  20     # this strategy, ActiveRecord would try to retrieve all data for an author
  21     # and all of its books via a single query:
  22     #
  23     #   SELECT * FROM authors
  24     #   LEFT OUTER JOIN books ON authors.id = books.id
  25     #   WHERE authors.name = 'Ken Akamatsu'
  26     #
  27     # However, this could result in many rows that contain redundant data. After
  28     # having received the first row, we already have enough data to instantiate
  29     # the Author object. In all subsequent rows, only the data for the joined
  30     # 'books' table is useful; the joined 'authors' data is just redundant, and
  31     # processing this redundant data takes memory and CPU time. The problem
  32     # quickly becomes worse and worse as the level of eager loading increases
  33     # (i.e. if ActiveRecord is to eager load the associations' assocations as
  34     # well).
  35     #
  36     # The second strategy is to use multiple database queries, one for each
  37     # level of association. Since Rails 2.1, this is the default strategy. In
  38     # situations where a table join is necessary (e.g. when the +:conditions+
  39     # option references an association's column), it will fallback to the table
  40     # join strategy.
  41     #
  42     # See also ActiveRecord::Associations::ClassMethods, which explains eager
  43     # loading in a more high-level (application developer-friendly) manner.
  44     module ClassMethods
  45       protected
  46
  47       # Eager loads the named associations for the given ActiveRecord record(s).
  48       #
  49       # In this description, 'association name' shall refer to the name passed
  50       # to an association creation method. For example, a model that specifies
  51       # <tt>belongs_to :author</tt>, <tt>has_many :buyers</tt> has association
  52       # names +:author+ and +:buyers+.
  53       #
  54       # == Parameters
  55       # +records+ is an array of ActiveRecord::Base. This array needs not be flat,
  56       # i.e. +records+ itself may also contain arrays of records. In any case,
  57       # +preload_associations+ will preload the associations all records by
  58       # flattening +records+.
  59       #
  60       # +associations+ specifies one or more associations that you want to
  61       # preload. It may be:
  62       # - a Symbol or a String which specifies a single association name. For
  63       #   example, specifiying +:books+ allows this method to preload all books
  64       #   for an Author.
  65       # - an Array which specifies multiple association names. This array
  66       #   is processed recursively. For example, specifying <tt>[:avatar, :books]</tt>
  67       #   allows this method to preload an author's avatar as well as all of his
  68       #   books.
  69       # - a Hash which specifies multiple association names, as well as
  70       #   association names for the to-be-preloaded association objects. For
  71       #   example, specifying <tt>{ :author => :avatar }</tt> will preload a
  72       #   book's author, as well as that author's avatar.
  73       #
  74       # +:associations+ has the same format as the +:include+ option for
  75       # <tt>ActiveRecord::Base.find</tt>. So +associations+ could look like this:
  76       #
  77       #   :books
  78       #   [ :books, :author ]
  79       #   { :author => :avatar }
  80       #   [ :books, { :author => :avatar } ]
  81       #
  82       # +preload_options+ contains options that will be passed to ActiveRecord#find
  83       # (which is called under the hood for preloading records). But it is passed
  84       # only one level deep in the +associations+ argument, i.e. it's not passed
  85       # to the child associations when +associations+ is a Hash.
  86       def preload_associations(records, associations, preload_options={})
  87         records = [records].flatten.compact.uniq
  88         return if records.empty?
  89         case associations
  90         when Array then associations.each {|association| preload_associations(records, association, preload_options)}
  91         when Symbol, String then preload_one_association(records, associations.to_sym, preload_options)
  92         when Hash then
  93           associations.each do |parent, child|
  94             raise "parent must be an association name" unless parent.is_a?(String) || parent.is_a?(Symbol)
  95             preload_associations(records, parent, preload_options)
  96             reflection = reflections[parent]
  97             parents = records.map {|record| record.send(reflection.name)}.flatten
  98             unless parents.empty? || parents.first.nil?
  99               parents.first.class.preload_associations(parents, child)
 100             end
 101           end
 102         end
 103       end
 104
 105       private
 106
 107       # Preloads a specific named association for the given records. This is
 108       # called by +preload_associations+ as its base case.
 109       def preload_one_association(records, association, preload_options={})
 110         class_to_reflection = {}
 111         # Not all records have the same class, so group then preload
 112         # group on the reflection itself so that if various subclass share the same association then we do not split them
 113         # unnecessarily
 114         records.group_by {|record| class_to_reflection[record.class] ||= record.class.reflections[association]}.each do |reflection, records|
 115           raise ConfigurationError, "Association named '#{ association }' was not found; perhaps you misspelled it?" unless reflection
 116
 117           # 'reflection.macro' can return 'belongs_to', 'has_many', etc. Thus,
 118           # the following could call 'preload_belongs_to_association',
 119           # 'preload_has_many_association', etc.
 120           send("preload_#{reflection.macro}_association", records, reflection, preload_options)
 121         end
 122       end
 123
 124       def add_preloaded_records_to_collection(parent_records, reflection_name, associated_record)
 125         parent_records.each do |parent_record|
 126           association_proxy = parent_record.send(reflection_name)
 127           association_proxy.loaded
 128           association_proxy.target.push(*[associated_record].flatten)
 129         end
 130       end
 131
 132       def add_preloaded_record_to_collection(parent_records, reflection_name, associated_record)
 133         parent_records.each do |parent_record|
 134           parent_record.send("set_#{reflection_name}_target", associated_record)
 135         end
 136       end
 137
 138       def set_association_collection_records(id_to_record_map, reflection_name, associated_records, key)
 139         associated_records.each do |associated_record|
 140           mapped_records = id_to_record_map[associated_record[key].to_s]
 141           add_preloaded_records_to_collection(mapped_records, reflection_name, associated_record)
 142         end
 143       end
 144
 145       def set_association_single_records(id_to_record_map, reflection_name, associated_records, key)
 146         seen_keys = {}
 147         associated_records.each do |associated_record|
 148           #this is a has_one or belongs_to: there should only be one record.
 149           #Unfortunately we can't (in portable way) ask the database for 'all records where foo_id in (x,y,z), but please
 150           # only one row per distinct foo_id' so this where we enforce that
 151           next if seen_keys[associated_record[key].to_s]
 152           seen_keys[associated_record[key].to_s] = true
 153           mapped_records = id_to_record_map[associated_record[key].to_s]
 154           mapped_records.each do |mapped_record|
 155             mapped_record.send("set_#{reflection_name}_target", associated_record)
 156           end
 157         end
 158       end
 159
 160       # Given a collection of ActiveRecord objects, constructs a Hash which maps
 161       # the objects' IDs to the relevant objects. Returns a 2-tuple
 162       # <tt>(id_to_record_map, ids)</tt> where +id_to_record_map+ is the Hash,
 163       # and +ids+ is an Array of record IDs.
 164       def construct_id_map(records, primary_key=nil)
 165         id_to_record_map = {}
 166         ids = []
 167         records.each do |record|
 168           primary_key ||= record.class.primary_key
 169           ids << record[primary_key]
 170           mapped_records = (id_to_record_map[ids.last.to_s] ||= [])
 171           mapped_records << record
 172         end
 173         ids.uniq!
 174         return id_to_record_map, ids
 175       end
 176
 177       def preload_has_and_belongs_to_many_association(records, reflection, preload_options={})
 178         table_name = reflection.klass.quoted_table_name
 179         id_to_record_map, ids = construct_id_map(records)
 180         records.each {|record| record.send(reflection.name).loaded}
 181         options = reflection.options
 182
 183         conditions = "t0.#{reflection.primary_key_name} #{in_or_equals_for_ids(ids)}"
 184         conditions << append_conditions(reflection, preload_options)
 185
 186         associated_records = reflection.klass.find(:all, :conditions => [conditions, ids],
 187         :include => options[:include],
 188         :joins => "INNER JOIN #{connection.quote_table_name options[:join_table]} as t0 ON #{reflection.klass.quoted_table_name}.#{reflection.klass.primary_key} = t0.#{reflection.association_foreign_key}",
 189         :select => "#{options[:select] || table_name+'.*'}, t0.#{reflection.primary_key_name} as the_parent_record_id",
 190         :order => options[:order])
 191
 192         set_association_collection_records(id_to_record_map, reflection.name, associated_records, 'the_parent_record_id')
 193       end
 194
 195       def preload_has_one_association(records, reflection, preload_options={})
 196         return if records.first.send("loaded_#{reflection.name}?")
 197         id_to_record_map, ids = construct_id_map(records)
 198         options = reflection.options
 199         records.each {|record| record.send("set_#{reflection.name}_target", nil)}
 200         if options[:through]
 201           through_records = preload_through_records(records, reflection, options[:through])
 202           through_reflection = reflections[options[:through]]
 203           through_primary_key = through_reflection.primary_key_name
 204           unless through_records.empty?
 205             source = reflection.source_reflection.name
 206             through_records.first.class.preload_associations(through_records, source)
 207             through_records.each do |through_record|
 208               add_preloaded_record_to_collection(id_to_record_map[through_record[through_primary_key].to_s],
 209                                                  reflection.name, through_record.send(source))
 210             end
 211           end
 212         else
 213           set_association_single_records(id_to_record_map, reflection.name, find_associated_records(ids, reflection, preload_options), reflection.primary_key_name)
 214         end
 215       end
 216
 217       def preload_has_many_association(records, reflection, preload_options={})
 218         return if records.first.send(reflection.name).loaded?
 219         options = reflection.options
 220
 221         primary_key_name = reflection.through_reflection_primary_key_name
 222         id_to_record_map, ids = construct_id_map(records, primary_key_name)
 223         records.each {|record| record.send(reflection.name).loaded}
 224
 225         if options[:through]
 226           through_records = preload_through_records(records, reflection, options[:through])
 227           through_reflection = reflections[options[:through]]
 228           unless through_records.empty?
 229             source = reflection.source_reflection.name
 230             through_records.first.class.preload_associations(through_records, source, options)
 231             through_records.each do |through_record|
 232               through_record_id = through_record[reflection.through_reflection_primary_key].to_s
 233               add_preloaded_records_to_collection(id_to_record_map[through_record_id], reflection.name, through_record.send(source))
 234             end
 235           end
 236
 237         else
 238           set_association_collection_records(id_to_record_map, reflection.name, find_associated_records(ids, reflection, preload_options),
 239                                              reflection.primary_key_name)
 240         end
 241       end
 242
 243       def preload_through_records(records, reflection, through_association)
 244         through_reflection = reflections[through_association]
 245         through_primary_key = through_reflection.primary_key_name
 246
 247         if reflection.options[:source_type]
 248           interface = reflection.source_reflection.options[:foreign_type]
 249           preload_options = {:conditions => ["#{connection.quote_column_name interface} = ?", reflection.options[:source_type]]}
 250
 251           records.compact!
 252           records.first.class.preload_associations(records, through_association, preload_options)
 253
 254           # Dont cache the association - we would only be caching a subset
 255           through_records = []
 256           records.each do |record|
 257             proxy = record.send(through_association)
 258
 259             if proxy.respond_to?(:target)
 260               through_records << proxy.target
 261               proxy.reset
 262             else # this is a has_one :through reflection
 263               through_records << proxy if proxy
 264             end
 265           end
 266           through_records.flatten!
 267         else
 268           records.first.class.preload_associations(records, through_association)
 269           through_records = records.map {|record| record.send(through_association)}.flatten
 270         end
 271         through_records.compact!
 272         through_records
 273       end
 274
 275       def preload_belongs_to_association(records, reflection, preload_options={})
 276         return if records.first.send("loaded_#{reflection.name}?")
 277         options = reflection.options
 278         primary_key_name = reflection.primary_key_name
 279
 280         if options[:polymorphic]
 281           polymorph_type = options[:foreign_type]
 282           klasses_and_ids = {}
 283
 284           # Construct a mapping from klass to a list of ids to load and a mapping of those ids back to their parent_records
 285           records.each do |record|
 286             if klass = record.send(polymorph_type)
 287               klass_id = record.send(primary_key_name)
 288               if klass_id
 289                 id_map = klasses_and_ids[klass] ||= {}
 290                 id_list_for_klass_id = (id_map[klass_id.to_s] ||= [])
 291                 id_list_for_klass_id << record
 292               end
 293             end
 294           end
 295           klasses_and_ids = klasses_and_ids.to_a
 296         else
 297           id_map = {}
 298           records.each do |record|
 299             key = record.send(primary_key_name)
 300             if key
 301               mapped_records = (id_map[key.to_s] ||= [])
 302               mapped_records << record
 303             end
 304           end
 305           klasses_and_ids = [[reflection.klass.name, id_map]]
 306         end
 307
 308         klasses_and_ids.each do |klass_and_id|
 309           klass_name, id_map = *klass_and_id
 310           klass = klass_name.constantize
 311
 312           table_name = klass.quoted_table_name
 313           primary_key = klass.primary_key
 314           column_type = klass.columns.detect{|c| c.name == primary_key}.type
 315           ids = id_map.keys.map do |id|
 316             if column_type == :integer
 317               id.to_i
 318             elsif column_type == :float
 319               id.to_f
 320             else
 321               id
 322             end
 323           end
 324           conditions = "#{table_name}.#{connection.quote_column_name(primary_key)} #{in_or_equals_for_ids(ids)}"
 325           conditions << append_conditions(reflection, preload_options)
 326           associated_records = klass.find(:all, :conditions => [conditions, ids],
 327                                           :include => options[:include],
 328                                           :select => options[:select],
 329                                           :joins => options[:joins],
 330                                           :order => options[:order])
 331           set_association_single_records(id_map, reflection.name, associated_records, primary_key)
 332         end
 333       end
 334
 335       def find_associated_records(ids, reflection, preload_options)
 336         options = reflection.options
 337         table_name = reflection.klass.quoted_table_name
 338
 339         if interface = reflection.options[:as]
 340           conditions = "#{reflection.klass.quoted_table_name}.#{connection.quote_column_name "#{interface}_id"} #{in_or_equals_for_ids(ids)} and #{reflection.klass.quoted_table_name}.#{connection.quote_column_name "#{interface}_type"} = '#{self.base_class.sti_name}'"
 341         else
 342           foreign_key = reflection.primary_key_name
 343           conditions = "#{reflection.klass.quoted_table_name}.#{foreign_key} #{in_or_equals_for_ids(ids)}"
 344         end
 345
 346         conditions << append_conditions(reflection, preload_options)
 347
 348         reflection.klass.find(:all,
 349                               :select => (preload_options[:select] || options[:select] || "#{table_name}.*"),
 350                               :include => preload_options[:include] || options[:include],
 351                               :conditions => [conditions, ids],
 352                               :joins => options[:joins],
 353                               :group => preload_options[:group] || options[:group],
 354                               :order => preload_options[:order] || options[:order])
 355       end
 356
 357
 358       def interpolate_sql_for_preload(sql)
 359         instance_eval("%@#{sql.gsub('@', '\@')}@")
 360       end
 361
 362       def append_conditions(reflection, preload_options)
 363         sql = ""
 364         sql << " AND (#{interpolate_sql_for_preload(reflection.sanitized_conditions)})" if reflection.sanitized_conditions
 365         sql << " AND (#{sanitize_sql preload_options[:conditions]})" if preload_options[:conditions]
 366         sql
 367       end
 368
 369       def in_or_equals_for_ids(ids)
 370         ids.size > 1 ? "IN (?)" : "= ?"
 371       end
 372     end
 373   end
 374 end