Querying guide: add mention of scoped, unscoped and default_scope to querying guide

1 files changed, 41 insertions, 0 deletions

diff --git a/railties/guides/source/active_record_querying.textile b/railties/guides/source/active_record_querying.textile
index e3871a3c34..3970625c35 100644
--- a/railties/guides/source/active_record_querying.textile
+++ b/railties/guides/source/active_record_querying.textile
@@ -965,6 +965,47 @@ Using a class method is the preferred way to accept arguments for scopes. These
 category.posts.1_week_before(time)
 </ruby>
 
+h4. Working with scopes
+
+Where a relational object is required, the +scoped+ method may come in handy. This will return an +ActiveRecord::Relation+ object which can have further scoping applied to it afterwards. A place where this may come in handy is on associations
+
+<ruby>
+  client = Client.find_by_first_name("Ryan")
+  orders = client.orders.scoped
+</ruby>
+
+With this new +orders+ object, we are able to ascertain that this object can have more scopes applied to it. For instance, if we wanted to return orders only in the last 30 days at a later point.
+
+<ruby>
+  orders.where("created_at > ?", 30.days.ago)
+</ruby>
+
+h4. Applying a default scope
+
+If we wish for a scope to be applied across all queries to the model we can use the +default_scope+ method within the model itself.
+
+<ruby>
+  class Client < ActiveRecord::Base
+    default_scope where("removed_at IS NULL")
+  end
+</ruby>
+
+When queries are executed on this model, the SQL query will now look something like this:
+
+<ruby>
+  SELECT * FROM clients WHERE removed_at IS NULL
+</ruby>
+
+h4. Removing all scoping
+
+If we wish to remove scoping for any reason we can use the +unscoped+ method. This is especially useful if a +default_scope+ is specified in the model and should not be applied for this particular query.
+
+<ruby>
+  Client.unscoped.all
+</ruby>
+
+This method removes all scoping and will do a normal query on the table.
+
 h3. Dynamic Finders
 
 For every field (also known as an attribute) you define in your table, Active Record provides a finder method. If you have a field called +first_name+ on your +Client+ model for example, you get +find_by_first_name+ and +find_all_by_first_name+ for free from Active Record. If you have a +locked+ field on the +Client+ model, you also get +find_by_locked+ and +find_all_by_locked+ methods.