Skip to content

Commit a135714

Browse files
JuanitoFatasJuanitoFatas
committed
Regular Maintenance.
1 parent c6fd1e1 commit a135714

File tree

4 files changed

+108
-119
lines changed

4 files changed

+108
-119
lines changed

‎source/active_record_querying.md

Lines changed: 93 additions & 113 deletions
Original file line numberDiff line numberDiff line change
@@ -93,9 +93,9 @@ The primary operation of `Model.find(options)` can be summarized as:
9393

9494
Active Record provides several different ways of retrieving a single object.
9595

96-
#### Using a Primary Key
96+
#### `find`
9797

98-
Using `Model.find(primary_key)`, you can retrieve the object corresponding to the specified _primary key_ that matches any supplied options. For example:
98+
Using the `find` method, you can retrieve the object corresponding to the specified _primary key_ that matches any supplied options. For example:
9999

100100
```ruby
101101
# Find the client with primary key (id) 10.
@@ -109,215 +109,180 @@ The SQL equivalent of the above is:
109109
SELECT * FROM clients WHERE (clients.id = 10) LIMIT 1
110110
```
111111

112-
`Model.find(primary_key)` will raise an `ActiveRecord::RecordNotFound` exception if no matching record is found.
112+
The `find` method will raise an `ActiveRecord::RecordNotFound` exception if no matching record is found.
113113

114-
#### `take`
115-
116-
`Model.take` retrieves a record without any implicit ordering. For example:
114+
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:
117115

118116
```ruby
119-
client = Client.take
120-
# => #<Client id: 1, first_name: "Lifo">
117+
# Find the clients with primary keys 1 and 10.
118+
client = Client.find([1, 10]) # Or even Client.find(1, 10)
119+
# => [#<Client id: 1, first_name: "Lifo">, #<Client id: 10, first_name: "Ryan">]
121120
```
122121

123122
The SQL equivalent of the above is:
124123

125124
```sql
126-
SELECT * FROM clients LIMIT 1
125+
SELECT * FROM clients WHERE (clients.id IN (1,10))
127126
```
128127

129-
`Model.take` returns `nil` if no record is found and no exception will be raised.
130-
131-
TIP: The retrieved record may vary depending on the database engine.
128+
WARNING: The `find` method will raise an `ActiveRecord::RecordNotFound` exception unless a matching record is found for **all** of the supplied primary keys.
132129

133-
#### `first`
130+
#### `take`
134131

135-
`Model.first` finds the first record ordered by the primary key. For example:
132+
The `take` method retrieves a record without any implicit ordering. For example:
136133

137134
```ruby
138-
client = Client.first
135+
client = Client.take
139136
# => #<Client id: 1, first_name: "Lifo">
140137
```
141138

142139
The SQL equivalent of the above is:
143140

144141
```sql
145-
SELECT * FROM clients ORDER BY clients.id ASC LIMIT 1
142+
SELECT * FROM clients LIMIT 1
146143
```
147144

148-
`Model.first` returns `nil` if no matching record is found and no exception will be raised.
149-
150-
#### `last`
145+
The `take` method returns `nil` if no record is found and no exception will be raised.
151146

152-
`Model.last` finds the last record ordered by the primary key. For example:
147+
You can pass in a numerical argument to the `take` method to return up to that number of results. For example
153148

154149
```ruby
155-
client = Client.last
156-
# => #<Client id: 221, first_name: "Russel">
150+
client = Client.take(2)
151+
# => [
152+
#<Client id: 1, first_name: "Lifo">,
153+
#<Client id: 220, first_name: "Sara">
154+
]
157155
```
158156

159157
The SQL equivalent of the above is:
160158

161159
```sql
162-
SELECT * FROM clients ORDER BY clients.id DESC LIMIT 1
160+
SELECT * FROM clients LIMIT 2
163161
```
164162

165-
`Model.last` returns `nil` if no matching record is found and no exception will be raised.
163+
The `take!` method behaves exactly like `take`, except that it will raise `ActiveRecord::RecordNotFound` if no matching record is found.
166164

167-
#### `find_by`
165+
TIP: The retrieved record may vary depending on the database engine.
168166

169-
`Model.find_by` finds the first record matching some conditions. For example:
167+
#### `first`
168+
169+
The `first` method finds the first record ordered by the primary key. For example:
170170

171171
```ruby
172-
Client.find_by first_name: 'Lifo'
172+
client = Client.first
173173
# => #<Client id: 1, first_name: "Lifo">
174-
175-
Client.find_by first_name: 'Jon'
176-
# => nil
177174
```
178175

179-
It is equivalent to writing:
176+
The SQL equivalent of the above is:
180177

