From 981258cf5e3c4ae8e3e2fa93327e2ac325e9b4b3 Mon Sep 17 00:00:00 2001 From: Michael Hutchinson Date: Wed, 14 Jul 2010 01:39:00 -0700 Subject: [PATCH 1/4] Active Record Query Interface Guide: Fixed minor typos. --- .../guides/source/active_record_querying.textile | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/railties/guides/source/active_record_querying.textile b/railties/guides/source/active_record_querying.textile index f5e70aef41..a8d86659d1 100644 --- a/railties/guides/source/active_record_querying.textile +++ b/railties/guides/source/active_record_querying.textile @@ -337,7 +337,7 @@ Just like in Ruby. If you want a shorter syntax be sure to check out the "Hash C h4. Hash Conditions -Active Record also allows you to pass in a hash conditions which can increase the readability of your conditions syntax. With hash conditions, you pass in a hash with keys of the fields you want conditionalised and the values of how you want to conditionalise them: +Active Record also allows you to pass in hash conditions which can increase the readability of your conditions syntax. With hash conditions, you pass in a hash with keys of the fields you want conditionalised and the values of how you want to conditionalise them: NOTE: Only equality, range and subset checking are possible with Hash conditions. @@ -473,7 +473,7 @@ SELECT * FROM clients LIMIT 5, 5 h4. Group -To apply +GROUP BY+ clause to the SQL fired by the finder, you can specify the +group+ method on the find. +To apply a +GROUP BY+ clause to the SQL fired by the finder, you can specify the +group+ method on the find. For example, if you want to find a collection of the dates orders were created on: @@ -527,7 +527,9 @@ client.save 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: +Locking is helpful for preventing race conditions when updating records in the database and ensuring atomic updates. + +Active Record provides two locking mechanisms: * Optimistic Locking * Pessimistic Locking @@ -569,7 +571,7 @@ end 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. +Pessimistic locking uses a 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. For example: @@ -601,7 +603,7 @@ end h3. Joining Tables -Model.find provides a +:joins+ option for specifying +JOIN+ clauses on the resulting SQL. There multiple different ways to specify the +:joins+ option: +Model.find provides a +:joins+ option for specifying +JOIN+ clauses on the resulting SQL. There are multiple ways to specify the +:joins+ option: h4. Using a String SQL Fragment @@ -782,7 +784,7 @@ You can specify an exclamation point (!) on the end of the dynamic find If you want to find both by name and locked, you can chain these finders together by simply typing +and+ between the fields for example +Client.find_by_first_name_and_locked("Ryan", true)+. -There's another set of dynamic finders that let you find or create/initialize objects if they aren't found. These work in a similar fashion to the other finders and can be used like +find_or_create_by_first_name(params[:first_name])+. Using this will firstly perform a find and then create if the find returns +nil+. The SQL looks like this for +Client.find_or_create_by_first_name("Ryan")+: +There's another set of dynamic finders that let you find or create/initialize objects if they aren't found. These work in a similar fashion to the other finders and can be used like +find_or_create_by_first_name(params[:first_name])+. Using this will first perform a find and then create if the find returns +nil+. The SQL looks like this for +Client.find_or_create_by_first_name("Ryan")+: SELECT * FROM clients WHERE (clients.first_name = 'Ryan') LIMIT 1 @@ -792,7 +794,7 @@ INSERT INTO clients (first_name, updated_at, created_at, orders_count, locked) COMMIT -+find_or_create+'s sibling, +find_or_initialize+, will find an object and if it does not exist will act similar to calling +new+ with the arguments you passed in. For example: ++find_or_create+'s sibling, +find_or_initialize+, will find an object and if it does not exist will act similarly to calling +new+ with the arguments you passed in. For example: client = Client.find_or_initialize_by_first_name('Ryan') From 6de6fa80106bd1a5b1b2369891536ec36e94037a Mon Sep 17 00:00:00 2001 From: Michael Hutchinson Date: Wed, 14 Jul 2010 02:30:12 -0700 Subject: [PATCH 2/4] Active Record Query Interface Guide: Fixed a few typos and made minor changes to improve readability. --- .../source/active_record_querying.textile | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/railties/guides/source/active_record_querying.textile b/railties/guides/source/active_record_querying.textile index a8d86659d1..8c43a02c96 100644 --- a/railties/guides/source/active_record_querying.textile +++ b/railties/guides/source/active_record_querying.textile @@ -347,7 +347,7 @@ h5. Equality Conditions Client.where({ :locked => true }) -The field name does not have to be a symbol it can also be a string: +The field name can also be a string: Client.where({ 'locked' => true }) @@ -447,7 +447,7 @@ h4. Limit and Offset To apply +LIMIT+ to the SQL fired by the +Model.find+, you can specify the +LIMIT+ using +limit+ and +offset+ methods on the relation. -If you want to limit the amount of records to a certain subset of all the records retrieved you usually use +limit+ for this, sometimes coupled with +offset+. Limit is the maximum number of records that will be retrieved from a query, and offset is the number of records it will start reading from from the first record of the set. For example: +You can use +limit+ to specify the number of records to be retrieved, and use +offset+ to specify the number of records to skip before starting to return the records. For example: Client.limit(5) @@ -491,7 +491,7 @@ SELECT * FROM orders GROUP BY date(created_at) 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. +SQL uses the +HAVING+ clause to specify conditions on the +GROUP BY+ fields. You can add the +HAVING+ clause to the SQL fired by the +Model.find+ by adding the +:having+ option to the find. For example: @@ -517,7 +517,7 @@ Any attempt to alter or destroy the readonly records will not succeed, raising a Client.first.readonly(true) -If you assign this record to a variable client, calling the following code will raise an +ActiveRecord::ReadOnlyRecord+ exception: +For example, calling the following code will raise an +ActiveRecord::ReadOnlyRecord+ exception: client = Client.first.readonly(true) @@ -540,7 +540,7 @@ Optimistic locking allows multiple users to access the same record for edits, an Optimistic locking column -In order to use optimistic locking, the table needs to have a column called +lock_version+. Each time the record is updated, Active Record increments the +lock_version+ column and the locking facilities ensure that records instantiated twice will let the last one saved raise an +ActiveRecord::StaleObjectError+ exception if the first was also updated. Example: +In order to use optimistic locking, the table needs to have a column called +lock_version+. Each time the record is updated, Active Record increments the +lock_version+ column. If an update request is made with a lower value in the +lock_version+ field than is currently in the +lock_version+ column in the database, the update request will fail with an +ActiveRecord::StaleObjectError+. Example: c1 = Client.find(1) @@ -700,7 +700,7 @@ time_range = (Time.now.midnight - 1.day)..Time.now.midnight Client.joins(:orders).where('orders.created_at' => time_range) -An alternative and cleaner syntax to this is to nest the hash conditions: +An alternative and cleaner syntax is to nest the hash conditions: time_range = (Time.now.midnight - 1.day)..Time.now.midnight @@ -729,7 +729,7 @@ This code looks fine at the first sight. But the problem lies within the total n Solution to N 1 queries problem -Active Record lets you specify all the associations in advanced that are going to be loaded. This is possible by specifying the +includes+ method of the +Model.find+ call. With +includes+, Active Record ensures that all the specified associations are loaded using minimum possible number of queries. +Active Record lets you specify in advance all the associations that are going to be loaded. This is possible by specifying the +includes+ method of the +Model.find+ call. With +includes+, Active Record ensures that all of the specified associations are loaded using the minimum possible number of queries. Revisiting the above case, we could rewrite +Client.all+ to use eager load addresses: @@ -751,7 +751,7 @@ SELECT addresses.* FROM addresses h4. Eager Loading Multiple Associations -Active Record lets you eager load any possible number of associations with a single +Model.find+ call by using an array, hash, or a nested hash of array/hash with the +includes+ method. +Active Record lets you eager load any number of associations with a single +Model.find+ call by using an array, hash, or a nested hash of array/hash with the +includes+ method. h5. Array of Multiple Associations @@ -767,7 +767,7 @@ h5. Nested Associations Hash Category.find(1).includes(:posts => [{:comments => :guest}, :tags]) -The above code finds the category with id 1 and eager loads all the posts associated with the found category. Additionally, it will also eager load every posts' tags and comments. Every comment's guest association will get eager loaded as well. +This will find the category with id 1 and eager load all of the associated posts, the associated posts' tags and comments, and every comment's guest association. h4. Specifying Conditions on Eager Loaded Associations @@ -838,7 +838,7 @@ Client.exists?(1,2,3) Client.exists?([1,2,3]) -Further more, +exists+ takes a +conditions+ option much like find: +The +exists+ method may also take a +conditions+ option much like find: Client.exists?(:conditions => "first_name = 'Ryan'") From 438bff6ccd0ba495c684a0377fd94cf302e340c5 Mon Sep 17 00:00:00 2001 From: Michael Hutchinson Date: Wed, 14 Jul 2010 03:36:55 -0700 Subject: [PATCH 3/4] Active Record Query Interface Guide: Corrected the explanation for the OFFSET example. --- railties/guides/source/active_record_querying.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/railties/guides/source/active_record_querying.textile b/railties/guides/source/active_record_querying.textile index 8c43a02c96..2e23604838 100644 --- a/railties/guides/source/active_record_querying.textile +++ b/railties/guides/source/active_record_querying.textile @@ -465,7 +465,7 @@ Or chaining both +limit+ and +offset+: Client.limit(5).offset(5) -This code will return a maximum of 5 clients and because it specifies an offset this time, it will return these records starting from the 5th client in the clients table. The SQL looks like: +This code will return a maximum of 5 clients beginning with the 6th client in the clients table, skipping the first five clients as specified by the offset. The SQL looks like: SELECT * FROM clients LIMIT 5, 5 From 59945678393b591e263cdee90a8e278a723f93df Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Wed, 14 Jul 2010 13:17:01 +0200 Subject: [PATCH 4/4] AR queying guide: let limit and offset be different numbers to help making clear what is what in the explanation, rewords also a bit --- .../guides/source/active_record_querying.textile | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/railties/guides/source/active_record_querying.textile b/railties/guides/source/active_record_querying.textile index 2e23604838..5c4ed3a803 100644 --- a/railties/guides/source/active_record_querying.textile +++ b/railties/guides/source/active_record_querying.textile @@ -447,28 +447,28 @@ h4. Limit and Offset To apply +LIMIT+ to the SQL fired by the +Model.find+, you can specify the +LIMIT+ using +limit+ and +offset+ methods on the relation. -You can use +limit+ to specify the number of records to be retrieved, and use +offset+ to specify the number of records to skip before starting to return the records. For example: +You can use +limit+ to specify the number of records to be retrieved, and use +offset+ to specify the number of records to skip before starting to return the records. For example Client.limit(5) -This code will return a maximum of 5 clients and because it specifies no offset it will return the first 5 clients in the table. The SQL it executes will look like this: +will return a maximum of 5 clients and because it specifies no offset it will return the first 5 in the table. The SQL it executes looks like this: SELECT * FROM clients LIMIT 5 -Or chaining both +limit+ and +offset+: +Adding +offset+ to that -Client.limit(5).offset(5) +Client.limit(5).offset(30) -This code will return a maximum of 5 clients beginning with the 6th client in the clients table, skipping the first five clients as specified by the offset. The SQL looks like: +will return instead a maximum of 5 clients beginning with the 31st. The SQL looks like: -SELECT * FROM clients LIMIT 5, 5 +SELECT * FROM clients LIMIT 5, 30 h4. Group