Skip to content

Commit e27c96e

Browse files
jordan-smith721jordan-smith721
authored
DOCSP-37548 Projection (#56)
1 parent b3c1fa3 commit e27c96e

File tree

5 files changed

+189
-1
lines changed

5 files changed

+189
-1
lines changed

‎source/includes/project/project.py

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# start-project-include
2+
results = restaurants.find({ "name" : "Emerald Pub"}, {"name": 1, "cuisine": 1, "borough": 1})
3+
4+
for restaurant in results:
5+
print(restaurant)
6+
# end-project-include
7+
8+
# start-project-include-without-id
9+
results = restaurants.find({ "name" : "Emerald Pub"}, {"_id": 0, "name": 1, "cuisine": 1, "borough": 1})
10+
11+
for restaurant in results:
12+
print(restaurant)
13+
# end-project-include-without-id
14+
15+
# start-project-exclude
16+
results = restaurants.find({ "name" : "Emerald Pub"}, {"grades": 0, "address": 0} )
17+
18+
for restaurant in results:
19+
print(restaurant)
20+
# end-project-exclude

‎source/includes/troubleshooting/projections.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
'Cannot Do Exclusion on Field <field> in Inclusion Projection'
2+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3+
4+
The driver returns an ``OperationFailure`` with this message if you attempt to
5+
include and exclude fields in a single projection. Ensure that your
6+
projection specifies only fields to include or fields to exclude.

‎source/read.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,11 @@ Read Data from MongoDB
1212
:maxdepth: 1
1313

1414
/read/retrieve
15+
/read/project
1516
/read/count
1617
/read/cursors
1718

1819
- :ref:`pymongo-retrieve`
20+
- :ref:`pymongo-project`
1921
- :ref:`pymongo-count`
2022
- :ref:`pymongo-cursors`

‎source/read/project.txt

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
.. _pymongo-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 specify which fields to return from a read
24+
operation by using a **projection**. A projection is a document that specifies
25+
which fields MongoDB returns from a query.
26+
27+
Sample Data
28+
~~~~~~~~~~~
29+
30+
The examples in this guide use the ``sample_restaurants.restaurants`` collection
31+
from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
32+
free MongoDB Atlas cluster and load the sample datasets, see the
33+
:ref:`<pymongo-get-started>` guide.
34+
35+
Projection Types
36+
----------------
37+
38+
You can use a projection to specify which fields to include in a return
39+
document, or to specify which fields to exclude. You cannot combine inclusion and
40+
exclusion statements in a single projection, unless you are excluding the
41+
``_id`` field.
42+
43+
Specify Fields to Include
44+
~~~~~~~~~~~~~~~~~~~~~~~~~
45+
46+
Use the following syntax to specify the fields to include in the result:
47+
48+
.. code-block:: json
49+
50+
{ "<Field Name>": 1 }
51+
52+
The following example uses the ``find()`` method to find all restaurants with
53+
the ``name`` field value of ``"Emerald Pub"``. It then uses a projection to
54+
return only the ``name``, ``cuisine``, and ``borough`` fields in the returned
55+
documents.
56+
57+
.. io-code-block::
58+
59+
.. input:: /includes/project/project.py
60+
:start-after: start-project-include
61+
:end-before: end-project-include
62+
:language: python
63+
:emphasize-lines: 1
64+
65+
.. output::
66+
67+
{'_id': ObjectId('...'), 'borough': 'Manhattan', 'cuisine': 'American', 'name': 'Emerald Pub'}
68+
{'_id': ObjectId('...'), 'borough': 'Queens', 'cuisine': 'American', 'name': 'Emerald Pub'}
69+
70+
When you use a projection to specify fields to include in the return
71+
document, the ``_id`` field is also included by default. All other fields are
72+
implicitly excluded. To remove the ``_id`` field from the return
73+
document, you must :ref:`explicitly exclude it <pymongo-project-remove-id>`.
74+
75+
.. _pymongo-project-remove-id:
76+
77+
Exclude the ``_id`` Field
78+
~~~~~~~~~~~~~~~~~~~~~~~~~
79+
80+
When specifying fields to include, you can also exclude the ``_id`` field from
81+
the returned document.
82+
83+
The following example performs the same query as the preceding example, but
84+
excludes the ``_id`` field from the projection:
85+
86+
.. io-code-block::
87+
88+
.. input:: /includes/project/project.py
89+
:start-after: start-project-include-without-id
90+
:end-before: end-project-include-without-id
91+
:language: python
92+
:emphasize-lines: 1
93+
94+
.. output::
95+
96+
{'borough': 'Manhattan', 'cuisine': 'American', 'name': 'Emerald Pub'}
97+
{'borough': 'Queens', 'cuisine': 'American', 'name': 'Emerald Pub'}
98+
99+
Specify Fields to Exclude
100+
~~~~~~~~~~~~~~~~~~~~~~~~~
101+
102+
Use the following syntax to specify the fields to exclude from the result:
103+
104+
.. code-block:: json
105+
106+
{ "<Field Name>": 0 }
107+
108+
The following example uses the ``find()`` method to find all restaurants with
109+
the ``name`` field value of ``"Emerald Pub"``. It then uses a projection to
110+
exclude the ``grades`` and ``address`` fields from the returned documents:
111+
112+
.. io-code-block::
113+
114+
.. input:: /includes/project/project.py
115+
:start-after: start-project-exclude
116+
:end-before: end-project-exclude
117+
:language: python
118+
:emphasize-lines: 1
119+
120+
.. output::
121+
122+
{'_id': ObjectId('...'), 'borough': 'Manhattan', 'cuisine': 'American', 'name': 'Emerald Pub', 'restaurant_id': '40367329'}
123+
{'_id': ObjectId('...'), 'borough': 'Queens', 'cuisine': 'American',
124+
'name': 'Emerald Pub', 'restaurant_id': '40668598'}
125+
126+
When you use a projection to specify which fields to exclude,
127+
any unspecified fields are implicitly included in the return document.
128+
129+
Troubleshooting
130+
---------------
131+
132+
The following sections describe errors you might see when using projections.
133+
134+
.. include:: /includes/troubleshooting/projections.rst
135+
136+
Additional Information
137+
----------------------
138+
139+
To learn more about projections, see the :manual:`Project Fields guide
140+
</tutorial/project-fields-from-query-results/>` in the MongoDB Server Manual.
141+
142+
API Documentation
143+
~~~~~~~~~~~~~~~~~
144+
145+
To learn more about any of the methods or types discussed in this
146+
guide, see the following API Documentation:
147+
148+
- `find() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.find>`__

‎source/troubleshooting.txt

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -423,4 +423,16 @@ The following Python idioms can produce this result:
423423
...
424424
pymongo.errors.BulkWriteError: batch op errors occurred
425425
>>> docs
426-
[{'_id': ObjectId('560f1933fba52279f0b0da0e')}]
426+
[{'_id': ObjectId('560f1933fba52279f0b0da0e')}]
427+
428+
.. _pymongo-troubleshoot-tls:
429+
430+
TLS
431+
---
432+
433+
.. include:: /includes/troubleshooting/tls.rst
434+
435+
Projections
436+
-----------
437+
438+
.. include:: /includes/troubleshooting/projections.rst

0 commit comments

Comments
 (0)