Updated README.rdoc again
[feedcatcher.git] / 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.compact
98 unless parents.empty?
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.with_exclusive_scope do
187 reflection.klass.find(:all, :conditions => [conditions, ids],
188 :include => options[:include],
189 :joins => "INNER JOIN #{connection.quote_table_name options[:join_table]} t0 ON #{reflection.klass.quoted_table_name}.#{reflection.klass.primary_key} = t0.#{reflection.association_foreign_key}",
190 :select => "#{options[:select] || table_name+'.*'}, t0.#{reflection.primary_key_name} as the_parent_record_id",
191 :order => options[:order])
192 end
193 set_association_collection_records(id_to_record_map, reflection.name, associated_records, 'the_parent_record_id')
194 end
195
196 def preload_has_one_association(records, reflection, preload_options={})
197 return if records.first.send("loaded_#{reflection.name}?")
198 id_to_record_map, ids = construct_id_map(records, reflection.options[:primary_key])
199 options = reflection.options
200 records.each {|record| record.send("set_#{reflection.name}_target", nil)}
201 if options[:through]
202 through_records = preload_through_records(records, reflection, options[:through])
203 through_reflection = reflections[options[:through]]
204 through_primary_key = through_reflection.primary_key_name
205 unless through_records.empty?
206 source = reflection.source_reflection.name
207 through_records.first.class.preload_associations(through_records, source)
208 if through_reflection.macro == :belongs_to
209 rev_id_to_record_map, rev_ids = construct_id_map(records, through_primary_key)
210 rev_primary_key = through_reflection.klass.primary_key
211 through_records.each do |through_record|
212 add_preloaded_record_to_collection(rev_id_to_record_map[through_record[rev_primary_key].to_s],
213 reflection.name, through_record.send(source))
214 end
215 else
216 through_records.each do |through_record|
217 add_preloaded_record_to_collection(id_to_record_map[through_record[through_primary_key].to_s],
218 reflection.name, through_record.send(source))
219 end
220 end
221 end
222 else
223 set_association_single_records(id_to_record_map, reflection.name, find_associated_records(ids, reflection, preload_options), reflection.primary_key_name)
224 end
225 end
226
227 def preload_has_many_association(records, reflection, preload_options={})
228 return if records.first.send(reflection.name).loaded?
229 options = reflection.options
230
231 primary_key_name = reflection.through_reflection_primary_key_name
232 id_to_record_map, ids = construct_id_map(records, primary_key_name || reflection.options[:primary_key])
233 records.each {|record| record.send(reflection.name).loaded}
234
235 if options[:through]
236 through_records = preload_through_records(records, reflection, options[:through])
237 through_reflection = reflections[options[:through]]
238 unless through_records.empty?
239 source = reflection.source_reflection.name
240 through_records.first.class.preload_associations(through_records, source, options)
241 through_records.each do |through_record|
242 through_record_id = through_record[reflection.through_reflection_primary_key].to_s
243 add_preloaded_records_to_collection(id_to_record_map[through_record_id], reflection.name, through_record.send(source))
244 end
245 end
246
247 else
248 set_association_collection_records(id_to_record_map, reflection.name, find_associated_records(ids, reflection, preload_options),
249 reflection.primary_key_name)
250 end
251 end
252
253 def preload_through_records(records, reflection, through_association)
254 through_reflection = reflections[through_association]
255 through_primary_key = through_reflection.primary_key_name
256
257 if reflection.options[:source_type]
258 interface = reflection.source_reflection.options[:foreign_type]
259 preload_options = {:conditions => ["#{connection.quote_column_name interface} = ?", reflection.options[:source_type]]}
260
261 records.compact!
262 records.first.class.preload_associations(records, through_association, preload_options)
263
264 # Dont cache the association - we would only be caching a subset
265 through_records = []
266 records.each do |record|
267 proxy = record.send(through_association)
268
269 if proxy.respond_to?(:target)
270 through_records << proxy.target
271 proxy.reset
272 else # this is a has_one :through reflection
273 through_records << proxy if proxy
274 end
275 end
276 through_records.flatten!
277 else
278 records.first.class.preload_associations(records, through_association)
279 through_records = records.map {|record| record.send(through_association)}.flatten
280 end
281 through_records.compact!
282 through_records
283 end
284
285 def preload_belongs_to_association(records, reflection, preload_options={})
286 return if records.first.send("loaded_#{reflection.name}?")
287 options = reflection.options
288 primary_key_name = reflection.primary_key_name
289
290 if options[:polymorphic]
291 polymorph_type = options[:foreign_type]
292 klasses_and_ids = {}
293
294 # Construct a mapping from klass to a list of ids to load and a mapping of those ids back to their parent_records
295 records.each do |record|
296 if klass = record.send(polymorph_type)
297 klass_id = record.send(primary_key_name)
298 if klass_id
299 id_map = klasses_and_ids[klass] ||= {}
300 id_list_for_klass_id = (id_map[klass_id.to_s] ||= [])
301 id_list_for_klass_id << record
302 end
303 end
304 end
305 klasses_and_ids = klasses_and_ids.to_a
306 else
307 id_map = {}
308 records.each do |record|
309 key = record.send(primary_key_name)
310 if key
311 mapped_records = (id_map[key.to_s] ||= [])
312 mapped_records << record
313 end
314 end
315 klasses_and_ids = [[reflection.klass.name, id_map]]
316 end
317
318 klasses_and_ids.each do |klass_and_id|
319 klass_name, id_map = *klass_and_id
320 next if id_map.empty?
321 klass = klass_name.constantize
322
323 table_name = klass.quoted_table_name
324 primary_key = klass.primary_key
325 column_type = klass.columns.detect{|c| c.name == primary_key}.type
326 ids = id_map.keys.map do |id|
327 if column_type == :integer
328 id.to_i
329 elsif column_type == :float
330 id.to_f
331 else
332 id
333 end
334 end
335 conditions = "#{table_name}.#{connection.quote_column_name(primary_key)} #{in_or_equals_for_ids(ids)}"
336 conditions << append_conditions(reflection, preload_options)
337 associated_records = klass.with_exclusive_scope do
338 klass.find(:all, :conditions => [conditions, ids],
339 :include => options[:include],
340 :select => options[:select],
341 :joins => options[:joins],
342 :order => options[:order])
343 end
344 set_association_single_records(id_map, reflection.name, associated_records, primary_key)
345 end
346 end
347
348 def find_associated_records(ids, reflection, preload_options)
349 options = reflection.options
350 table_name = reflection.klass.quoted_table_name
351
352 if interface = reflection.options[:as]
353 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}'"
354 else
355 foreign_key = reflection.primary_key_name
356 conditions = "#{reflection.klass.quoted_table_name}.#{foreign_key} #{in_or_equals_for_ids(ids)}"
357 end
358
359 conditions << append_conditions(reflection, preload_options)
360
361 reflection.klass.with_exclusive_scope do
362 reflection.klass.find(:all,
363 :select => (preload_options[:select] || options[:select] || "#{table_name}.*"),
364 :include => preload_options[:include] || options[:include],
365 :conditions => [conditions, ids],
366 :joins => options[:joins],
367 :group => preload_options[:group] || options[:group],
368 :order => preload_options[:order] || options[:order])
369 end
370 end
371
372
373 def interpolate_sql_for_preload(sql)
374 instance_eval("%@#{sql.gsub('@', '\@')}@")
375 end
376
377 def append_conditions(reflection, preload_options)
378 sql = ""
379 sql << " AND (#{interpolate_sql_for_preload(reflection.sanitized_conditions)})" if reflection.sanitized_conditions
380 sql << " AND (#{sanitize_sql preload_options[:conditions]})" if preload_options[:conditions]
381 sql
382 end
383
384 def in_or_equals_for_ids(ids)
385 ids.size > 1 ? "IN (?)" : "= ?"
386 end
387 end
388 end
389 end