Skip to content

Commit e994533

Browse files
norareidynorareidy
authored
DOCSP-41975: Retrieve data (#102)
* DOCSP-41975: Retrieve data * fixes * quotes * code fix * JS feedback * JT feedback * code format * fix * JT feedback 2 * edit
1 parent 2419c76 commit e994533

File tree

5 files changed

+297
-0
lines changed

5 files changed

+297
-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/retrieve.php

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
<?php
2+
require 'vendor/autoload.php';
3+
4+
$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset');
5+
$client = new MongoDB\Client($uri);
6+
7+
// start-db-coll
8+
$db = $client->sample_training;
9+
$collection = $db->companies;
10+
// end-db-coll
11+
12+
// Finds one document with a "name" value of "LinkedIn"
13+
// start-find-one
14+
$document = $collection->findOne(['name' => 'LinkedIn']);
15+
echo json_encode($document) . "\n";
16+
// end-find-one
17+
18+
// Finds documents with a "founded_year" value of 1970
19+
// start-find-many
20+
$results = $collection->find(['founded_year' => 1970]);
21+
// end-find-many
22+
23+
// Prints documents with a "founded_year" value of 1970
24+
// start-cursor
25+
foreach ($results as $doc) {
26+
echo json_encode($doc) . "\n";
27+
}
28+
// end-cursor
29+
30+
// Finds and prints up to 5 documents with a "number_of_employees" value of 1000
31+
// start-modify
32+
$results = $collection->find(
33+
['number_of_employees' => 1000],
34+
['limit' => 5]
35+
);
36+
37+
foreach ($results as $doc) {
38+
echo json_encode($doc) . "\n";
39+
}
40+
// end-modify

‎source/index.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ MongoDB PHP Library
1212

1313
Installation </tutorial/install-php-library>
1414
Get Started </get-started>
15+
/read
1516
/tutorial
1617
/upgrade
1718
/reference

‎source/read.txt

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
.. _php-read:
2+
3+
======================
4+
Read Data from MongoDB
5+
======================
6+
7+
.. toctree::
8+
:titlesonly:
9+
:maxdepth: 1
10+
11+
/read/retrieve

‎source/read/retrieve.txt

Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
.. _php-retrieve:
2+
3+
=============
4+
Retrieve Data
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: code examples, read, query, cursor
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use the {+php-library+} to retrieve
24+
data from a MongoDB collection by using **read operations**. You can call the
25+
``MongoDB\Collection::find()`` or ``MongoDB\Collection::findOne()`` method
26+
on a collection to retrieve documents that match a set of criteria.
27+
28+
Sample Data
29+
~~~~~~~~~~~
30+
31+
The examples in this guide use the ``companies`` collection in the ``sample_training``
32+
database from the :atlas:`Atlas sample datasets </sample-data>`. To access this collection
33+
from your PHP application, instantiate a ``MongoDB\Client`` that connects to an Atlas cluster
34+
and assign the following values to your ``db`` and ``collection`` variables:
35+
36+
.. literalinclude:: /includes/read/retrieve.php
37+
:language: php
38+
:dedent:
39+
:start-after: start-db-coll
40+
:end-before: end-db-coll
41+
42+
To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the
43+
:atlas:`Get Started with Atlas </getting-started>` guide.
44+
45+
.. _php-retrieve-find:
46+
47+
Find Documents
48+
--------------
49+
50+
The {+php-library+} includes two methods for retrieving documents from a collection:
51+
``MongoDB\Collection::findOne()`` and ``MongoDB\Collection::find()``. These methods
52+
take a **query filter** and return one or more matching documents. A query filter
53+
specifies the search criteria that the driver uses to retrieve documents in your query.
54+
55+
.. TODO: To learn more about query filters, see :ref:`php-specify-query`.
56+
57+
.. _php-retrieve-find-one:
58+
59+
Find One Document
60+
~~~~~~~~~~~~~~~~~
61+
62+
To find a single document in a collection, call the ``MongoDB\Collection::findOne()``
63+
method and pass a query filter that specifies the criteria of the document you want to find.
64+
65+
The ``findOne()`` method returns an ``array``, ``object``, or ``null`` value. If the
66+
query filter matches a document, the method returns an ``array|object`` instance containing
67+
the document. The return type depends on the value of the ``typeMap`` option. If the query
68+
filter does not match any documents, the method returns ``null``.
69+
70+
.. tip::
71+
72+
To learn more about ``findOne()`` options, such as ``typeMap``, see the :ref:`php-retrieve-modify`
73+
section of this guide.
74+
75+
If the query filter matches more than one document, the ``findOne()`` method returns the *first*
76+
matching document from the retrieved results.
77+
78+
The following example uses the ``findOne()`` method to find the first document in which
79+
the ``name`` field has the value ``'LinkedIn'``:
80+
81+
.. io-code-block::
82+
:copyable:
83+
84+
.. input:: /includes/read/retrieve.php
85+
:start-after: start-find-one
86+
:end-before: end-find-one
87+
:language: php
88+
:dedent:
89+
90+
.. output::
91+
92+
{"_id":{"$oid":"..."},"name":"LinkedIn","permalink":"linkedin","crunchbase_url":
93+
"http:\/\/www.crunchbase.com\/company\/linkedin","homepage_url":"http:\/\/linkedin.com",
94+
... }
95+
96+
.. tip:: Sort Order
97+
98+
The ``findOne()`` method returns the first document in
99+
:manual:`natural order </reference/glossary/#std-term-natural-order>`
100+
on disk if no sort criteria is specified.
101+
102+
.. _php-retrieve-find-multiple:
103+
104+
Find Multiple Documents
105+
~~~~~~~~~~~~~~~~~~~~~~~
106+
107+
To find multiple documents in a collection, pass a query filter to the
108+
``MongoDB\Collection::find()`` method that specifies the criteria of the
109+
documents you want to retrieve.
110+
111+
The following example uses the ``find()`` method to find all documents in which
112+
the ``founded_year`` field has the value ``1970``:
113+
114+
.. literalinclude:: /includes/read/retrieve.php
115+
:language: php
116+
:dedent:
117+
:start-after: start-find-many
118+
:end-before: end-find-many
119+
120+
The ``find()`` method returns an instance of ``MongoDB\Driver\Cursor``, which you can
121+
iterate over to see the matching documents. A cursor is a mechanism that allows an
122+
application to iterate over database results while holding only a subset of them in
123+
memory at a given time. Cursors are useful when your ``find()`` method returns a large
124+
amount of documents.
125+
126+
You can iterate over the documents in a cursor by using a ``foreach`` loop, as shown in
127+
the following example:
128+
129+
.. io-code-block::
130+
:copyable:
131+
132+
.. input:: /includes/read/retrieve.php
133+
:start-after: start-cursor
134+
:end-before: end-cursor
135+
:language: php
136+
:dedent:
137+
138+
.. output::
139+
140+
{"_id":{"$oid":"..."},"name":"Mitsubishi Motors","permalink":"mitsubishi-motors",
141+
"crunchbase_url":"http:\/\/www.crunchbase.com\/company\/mitsubishi-motors",
142+
... }
143+
144+
{"_id":{"$oid":"..."},"name":"Western Digital","permalink":"western-digital",
145+
"crunchbase_url":"http:\/\/www.crunchbase.com\/company\/western-digital",
146+
... }
147+
148+
{"_id":{"$oid":"..."},"name":"Celarayn","permalink":"celarayn","crunchbase_url":
149+
"http:\/\/www.crunchbase.com\/company\/celarayn",
150+
... }
151+
152+
.. note:: Find All Documents
153+
154+
To find all documents in a collection, pass an empty filter
155+
to the ``find()`` method:
156+
157+
.. code-block:: php
158+
159+
$cursor = $collection->find([]);
160+
161+
.. _php-retrieve-modify:
162+
163+
Modify Find Behavior
164+
~~~~~~~~~~~~~~~~~~~~
165+
166+
You can modify the behavior of the ``MongoDB\Collection::find()`` and
167+
``MongoDB\Collection::findOne()`` methods by passing an array that specifies
168+
option values as a parameter. The following table describes some options
169+
you can set in the array:
170+
171+
.. list-table::
172+
:widths: 30 70
173+
:header-rows: 1
174+
175+
* - Option
176+
- Description
177+
178+
* - ``batchSize``
179+
- | The number of documents to return per batch. The default value is ``101``.
180+
| **Type**: ``integer``
181+
182+
* - ``collation``
183+
- | The collation to use for the operation. The default value is the collation
184+
specified for the collection.
185+
| **Type**: ``array|object``
186+
187+
* - ``comment``
188+
- | The comment to attach to the operation.
189+
| **Type**: any BSON type
190+
191+
* - ``cursorType``
192+
- | The type of cursor to use for the operation. The default value is
193+
``MongoDB\Operation\Find::NON_TAILABLE``.
194+
| **Type**: ``MongoDB\Operation\Find``
195+
196+
* - ``limit``
197+
- | The maximum number of documents the operation can return.
198+
| **Type**: ``integer``
199+
200+
* - ``skip``
201+
- | The number of documents to skip before returning results.
202+
| **Type**: ``integer``
203+
204+
* - ``sort``
205+
- | The order in which the operation returns matching documents.
206+
| **Type**: ``array|object``
207+
208+
* - ``typeMap``
209+
- | The type map to apply to cursors, which determines how BSON documents
210+
are converted to PHP values. The default value is the collection's type map.
211+
| **Type**: ``array``
212+
213+
The following example uses the ``find()`` method to find all documents in which
214+
the ``number_of_employees`` field has the value ``1000``. The example uses the
215+
``limit`` option to return a maximum of ``5`` results:
216+
217+
.. literalinclude:: /includes/read/retrieve.php
218+
:language: php
219+
:emphasize-lines: 3
220+
:start-after: start-modify
221+
:end-before: end-modify
222+
223+
For a full list of options, see the API documentation for the
224+
`findOne() <{+api+}/method/MongoDBCollection-findOne/#parameters>`__ and
225+
`find() <{+api+}/method/MongoDBCollection-find/#parameters>`__ parameters.
226+
227+
.. _php-retrieve-additional-information:
228+
229+
Additional Information
230+
----------------------
231+
232+
.. TODO:
233+
To learn more about query filters, see :ref:`php-specify-query`.
234+
For runnable code examples of retrieving documents with the {+php-library+},
235+
see :ref:`php-read`.
236+
237+
API Documentation
238+
~~~~~~~~~~~~~~~~~
239+
240+
To learn more about any of the methods or types discussed in this
241+
guide, see the following API documentation:
242+
243+
- `findOne() <{+api+}/method/MongoDBCollection-findOne/>`__
244+
- `find() <{+api+}/method/MongoDBCollection-find/>`__

0 commit comments

Comments
 (0)