Skip to content

Commit e26c4d2

Browse files
jordan-smith721jordan-smith721
authored
DOCSP-37540/1/9 Limit, Sort, Skip (#66)
1 parent ce91c70 commit e26c4d2

File tree

3 files changed

+311
-0
lines changed

3 files changed

+311
-0
lines changed

‎source/includes/read/specify-documents-to-return.py

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# start-limit-method
2+
results = restaurants.find({ "cuisine" : "Italian"}).limit(5)
3+
4+
for restaurant in results:
5+
print(restaurant["name"])
6+
# end-limit-method
7+
8+
# start-limit-option
9+
results = restaurants.find({ "cuisine" : "Italian"}, limit=5)
10+
11+
for restaurant in results:
12+
print(restaurant["name"])
13+
# end-limit-option
14+
15+
# start-sort-method
16+
results = restaurants.find({ "cuisine" : "Italian"}).sort("name", pymongo.ASCENDING)
17+
18+
for restaurant in results:
19+
print(restaurant["name"])
20+
# end-sort-method
21+
22+
# start-sort-option
23+
results = restaurants.find({ "cuisine" : "Italian"}, sort={"name": pymongo.ASCENDING} )
24+
25+
for restaurant in results:
26+
print(restaurant["name"])
27+
# end-sort-option
28+
29+
# start-skip
30+
results = restaurants.find({ "borough" : "Manhattan"}).skip(10)
31+
32+
for restaurant in results:
33+
print(restaurant["name"])
34+
# end-skip
35+
36+
# start-skip-option
37+
results = restaurants.find({ "borough" : "Manhattan"}, skip=10)
38+
39+
for restaurant in results:
40+
print(restaurant["name"])
41+
# end-skip-option
42+
43+
# start-limit-sort-skip
44+
results = restaurants.find({ "cuisine" : "Italian"}) \
45+
.sort("name", pymongo.ASCENDING) \
46+
.limit(5) \
47+
.skip(10)
48+
49+
for restaurant in results:
50+
print(restaurant["name"])
51+
# end-limit-sort-skip
52+
53+
# start-limit-sort-skip-option
54+
results = restaurants.find({ "cuisine" : "Italian"}, limit=5, sort={"name": pymongo.ASCENDING}, skip=10)
55+
56+
for restaurant in results:
57+
print(restaurant["name"])
58+
# end-limit-sort-skip-option

‎source/read.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,13 +14,16 @@ Read Data from MongoDB
1414
/read/specify-a-query
1515
/read/retrieve
1616
/read/project
17+
/read/specify-documents-to-return
1718
/read/count
1819
/read/distinct
1920
/read/cursors
2021

2122
- :ref:`pymongo-specify-query`
2223
- :ref:`pymongo-retrieve`
2324
- :ref:`pymongo-project`
25+
- :ref:`pymongo-specify-documents-to-return`
2426
- :ref:`pymongo-count`
2527
- :ref:`pymongo-distinct`
2628
- :ref:`pymongo-cursors`
29+

‎source/read/specify-documents-to-return.txt

Lines changed: 250 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,250 @@
1+
.. _pymongo-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 from a read
24+
operation by using the following methods:
25+
26+
- ``limit()``: Specifies the maximum number of documents to return from a query.
27+
- ``sort()``: Specifies the sort order for the returned documents.
28+
- ``skip()``: Specifies the number of documents to skip before returning query results.
29+
30+
Sample Data
31+
~~~~~~~~~~~
32+
33+
The examples in this guide use the ``sample_restaurants.restaurants`` collection
34+
from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
35+
free MongoDB Atlas cluster and load the sample datasets, see the :ref:`<pymongo-get-started>`.
36+
37+
Limit
38+
-----
39+
40+
To specify the maximum number of documents returned from a read operation,
41+
call the ``limit()`` method.
42+
43+
The following example finds all restaurants that have a ``cuisine`` field value
44+
of ``"Italian"``, and limits the results to 5 documents:
45+
46+
.. io-code-block::
47+
48+
.. input:: /includes/read/specify-documents-to-return.py
49+
:start-after: start-limit-method
50+
:end-before: end-limit-method
51+
:language: python
52+
53+
.. output::
54+
55+
Isle Of Capri Resturant Italian
56+
Arturo'S Italian
57+
Patsy'S Italian Restaurant Italian
58+
Piccola Venezia Italian
59+
Roadhouse Restaurant Italian
60+
61+
You can also limit the number of returned documents by specifying the ``limit``
62+
parameter in your ``find()`` method:
63+
64+
.. io-code-block::
65+
66+
.. input:: /includes/read/specify-documents-to-return.py
67+
:start-after: start-limit-option
68+
:end-before: end-limit-option
69+
:language: python
70+
71+
.. output::
72+
73+
Isle Of Capri Resturant Italian
74+
Arturo'S Italian
75+
Patsy'S Italian Restaurant Italian
76+
Piccola Venezia Italian
77+
Roadhouse Restaurant Italian
78+
79+
.. tip::
80+
81+
The preceding examples return the first five documents returned by the query, in
82+
no particular order. The following section describes how to return the documents
83+
in a specified sort order.
84+
85+
Sort
86+
----
87+
88+
To return documents in a specified order, call the ``sort()`` method. The ``sort()``
89+
method takes two parameters: the field to sort the results by, and a sort direction. To
90+
specify the sort direction, specify either ``pymongo.ASCENDING`` or
91+
``pymongo.DESCENDING``. ``ASCENDING`` sorts values from lowest to highest, and
92+
``DESCENDING`` sorts them from highest to lowest. If you don't specify either
93+
direction, the method defaults to sorting in ascending order.
94+
95+
The following example returns all documents with the ``cuisine`` value of
96+
``"Italian"``, sorted in ascending order:
97+
98+
.. io-code-block::
99+
100+
.. input:: /includes/read/specify-documents-to-return.py
101+
:start-after: start-sort-method
102+
:end-before: end-sort-method
103+
:language: python
104+
105+
.. output::
106+
107+
(Lewis Drug Store) Locanda Vini E Olii
108+
101 Restaurant And Bar
109+
44 Sw Ristorante & Bar
110+
900 Park
111+
A Voce
112+
...
113+
Zucchero E Pomodori
114+
115+
You can also sort documents by specifying the ``sort`` parameter in your ``find()``
116+
method. The following example specifies the ``sort`` parameter to return the
117+
results in the same order as the preceding example:
118+
119+
.. io-code-block::
120+
121+
.. input:: /includes/read/specify-documents-to-return.py
122+
:start-after: start-sort-option
123+
:end-before: end-sort-option
124+
:language: python
125+
126+
.. output::
127+
128+
(Lewis Drug Store) Locanda Vini E Olii
129+
101 Restaurant And Bar
130+
44 Sw Ristorante & Bar
131+
900 Park
132+
A Voce
133+
...
134+
Zucchero E Pomodori
135+
136+
Skip
137+
----
138+
139+
To skip a specified number of documents before returning your query results,
140+
call the ``skip()`` method and pass in the number of documents to skip. The
141+
``skip()`` method ignores the specified number of documents in your query
142+
results and returns the rest.
143+
144+
The following example returns all documents that have a ``borough`` field value
145+
of ``"Manhattan"``, and skips the first 10 documents:
146+
147+
.. io-code-block::
148+
149+
.. input:: /includes/read/specify-documents-to-return.py
150+
:start-after: start-skip
151+
:end-before: end-skip
152+
:language: python
153+
154+
.. output::
155+
156+
Dorrian'S Red Hand Restaurant
157+
The Princeton Club
158+
Moran'S Chelsea
159+
La Parisienne Diner
160+
Jimmy'S Corner
161+
...
162+
163+
You can also skip returned documents by using the ``skip``
164+
parameter of the ``find()`` method. The following example specifies the
165+
same skip as the preceding example:
166+
167+
.. io-code-block::
168+
169+
.. input:: /includes/read/specify-documents-to-return.py
170+
:start-after: start-skip-option
171+
:end-before: end-skip-option
172+
:language: python
173+
174+
.. output::
175+
176+
Dorrian'S Red Hand Restaurant
177+
The Princeton Club
178+
Moran'S Chelsea
179+
La Parisienne Diner
180+
Jimmy'S Corner
181+
...
182+
183+
Combine Limit, Sort, and Skip
184+
-----------------------------
185+
186+
You can combine the ``limit()``, ``sort()``, and ``skip()`` methods in a single
187+
operation. This allows you to set a maximum number of sorted documents to
188+
return, skipping a specified number of documents before returning.
189+
190+
The following example returns documents with the ``cuisine`` value of
191+
``"Italian"``. The results are sorted in alphabetical order, skipping the first
192+
10 documents:
193+
194+
.. io-code-block::
195+
196+
.. input:: /includes/read/specify-documents-to-return.py
197+
:start-after: start-limit-sort-skip
198+
:end-before: end-limit-sort-skip
199+
:language: python
200+
201+
.. output::
202+
203+
Acqua
204+
Acqua Restaurant
205+
Acqua Santa
206+
Acquista Trattoria
207+
Acquolina Catering
208+
209+
.. note::
210+
211+
The order in which you call these methods doesn't change the documents
212+
that are returned. The driver automatically reorders the calls to perform the
213+
sort and skip operations first, and the limit operation afterward.
214+
215+
You can also limit, sort, and skip results by specifying them as
216+
parameters in the ``find()`` method. The following example specifies the
217+
same query as the preceding example:
218+
219+
.. io-code-block::
220+
221+
.. input:: /includes/read/specify-documents-to-return.py
222+
:start-after: start-limit-sort-skip-option
223+
:end-before: end-limit-sort-skip-option
224+
:language: python
225+
226+
.. output::
227+
228+
Acqua
229+
Acqua Restaurant
230+
Acqua Santa
231+
Acquista Trattoria
232+
Acquolina Catering
233+
234+
Additional Information
235+
----------------------
236+
237+
For more information about specifying a query, see :ref:`pymongo-specify-query`.
238+
239+
For more information about retrieving documents, see :ref:`pymongo-retrieve`.
240+
241+
API Documentation
242+
~~~~~~~~~~~~~~~~~
243+
244+
To learn more about any of the methods or types discussed in this
245+
guide, see the following API Documentation:
246+
247+
- `find() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.find>`__
248+
- `limit() <{+api-root+}pymongo/cursor.html#pymongo.cursor.Cursor.limit>`__
249+
- `sort() <{+api-root+}pymongo/cursor.html#pymongo.cursor.Cursor.sort>`__
250+
- `skip() <{+api-root+}pymongo/cursor.html#pymongo.cursor.Cursor.skip>`__

0 commit comments

Comments
 (0)