Skip to content

Commit 6d1befc

Browse files
norareidynorareidy
committed
DOCSP-41976: Projection guide
1 parent 2419c76 commit 6d1befc

File tree

2 files changed

+228
-0
lines changed

2 files changed

+228
-0
lines changed

‎source/includes/read/project.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+
use MongoDB\Client;
6+
7+
$client = new Client('<connection string>');
8+
9+
// start-db-coll
10+
$db = $client->sample_restaurants;
11+
$collection = $db->restaurants;
12+
// end-db-coll
13+
14+
// Retrieves documents matching the "name" field query and projects their "name", "cuisine", and "borough" values
15+
// start-project-include
16+
$options = [
17+
'projection' => [
18+
'name' => 1,
19+
'cuisine' => 1,
20+
'borough' => 1,
21+
],
22+
];
23+
24+
$cursor = $collection->find(['name' => 'Emerald Pub'], $options);
25+
foreach ($cursor as $doc) {
26+
echo json_encode($doc), PHP_EOL;
27+
}
28+
// end-project-include
29+
30+
// Retrieves documents matching the "name" field query
31+
// and projects their "name", "cuisine", and "borough" values while excluding the "_id" values
32+
// start-project-include-without-id
33+
$options = [
34+
'projection' => [
35+
'_id' => 0,
36+
'name' => 1,
37+
'cuisine' => 1,
38+
'borough' => 1,
39+
],
40+
];
41+
42+
$cursor = $collection->find(['name' => 'Emerald Pub'], $options);
43+
foreach ($cursor as $doc) {
44+
echo json_encode($doc), PHP_EOL;
45+
}
46+
// end-project-include-without-id
47+
48+
// Retrieves documents matching the "name" field query and excludes their "grades" and "address" values when printing
49+
// start-project-exclude
50+
$options = [
51+
'projection' => [
52+
'grades' => 0,
53+
'address' => 0,
54+
],
55+
];
56+
57+
$cursor = $collection->find(['name' => 'Emerald Pub'], $options);
58+
foreach ($cursor as $doc) {
59+
echo json_encode($doc), PHP_EOL;
60+
}
61+
// end-project-exclude
62+
63+
?>

‎source/read/project.txt

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
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 values to your ``db`` and ``collection`` variables:
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. To set this option, use the following syntax:
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+
74+
.. input:: /includes/read/project.php
75+
:start-after: start-project-include
76+
:end-before: end-project-include
77+
:language: php
78+
:dedent:
79+
80+
.. output::
81+
82+
{ "_id" : { "$oid" : "..." }, "borough" : "Manhattan", "cuisine" : "American", "name" : "Emerald Pub" }
83+
{ "_id" : { "$oid" : "..." }, "borough" : "Queens", "cuisine" : "American", "name" : "Emerald Pub" }
84+
85+
When you use a projection to specify fields to include in the return
86+
document, the ``_id`` field is also included by default. All other fields are
87+
implicitly excluded. To remove the ``_id`` field from the return
88+
document, you must :ref:`explicitly exclude it <php-project-remove-id>`.
89+
90+
.. _php-project-remove-id:
91+
92+
Exclude the ``_id`` Field
93+
~~~~~~~~~~~~~~~~~~~~~~~~~
94+
95+
When specifying fields to include, you can also exclude the ``_id`` field from
96+
the returned document.
97+
98+
The following example performs the same query as the preceding example but
99+
excludes the ``_id`` field from the projection:
100+
101+
.. io-code-block::
102+
103+
.. input:: /includes/read/project.php
104+
:start-after: start-project-include-without-id
105+
:end-before: end-project-include-without-id
106+
:language: php
107+
:dedent:
108+
:emphasize-lines: 3
109+
110+
.. output::
111+
112+
{ "borough" : "Manhattan", "cuisine" : "American", "name" : "Emerald Pub" }
113+
{ "borough" : "Queens", "cuisine" : "American", "name" : "Emerald Pub" }
114+
115+
Specify Fields to Exclude
116+
~~~~~~~~~~~~~~~~~~~~~~~~~
117+
118+
To specify the fields to include in the result, pass an options array to the
119+
``MongoDB\Collection::findOne()`` or ``MongoDB\Collection::find()`` method that
120+
sets the ``projection`` option. To set this option, use the following syntax:
121+
122+
.. code-block:: php
123+
124+
$options = [
125+
'projection' => [
126+
'<field name>' => 0,
127+
],
128+
];
129+
130+
The following example creates an options array and sets the ``projection`` option
131+
to exclude the ``grades`` and ``address`` fields of matching documents.
132+
It then calls the ``find()`` method to find all restaurants in which the ``name``
133+
field value is ``"Emerald Pub"``, passing the options array as a parameter to
134+
``find()``:
135+
136+
.. io-code-block::
137+
138+
.. input:: /includes/read/project.php
139+
:start-after: start-project-exclude
140+
:end-before: end-project-exclude
141+
:language: php
142+
:dedent:
143+
144+
.. output::
145+
146+
{ "_id" : { "$oid" : "..." }, "borough" : "Manhattan", "cuisine" : "American", "name" : "Emerald Pub", "restaurant_id" : "40367329" }
147+
{ "_id" : { "$oid" : "..." }, "borough" : "Queens", "cuisine" : "American", "name" : "Emerald Pub", "restaurant_id" : "40668598" }
148+
149+
When you use a projection to specify which fields to exclude,
150+
any unspecified fields are implicitly included in the return document.
151+
152+
Additional Information
153+
----------------------
154+
155+
To learn more about projections, see the :manual:`Project Fields
156+
</tutorial/project-fields-from-query-results/>` guide in the {+mdb-server+} manual.
157+
158+
API Documentation
159+
~~~~~~~~~~~~~~~~~
160+
161+
To learn more about any of the methods or types discussed in this
162+
guide, see the following API documentation:
163+
164+
- `MongoDB\\Collection::findOne() <{+api+}/method/MongoDBCollection-findOne/>`__
165+
- `MongoDB\\Collection::find() <{+api+}/method/MongoDBCollection-find/>`__

0 commit comments

Comments
 (0)