Skip to content

Commit 3ec55d1

Browse files
norareidynorareidy
committed
DOCSP-41977: Specify documents to return
1 parent 2419c76 commit 3ec55d1

File tree

3 files changed

+262
-0
lines changed

3 files changed

+262
-0
lines changed

‎snooty.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,3 +24,4 @@ php-library = "MongoDB PHP Library"
2424

2525
[constants]
2626
php-library = "MongoDB PHP Library"
27+
api = "https://www.mongodb.com/docs/php-library/current/reference"

‎source/includes/read/limit-skip-sort.php

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
<?php
2+
3+
require 'vendor/autoload.php';
4+
5+
$client = new MongoDB\Client('<connection string>');
6+
7+
// start-db-coll
8+
$db = $client->sample_restaurants;
9+
$collection = $db->restaurants;
10+
// end-db-coll
11+
12+
// Retrieves 5 documents that have a "cuisine" value of "Italian"
13+
// start-limit
14+
$options = [
15+
'limit' => 5,
16+
];
17+
$cursor = $collection->find(['cuisine' => 'Italian'], $options);
18+
19+
foreach ($cursor as $doc) {
20+
echo json_encode($doc) . PHP_EOL;
21+
}
22+
// end-limit
23+
24+
// Retrieves documents with a "cuisine" value of "Italian" and sorts in ascending "name" order
25+
// start-sort
26+
$options = [
27+
'sort' => ['name' => 1],
28+
];
29+
30+
$cursor = $collection->find(['cuisine' => 'Italian'], $options);
31+
foreach ($cursor as $doc) {
32+
echo json_encode($doc) . PHP_EOL;
33+
}
34+
// end-sort
35+
36+
// Retrieves documents with a "borough" value of "Manhattan" but skips the first 10 results
37+
// start-skip
38+
$options = [
39+
'skip' => 10,
40+
];
41+
42+
$cursor = $collection->find(['borough' => 'Manhattan'], $options);
43+
foreach ($cursor as $doc) {
44+
echo json_encode($doc) . PHP_EOL;
45+
}
46+
// end-skip
47+
48+
// Retrieves 5 documents with a "cuisine" value of "Italian", skips the first 10 results,
49+
// and sorts by ascending "name" order
50+
// start-limit-sort-skip
51+
$options = [
52+
'sort' => ['name' => 1],
53+
'limit' => 5,
54+
'skip' => 10,
55+
];
56+
57+
$cursor = $collection->find(['cuisine' => 'Italian'], $options);
58+
foreach ($cursor as $doc) {
59+
echo json_encode($doc) . PHP_EOL;
60+
}
61+
// end-limit-sort-skip
62+
63+
?>

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

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
.. _php-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 passing the following options to the ``MongoDB\Collection::find()`` or
25+
``MongoDB\Collection::findOne()`` method:
26+
27+
- :ref:`limit <php-return-documents-limit>`: Specifies the maximum number of documents
28+
to return from a query.
29+
- :ref:`sort <php-return-documents-sort>`: Specifies the sort order for the returned documents.
30+
- :ref:`skip <php-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 PHP application, instantiate a ``MongoDB\Client`` that connects to an Atlas cluster
39+
and assign the following values to your ``db`` and ``collection`` variables:
40+
41+
.. literalinclude:: /includes/read/project.php
42+
:language: php
43+
:dedent:
44+
:start-after: start-db-coll
45+
:end-before: end-db-coll
46+
47+
To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the
48+
:atlas:`Get Started with Atlas </getting-started>` guide.
49+
50+
.. _php-return-documents-limit:
51+
52+
Limit
53+
-----
54+
55+
To specify the maximum number of documents returned from a read operation, create
56+
an array that sets the ``limit`` option and pass the array as a parameter to the
57+
``MongoDB\Collection::find()`` or ``MongoDB\Collection::findOne()`` method.
58+
59+
The following example finds all restaurants that have a ``cuisine`` field value
60+
of ``'Italian'`` and limits the results to ``5`` documents:
61+
62+
.. io-code-block::
63+
:copyable:
64+
65+
.. input:: /includes/read/limit-skip-sort.php
66+
:start-after: start-limit
67+
:end-before: end-limit
68+
:language: php
69+
:dedent:
70+
71+
.. output::
72+
73+
{ "_id" : { "$oid" : "..." }, ..., "name" : "Philadelphia Grille Express", "restaurant_id" : "40364305" }
74+
{ "_id" : { "$oid" : "..." }, ..., "name" : "Isle Of Capri Restaurant", "restaurant_id" : "40364373" }
75+
{ "_id" : { "$oid" : "..." }, ..., "name" : "Marchis Restaurant", "restaurant_id" : "40364668" }
76+
{ "_id" : { "$oid" : "..." }, ..., "name" : "Crystal Room", "restaurant_id" : "40365013" }
77+
{ "_id" : { "$oid" : "..." }, ..., "name" : "Forlinis Restaurant", "restaurant_id" : "40365098" }
78+
79+
.. tip::
80+
81+
The preceding example returns the first five documents matched by the query
82+
according to their :manual:`natural order </reference/glossary/#std-term-natural-order>`
83+
in the database. The following section describes how to return the documents
84+
in a specified order.
85+
86+
.. _php-return-documents-sort:
87+
88+
Sort
89+
----
90+
91+
To return documents in a specified order, create an array that sets the ``sort``
92+
option. When setting this option, include the field to sort the results by and
93+
the sort direction. A value of ``1`` sorts values from lowest to highest, and
94+
a value of ``-1`` sorts them from highest to lowest. Then, pass the array as a
95+
parameter to the ``MongoDB\Collection::find()`` or ``MongoDB\Collection::findOne()``
96+
method.
97+
98+
The following example returns all documents that have a ``cuisine`` value of ``'Italian'``,
99+
sorted in ascending order of ``name`` field values:
100+
101+
.. io-code-block::
102+
:copyable:
103+
104+
.. input:: /includes/read/limit-skip-sort.php
105+
:start-after: start-sort
106+
:end-before: end-sort
107+
:language: php
108+
:dedent:
109+
110+
.. output::
111+
112+
{ "_id" : { "$oid" : "..." }, ..., "name" : "(Lewis Drug Store) Locanda Vini E Olii", "restaurant_id" : "40804423" }
113+
{ "_id" : { "$oid" : "..." }, ..., "name" : "101 Restaurant And Bar", "restaurant_id" : "40560108" }
114+
{ "_id" : { "$oid" : "..." }, ..., "name" : "44 Sw Ristorante & Bar", "restaurant_id" : "40698807" }
115+
...
116+
{ "_id" : { "$oid" : "..." }, ..., "name" : "Zucchero E Pomodori", "restaurant_id" : "41189590" }
117+
118+
.. _php-return-documents-skip:
119+
120+
Skip
121+
----
122+
123+
To skip a specified number of documents before returning your query results, create
124+
an array that sets the ``skip`` option and pass the array as a parameter to the
125+
``MongoDB\Collection::find()`` or ``MongoDB\Collection::findOne()`` method.
126+
127+
The following example returns all documents that have a ``borough`` field value
128+
of ``'Manhattan'`` and skips the first ``10`` documents:
129+
130+
.. io-code-block::
131+
:copyable:
132+
133+
.. input:: /includes/read/limit-skip-sort.php
134+
:start-after: start-skip
135+
:end-before: end-skip
136+
:language: php
137+
:dedent:
138+
139+
.. output::
140+
141+
{ "_id" : { "$oid" : "..." }, ..., "name" : "Cafe Metro", "restaurant_id" : "40363298" }
142+
{ "_id" : { "$oid" : "..." }, ..., "name" : "Lexler Deli", "restaurant_id" : "40363426" }
143+
{ "_id" : { "$oid" : "..." }, ..., "name" : "Domino'S Pizza", "restaurant_id" : "40363644" }
144+
...
145+
146+
.. _php-return-documents-combine:
147+
148+
Combine Limit, Sort, and Skip
149+
-----------------------------
150+
151+
You can set the ``limit``, ``sort``, and ``skip`` options in a single
152+
options array and pass the array as a parameter to the read operation.
153+
This allows you to set a maximum number of sorted documents to return,
154+
skipping a specified number of documents before returning.
155+
156+
The following example returns ``5`` documents that have a ``cuisine`` value of
157+
``'Italian'``. The results are sorted in ascending order by ``name`` field value,
158+
skipping the first ``10`` documents:
159+
160+
.. io-code-block::
161+
:copyable:
162+
163+
.. input:: /includes/read/limit-skip-sort.php
164+
:start-after: start-limit-sort-skip
165+
:end-before: end-limit-sort-skip
166+
:language: php
167+
:dedent:
168+
169+
.. output::
170+
171+
{ "_id" : { "$oid" : "..." }, ..., "name" : "Acqua", "restaurant_id" : "40871070" }
172+
{ "_id" : { "$oid" : "..." }, ..., "name" : "Acqua Restaurant", "restaurant_id" : "41591488" }
173+
{ "_id" : { "$oid" : "..." }, ..., "name" : "Acqua Santa", "restaurant_id" : "40735858" }
174+
{ "_id" : { "$oid" : "..." }, ..., "name" : "Acquista Trattoria", "restaurant_id" : "40813992" }
175+
{ "_id" : { "$oid" : "..." }, ..., "name" : "Acquolina Catering", "restaurant_id" : "41381423" }
176+
177+
.. note::
178+
179+
The order in which you call these methods doesn't change the documents
180+
that are returned. The {+php-library+} automatically reorders the calls to
181+
perform the sort operation first, the skip operation next, and then the limit
182+
operation.
183+
184+
Additional Information
185+
----------------------
186+
187+
For more information about retrieving documents, see the :ref:`php-retrieve` guide.
188+
189+
For more information about specifying a query, see the :ref:`php-specify-query` guide.
190+
191+
API Documentation
192+
~~~~~~~~~~~~~~~~~
193+
194+
To learn more about any of the methods or types discussed in this
195+
guide, see the following API documentation:
196+
197+
- `MongoDB\\Collection::findOne() <{+api+}/method/MongoDBCollection-findOne/>`__
198+
- `MongoDB\\Collection::find() <{+api+}/method/MongoDBCollection-find/>`__

0 commit comments

Comments
 (0)