Permalink
Browse files

Merge branch 'master' of github.com:rails/docrails

Conflicts:
	activerecord/lib/active_record/base.rb
  • Loading branch information...
2 parents 4248785 + d97d837 commit 46d2a517a43b6707927b6d712ae317e6960ece61 @vijaydev vijaydev committed Jul 12, 2014
Showing with 93 additions and 113 deletions.
  1. +93 −113 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,215 +109,180 @@ 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.
-#### `take`
-
-`Model.take` retrieves a record without any implicit ordering. For example:
+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
-client = Client.take
-# => #<Client id: 1, first_name: "Lifo">
+# Find the clients with primary keys 1 and 10.
+client = Client.find([1, 10]) # Or even Client.find(1, 10)
+# => [#<Client id: 1, first_name: "Lifo">, #<Client id: 10, first_name: "Ryan">]
```
The SQL equivalent of the above is:
```sql
-SELECT * FROM clients LIMIT 1
+SELECT * FROM clients WHERE (clients.id IN (1,10))
```
-`Model.take` returns `nil` if no record is found and no exception will be raised.
-
-TIP: The retrieved record may vary depending on the database engine.
+WARNING: The `find` method will raise an `ActiveRecord::RecordNotFound` exception unless a matching record is found for **all** of the supplied primary keys.
-#### `first`
+#### `take`
-`Model.first` finds the first record ordered by the primary key. For example:
+The `take` method retrieves a record without any implicit ordering. For example:
```ruby
-client = Client.first
+client = Client.take
# => #<Client id: 1, first_name: "Lifo">
```
The SQL equivalent of the above is:
```sql
-SELECT * FROM clients ORDER BY clients.id ASC LIMIT 1
+SELECT * FROM clients LIMIT 1
```
-`Model.first` returns `nil` if no matching record is found and no exception will be raised.
-
-#### `last`
+The `take` method returns `nil` if no record is found and no exception will be raised.
-`Model.last` finds the last record ordered by the primary key. For example:
+You can pass in a numerical argument to the `take` method to return up to that number of results. For example
```ruby
-client = Client.last
-# => #<Client id: 221, first_name: "Russel">
+client = Client.take(2)
+# => [
+ #<Client id: 1, first_name: "Lifo">,
+ #<Client id: 220, first_name: "Sara">
+]
```
The SQL equivalent of the above is:
```sql
-SELECT * FROM clients ORDER BY clients.id DESC LIMIT 1
+SELECT * FROM clients LIMIT 2
```
-`Model.last` returns `nil` if no matching record is found and no exception will be raised.
+The `take!` method behaves exactly like `take`, except that it will raise `ActiveRecord::RecordNotFound` if no matching record is found.
-#### `find_by`
+TIP: The retrieved record may vary depending on the database engine.
-`Model.find_by` finds the first record matching some conditions. For example:
+#### `first`
+
+The `first` method finds the first record ordered by the primary key. For example:
```ruby
-Client.find_by first_name: 'Lifo'
+client = Client.first
# => #<Client id: 1, first_name: "Lifo">
-
-Client.find_by first_name: 'Jon'
-# => nil
```
-It is equivalent to writing:
+The SQL equivalent of the above is:
-```ruby
-Client.where(first_name: 'Lifo').take
+```sql
+SELECT * FROM clients ORDER BY clients.id ASC LIMIT 1
```
-#### `take!`
+The `first` method returns `nil` if no matching record is found and no exception will be raised.
-`Model.take!` retrieves a record without any implicit ordering. For example:
+You can pass in a numerical argument to the `first` method to return up to that number of results. For example
```ruby
-client = Client.take!
-# => #<Client id: 1, first_name: "Lifo">
+client = Client.first(3)
+# => [
+ #<Client id: 1, first_name: "Lifo">,
+ #<Client id: 2, first_name: "Fifo">,
+ #<Client id: 3, first_name: "Filo">
+]
```
The SQL equivalent of the above is:
```sql
-SELECT * FROM clients LIMIT 1
+SELECT * FROM clients ORDER BY clients.id ASC LIMIT 3
```
-`Model.take!` raises `ActiveRecord::RecordNotFound` if no matching record is found.
+The `first!` method behaves exactly like `first`, except that it will raise `ActiveRecord::RecordNotFound` if no matching record is found.
-#### `first!`
+#### `last`
-`Model.first!` finds the first 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.first!
-# => #<Client id: 1, first_name: "Lifo">
+client = Client.last
+# => #<Client id: 221, first_name: "Russel">
```
The SQL equivalent of the above is:
```sql
-SELECT * FROM clients ORDER BY clients.id ASC LIMIT 1
+SELECT * FROM clients ORDER BY clients.id DESC LIMIT 1
```
-`Model.first!` raises `ActiveRecord::RecordNotFound` if no matching record is found.
-
-#### `last!`
+The `last` method returns `nil` if no matching record is found and no exception will be raised.
-`Model.last!` finds the last record ordered by the primary key. For example:
+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!
-# => #<Client id: 221, first_name: "Russel">
+client = Client.last(3)
+# => [
+ #<Client id: 219, first_name: "James">,
+ #<Client id: 220, first_name: "Sara">,
+ #<Client id: 221, first_name: "Russel">
+]
```
The SQL equivalent of the above is:
```sql
-SELECT * FROM clients ORDER BY clients.id DESC LIMIT 1
+SELECT * FROM clients ORDER BY clients.id DESC LIMIT 3
```
-`Model.last!` raises `ActiveRecord::RecordNotFound` if no matching record is found.
+The `last!` method behaves exactly like `last`, except that it will raise `ActiveRecord::RecordNotFound` if no matching record is found.
-#### `find_by!`
+#### `find_by`
-`Model.find_by!` finds the first record matching some conditions. It raises `ActiveRecord::RecordNotFound` if no matching record is found. For example:
+The `find_by` method finds the first record matching some conditions. For example:
```ruby
-Client.find_by! first_name: 'Lifo'
+Client.find_by first_name: 'Lifo'
# => #<Client id: 1, first_name: "Lifo">
-Client.find_by! first_name: 'Jon'
-# => ActiveRecord::RecordNotFound
+Client.find_by first_name: 'Jon'
+# => nil
```
It is equivalent to writing:
```ruby
-Client.where(first_name: 'Lifo').take!
+Client.where(first_name: 'Lifo').take
```
-### 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:
+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
-# Find the clients with primary keys 1 and 10.
-client = Client.find([1, 10]) # Or even Client.find(1, 10)
-# => [#<Client id: 1, first_name: "Lifo">, #<Client id: 10, first_name: "Ryan">]
-```
-
-The SQL equivalent of the above is:
-
-```sql
-SELECT * FROM clients WHERE (clients.id IN (1,10))
+Client.find_by! first_name: 'does not exist'
+# => ActiveRecord::RecordNotFound
```
-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:
+This is equivalent to writing:
```ruby
-Client.take(2)
-# => [#<Client id: 1, first_name: "Lifo">,
- #<Client id: 2, first_name: "Raf">]
-```
-
-The SQL equivalent of the above is:
-
-```sql
-SELECT * FROM clients LIMIT 2
+Client.where(first_name: 'does not exist').take!
```
-#### first
+#### `last!`
-`Model.first(limit)` finds the first number of records specified by `limit` ordered by primary key:
+`Model.last!` finds the last record ordered by the primary key. For example:
```ruby
-Client.first(2)
-# => [#<Client id: 1, first_name: "Lifo">,
- #<Client id: 2, first_name: "Raf">]
+client = Client.last!
+# => #<Client id: 221, first_name: "Russel">
```
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:
-
-```ruby
-Client.last(2)
-# => [#<Client id: 10, first_name: "Ryan">,
- #<Client id: 9, first_name: "John">]
+SELECT * FROM clients ORDER BY clients.id DESC LIMIT 1
```
-The SQL equivalent of the above is:
-
-```sql
-SELECT * FROM clients ORDER BY id DESC LIMIT 2
-```
+`Model.last!` raises `ActiveRecord::RecordNotFound` if no matching record is found.
### Retrieving Multiple Objects in Batches
@@ -344,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
```
@@ -707,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:
@@ -720,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)
@@ -759,8 +732,6 @@ The `reorder` method overrides the default scope order. For example:
```ruby
class Article < ActiveRecord::Base
- ..
- ..
has_many :comments, -> { order('posted_at DESC') }
end
@@ -1487,6 +1458,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")
+# => [
+ #<Client id: 1, first_name: "Lucas" >,
+ #<Client id: 2, first_name: "Jan" >,
+ # ...
+]
```
`find_by_sql` provides you with a simple way of making custom calls to the database and retrieving instantiated objects.
@@ -1496,7 +1472,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`

0 comments on commit 46d2a51

Please sign in to comment.