From 9d906d04ef09c585f215c0dcae6af05e0316831e Mon Sep 17 00:00:00 2001
From: Marcelo Silveira <marcelo@mhfs.com.br>
Date: Sat, 5 May 2012 13:15:09 -0300
Subject: Update `first`, `last` and `take` in guides

---
 guides/source/active_record_querying.textile | 50 +++++++++++++++++++++++-----
 1 file changed, 42 insertions(+), 8 deletions(-)

(limited to 'guides/source')

diff --git a/guides/source/active_record_querying.textile b/guides/source/active_record_querying.textile
index f9dbaa1125..d16cdd66ee 100644
--- a/guides/source/active_record_querying.textile
+++ b/guides/source/active_record_querying.textile
@@ -99,9 +99,26 @@ SELECT * FROM clients WHERE (clients.id = 10) LIMIT 1
 
 <tt>Model.find(primary_key)</tt> will raise an +ActiveRecord::RecordNotFound+ exception if no matching record is found.
 
+h5. +take+
+
+<tt>Model.take</tt> retrieves a record without any implicit ordering. The retrieved record may vary depending on the database engine. For example:
+
+<ruby>
+client = Client.take
+# => #<Client id: 1, first_name: "Lifo">
+</ruby>
+
+The SQL equivalent of the above is:
+
+<sql>
+SELECT * FROM clients LIMIT 1
+</sql>
+
+<tt>Model.take</tt> returns +nil+ if no record is found. No exception will be raised.
+
 h5. +first+
 
-<tt>Model.first</tt> finds the first record matched by the supplied options, if any. For example:
+<tt>Model.first</tt> finds the first record. If no order is chained it will order by primary key. For example:
 
 <ruby>
 client = Client.first
@@ -111,14 +128,14 @@ client = Client.first
 The SQL equivalent of the above is:
 
 <sql>
-SELECT * FROM clients LIMIT 1
+SELECT * FROM clients ORDER BY clients.id ASC LIMIT 1
 </sql>
 
 <tt>Model.first</tt> returns +nil+ if no matching record is found. No exception will be raised.
 
 h5. +last+
 
-<tt>Model.last</tt> finds the last record matched by the supplied options. For example:
+<tt>Model.last</tt> finds the last record. If no order is chained it will order by primary key. For example:
 
 <ruby>
 client = Client.last
@@ -148,12 +165,29 @@ Client.find_by first_name: 'Jon'
 It is equivalent to writing:
 
 <ruby>
-Client.where(first_name: 'Lifo').first
+Client.where(first_name: 'Lifo').take
 </ruby>
 
+h5(#take_1). +take!+
+
+<tt>Model.take!</tt> retrieves a record without any implicit ordering. For example:
+
+<ruby>
+client = Client.take!
+# => #<Client id: 1, first_name: "Lifo">
+</ruby>
+
+The SQL equivalent of the above is:
+
+<sql>
+SELECT * FROM clients LIMIT 1
+</sql>
+
+<tt>Model.take!</tt> raises +RecordNotFound+ if no matching record is found.
+
 h5(#first_1). +first!+
 
-<tt>Model.first!</tt> finds the first record. For example:
+<tt>Model.first!</tt> finds the first record. If no order is chained it will order by primary key. For example:
 
 <ruby>
 client = Client.first!
@@ -163,14 +197,14 @@ client = Client.first!
 The SQL equivalent of the above is:
 
 <sql>
-SELECT * FROM clients LIMIT 1
+SELECT * FROM clients ORDER BY clients.id ASC LIMIT 1
 </sql>
 
 <tt>Model.first!</tt> raises +RecordNotFound+ if no matching record is found.
 
 h5(#last_1). +last!+
 
-<tt>Model.last!</tt> finds the last record. For example:
+<tt>Model.last!</tt> finds the last record. If no order is chained it will order by primary key. For example:
 
 <ruby>
 client = Client.last!
@@ -200,7 +234,7 @@ Client.find_by! first_name: 'Jon'
 It is equivalent to writing:
 
 <ruby>
-Client.where(first_name: 'Lifo').first!
+Client.where(first_name: 'Lifo').take!
 </ruby>
 
 h4. Retrieving Multiple Objects
-- 
cgit v1.2.3