Skip to content

Commit 3bc777b

Browse files
norareidynorareidy
authored
DOCSP-45196: Limit, skip, and sort (#109)
* DOCSP-45196: Limit, skip, and sort * code output * fixes
1 parent a1238e5 commit 3bc777b

File tree

3 files changed

+263
-1
lines changed

3 files changed

+263
-1
lines changed

Diff for: ‎source/includes/read/limit-skip-sort.rb

+51
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
require 'bundler/inline'
2+
3+
gemfile do
4+
source 'https://rubygems.org'
5+
gem 'mongo'
6+
end
7+
8+
uri = '<connection string>'
9+
10+
Mongo::Client.new(uri) do |client|
11+
# Access the database and collection
12+
# start-db-coll
13+
database = client.use('sample_restaurants')
14+
collection = database[:restaurants]
15+
# end-db-coll
16+
17+
# Retrieves 5 documents that have a "cuisine" value of "Italian"
18+
# start-limit
19+
filter = { cuisine: 'Italian' }
20+
collection.find(filter)
21+
.limit(5)
22+
.each { |doc| puts doc }
23+
# end-limit
24+
25+
# Retrieves documents with a "cuisine" value of "Italian" and sorts in ascending "name" order
26+
# start-sort
27+
filter = { cuisine: 'Italian' }
28+
collection.find(filter)
29+
.sort(name: 1)
30+
.each { |doc| puts doc }
31+
# end-sort
32+
33+
# Retrieves documents with a "borough" value of "Manhattan" but skips the first 10 results
34+
# start-skip
35+
filter = { borough: 'Manhattan' }
36+
collection.find(filter)
37+
.skip(10)
38+
.each { |doc| puts doc }
39+
# end-skip
40+
41+
# Retrieves 5 documents with a "cuisine" value of "Italian", skips the first 10 results,
42+
# and sorts by ascending "name" order
43+
# start-limit-sort-skip
44+
filter = { cuisine: 'Italian' }
45+
collection.find(filter)
46+
.limit(5)
47+
.skip(10)
48+
.sort(name: 1)
49+
.each { |doc| puts doc }
50+
# end-limit-sort-skip
51+
end

Diff for: ‎source/read.txt

+2-1
Original file line numberDiff line numberDiff line change
@@ -23,4 +23,5 @@ Read Data from MongoDB
2323
:maxdepth: 1
2424

2525
Retrieve Data </read/retrieve>
26-
Specify Fields to Return </read/project>
26+
Specify Documents to Return </read/specify-documents-to-return>
27+
Specify Fields to Return </read/project>

Diff for: ‎source/read/specify-documents-to-return.txt

+210
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
.. _ruby-specify-documents-to-return:
2+
3+
===========================
4+
Specify Documents to Return
5+
===========================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: read, paginate, pagination, order, code example
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to specify which documents to return
24+
from a read operation by chaining the following methods to the ``find``
25+
method:
26+
27+
- :ref:`limit <ruby-return-documents-limit>`: Specifies the maximum number of documents
28+
to return from a query
29+
- :ref:`sort <ruby-return-documents-sort>`: Specifies the sort order for the returned documents
30+
- :ref:`skip <ruby-return-documents-skip>`: Specifies the number of documents to skip before
31+
returning query results
32+
33+
Sample Data
34+
~~~~~~~~~~~
35+
36+
The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants``
37+
database from the :atlas:`Atlas sample datasets </sample-data>`. To access this collection
38+
from your {+language+} application, create a ``Mongo::Client`` object that connects to
39+
an Atlas cluster and assign the following values to your ``database`` and ``collection``
40+
variables:
41+
42+
.. literalinclude:: /includes/read/limit-skip-sort.rb
43+
:language: ruby
44+
:dedent:
45+
:start-after: start-db-coll
46+
:end-before: end-db-coll
47+
48+
To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the
49+
:atlas:`Get Started with Atlas </getting-started>` guide.
50+
51+
.. _ruby-return-documents-limit:
52+
53+
Limit
54+
-----
55+
56+
To specify the maximum number of documents returned from a read operation, apply
57+
the ``limit`` option to the operation. You can set this option by chaining the
58+
``limit`` setter method to the ``find`` method.
59+
60+
The following example finds all restaurants that have a ``cuisine`` field value
61+
of ``'Italian'`` and limits the results to ``5`` documents:
62+
63+
.. io-code-block::
64+
:copyable:
65+
66+
.. input:: /includes/read/limit-skip-sort.rb
67+
:start-after: start-limit
68+
:end-before: end-limit
69+
:language: ruby
70+
:dedent:
71+
72+
.. output::
73+
:visible: false
74+
75+
{"_id"=>BSON::ObjectId('...'), ... , "name"=>"Philadelhia Grille Express",
76+
"restaurant_id"=>"40364305"}
77+
{"_id"=>BSON::ObjectId('...'), ... , "name"=>"Isle Of Capri Restaurant",
78+
"restaurant_id"=>"40364373"}
79+
{"_id"=>BSON::ObjectId('...'), ... , "name"=>"Marchis Restaurant",
80+
"restaurant_id"=>"40364668"}
81+
{"_id"=>BSON::ObjectId('...'), ... , "name"=>"Crystal Room",
82+
"restaurant_id"=>"40365013"}
83+
{"_id"=>BSON::ObjectId('...'), ... , name"=>"Forlinis Restaurant",
84+
"restaurant_id"=>"40365098"}
85+
86+
.. tip::
87+
88+
The preceding example returns the first five documents matched by the query
89+
according to their :manual:`natural order </reference/glossary/#std-term-natural-order>`
90+
in the database. The following section describes how to return the documents
91+
in a specified order.
92+
93+
.. _ruby-return-documents-sort:
94+
95+
Sort
96+
----
97+
98+
To return documents in a specified order, apply the ``sort`` option to
99+
the read operation. You can set this option by chaining the ``sort``
100+
setter method to the ``find`` method.
101+
102+
When calling ``sort``, pass the field to sort the results by and the
103+
sort direction. A sort direction value of ``1`` sorts values from lowest
104+
to highest, and a value of ``-1`` sorts them from highest to lowest.
105+
106+
The following example returns all documents that have a ``cuisine`` field value
107+
of ``'Italian'``, sorted in ascending order of ``name`` field values:
108+
109+
.. io-code-block::
110+
:copyable:
111+
112+
.. input:: /includes/read/limit-skip-sort.rb
113+
:start-after: start-sort
114+
:end-before: end-sort
115+
:language: ruby
116+
:dedent:
117+
118+
.. output::
119+
:visible: false
120+
121+
{"_id"=>BSON::ObjectId('...'), ... , "name"=>"(Lewis Drug Store) Locanda Vini E Olii",
122+
"restaurant_id"=>"40804423"}
123+
{"_id"=>BSON::ObjectId('...'), ... , "name"=>"101 Restaurant And Bar",
124+
"restaurant_id"=>"40560108"}
125+
...
126+
{"_id"=>BSON::ObjectId('...'), ... , "name"=>"Zucchero E Pomodori",
127+
"restaurant_id"=>"41189590"}
128+
129+
.. _ruby-return-documents-skip:
130+
131+
Skip
132+
----
133+
134+
To skip a specified number of documents before returning your query results, apply
135+
the ``skip`` option to the read operation. You can set this option by chaining the
136+
``skip`` setter method to the ``find`` method.
137+
138+
The following example returns all documents that have a ``borough`` field value
139+
of ``'Manhattan'`` and skips the first ``10`` documents:
140+
141+
.. io-code-block::
142+
:copyable:
143+
144+
.. input:: /includes/read/limit-skip-sort.rb
145+
:start-after: start-skip
146+
:end-before: end-skip
147+
:language: ruby
148+
:dedent:
149+
150+
.. output::
151+
:visible: false
152+
153+
{"_id"=>BSON::ObjectId('...'), ... , "name"=>"Cafe Metro", "restaurant_id"=>"40363298"}
154+
{"_id"=>BSON::ObjectId('...'), ... , "name"=>"Lexler Deli", "restaurant_id"=>"40363426"}
155+
{"_id"=>BSON::ObjectId('...'), ... , "name"=>"Domino'S Pizza", "restaurant_id"=>"40363644"}
156+
...
157+
158+
.. _ruby-return-documents-combine:
159+
160+
Combine Limit, Sort, and Skip
161+
-----------------------------
162+
163+
You can chain the ``limit``, ``sort``, and ``skip`` methods to a single
164+
``find`` method call. This allows you to set a maximum number of sorted documents
165+
to return from the read operation, skipping a specified number of documents before
166+
returning.
167+
168+
The following example returns ``5`` documents that have a ``cuisine`` value of
169+
``'Italian'``. The results are sorted in ascending order by the ``name`` field value,
170+
skipping the first ``10`` documents:
171+
172+
.. io-code-block::
173+
:copyable:
174+
175+
.. input:: /includes/read/limit-skip-sort.rb
176+
:start-after: start-limit-sort-skip
177+
:end-before: end-limit-sort-skip
178+
:language: ruby
179+
:dedent:
180+
181+
.. output::
182+
:visible: false
183+
184+
{"_id"=>BSON::ObjectId('...'), ... , "name"=>"Acqua", "restaurant_id"=>"40871070"}
185+
{"_id"=>BSON::ObjectId('...'), ... , "name"=>"Acqua Restaurant",
186+
"restaurant_id"=>"41591488"}
187+
{"_id"=>BSON::ObjectId('...'), ... , "name"=>"Acqua Santa", "restaurant_id"=>"40735858"}
188+
{"_id"=>BSON::ObjectId('...'), ... , "name"=>"Acquista Trattoria",
189+
"restaurant_id"=>"40813992"}
190+
{"_id"=>BSON::ObjectId('...'), ... , "name"=>"Acquolina Catering", "restaurant_id"=>"41381423"}
191+
192+
.. note::
193+
194+
The order in which you call these methods doesn't change the documents
195+
that are returned. The {+driver-short+} automatically reorders the calls to
196+
perform the sort operation first, the skip operation next, and then the limit
197+
operation.
198+
199+
Additional Information
200+
----------------------
201+
202+
For more information about retrieving documents, see the :ref:`ruby-retrieve` guide.
203+
204+
.. TODO: For more information about specifying a query, see the :ref:`ruby-specify-query` guide.
205+
206+
API Documentation
207+
~~~~~~~~~~~~~~~~~
208+
209+
To learn more about the ``find`` method and its options, see the `API documentation.
210+
<{+api-root+}/Mongo/Collection.html#find-instance_method>`__

0 commit comments

Comments
 (0)