Skip to content

Commit 23240f3

Browse files
kay-kimkay-kim
committed
DOCS-368 projection operators - incorporate git comments
1 parent a978586 commit 23240f3

File tree

3 files changed

+86
-93
lines changed

3 files changed

+86
-93
lines changed

‎source/reference/operator/positional.txt‎

Lines changed: 3 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,20 +4,15 @@
44

55
.. default-domain:: mongodb
66

7-
This page documents the use of the ``positional $`` operator to
8-
identify the array element to update in the :method:`update()
9-
<db.collection.update()>` method. For the positional ``$`` projection
10-
operator used to return an array element from a read operation, see the
11-
:doc:`positional $ </reference/projection/positional>` projection
12-
operator.
13-
147
.. operator:: $
158

169
*Syntax*: ``{ "<array>.$" : value }``
1710

1811
The positional :operator:`$` operator identifies an element in an
1912
``array`` field to update without explicitly specifying the position
20-
of the element in the array.
13+
of the element in the array. To project, or return, an array element
14+
from a read operation, see the :doc:`$
15+
</reference/projection/positional>` projection operator.
2116

2217
When used with the :method:`update() <db.collection.update()>`
2318
method,

‎source/reference/projection/elemMatch.txt‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -12,22 +12,19 @@ $elemMatch (projection)
1212

1313
The :projection:`$elemMatch` projection operator limits the contents
1414
of an array field that is included in the query results to contain
15-
only the element that matches the query condition.
16-
17-
*Syntax*: ``{ $elemMatch: { <array>: <value> } }``
18-
19-
The ``<value>`` can be documents that contains :ref:`query operator
20-
expressions <query-selectors-comparison>`.
15+
only the array element that matches the :projection:`$elemMatch`
16+
condition.
2117

2218
.. note::
2319

20+
- The elements of the array are documents.
21+
2422
- If multiple elements match the :projection:`$elemMatch`
2523
condition, the operator returns the **first** matching element
26-
in the ``<array>`` field.
27-
28-
- The :projection:`$elemMatch` projection operator is similar to the
29-
:doc:`positional $ </reference/projection/positional>`
30-
projection operator.
24+
in the array.
25+
26+
- The :projection:`$elemMatch` projection operator is similar to
27+
the positional :projection:`$` projection operator.
3128

3229
The examples on the :projection:`$elemMatch` projection operator
3330
assumes a collection ``school`` with the following documents:
@@ -99,7 +96,7 @@ $elemMatch (projection)
9996
- The document with ``_id`` equal to ``3`` does not contain the
10097
``students`` field in the result since no element in its
10198
``students`` array matched the :projection:`$elemMatch`
102-
criterion.
99+
condition.
103100

104101
The :projection:`$elemMatch` projection can specify criteria on multiple
105102
fields:
@@ -149,7 +146,10 @@ $elemMatch (projection)
149146

150147
.. code-block:: javascript
151148

152-
db.schools.find( { zipcode: 63109 }, { students: { $elemMatch: { school: 102 } } } ).sort( { "students.age": -1 } )
149+
db.schools.find(
150+
{ zipcode: 63109 },
151+
{ students: { $elemMatch: { school: 102 } } }
152+
).sort( { "students.age": -1 } )
153153

154154
The operation applies the :method:`~cursor.sort()` to order the
155155
documents that have the field ``zipcode`` equal to ``63109`` and
@@ -164,4 +164,4 @@ $elemMatch (projection)
164164

165165
.. seealso::
166166

167-
:doc:`positional $ </reference/projection/positional>` projection operator
167+
:projection:`$ (projection) <$>` operator

‎source/reference/projection/positional.txt‎

Lines changed: 69 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -4,25 +4,17 @@
44

55
.. default-domain:: mongodb
66

7-
.. note::
8-
This page documents the use of the ``positional $`` operator in the
9-
:term:`projection` document of the :method:`~db.collection.find()`
10-
and the :method:`~db.collection.findOne()` methods. For the use of
11-
the positional ``$`` operator with the
12-
:method:`~db.collection.update()` method, see the :doc:`positional $
13-
operator for updates </reference/operator/positional>` .
14-
157
.. operator:: $
168

17-
*Syntax*: ``{ "<array>.$" : 1 }``
18-
199
The positional :projection:`$` operator limits the contents of the
2010
``<array>`` field that is included in the query results to contain
21-
the **first** matching element.
11+
the **first** matching element. To specify an array element to
12+
update, see the :doc:`positional $ operator for updates
13+
</reference/operator/positional>`.
2214

