Skip to content

Commit

Permalink
[ci skip] Consolidate docs for find
Browse files Browse the repository at this point in the history
Put all options for overloading `find` in one section
  • Loading branch information
schneems committed Jun 28, 2014
1 parent d4fd0bd commit 63f4155
Showing 1 changed file with 19 additions and 25 deletions.
44 changes: 19 additions & 25 deletions guides/source/active_record_querying.md
Expand Up @@ -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. 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 ```ruby
# Find the client with primary key (id) 10. # Find the client with primary key (id) 10.
Expand All @@ -109,7 +109,23 @@ The SQL equivalent of the above is:
SELECT * FROM clients WHERE (clients.id = 10) LIMIT 1 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)
# => [#<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))
```

WARNING: The `find` method will raise an `ActiveRecord::RecordNotFound` exception unless a matching record is found for **all** of the supplied primary keys.


#### `take` #### `take`


Expand Down Expand Up @@ -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. `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)
# => [#<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))
```

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 ### 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. 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.
Expand Down

0 comments on commit 63f4155

Please sign in to comment.