From 93c6fc6ee840fedcaf151048fa2748c8067c9512 Mon Sep 17 00:00:00 2001 From: Pratik Naik Date: Sat, 7 Feb 2009 18:22:28 +0000 Subject: Reorder find options under a same section --- .../guides/source/active_record_querying.textile | 34 ++++++++++++++++------ 1 file changed, 25 insertions(+), 9 deletions(-) (limited to 'railties/guides') diff --git a/railties/guides/source/active_record_querying.textile b/railties/guides/source/active_record_querying.textile index ec5938eeae..c818a2319c 100644 --- a/railties/guides/source/active_record_querying.textile +++ b/railties/guides/source/active_record_querying.textile @@ -348,7 +348,23 @@ Client.all(:joins => "orders", :conditions => { :orders => { :created_at => (Tim This will find all clients who have orders that were created yesterday, again using a BETWEEN expression. -h3. Ordering +h3. Find options + +Apart from +:conditions+, +Model.find+ takes a variety of other options via the options hash for customizing the resulting record set. + + +Model.find(id_or_array_of_ids, options_hash) +Model.find(:last, options_hash) +Model.find(:first, options_hash) + +Model.first(options_hash) +Model.last(options_hash) +Model.all(options_hash) + + +The following sections give a top level overview of all the possible keys for the +options_hash+. + +h4. Ordering To retrieve records from the database in a specific order, you can specify the +:order+ option to the +find+ call. @@ -372,7 +388,7 @@ Or ordering by multiple fields: Client.all(:order => "orders_count ASC, created_at DESC") -h3. Selecting specific fields +h4. Selecting specific fields By default, Model.find selects all the fields from the result set using +select *+. @@ -408,7 +424,7 @@ You can also call SQL functions within the select option. For example, if you wo Client.all(:select => "DISTINCT(name)") -h3. Limit and Offset +h4. Limit and Offset To apply +LIMIT+ to the SQL fired by the +Model.find+, you can specify the +LIMIT+ using +:limit+ and +:offset+ options on the find. @@ -436,7 +452,7 @@ This code will return a maximum of 5 clients and because it specifies an offset SELECT * FROM clients LIMIT 5, 5 -h3. Group +h4. Group To apply +GROUP BY+ clause to the SQL fired by the +Model.find+, you can specify the +:group+ option on the find. @@ -454,7 +470,7 @@ The SQL that would be executed would be something like this: SELECT * FROM orders GROUP BY date(created_at) -h3. Having +h4. Having SQL uses +HAVING+ clause to specify conditions on the +GROUP BY+ fields. You can specify the +HAVING+ clause to the SQL fired by the +Model.find+ using +:having+ option on the find. @@ -472,7 +488,7 @@ SELECT * FROM orders GROUP BY date(created_at) HAVING created_at > '2009-01-15' This will return single order objects for each day, but only for the last month. -h3. Readonly objects +h4. Readonly objects To explicitly disallow modification/destroyal of the matching records returned by +Model.find+, you could specify the +:readonly+ option as +true+ to the find call. @@ -490,14 +506,14 @@ client.locked = false client.save -h3. Locking records for update +h4. Locking records for update Locking is helpful for preventing the race conditions when updating records in the database and ensuring atomic updated. Active Record provides two locking mechanism: * Optimistic Locking * Pessimistic Locking -h4. Optimistic Locking +h5. Optimistic Locking Optimistic locking allows multiple users to access the same record for edits, and assumes a minimum of conflicts with the data. It does this by checking whether another process has made changes to a record since it was opened. An +ActiveRecord::StaleObjectError+ exception is thrown if that has occurred and the update is ignored. @@ -532,7 +548,7 @@ class Client < ActiveRecord::Base end -h4. Pessimistic Locking +h5. Pessimistic Locking Pessimistic locking uses locking mechanism provided by the underlying database. Passing +:lock => true+ to +Model.find+ obtains an exclusive lock on the selected rows. +Model.find+ using +:lock+ are usually wrapped inside a transaction for preventing deadlock conditions. -- cgit v1.2.3