23-
Used with the :method:`~db.collection.find()` or
24-
:method:`~db.collection.findOne()` method in the :term:`projection`
25-
document:
15+
Used in the :term:`projection` document of the
16+
:method:`~db.collection.find()` method or the
17+
:method:`~db.collection.findOne()` method:
2618

2719
- The :projection:`$` projection operator limits the content of the
2820
``<array>`` field to the **first** element that matches the
@@ -53,40 +45,40 @@
5345
db.collection.find( { <array>: <value>, <someOtherArray>: <value2> },
5446
{ "<array>.$": 1 } )
5547

56-
Consider a collection ``students`` with the following documents:
48+
.. example::
5749

58-
.. code-block:: javascript
50+
A collection ``students`` contains the following documents:
5951

60-
{ "_id" : 1, "semester" : 1, "grades" : [ 70, 87, 90 ] }
61-
{ "_id" : 2, "semester" : 1, "grades" : [ 90, 88, 92 ] }
62-
{ "_id" : 3, "semester" : 1, "grades" : [ 85, 100, 90 ] }
63-
{ "_id" : 4, "semester" : 2, "grades" : [ 79, 85, 80 ] }
64-
{ "_id" : 5, "semester" : 2, "grades" : [ 88, 88, 92 ] }
65-
{ "_id" : 6, "semester" : 2, "grades" : [ 95, 90, 96 ] }
52+
.. code-block:: javascript
6653

67-
The following example queries for documents where the ``semester``
68-
field equals ``1`` and the ``grades`` array contains an element
69-
greater than or equal to ``85``. The example includes the
70-
:projection:`$` projection operator to return only the element in
71-
the ``grades`` array that matches the query criteria; the ``_id``
72-
field is by default implicitly included in the results:
54+
{ "_id" : 1, "semester" : 1, "grades" : [ 70, 87, 90 ] }
55+
{ "_id" : 2, "semester" : 1, "grades" : [ 90, 88, 92 ] }
56+
{ "_id" : 3, "semester" : 1, "grades" : [ 85, 100, 90 ] }
57+
{ "_id" : 4, "semester" : 2, "grades" : [ 79, 85, 80 ] }
58+
{ "_id" : 5, "semester" : 2, "grades" : [ 88, 88, 92 ] }
59+
{ "_id" : 6, "semester" : 2, "grades" : [ 95, 90, 96 ] }
7360

74-
.. code-block:: javascript
61+
In the following query, the projection ``{ "grades.$": 1 }``
62+
returns only the first element greater than or equal to ``85``
63+
for the ``grades`` field.
7564

76-
db.students.find( { semester: 1, grades: { $gte: 85 } }, { "grades.$": 1 } )
65+
.. code-block:: javascript
7766

78-
The read operation returns the following matching documents:
67+
db.students.find( { semester: 1, grades: { $gte: 85 } },
68+
{ "grades.$": 1 } )
7969

80-
.. code-block:: javascript
70+
The operation returns the following documents:
8171

82-
{ "_id" : 1, "grades" : [ 87 ] }
83-
{ "_id" : 2, "grades" : [ 90 ] }
84-
{ "_id" : 3, "grades" : [ 85 ] }
72+
.. code-block:: javascript
8573

86-
Although the array field ``grades`` may contain multiple elements
87-
that are greater than or equal to ``85``, the :projection:`$`
88-
projection operator returns only the first matching element from the
89-
array.
74+
{ "_id" : 1, "grades" : [ 87 ] }
75+
{ "_id" : 2, "grades" : [ 90 ] }
76+
{ "_id" : 3, "grades" : [ 85 ] }
77+
78+
Although the array field ``grades`` may contain multiple elements
79+
that are greater than or equal to ``85``, the :projection:`$`
80+
projection operator returns only the first matching element from the
81+
array.
9082

9183
.. important::
9284
When the :method:`~db.collection.find()` method includes a
@@ -102,53 +94,59 @@
10294
applied to the elements of the array before the :projection:`$`
10395
projection operator.
10496

105-
Consider the following documents in the ``students`` collection
106-
where the ``grades`` field is an array of documents; each document
107-
contain the three field names ``grade``, ``mean``, and ``std``:
97+
.. example::
10898

