Permalink
Browse files

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

…querying guide
  • Loading branch information...
1 parent 1b089a0 commit a6293ff259b4f7f92f629d6258d2d33052c692c9 @radar radar committed Jun 26, 2011
Showing with 41 additions and 0 deletions.
  1. +41 −0 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.

0 comments on commit a6293ff

Please sign in to comment.