Skip to content

Commit b80b949

Browse files
terakilobyteterakilobyte
authored
Docsp 9559 (#89)
* first pass * add to toc * nits * remove redundant example * fix line highlight * nits
1 parent 40c7b00 commit b80b949

File tree

2 files changed

+150
-2
lines changed

2 files changed

+150
-2
lines changed

‎source/fundamentals/crud/read-operations.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,9 @@ Read Operations
1010
- :doc:`/fundamentals/crud/read-operations/skip`
1111
- :doc:`/fundamentals/crud/read-operations/limit`
1212
- :doc:`/fundamentals/crud/read-operations/geo`
13+
- :doc:`/fundamentals/crud/read-operations/project`
1314

1415
..
15-
- :doc:`/fundamentals/crud/read-operations/project`
1616
- :doc:`/fundamentals/crud/read-operations/text`
1717

1818
.. toctree::
@@ -24,8 +24,8 @@ Read Operations
2424
/fundamentals/crud/read-operations/skip
2525
/fundamentals/crud/read-operations/limit
2626
/fundamentals/crud/read-operations/geo
27+
/fundamentals/crud/read-operations/project
2728

2829
..
29-
/fundamentals/crud/read-operations/project
3030
/fundamentals/crud/read-operations/text
3131

‎source/fundamentals/crud/read-operations/project.txt

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
==============================
2+
Specify Which Fields to Return
3+
==============================
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
In this guide, you will learn how to control which fields appear in
14+
documents returned by read operations.
15+
16+
Many read requests require only a subset of fields in a document.
17+
For example, when logging a user in you may only need their username, and
18+
not all of their profile information. By default, queries in MongoDB return
19+
all fields in matching documents. You can use a **projection** to return
20+
only the data you need.
21+
22+
A projection is a document that instructs MongoDB which fields of a
23+
document to return. Use the :ref:`Projections <projections-builders>` class
24+
to construct a projection document.
25+
26+
Behavior
27+
--------
28+
29+
Projections work in two ways:
30+
31+
- Explicitly including fields. This has the side-effect of implicitly
32+
excluding all unspecified fields.
33+
34+
- Implicitly excluding fields. This has the side-effect of implicitly
35+
including all unspecified fields.
36+
37+
These two methods of projection are mutually exclusive: if you
38+
explicitly include fields, you cannot explicitly exclude fields, and
39+
vice versa.
40+
41+
.. important::
42+
43+
The ``_id`` field is **not** subject to these mechanics. You must
44+
explicitly exclude the ``_id`` field if you do not want it returned.
45+
You can exclude the ``_id`` field even if you have specified certain
46+
fields to include.
47+
48+
Explanation
49+
-----------
50+
51+
Consider the following collection containing documents that describe
52+
varieties of fruit:
53+
54+
.. code-block:: json
55+
56+
{ "_id": 1, "name": "apples", "qty": 5, "rating": 3 },
57+
{ "_id": 2, "name": "bananas", "qty": 7, "rating": 1 },
58+
{ "_id": 3, "name": "oranges", "qty": 6, "rating": 2 },
59+
{ "_id": 4, "name": "avocados", "qty": 3, "rating": 5 },
60+
61+
In the following query, pass the projection to return the ``name``
62+
field of each document:
63+
64+
.. code-block:: java
65+
:emphasize-lines: 3
66+
67+
// return all documents with *only* the name field
68+
Bson filter = Filters.empty();
69+
Bson projection = Projections.fields(Projections.include("name"));
70+
collection.find(filter).projection(projection).forEach(doc -> System.out.println(doc));
71+
72+
The projection document specifies that the read operation result should
73+
*include* the ``name`` field of each returned document. As a result, this
74+
projection implicitly excludes the ``qty`` and ``rating`` fields. Chaining
75+
this projection to ``find()`` with an empty query document yields the
76+
following results:
77+
78+
.. code-block:: json
79+
80+
{ "_id": 1, "name": "apples" }
81+
{ "_id": 2, "name": "bananas" }
82+
{ "_id": 3, "name": "oranges" }
83+
{ "_id": 4, "name": "avocados" }
84+
85+
Despite the fact that this projection only explicitly included the
86+
``name`` field, the query returned the ``_id`` field as well.
87+
88+
The ``_id`` field is a special case: it is always included in every query
89+
result unless explicitly excluded. That's because the ``_id`` field is a
90+
unique identifier for each document, a property that can be useful when
91+
constructing queries.
92+
93+
A ``movies`` collection is a good example of why this property is useful:
94+
because remakes and even separate works sometimes reuse movie titles,
95+
you need a unique ``_id`` value to refer to any specific movie.
96+
97+
The ``_id`` is the only exception to the mutually exclusive include-exclude
98+
behavior in projections: you *can* explicitly exclude the ``_id`` field
99+
even when explicitly including other fields if you do not want ``_id``
100+
to be present in returned documents.
101+
102+
.. code-block:: java
103+
:emphasize-lines: 3
104+
105+
// return all documents with only the name field
106+
Bson filter = Filters.empty();
107+
Bson projection = Projections.fields(Projections.include("name"), Projections.excludeId());
108+
collection.find(filter).projection(projection).forEach(doc -> System.out.println(doc));
109+
110+
The projection document specifies that the read operation result should
111+
*include* the ``name`` field of each returned document, and specifies to
112+
*exclude* the ``_id`` field. As a result, this projection implicitly
113+
excludes the ``qty`` and ``rating`` fields. Chaining this projection to
114+
``find()`` with an empty query document yields the following results:
115+
116+
.. code-block:: javascript
117+
118+
{ "name": "apples" }
119+
{ "name": "bananas" }
120+
{ "name": "oranges" }
121+
{ "name": "avocados" }
122+
123+
You can also specify multiple fields to include in your projection.
124+
125+
.. tip::
126+
127+
The order in which you specify the fields in the projection does not
128+
alter the order in which they are returned.
129+
130+
.. code-block:: java
131+
:emphasize-lines: 2
132+
133+
Bson filter = Filters.empty();
134+
Bson projection = Projections.fields(Projections.include("name", "rating"), Projections.excludeId());
135+
collection.find(filter).projection(projection).forEach(doc -> System.out.println(doc));
136+
137+
This example that identifies two fields to include in the projection yields
138+
the following results:
139+
140+
.. code-block:: json
141+
142+
{ "name": "apples", "rating": 3 }
143+
{ "name": "bananas", "rating": 1 }
144+
{ "name": "oranges", "rating": 2 }
145+
{ "name": "avocados", "rating": 5 }
146+
147+
For additional projection examples, see the
148+
:manual:`MongoDB Manual page on Project Fields to Return from Query </tutorial/project-fields-from-query-results/>`.

0 commit comments

Comments
 (0)