From e9f04cdb6b3814b33ced289000e496416f894ee1 Mon Sep 17 00:00:00 2001 From: schneems Date: Sat, 28 Jun 2014 13:54:24 -0500 Subject: [ci skip] Add return values to examples --- guides/source/active_record_querying.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) (limited to 'guides/source') diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md index 486e7b80ff..69d6205715 100644 --- a/guides/source/active_record_querying.md +++ b/guides/source/active_record_querying.md @@ -1487,6 +1487,11 @@ If you'd like to use your own SQL to find records in a table you can use `find_b Client.find_by_sql("SELECT * FROM clients INNER JOIN orders ON clients.id = orders.client_id ORDER BY clients.created_at desc") +# => [ + #, + #, + # ... +] ``` `find_by_sql` provides you with a simple way of making custom calls to the database and retrieving instantiated objects. @@ -1496,7 +1501,11 @@ Client.find_by_sql("SELECT * FROM clients `find_by_sql` has a close relative called `connection#select_all`. `select_all` will retrieve objects from the database using custom SQL just like `find_by_sql` but will not instantiate them. Instead, you will get an array of hashes where each hash indicates a record. ```ruby -Client.connection.select_all("SELECT * FROM clients WHERE id = '1'") +Client.connection.select_all("SELECT first_name, created_at FROM clients WHERE id = '1'") +# => [ + {"first_name"=>"Rafael", "created_at"=>"2012-11-10 23:23:45.281189"}, + {"first_name"=>"Eileen", "created_at"=>"2013-12-09 11:22:35.221282"} +] ``` ### `pluck` -- cgit v1.2.3 From caa25e9fc3862ea036c81d7b7d58101b6bb79cb8 Mon Sep 17 00:00:00 2001 From: schneems Date: Sat, 28 Jun 2014 14:03:00 -0500 Subject: [ci skip] Consolidate docs for `first` Add docs for `first` when provided a numerical argument. Since `first!` behaves exactly the same way but can raise an argument we can consolidate it in the `first` section. --- guides/source/active_record_querying.md | 56 +++++++++++++-------------------- 1 file changed, 21 insertions(+), 35 deletions(-) (limited to 'guides/source') diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md index 69d6205715..0d3a1dc948 100644 --- a/guides/source/active_record_querying.md +++ b/guides/source/active_record_querying.md @@ -132,7 +132,7 @@ TIP: The retrieved record may vary depending on the database engine. #### `first` -`Model.first` finds the first record ordered by the primary key. For example: +The `first` method finds the first record ordered by the primary key. For example: ```ruby client = Client.first @@ -145,7 +145,26 @@ The SQL equivalent of the above is: SELECT * FROM clients ORDER BY clients.id ASC LIMIT 1 ``` -`Model.first` returns `nil` if no matching record is found and no exception will be raised. +The `first` method returns `nil` if no matching record is found and no exception will be raised. + +You can pass in a numerical argument to the `first` method to return up to that number of results. For example + +```ruby +client = Client.first(3) +# => [ + #, + #, + # +] +``` + +The SQL equivalent of the above is: + +```sql +SELECT * FROM clients ORDER BY clients.id ASC LIMIT 3 +``` + +The `first!` method behaves exactly like `first`, except that it will raise `ActiveRecord::RecordNotFound` if no matching record is found. #### `last` @@ -199,23 +218,6 @@ SELECT * FROM clients LIMIT 1 `Model.take!` raises `ActiveRecord::RecordNotFound` if no matching record is found. -#### `first!` - -`Model.first!` finds the first record ordered by the primary key. For example: - -```ruby -client = Client.first! -# => # -``` - -The SQL equivalent of the above is: - -```sql -SELECT * FROM clients ORDER BY clients.id ASC LIMIT 1 -``` - -`Model.first!` raises `ActiveRecord::RecordNotFound` if no matching record is found. - #### `last!` `Model.last!` finds the last record ordered by the primary key. For example: @@ -287,22 +289,6 @@ The SQL equivalent of the above is: SELECT * FROM clients LIMIT 2 ``` -#### first - -`Model.first(limit)` finds the first number of records specified by `limit` ordered by primary key: - -```ruby -Client.first(2) -# => [#, - #] -``` - -The SQL equivalent of the above is: - -```sql -SELECT * FROM clients ORDER BY id ASC LIMIT 2 -``` - #### last `Model.last(limit)` finds the number of records specified by `limit` ordered by primary key in descending order: -- cgit v1.2.3 From 7d9c3ff55c288d277b20c69df4a61c505a99f90c Mon Sep 17 00:00:00 2001 From: schneems Date: Sat, 28 Jun 2014 14:07:25 -0500 Subject: [ci skip] Consolidate docs for `find_by` Since `find_by!` behaves exactly the same way but can raise an argument we can consolidate it in the `find_by` section. --- guides/source/active_record_querying.md | 33 ++++++++++++++------------------- 1 file changed, 14 insertions(+), 19 deletions(-) (limited to 'guides/source') diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md index 0d3a1dc948..ecfc743642 100644 --- a/guides/source/active_record_querying.md +++ b/guides/source/active_record_querying.md @@ -185,7 +185,7 @@ SELECT * FROM clients ORDER BY clients.id DESC LIMIT 1 #### `find_by` -`Model.find_by` finds the first record matching some conditions. For example: +The `find_by` method finds the first record matching some conditions. For example: ```ruby Client.find_by first_name: 'Lifo' @@ -201,6 +201,19 @@ It is equivalent to writing: Client.where(first_name: 'Lifo').take ``` +The `find_by!` method behaves exactly like `find_by`, except that it will raise `ActiveRecord::RecordNotFound` if no matching record is found. For example: + +```ruby +Client.find_by! first_name: 'does not exist' +# => ActiveRecord::RecordNotFound +``` + +This is equivalent to writing: + +```ruby +Client.where(first_name: 'does not exist').take! +``` + #### `take!` `Model.take!` retrieves a record without any implicit ordering. For example: @@ -235,24 +248,6 @@ SELECT * FROM clients ORDER BY clients.id DESC LIMIT 1 `Model.last!` raises `ActiveRecord::RecordNotFound` if no matching record is found. -#### `find_by!` - -`Model.find_by!` finds the first record matching some conditions. It raises `ActiveRecord::RecordNotFound` if no matching record is found. For example: - -```ruby -Client.find_by! first_name: 'Lifo' -# => # - -Client.find_by! first_name: 'Jon' -# => ActiveRecord::RecordNotFound -``` - -It is equivalent to writing: - -```ruby -Client.where(first_name: 'Lifo').take! -``` - ### Retrieving Multiple Objects #### Using Multiple Primary Keys -- cgit v1.2.3 From d319ef851a5d5967271ed7169d6c5c1e028951c6 Mon Sep 17 00:00:00 2001 From: schneems Date: Sat, 28 Jun 2014 14:16:49 -0500 Subject: [ci skip] Consolidate docs for `take` Add docs on what happens when a numerical argument is provided to take. Since `take!` behaves exactly the same way but can raise an argument we can consolidate it in the `take` section. --- guides/source/active_record_querying.md | 55 ++++++++++++--------------------- 1 file changed, 20 insertions(+), 35 deletions(-) (limited to 'guides/source') diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md index ecfc743642..2533edc706 100644 --- a/guides/source/active_record_querying.md +++ b/guides/source/active_record_querying.md @@ -113,7 +113,7 @@ SELECT * FROM clients WHERE (clients.id = 10) LIMIT 1 #### `take` -`Model.take` retrieves a record without any implicit ordering. For example: +The `take` method retrieves a record without any implicit ordering. For example: ```ruby client = Client.take @@ -126,7 +126,25 @@ The SQL equivalent of the above is: SELECT * FROM clients LIMIT 1 ``` -`Model.take` returns `nil` if no record is found and no exception will be raised. +The `take` method returns `nil` if no record is found and no exception will be raised. + +You can pass in a numerical argument to the `take` method to return up to that number of results. For example + +```ruby +client = Client.take(2) +# => [ + #, + # +] +``` + +The SQL equivalent of the above is: + +```sql +SELECT * FROM clients LIMIT 2 +``` + +The `take!` method behaves exactly like `take`, except that it will raise `ActiveRecord::RecordNotFound` if no matching record is found. TIP: The retrieved record may vary depending on the database engine. @@ -214,23 +232,6 @@ This is equivalent to writing: Client.where(first_name: 'does not exist').take! ``` -#### `take!` - -`Model.take!` retrieves a record without any implicit ordering. For example: - -```ruby -client = Client.take! -# => # -``` - -The SQL equivalent of the above is: - -```sql -SELECT * FROM clients LIMIT 1 -``` - -`Model.take!` raises `ActiveRecord::RecordNotFound` if no matching record is found. - #### `last!` `Model.last!` finds the last record ordered by the primary key. For example: @@ -268,22 +269,6 @@ SELECT * FROM clients WHERE (clients.id IN (1,10)) WARNING: `Model.find(array_of_primary_key)` will raise an `ActiveRecord::RecordNotFound` exception unless a matching record is found for **all** of the supplied primary keys. -#### take - -`Model.take(limit)` retrieves the first number of records specified by `limit` without any explicit ordering: - -```ruby -Client.take(2) -# => [#, - #] -``` - -The SQL equivalent of the above is: - -```sql -SELECT * FROM clients LIMIT 2 -``` - #### last `Model.last(limit)` finds the number of records specified by `limit` ordered by primary key in descending order: -- cgit v1.2.3 From d4fd0bd17709735ac91e434c94fe99429f078c6e Mon Sep 17 00:00:00 2001 From: schneems Date: Sat, 28 Jun 2014 14:30:52 -0500 Subject: [ci skip] Consolidate docs for `last` Add docs on what happens when a numerical argument is provided to last. Since `last!` behaves exactly the same way but can raise an argument we can consolidate it in the `last` section. --- guides/source/active_record_querying.md | 37 +++++++++++++++++++-------------- 1 file changed, 21 insertions(+), 16 deletions(-) (limited to 'guides/source') diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md index 2533edc706..a699a3dffe 100644 --- a/guides/source/active_record_querying.md +++ b/guides/source/active_record_querying.md @@ -186,7 +186,7 @@ The `first!` method behaves exactly like `first`, except that it will raise `Act #### `last` -`Model.last` finds the last record ordered by the primary key. For example: +The `last` method finds the last record ordered by the primary key. For example: ```ruby client = Client.last @@ -199,7 +199,26 @@ The SQL equivalent of the above is: SELECT * FROM clients ORDER BY clients.id DESC LIMIT 1 ``` -`Model.last` returns `nil` if no matching record is found and no exception will be raised. +The `last` method returns `nil` if no matching record is found and no exception will be raised. + +You can pass in a numerical argument to the `last` method to return up to that number of results. For example + +```ruby +client = Client.last(3) +# => [ + #, + #, + # +] +``` + +The SQL equivalent of the above is: + +```sql +SELECT * FROM clients ORDER BY clients.id DESC LIMIT 3 +``` + +The `last!` method behaves exactly like `last`, except that it will raise `ActiveRecord::RecordNotFound` if no matching record is found. #### `find_by` @@ -269,21 +288,7 @@ SELECT * FROM clients WHERE (clients.id IN (1,10)) WARNING: `Model.find(array_of_primary_key)` will raise an `ActiveRecord::RecordNotFound` exception unless a matching record is found for **all** of the supplied primary keys. -#### last - -`Model.last(limit)` finds the number of records specified by `limit` ordered by primary key in descending order: - -```ruby -Client.last(2) -# => [#, - #] -``` - -The SQL equivalent of the above is: -```sql -SELECT * FROM clients ORDER BY id DESC LIMIT 2 -``` ### Retrieving Multiple Objects in Batches -- cgit v1.2.3 From 63f4155596d1403dbf4972adc0d5877c1ea6d2b0 Mon Sep 17 00:00:00 2001 From: schneems Date: Sat, 28 Jun 2014 14:38:16 -0500 Subject: [ci skip] Consolidate docs for `find` Put all options for overloading `find` in one section --- guides/source/active_record_querying.md | 44 ++++++++++++++------------------- 1 file changed, 19 insertions(+), 25 deletions(-) (limited to 'guides/source') diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md index a699a3dffe..0b6f40c129 100644 --- a/guides/source/active_record_querying.md +++ b/guides/source/active_record_querying.md @@ -93,9 +93,9 @@ The primary operation of `Model.find(options)` can be summarized as: Active Record provides several different ways of retrieving a single object. -#### Using a Primary Key +#### `find` -Using `Model.find(primary_key)`, you can retrieve the object corresponding to the specified _primary key_ that matches any supplied options. For example: +Using the `find` method, you can retrieve the object corresponding to the specified _primary key_ that matches any supplied options. For example: ```ruby # Find the client with primary key (id) 10. @@ -109,7 +109,23 @@ The SQL equivalent of the above is: SELECT * FROM clients WHERE (clients.id = 10) LIMIT 1 ``` -`Model.find(primary_key)` will raise an `ActiveRecord::RecordNotFound` exception if no matching record is found. +The `find` method will raise an `ActiveRecord::RecordNotFound` exception if no matching record is found. + +You can also use this method to query for multiple objects. Call the `find` method and pass in an array of primary keys. The return will be an array containing all of the matching records for the supplied _primary keys_. For example: + +```ruby +# Find the clients with primary keys 1 and 10. +client = Client.find([1, 10]) # Or even Client.find(1, 10) +# => [#, #] +``` + +The SQL equivalent of the above is: + +```sql +SELECT * FROM clients WHERE (clients.id IN (1,10)) +``` + +WARNING: The `find` method will raise an `ActiveRecord::RecordNotFound` exception unless a matching record is found for **all** of the supplied primary keys. #### `take` @@ -268,28 +284,6 @@ SELECT * FROM clients ORDER BY clients.id DESC LIMIT 1 `Model.last!` raises `ActiveRecord::RecordNotFound` if no matching record is found. -### Retrieving Multiple Objects - -#### Using Multiple Primary Keys - -`Model.find(array_of_primary_key)` accepts an array of _primary keys_, returning an array containing all of the matching records for the supplied _primary keys_. For example: - -```ruby -# Find the clients with primary keys 1 and 10. -client = Client.find([1, 10]) # Or even Client.find(1, 10) -# => [#, #] -``` - -The SQL equivalent of the above is: - -```sql -SELECT * FROM clients WHERE (clients.id IN (1,10)) -``` - -WARNING: `Model.find(array_of_primary_key)` will raise an `ActiveRecord::RecordNotFound` exception unless a matching record is found for **all** of the supplied primary keys. - - - ### Retrieving Multiple Objects in Batches We often need to iterate over a large set of records, as when we send a newsletter to a large set of users, or when we export data. -- cgit v1.2.3 From f7e4362011ceb1317fd401125d48d7ccb9a1079c Mon Sep 17 00:00:00 2001 From: schneems Date: Sat, 28 Jun 2014 14:46:33 -0500 Subject: [ci skip] Doc ability to chain in `find_each` Also use appropriate mailer syntax in the `find_each` block. --- guides/source/active_record_querying.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) (limited to 'guides/source') diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md index 0b6f40c129..311df3a953 100644 --- a/guides/source/active_record_querying.md +++ b/guides/source/active_record_querying.md @@ -309,7 +309,15 @@ The `find_each` method retrieves a batch of records and then yields _each_ recor ```ruby User.find_each do |user| - NewsLetter.weekly_deliver(user) + NewsMailer.weekly(user).deliver +end +``` + +To add conditions to a `find_each` operation you can chain other Active Record methods such as `where`: + +```ruby +User.where(weekly_subscriber: true).find_each do |user| + NewsMailer.weekly(user).deliver end ``` -- cgit v1.2.3 From 0f6b101e09d210cea2494c5d4225760f1951ea67 Mon Sep 17 00:00:00 2001 From: schneems Date: Sat, 28 Jun 2014 14:57:10 -0500 Subject: [ci skip] Fix doc for except The example showed is `except`, however the method "documented" is `unstop`. Fix to align the docs to the example. --- guides/source/active_record_querying.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) (limited to 'guides/source') diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md index 311df3a953..2f7fe6fe98 100644 --- a/guides/source/active_record_querying.md +++ b/guides/source/active_record_querying.md @@ -675,9 +675,9 @@ This will return single order objects for each day, but only those that are orde Overriding Conditions --------------------- -### `unscope` +### `except` -You can specify certain conditions to be removed using the `unscope` method. For example: +You can specify certain conditions to be removed using the `except` method. For example: ```ruby Article.where('id > 10').limit(20).order('id asc').except(:order) @@ -688,12 +688,11 @@ The SQL that would be executed: ```sql SELECT * FROM articles WHERE id > 10 LIMIT 20 -# Original query without `unscope` +# Original query without `except` SELECT * FROM articles WHERE id > 10 ORDER BY id asc LIMIT 20 - ``` -You can additionally unscope specific where clauses. For example: +You can additionally call `unscope` to remove a specific where clauses. For example: ```ruby Article.where(id: 10, trashed: false).unscope(where: :id) -- cgit v1.2.3 From 9d74a298f1dd72beb337001c69b63fc76ef20457 Mon Sep 17 00:00:00 2001 From: schneems Date: Sat, 28 Jun 2014 15:05:05 -0500 Subject: [ci skip] remove invalid code from docs --- guides/source/active_record_querying.md | 2 -- 1 file changed, 2 deletions(-) (limited to 'guides/source') diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md index 2f7fe6fe98..aa206242c4 100644 --- a/guides/source/active_record_querying.md +++ b/guides/source/active_record_querying.md @@ -731,8 +731,6 @@ The `reorder` method overrides the default scope order. For example: ```ruby class Article < ActiveRecord::Base - .. - .. has_many :comments, -> { order('posted_at DESC') } end -- cgit v1.2.3 From 85f463f616b2504428b3dfdb12608bbf023f3758 Mon Sep 17 00:00:00 2001 From: Vijay Dev Date: Sat, 12 Jul 2014 10:14:29 +0000 Subject: Revert "[ci skip] Fix doc for except" This reverts commit 0f6b101e09d210cea2494c5d4225760f1951ea67. Reason: It's better to let `unscope` be documented. We can add a separate section for `except`. --- guides/source/active_record_querying.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'guides/source') diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md index aa206242c4..f9368a6a1a 100644 --- a/guides/source/active_record_querying.md +++ b/guides/source/active_record_querying.md @@ -675,9 +675,9 @@ This will return single order objects for each day, but only those that are orde Overriding Conditions --------------------- -### `except` +### `unscope` -You can specify certain conditions to be removed using the `except` method. For example: +You can specify certain conditions to be removed using the `unscope` method. For example: ```ruby Article.where('id > 10').limit(20).order('id asc').except(:order) @@ -688,11 +688,12 @@ The SQL that would be executed: ```sql SELECT * FROM articles WHERE id > 10 LIMIT 20 -# Original query without `except` +# Original query without `unscope` SELECT * FROM articles WHERE id > 10 ORDER BY id asc LIMIT 20 + ``` -You can additionally call `unscope` to remove a specific where clauses. For example: +You can additionally unscope specific where clauses. For example: ```ruby Article.where(id: 10, trashed: false).unscope(where: :id) -- cgit v1.2.3 From d97d8379eb036e3129cd2d80deb6a026f11cd3be Mon Sep 17 00:00:00 2001 From: Vijay Dev Date: Sat, 12 Jul 2014 10:21:00 +0000 Subject: fix mismatched example call [ci skip] --- guides/source/active_record_querying.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'guides/source') diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md index f9368a6a1a..c9e265de08 100644 --- a/guides/source/active_record_querying.md +++ b/guides/source/active_record_querying.md @@ -680,7 +680,7 @@ Overriding Conditions You can specify certain conditions to be removed using the `unscope` method. For example: ```ruby -Article.where('id > 10').limit(20).order('id asc').except(:order) +Article.where('id > 10').limit(20).order('id asc').unscope(:order) ``` The SQL that would be executed: @@ -693,7 +693,7 @@ SELECT * FROM articles WHERE id > 10 ORDER BY id asc LIMIT 20 ``` -You can additionally unscope specific where clauses. For example: +You can also unscope specific `where` clauses. For example: ```ruby Article.where(id: 10, trashed: false).unscope(where: :id) -- cgit v1.2.3