Improve 'Joining Tables' section with additional examples and explanation.

1 files changed, 29 insertions, 1 deletions

diff --git a/railties/guides/source/active_record_querying.textile b/railties/guides/source/active_record_querying.textile
index 6cba34c7cd..0690b5e169 100644
--- a/railties/guides/source/active_record_querying.textile
+++ b/railties/guides/source/active_record_querying.textile
@@ -675,7 +675,7 @@ class Post < ActiveRecord::Base
   has_many :tags
 end
 
-class Comments < ActiveRecord::Base
+class Comment < ActiveRecord::Base
   belongs_to :post
   has_one :guest
 end
@@ -683,6 +683,10 @@ end
 class Guest < ActiveRecord::Base
   belongs_to :comment
 end
+
+class Tag < ActiveRecord::Base
+  belongs_to :post
+end
 </ruby>
 
 Now all of the following will produce the expected join queries using +INNER JOIN+:
@@ -700,6 +704,8 @@ SELECT categories.* FROM categories
   INNER JOIN posts ON posts.category_id = categories.id
 </sql>
 
+Or, in English: "return a category object for all categories with posts". (You will see duplicate categories if more than one post has the same category. If you want unique posts, you can use Category.joins(:post).select("distinct(categories.id)).)
+
 h5. Joining Multiple Associations
 
 <ruby>
@@ -714,18 +720,40 @@ SELECT posts.* FROM posts
   INNER JOIN comments ON comments.post_id = posts.id
 </sql>
 
+Or, in English: "return all posts that have a category and at least one comment". Note again that posts with multiple comments will show up multiple times.
+
 h5. Joining Nested Associations (Single Level)
 
 <ruby>
 Post.joins(:comments => :guest)
 </ruby>
 
+This produces:
+
+<sql>
+SELECT posts.* FROM posts
+  INNER JOIN comments ON comments.post_id = posts.id
+  INNER JOIN guests ON guests.comment_id = comments.id
+</sql>
+
+Or, in English: "return all posts that have a comment made by a guest."
+
 h5. Joining Nested Associations (Multiple Level)
 
 <ruby>
 Category.joins(:posts => [{:comments => :guest}, :tags])
 </ruby>
 
+This produces:
+
+<sql>
+SELECT categories.* FROM categories
+  INNER JOIN posts ON posts.category_id = categories.id
+  INNER JOIN comments ON comments.post_id = posts.id
+  INNER JOIN guests ON guests.comment_id = comments.id
+  INNER JOIN tags ON tags.post_id = posts.id
+</sql>
+
 h4. Specifying Conditions on the Joined Tables
 
 You can specify conditions on the joined tables using the regular "Array":#array-conditions and "String":#pure-string-conditions conditions. "Hash conditions":#hash-conditions provides a special syntax for specifying conditions for the joined tables: