Skip to content

Commit 0c9c6e5

Browse files
norareidynorareidy
committed
DOCSP-41975: Retrieve data
1 parent 2419c76 commit 0c9c6e5

File tree

4 files changed

+297
-0
lines changed

4 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: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
<?php
2+
require 'vendor/autoload.php'; // includes the library
3+
4+
$uri = "<connection string>";
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+
$options = [
33+
'limit' => 5,
34+
];
35+
36+
$results = $collection->find(['number_of_employees' => 1000], $options);
37+
38+
foreach ($results as $doc) {
39+
echo json_encode($doc) . "\n";
40+
}
41+
// end-modify
42+
?>

‎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: 243 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,243 @@
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 is
53+
an object that specifies the documents you want to retrieve 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+
83+
.. input:: /includes/read/retrieve.php
84+
:start-after: start-find-one
85+
:end-before: end-find-one
86+
:language: php
87+
:dedent:
88+
89+
.. output::
90+
91+
{"_id":{"$oid":"..."},"name":"LinkedIn","permalink":"linkedin","crunchbase_url":
92+
"http:\/\/www.crunchbase.com\/company\/linkedin","homepage_url":"http:\/\/linkedin.com",
93+
...
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+
131+
.. input:: /includes/read/retrieve.php
132+
:start-after: start-cursor
133+
:end-before: end-cursor
134+
:language: php
135+
:dedent:
136+
137+
.. output::
138+
139+
{"_id":{"$oid":"..."},"name":"Mitsubishi Motors","permalink":"mitsubishi-motors",
140+
"crunchbase_url":"http:\/\/www.crunchbase.com\/company\/mitsubishi-motors",
141+
... }
142+
143+
{"_id":{"$oid":"..."},"name":"Western Digital","permalink":"western-digital",
144+
"crunchbase_url":"http:\/\/www.crunchbase.com\/company\/western-digital",
145+
... }
146+
147+
{"_id":{"$oid":"..."},"name":"Celarayn","permalink":"celarayn","crunchbase_url":
148+
"http:\/\/www.crunchbase.com\/company\/celarayn",
149+
... }
150+
151+
.. note:: Find All Documents
152+
153+
To find all documents in a collection, pass an empty filter
154+
to the ``find()`` method:
155+
156+
.. code-block:: php
157+
158+
$cursor = $collection->find([]);
159+
160+
.. _php-retrieve-modify:
161+
162+
Modify Find Behavior
163+
~~~~~~~~~~~~~~~~~~~~
164+
165+
You can modify the behavior of the ``MongoDB\Collection::find()`` and
166+
``MongoDB\Collection::findOne()`` methods by passing an array that specifies
167+
option values as a parameter. The following table describes some of the options
168+
you can set in the array:
169+
170+
.. list-table::
171+
:widths: 30 70
172+
:header-rows: 1
173+
174+
* - Option
175+
- Description
176+
177+
* - ``batchSize``
178+
- | The number of documents to return per batch. The default value is ``101``.
179+
| **Type**: ``integer``
180+
181+
* - ``collation``
182+
- | The collation to use for the operation. The default value is the collation
183+
specified for the collection.
184+
| **Type**: ``array|object``
185+
186+
* - ``comment``
187+
- | The comment to attach to the operation.
188+
| **Type**: any BSON type
189+
190+
* - ``cursorType``
191+
- | The type of cursor to use for the operation. The default value is
192+
``MongoDB\Operation\Find::NON_TAILABLE``.
193+
| **Type**: ``MongoDB\Operation\Find``
194+
195+
* - ``limit``
196+
- | The maximum number of documents the operation can return.
197+
| **Type**: ``integer``
198+
199+
* - ``skip``
200+
- | The number of documents to skip before returning results.
201+
| **Type**: ``integer``
202+
203+
* - ``sort``
204+
- | The order in which the operation returns matching documents.
205+
| **Type**: ``array|object``
206+
207+
* - ``typeMap``
208+
- | The type map to apply to cursors, which determines how BSON documents
209+
are converted to PHP values. The default value is the collection's type map.
210+
| **Type**: ``array``
211+
212+
The following example uses the ``find()`` method to find all documents in which
213+
the ``number_of_employees`` field has the value ``1000`` and instructs the
214+
operation to return a maximum of ``5`` results:
215+
216+
.. literalinclude:: /includes/read/retrieve.php
217+
:language: php
218+
:dedent:
219+
:start-after: start-modify
220+
:end-before: end-modify
221+
222+
For a full list of options, see the API documentation for the
223+
`findOne() {+api+}/method/MongoDBCollection-findOne/#parameters`__ and
224+
`find() {+api+}/method/MongoDBCollection-find/#parameters`__ parameters.
225+
226+
.. _php-retrieve-additional-information:
227+
228+
Additional Information
229+
----------------------
230+
231+
.. TODO:
232+
To learn more about query filters, see :ref:`php-specify-query`.
233+
For runnable code examples of retrieving documents with the {+php-library+},
234+
see :ref:`php-read`.
235+
236+
API Documentation
237+
~~~~~~~~~~~~~~~~~
238+
239+
To learn more about any of the methods or types discussed in this
240+
guide, see the following API documentation:
241+
242+
- `findOne() {+api+}/method/MongoDBCollection-findOne/`__
243+
- `find() {+api+}/method/MongoDBCollection-find/`__

0 commit comments

Comments
 (0)