181-
```ruby
182-
Client.where(first_name: 'Lifo').take
178+
```sql
179+
SELECT * FROM clients ORDER BY clients.id ASC LIMIT 1
183180
```
184181

185-
#### `take!`
182+
The `first` method returns `nil` if no matching record is found and no exception will be raised.
186183

187-
`Model.take!` retrieves a record without any implicit ordering. For example:
184+
You can pass in a numerical argument to the `first` method to return up to that number of results. For example
188185

189186
```ruby
190-
client = Client.take!
191-
# => #<Client id: 1, first_name: "Lifo">
187+
client = Client.first(3)
188+
# => [
189+
#<Client id: 1, first_name: "Lifo">,
190+
#<Client id: 2, first_name: "Fifo">,
191+
#<Client id: 3, first_name: "Filo">
192+
]
192193
```
193194

194195
The SQL equivalent of the above is:
195196

196197
```sql
197-
SELECT * FROM clients LIMIT 1
198+
SELECT * FROM clients ORDER BY clients.id ASC LIMIT 3
198199
```
199200

200-
`Model.take!` raises `ActiveRecord::RecordNotFound` if no matching record is found.
201+
The `first!` method behaves exactly like `first`, except that it will raise `ActiveRecord::RecordNotFound` if no matching record is found.
201202

202-
#### `first!`
203+
#### `last`
203204

204-
`Model.first!` finds the first record ordered by the primary key. For example:
205+
The `last` method finds the last record ordered by the primary key. For example:
205206

206207
```ruby
207-
client = Client.first!
208-
# => #<Client id: 1, first_name: "Lifo">
208+
client = Client.last
209+
# => #<Client id: 221, first_name: "Russel">
209210
```
210211

211212
The SQL equivalent of the above is:
212213

213214
```sql
214-
SELECT * FROM clients ORDER BY clients.id ASC LIMIT 1
215+
SELECT * FROM clients ORDER BY clients.id DESC LIMIT 1
215216
```
216217

217-
`Model.first!` raises `ActiveRecord::RecordNotFound` if no matching record is found.
218-
219-
#### `last!`
218+
The `last` method returns `nil` if no matching record is found and no exception will be raised.
220219

221-
`Model.last!` finds the last record ordered by the primary key. For example:
220+
You can pass in a numerical argument to the `last` method to return up to that number of results. For example
222221

223222
```ruby
224-
client = Client.last!
225-
# => #<Client id: 221, first_name: "Russel">
223+
client = Client.last(3)
224+
# => [
225+
#<Client id: 219, first_name: "James">,
226+
#<Client id: 220, first_name: "Sara">,
227+
#<Client id: 221, first_name: "Russel">
228+
]
226229
```
227230

228231
The SQL equivalent of the above is:
229232

230233
```sql
231-
SELECT * FROM clients ORDER BY clients.id DESC LIMIT 1
234+
SELECT * FROM clients ORDER BY clients.id DESC LIMIT 3
232235
```
233236

234-
`Model.last!` raises `ActiveRecord::RecordNotFound` if no matching record is found.
237+
The `last!` method behaves exactly like `last`, except that it will raise `ActiveRecord::RecordNotFound` if no matching record is found.
235238

236-
#### `find_by!`
239+
#### `find_by`
237240

238-
`Model.find_by!` finds the first record matching some conditions. It raises `ActiveRecord::RecordNotFound` if no matching record is found. For example:
241+
The `find_by` method finds the first record matching some conditions. For example:
239242

240243
```ruby
241-
Client.find_by! first_name: 'Lifo'
244+
Client.find_by first_name: 'Lifo'
242245
# => #<Client id: 1, first_name: "Lifo">
243246

244-
Client.find_by! first_name: 'Jon'
245-
# => ActiveRecord::RecordNotFound
247+
Client.find_by first_name: 'Jon'
248+
# => nil
246249
```
247250

248251
It is equivalent to writing:
249252

250253
```ruby
251-
Client.where(first_name: 'Lifo').take!
254+
Client.where(first_name: 'Lifo').take
252255
```
253256

254-
### Retrieving Multiple Objects
255-
256-
#### Using Multiple Primary Keys
257-
258-
`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:
257+
The `find_by!` method behaves exactly like `find_by`, except that it will raise `ActiveRecord::RecordNotFound` if no matching record is found. For example:
259258

260259
```ruby
261-
# Find the clients with primary keys 1 and 10.
262-
client = Client.find([1, 10]) # Or even Client.find(1, 10)
263-
# => [#<Client id: 1, first_name: "Lifo">, #<Client id: 10, first_name: "Ryan">]
264-
```
265-
266-
The SQL equivalent of the above is:
267-
268-
```sql
269-
SELECT * FROM clients WHERE (clients.id IN (1,10))
260+
Client.find_by! first_name: 'does not exist'
261+
# => ActiveRecord::RecordNotFound
270262
```
271263

272-
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.
273-
274-
#### take
275-
276-
`Model.take(limit)` retrieves the first number of records specified by `limit` without any explicit ordering:
264+
This is equivalent to writing:
277265

278266
```ruby
279-
Client.take(2)
280-
# => [#<Client id: 1, first_name: "Lifo">,
281-
#<Client id: 2, first_name: "Raf">]
282-
```
283-
284-
The SQL equivalent of the above is:
285-
286-
```sql
287-
SELECT * FROM clients LIMIT 2
267+
Client.where(first_name: 'does not exist').take!
288268
```
289269

290-
#### first
270+
#### `last!`
291271

292-
`Model.first(limit)` finds the first number of records specified by `limit` ordered by primary key:
272+
`Model.last!` finds the last record ordered by the primary key. For example:
293273

