-
Notifications
You must be signed in to change notification settings - Fork 1.7k
/
db.collection.findOne.txt
271 lines (184 loc) · 6.85 KB
/
db.collection.findOne.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
=======================
db.collection.findOne()
=======================
.. default-domain:: mongodb
.. meta::
:description: Find a single document in a collection or view.
.. facet::
:name: programming_language
:values: shell
.. contents:: On this page
:local:
:backlinks: none
:depth: 1
:class: singlecol
Definition
----------
.. method:: db.collection.findOne(query, projection, options)
.. |dbcommand| replace:: :dbcommand:`find` command
.. include:: /includes/fact-mongosh-shell-method-alt.rst
Returns one document that satisfies the specified query criteria on
the collection or :ref:`view <views-landing-page>`.
If multiple documents satisfy the query, this method returns the first document
according to the :term:`natural order` which reflects the order of
documents on the disk. In :term:`capped collections
<capped collection>`, natural order is the same as insertion order.
If no document satisfies the query, the method returns ``null``.
If you specify a ``projection``
parameter, :method:`~db.collection.findOne()` returns a document
that only contains the ``projection`` fields. The ``_id``
field is always included unless you explicitly exclude it.
.. note::
Although similar to the :method:`~db.collection.find()` method,
the :method:`~db.collection.findOne()` method returns a document
rather than a cursor.
Compatibility
-------------
.. |operator-method| replace:: ``db.collection.findOne()``
.. include:: /includes/fact-compatibility.rst
Syntax
------
The :method:`~db.collection.findOne()` method has the following
form:
.. code-block:: javascript
db.collection.findOne( <query>, <projection>, <options> )
The :method:`~db.collection.findOne()` method takes the following
parameters:
.. list-table::
:header-rows: 1
:widths: 20 20 80
* - Parameter
- Type
- Description
* - ``query``
- document
- Optional. Specifies query selection criteria using
:ref:`query operators <query-projection-operators-top>`.
* - ``projection``
- document
- Optional. Specifies the fields to return using
:ref:`projection operators <query-projection-operators-top>`.
Omit this parameter to return all fields in the matching
document. For details, see :ref:`findOne-projection`.
* - ``options``
- document
- .. include:: /includes/find-options-description.rst
Behavior
--------
.. |operation| replace:: :method:`db.collection.findOne()`
Client Disconnection
~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/extracts/4.2-changes-disconnect.rst
.. _findOne-projection:
Projection
~~~~~~~~~~
.. important:: Language Consistency
As part of making :method:`~db.collection.find` and
:method:`~db.collection.findAndModify` projection consistent with
aggregation's :pipeline:`$project` stage:
- The :method:`~db.collection.find` and
:method:`~db.collection.findAndModify` projection can accept
:ref:`aggregation expressions and syntax
<aggregation-expressions>`.
- MongoDB enforces additional restrictions with regards to
projections. See :limit:`Projection Restrictions` for details.
The ``projection`` parameter determines which fields are returned in
the matching documents. The ``projection`` parameter takes a document
of the following form:
.. code-block:: javascript
{ field1: <value>, field2: <value> ... }
.. include:: /includes/extracts/projection-values-table.rst
Embedded Field Specification
````````````````````````````
.. include:: /includes/extracts/projection-embedded-field-format.rst
``_id`` Field Projection
````````````````````````
.. include:: /includes/extracts/projection-id-field.rst
Inclusion or Exclusion
``````````````````````
.. include:: /includes/extracts/projection-inclusion-exclusion.rst
For more information on projection, see also:
- :ref:`find-projection`
- :ref:`read-operations-projection`
Examples
--------
With Empty Query Specification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following operation returns a single document from
the :ref:`bios collection <bios-example-collection>`:
.. code-block:: javascript
db.bios.findOne()
With a Query Specification
~~~~~~~~~~~~~~~~~~~~~~~~~~
The following operation returns the first matching document from the
bios collection where either the field ``first`` in the embedded
document ``name`` starts with the letter ``G`` **or** where the field
``birth`` is less than ``new
Date('01/01/1945')``:
.. code-block:: javascript
db.bios.findOne(
{
$or: [
{ 'name.first' : /^G/ },
{ birth: { $lt: new Date('01/01/1945') } }
]
}
)
With a Projection
~~~~~~~~~~~~~~~~~
The ``projection`` parameter specifies which fields to return. The
parameter contains either include or exclude specifications, not both,
unless the exclude is for the ``_id`` field.
Specify the Fields to Return
````````````````````````````
The following operation finds a document in the bios collection and
returns only the ``name``, ``contribs`` and ``_id`` fields:
.. code-block:: javascript
db.bios.findOne(
{ },
{ name: 1, contribs: 1 }
)
Return All but the Excluded Fields
``````````````````````````````````
The following operation returns a document in the bios collection
where the ``contribs`` field contains the element ``OOP`` and returns
all fields *except* the ``_id`` field, the ``first`` field in the
``name`` embedded document, and the ``birth`` field:
.. code-block:: javascript
db.bios.findOne(
{ contribs: 'OOP' },
{ _id: 0, 'name.first': 0, birth: 0 }
)
The ``findOne`` Result Document
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You cannot apply cursor methods to the result of
:method:`~db.collection.findOne()` because a single document is
returned. You have access to the document directly:
.. code-block:: javascript
var myDocument = db.bios.findOne();
if (myDocument) {
var myName = myDocument.name;
print (tojson(myName));
}
Use Variables in ``let`` Option
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can specify query options to modify query behavior and indicate how
results are returned.
For example, to define variables that you can access elsewhere in the
``findOne`` method, use the ``let`` option. To filter results using a
variable, you must access the variable within the :query:`$expr`
operator.
.. include:: /includes/let-example-create-flavors.rst
The following example defines a ``targetFlavor`` variable in ``let`` and
uses the variable to retrieve the chocolate cake flavor:
.. code-block:: javascript
db.cakeFlavors.findOne(
{ $expr: { $eq: [ "$flavor", "$$targetFlavor" ] } },
{ _id: 0 },
{ let : { targetFlavor: "chocolate" }
} )
Output:
.. code-block:: javascript
{ flavor: 'chocolate' }
To see all available query options, see :node-api-4.0:`FindOptions
</interfaces/findoptions.html>`.