From 3b6d66a0c8cb631b8fadf7472bc068c9b9bf9f65 Mon Sep 17 00:00:00 2001
From: Vijay Dev <vijaydev.cse@gmail.com>
Date: Wed, 30 May 2012 23:05:48 +0530
Subject: Revert "Revert "[AR querying guide] Add examples for take(limit),
 first(limit) and last(limit)""

This reverts commit 5559a2ae98dcda6854f38890025b52edfb2836f5.

Reason: These are for selecting multiple objects and there isn't a need
to club them with the selecting single objects section, as discussed
with the author.
---
 guides/source/active_record_querying.textile | 48 ++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

(limited to 'guides/source')

diff --git a/guides/source/active_record_querying.textile b/guides/source/active_record_querying.textile
index 294ef25b33..eceeb814fd 100644
--- a/guides/source/active_record_querying.textile
+++ b/guides/source/active_record_querying.textile
@@ -259,6 +259,54 @@ SELECT * FROM clients WHERE (clients.id IN (1,10))
 
 WARNING: <tt>Model.find(array_of_primary_key)</tt> will raise an +ActiveRecord::RecordNotFound+ exception unless a matching record is found for <strong>all</strong> of the supplied primary keys.
 
+h5. take
+
+<tt>Model.take(limit)</tt> retrieves the first number of records specified by +limit+ without any explicit ordering:
+
+<ruby>
+Client.take(2)
+# => [#<Client id: 1, first_name: "Lifo">, 
+      #<Client id: 2, first_name: "Raf">]
+</ruby>
+
+The SQL equivalent of the above is:
+
+<sql>
+SELECT * FROM clients LIMIT 2
+</sql>
+
+h5. first
+
+<tt>Model.first(limit)</tt> finds the first number of records specified by +limit+ ordered by primary key:
+
+<ruby>
+Client.first(2)
+# => [#<Client id: 1, first_name: "Lifo">, 
+      #<Client id: 2, first_name: "Raf">]
+</ruby>
+
+The SQL equivalent of the above is:
+
+<sql>
+SELECT * FROM clients LIMIT 2
+</sql>
+
+h5. last
+
+<tt>Model.last(limit)</tt> 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">]
+</ruby>
+
+The SQL equivalent of the above is:
+
+<sql>
+SELECT * FROM clients ORDER By id DESC LIMIT 2
+</sql>
+
 h4. 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