294274
```ruby
295-
Client.first(2)
296-
# => [#<Client id: 1, first_name: "Lifo">,
297-
#<Client id: 2, first_name: "Raf">]
275+
client = Client.last!
276+
# => #<Client id: 221, first_name: "Russel">
298277
```
299278

300279
The SQL equivalent of the above is:
301280

302281
```sql
303-
SELECT * FROM clients ORDER BY id ASC LIMIT 2
304-
```
305-
306-
#### last
307-
308-
`Model.last(limit)` finds the number of records specified by `limit` ordered by primary key in descending order:
309-
310-
```ruby
311-
Client.last(2)
312-
# => [#<Client id: 10, first_name: "Ryan">,
313-
#<Client id: 9, first_name: "John">]
282+
SELECT * FROM clients ORDER BY clients.id DESC LIMIT 1
314283
```
315284

316-
The SQL equivalent of the above is:
317-
318-
```sql
319-
SELECT * FROM clients ORDER BY id DESC LIMIT 2
320-
```
285+
`Model.last!` raises `ActiveRecord::RecordNotFound` if no matching record is found.
321286

322287
### Retrieving Multiple Objects in Batches
323288

@@ -344,7 +309,15 @@ The `find_each` method retrieves a batch of records and then yields _each_ recor
344309

345310
```ruby
346311
User.find_each do |user|
347-
NewsLetter.weekly_deliver(user)
312+
NewsMailer.weekly(user).deliver
313+
end
314+
```
315+
316+
To add conditions to a `find_each` operation you can chain other Active Record methods such as `where`:
317+
318+
```ruby
319+
User.where(weekly_subscriber: true).find_each do |user|
320+
NewsMailer.weekly(user).deliver
348321
end
349322
```
350323

@@ -707,7 +680,7 @@ Overriding Conditions
707680
You can specify certain conditions to be removed using the `unscope` method. For example:
708681

709682
```ruby
710-
Article.where('id > 10').limit(20).order('id asc').except(:order)
683+
Article.where('id > 10').limit(20).order('id asc').unscope(:order)
711684
```
712685

713686
The SQL that would be executed:
@@ -720,7 +693,7 @@ SELECT * FROM articles WHERE id > 10 ORDER BY id asc LIMIT 20
720693

721694
```
722695

723-
You can additionally unscope specific where clauses. For example:
696+
You can also unscope specific `where` clauses. For example:
724697

725698
```ruby
726699
Article.where(id: 10, trashed: false).unscope(where: :id)
@@ -759,8 +732,6 @@ The `reorder` method overrides the default scope order. For example:
759732

760733
```ruby
761734
class Article < ActiveRecord::Base
762-
..
763-
..
764735
has_many :comments, -> { order('posted_at DESC') }
765736
end
766737

@@ -1487,6 +1458,11 @@ If you'd like to use your own SQL to find records in a table you can use `find_b
14871458
Client.find_by_sql("SELECT * FROM clients
14881459
INNER JOIN orders ON clients.id = orders.client_id
14891460
ORDER BY clients.created_at desc")
1461+
# => [
1462+
#<Client id: 1, first_name: "Lucas" >,
1463+
#<Client id: 2, first_name: "Jan" >,
1464+
# ...
1465+
]
14901466
```
14911467

14921468
`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
14961472
`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.
14971473

14981474
```ruby
1499-
Client.connection.select_all("SELECT * FROM clients WHERE id = '1'")
1475+
Client.connection.select_all("SELECT first_name, created_at FROM clients WHERE id = '1'")
1476+
# => [
1477+
{"first_name"=>"Rafael", "created_at"=>"2012-11-10 23:23:45.281189"},
1478+
{"first_name"=>"Eileen", "created_at"=>"2013-12-09 11:22:35.221282"}
1479+
]
15001480
```
15011481

15021482
### `pluck`

‎source/active_record_validations.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -910,8 +910,8 @@ end
910910
The easiest way to add custom validators for validating individual attributes
911911
is with the convenient `ActiveModel::EachValidator`. In this case, the custom
912912
validator class must implement a `validate_each` method which takes three
913-
arguments: record, attribute and value which correspond to the instance, the
914-
attribute to be validated and the value of the attribute in the passed
913+
arguments: record, attribute, and value. These correspond to the instance, the
914+
attribute to be validated, and the value of the attribute in the passed
915915
instance.
916916

917917
```ruby

‎source/getting_started.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -749,8 +749,7 @@ to create an article. Try it! You should get an error that looks like this:
749749
(images/getting_started/forbidden_attributes_for_new_article.png)
750750

751751
Rails has several security features that help you write secure applications,
752-
and you're running into one of them now. This one is called `[strong_parameters]
753-
(http://guides.rubyonrails.org/action_controller_overview.html#strong-parameters)`,
752+
and you're running into one of them now. This one is called [strong parameters](http://guides.rubyonrails.org/action_controller_overview.html#strong-parameters),
754753
which requires us to tell Rails exactly which parameters are allowed into our
755754
controller actions.
756755

0 commit comments

Comments
 (0)