Skip to content

Commit f4d7b49

Browse files
norareidynorareidy
authored
DOCSP-41976: Projection guide (#104)
* DOCSP-41976: Projection guide * edits * fixes * code edits, output * JS feedback * JT feedback
1 parent 1104051 commit f4d7b49

File tree

6 files changed

+237
-4
lines changed

6 files changed

+237
-4
lines changed

‎snooty.toml

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

2626
[constants]
2727
php-library = "MongoDB PHP Library"
28+
mdb-server = "MongoDB Server"
2829
api = "https://www.mongodb.com/docs/php-library/current/reference"

‎source/includes/read/project.php

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
<?php
2+
3+
require 'vendor/autoload.php';
4+
5+
$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset');
6+
$client = new MongoDB\Client($uri);
7+
8+
// start-db-coll
9+
$collection = $client->sample_restaurants->restaurants;
10+
// end-db-coll
11+
12+
// Retrieves documents matching the "name" field query and projects their "name", "cuisine", and "borough" values
13+
// start-project-include
14+
$options = [
15+
'projection' => [
16+
'name' => 1,
17+
'cuisine' => 1,
18+
'borough' => 1,
19+
],
20+
];
21+
22+
$cursor = $collection->find(['name' => 'Emerald Pub'], $options);
23+
foreach ($cursor as $doc) {
24+
echo json_encode($doc) . PHP_EOL;
25+
}
26+
// end-project-include
27+
28+
// Retrieves documents matching the "name" field query
29+
// and projects their "name", "cuisine", and "borough" values while excluding the "_id" values
30+
// start-project-include-without-id
31+
$options = [
32+
'projection' => [
33+
'_id' => 0,
34+
'name' => 1,
35+
'cuisine' => 1,
36+
'borough' => 1,
37+
],
38+
];
39+
40+
$cursor = $collection->find(['name' => 'Emerald Pub'], $options);
41+
foreach ($cursor as $doc) {
42+
echo json_encode($doc) . PHP_EOL;
43+
}
44+
// end-project-include-without-id
45+
46+
// Retrieves documents matching the "name" field query and excludes their "grades" and "address" values when printing
47+
// start-project-exclude
48+
$options = [
49+
'projection' => [
50+
'grades' => 0,
51+
'address' => 0,
52+
],
53+
];
54+
55+
$cursor = $collection->find(['name' => 'Emerald Pub'], $options);
56+
foreach ($cursor as $doc) {
57+
echo json_encode($doc) . PHP_EOL;
58+
}
59+
// end-project-exclude

‎source/includes/read/retrieve.php

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,7 @@
55
$client = new MongoDB\Client($uri);
66

77
// start-db-coll
8-
$db = $client->sample_training;
9-
$collection = $db->companies;
8+
$collection = $client->sample_training->companies;
109
// end-db-coll
1110

1211
// Finds one document with a "name" value of "LinkedIn"

‎source/read.txt

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,6 @@ Read Data from MongoDB
88
:titlesonly:
99
:maxdepth: 1
1010

11-
/read/retrieve
11+
/read/retrieve
12+
/read/project
13+

‎source/read/project.txt

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
.. _php-project:
2+
3+
========================
4+
Specify Fields 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, filter, project, select
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use the {+php-library+} to specify which fields
24+
to return from a read operation by using a **projection**. A projection is a document
25+
that specifies which fields MongoDB returns from a query.
26+
27+
Sample Data
28+
~~~~~~~~~~~
29+
30+
The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants``
31+
database from the :atlas:`Atlas sample datasets </sample-data>`. To access this collection
32+
from your PHP application, instantiate a ``MongoDB\Client`` that connects to an Atlas cluster
33+
and assign the following value to your ``collection`` variable:
34+
35+
.. literalinclude:: /includes/read/project.php
36+
:language: php
37+
:dedent:
38+
:start-after: start-db-coll
39+
:end-before: end-db-coll
40+
41+
To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the
42+
:atlas:`Get Started with Atlas </getting-started>` guide.
43+
44+
Projection Types
45+
----------------
46+
47+
You can use a projection to specify which fields to include in a return
48+
document, or to specify which fields to exclude. You cannot combine inclusion and
49+
exclusion statements in a single projection, unless you are excluding the
50+
``_id`` field.
51+
52+
Specify Fields to Include
53+
~~~~~~~~~~~~~~~~~~~~~~~~~
54+
55+
To specify the fields to include in the result, pass an options array to the
56+
``MongoDB\Collection::findOne()`` or ``MongoDB\Collection::find()`` method that
57+
sets the ``projection`` option. Use the following syntax to set this option:
58+
59+
.. code-block:: php
60+
61+
$options = [
62+
'projection' => [
63+
'<field name>' => 1,
64+
],
65+
];
66+
67+
The following example creates an options array and sets the ``projection`` option
68+
to return only the ``name``, ``cuisine``, and ``borough`` fields of matching documents.
69+
It then calls the ``find()`` method to find all restaurants in which the ``name`` field
70+
value is ``'Emerald Pub'``, passing the options array as a parameter to ``find()``:
71+
72+
.. io-code-block::
73+
:copyable:
74+
75+
.. input:: /includes/read/project.php
76+
:start-after: start-project-include
77+
:end-before: end-project-include
78+
:language: php
79+
:dedent:
80+
81+
.. output::
82+
:visible: false
83+
84+
{"_id":{"$oid":"..."},"borough":"Manhattan","cuisine":"American","name":"Emerald Pub"}
85+
{"_id":{"$oid":"..."},"borough":"Queens","cuisine":"American","name":"Emerald Pub"}
86+
87+
When you use a projection to specify fields to include in the return
88+
document, the ``_id`` field is also included by default. All other fields are
89+
implicitly excluded. To remove the ``_id`` field from the return
90+
document, you must :ref:`explicitly exclude it <php-project-remove-id>`.
91+
92+
.. _php-project-remove-id:
93+
94+
Exclude the ``_id`` Field
95+
~~~~~~~~~~~~~~~~~~~~~~~~~
96+
97+
When specifying fields to include, you can also exclude the ``_id`` field from
98+
the returned document.
99+
100+
The following example performs the same query as the preceding example but
101+
excludes the ``_id`` field from the projection:
102+
103+
.. io-code-block::
104+
:copyable:
105+
106+
.. input:: /includes/read/project.php
107+
:start-after: start-project-include-without-id
108+
:end-before: end-project-include-without-id
109+
:language: php
110+
:dedent:
111+
112+
.. output::
113+
:visible: false
114+
115+
{"borough":"Manhattan","cuisine":"American","name":"Emerald Pub"}
116+
{"borough":"Queens","cuisine":"American","name":"Emerald Pub"}
117+
118+
Specify Fields to Exclude
119+
~~~~~~~~~~~~~~~~~~~~~~~~~
120+
121+
To specify the fields to exclude from the result, pass an options array to the
122+
``MongoDB\Collection::findOne()`` or ``MongoDB\Collection::find()`` method that
123+
sets the ``projection`` option. Use the following syntax to set this option:
124+
125+
.. code-block:: php
126+
127+
$options = [
128+
'projection' => [
129+
'<field name>' => 0,
130+
],
131+
];
132+
133+
The following example creates an options array and sets the ``projection`` option
134+
to exclude the ``grades`` and ``address`` fields of matching documents.
135+
It then calls the ``find()`` method to find all restaurants in which the ``name``
136+
field value is ``'Emerald Pub'``, passing the options array as a parameter to
137+
``find()``:
138+
139+
.. io-code-block::
140+
:copyable:
141+
142+
.. input:: /includes/read/project.php
143+
:start-after: start-project-exclude
144+
:end-before: end-project-exclude
145+
:language: php
146+
:dedent:
147+
148+
.. output::
149+
:visible: false
150+
151+
{"_id":{"$oid":"..."},"borough":"Manhattan","cuisine":"American",
152+
"name":"Emerald Pub","restaurant_id":"40367329"}
153+
{"_id":{"$oid":"..."},"borough":"Queens","cuisine":"American",
154+
"name":"Emerald Pub","restaurant_id":"40668598"}
155+
156+
When you use a projection to specify which fields to exclude,
157+
any unspecified fields are implicitly included in the return document.
158+
159+
Additional Information
160+
----------------------
161+
162+
To learn more about projections, see the :manual:`Project Fields
163+
</tutorial/project-fields-from-query-results/>` guide in the {+mdb-server+} manual.
164+
165+
API Documentation
166+
~~~~~~~~~~~~~~~~~
167+
168+
To learn more about any of the methods or types discussed in this
169+
guide, see the following API documentation:
170+
171+
- `MongoDB\\Collection::findOne() <{+api+}/method/MongoDBCollection-findOne/>`__
172+
- `MongoDB\\Collection::find() <{+api+}/method/MongoDBCollection-find/>`__

‎source/read/retrieve.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ Sample Data
3131
The examples in this guide use the ``companies`` collection in the ``sample_training``
3232
database from the :atlas:`Atlas sample datasets </sample-data>`. To access this collection
3333
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:
34+
and assign the following value to your ``collection`` variable:
3535

3636
.. literalinclude:: /includes/read/retrieve.php
3737
:language: php

0 commit comments

Comments
 (0)