Permalink
Browse files

Document deep eager includes. Closes #6267.

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@6790 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
  • Loading branch information...
1 parent c7c867e commit 5b414190d034e18a3080b74a57a13039134f2834 @jeremy jeremy committed May 19, 2007
Showing with 12 additions and 2 deletions.
  1. +3 −1 activerecord/CHANGELOG
  2. +9 −1 activerecord/lib/active_record/associations.rb
View
@@ -1,6 +1,8 @@
*SVN*
-* Docs: warn that associations names shouldn't be reserved words. #4378 [murphy@cYcnus.de, Josh Susser]
+* Document deep eager includes. #6267 [Josh Susser, Dan Manges]
+
+* Document warning that associations names shouldn't be reserved words. #4378 [murphy@cYcnus.de, Josh Susser]
* Sanitize Base#inspect. #8392 [Nik Wakelin]
@@ -422,7 +422,15 @@ def clear_association_cache #:nodoc:
# for post in Post.find(:all, :include => [ :author, :comments ])
#
# That'll add another join along the lines of: LEFT OUTER JOIN comments ON comments.post_id = posts.id. And we'll be down to 1 query.
- # But that shouldn't fool you to think that you can pull out huge amounts of data with no performance penalty just because you've reduced
+ #
+ # To include a deep hierarchy of associations, using a hash:
+ #
+ # for post in Post.find(:all, :include => [ :author, { :comments => { :author => :gravatar } } ])
+ #
+ # That'll grab not only all the comments but all their authors and gravatar pictures. You can mix and match
+ # symbols, arrays and hashes in any combination to describe the associations you want to load.
+ #
+ # All of this power shouldn't fool you into thinking that you can pull out huge amounts of data with no performance penalty just because you've reduced
# the number of queries. The database still needs to send all the data to Active Record and it still needs to be processed. So it's no
# catch-all for performance problems, but it's a great way to cut down on the number of queries in a situation as the one described above.
#

0 comments on commit 5b41419

Please sign in to comment.