109-
.. code-block:: javascript
99+
A ``students`` collection contains the following documents
100+
where the ``grades`` field is an array of documents; each document
101+
contain the three field names ``grade``, ``mean``, and ``std``:
110102

111-
{ "_id" : 7, semester: 3, "grades" : [ { grade: 80, mean: 75, std: 8 },
112-
{ grade: 85, mean: 90, std: 5 },
113-
{ grade: 90, mean: 85, std: 3 } ] }
103+
.. code-block:: javascript
114104

115-
{ "_id" : 8, semester: 3, "grades" : [ { grade: 92, mean: 88, std: 8 },
116-
{ grade: 78, mean: 90, std: 5 },
117-
{ grade: 88, mean: 85, std: 3 } ] }
105+
{ "_id" : 7, semester: 3, "grades" : [ { grade: 80, mean: 75, std: 8 },
106+
{ grade: 85, mean: 90, std: 5 },
107+
{ grade: 90, mean: 85, std: 3 } ] }
118108

119-
The following example queries for documents with the array field
120-
``grades`` that contain an element with the ``mean`` greater than
121-
``70``. The query includes a projection to return the ``_id`` field
122-
and only the matching array element in the ``grades`` array. The
123-
query also includes a :method:`~cursor.sort()` to order by ascending
124-
``grades.grade`` field:
109+
{ "_id" : 8, semester: 3, "grades" : [ { grade: 92, mean: 88, std: 8 },
110+
{ grade: 78, mean: 90, std: 5 },
111+
{ grade: 88, mean: 85, std: 3 } ] }
125112

126-
.. code-block:: javascript
113+
In the following query, the projection ``{ "grades.$": 1 }``
114+
returns only the first element with the ``mean`` greater
115+
than ``70`` for the ``grades`` field. The query also includes a
116+
:method:`~cursor.sort()` to order by ascending ``grades.grade``
117+
field:
127118

128-
db.students.find( { "grades.mean": { $gt: 70 } }, { "grades.$": 1 } ).sort( { "grades.grade": 1 } )
119+
.. code-block:: javascript
129120

130-
The :method:`~db.collection.find()` method applies the
131-
:method:`~cursor.sort()` to the matching documents **before** it
132-
applies the :projection:`$` projection operator on the ``grades``
133-
array. Thus, the results with the projected array elements do not
134-
reflect the ascending ``grades.grade`` sort order:
121+
db.students.find( { "grades.mean": { $gt: 70 } },
122+
{ "grades.$": 1 }
123+
).sort( { "grades.grade": 1 } )
135124

136-
.. code-block:: javascript
125+
The :method:`~db.collection.find()` method sorts the matching
126+
documents **before** it applies the :projection:`$` projection
127+
operator on the ``grades`` array. Thus, the results with the
128+
projected array elements do not reflect the ascending
129+
``grades.grade`` sort order:
130+
131+
.. code-block:: javascript
137132

138-
{ "_id" : 8, "grades" : [ { "grade" : 92, "mean" : 88, "std" : 8 } ] }
139-
{ "_id" : 7, "grades" : [ { "grade" : 80, "mean" : 75, "std" : 8 } ] }
133+
{ "_id" : 8, "grades" : [ { "grade" : 92, "mean" : 88, "std" : 8 } ] }
134+
{ "_id" : 7, "grades" : [ { "grade" : 80, "mean" : 75, "std" : 8 } ] }
140135

141-
.. note::
136+
.. note::
142137

143-
Since only **one** array field can appear in the ``query
144-
document``, if the array contains documents, to specify criteria
145-
on multiple fields of these documents, use the
138+
Since only **one** array field can appear in the query document,
139+
if the array contains documents, to specify criteria on multiple
140+
fields of these documents, use the
146141
:doc:`/reference/operator/elemMatch/` operator, e.g.:
147142

148143
.. code-block:: javascript
149144

150-
db.students.find( { grades: { $elemMatch: { mean: { $gt: 70 }, grade: { $gt:90 } } } },
145+
db.students.find( { grades: { $elemMatch: {
146+
mean: { $gt: 70 },
147+
grade: { $gt:90 }
148+
} } },
151149
{ "grades.$": 1 } )
152150

153151
.. seealso::
154-
:doc:`/reference/projection/elemMatch`
152+
:projection:`$elemMatch (projection) <$elemMatch>`

0 commit comments

Comments
 (0)