Docs Home → MongoDB Manual
db.collection.findOne[query, projection, options]
Important
mongosh Method
This page documents a mongosh
method. This is not the documentation for database commands or language-specific drivers, such as Node.js. To use the database command, see the
find
command.
For MongoDB API drivers, refer to the language-specific MongoDB driver documentation.
For the legacy mongo
shell documentation, refer to the documentation for the corresponding MongoDB Server release:
mongo shell v4.4
mongo shell v4.2
Returns one document that satisfies the specified query criteria on the collection or view. If multiple documents satisfy the query, this method returns the first document according to the natural order which reflects the order of documents on the disk. In capped collections, natural order is the same as insertion order. If no document satisfies the query, the method returns null.
| document | Optional. Specifies query selection criteria using query operators. |
| document | Optional. Specifies the fields to return using projection operators. Omit this parameter to return all fields in the matching document. For details, see Projection. |
| document | Optional. Specifies additional options for the query. These options modify query behavior and how results are returned. To see available options, see FindOptions. |
One document that satisfies the criteria specified as the first argument to this method. If you specify a projection parameter, findOne[] returns a document that only contains the projection fields. The _id field is always included unless you explicitly exclude it.Although
similar to the |
Starting in MongoDB 4.2, if the client that issued db.collection.findOne[]
disconnects before the operation completes, MongoDB marks
db.collection.findOne[]
for termination using killOp
.
Important
Language Consistency
The projection
parameter
determines which fields are returned in the matching documents. The projection
parameter takes a document of the following form:
{ field1: , field2: ... }
| Specifies the inclusion of a field. Non-zero integers are also treated as |
| Specifies the exclusion of a field. |
| With the use of the |
| Using the array projection operators |
| Using the |
| Specifies the value of the projected field. Starting in MongoDB 4.4, with the use of aggregation expressions and syntax, including the use of literals and aggregation variables, you can project new fields or project existing fields with new values. For example,
In versions 4.2 and earlier, any specification value [with the exception of the previously unsupported document value] is treated as either New in version 4.4. |
For fields in an embedded documents, you can specify the field using either:
dot notation; e.g.
"field.nestedfield":
nested form; e.g.
{ field: { nestedfield: } }
[Starting in MongoDB 4.4]
The _id
field is included in the returned documents by default unless you explicitly
specify _id: 0
in the projection to suppress the field.
A projection
cannot contain both include and exclude specifications, with the exception of the _id
field:
In projections that explicitly include fields, the
_id
field is the only field that you can explicitly exclude.In projections that explicitly excludes fields, the
_id
field is the only field that you can explicitly include; however, the_id
field is included by default.
For more information on projection, see also:
Projection
Project Fields to Return from Query
The following operation returns a single document from the bios collection:
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']
:
db.bios.findOne[ { $or: [ { 'name.first' : /^G/ }, { birth: { $lt: new Date['01/01/1945'] } } ] } ]
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.
The following operation finds a document in the
bios collection and returns only the name
, contribs
and _id
fields:
db.bios.findOne[ { }, { name: 1, contribs: 1 } ]
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:
db.bios.findOne[ { contribs: 'OOP' }, { _id: 0, 'name.first': 0, birth: 0 } ]
You cannot apply cursor methods to the result of findOne[]
because a single document is returned. You have access to the document directly:
var myDocument = db.bios.findOne[]; if [myDocument] { var myName = myDocument.name; print [tojson[myName]]; }
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 $expr
operator.
Create a collection cakeFlavors
:
db.cakeFlavors.insertMany[ [ { _id: 1, flavor: "chocolate" }, { _id: 2, flavor: "strawberry" }, { _id: 3, flavor: "cherry" } ] ]
The following example defines a
targetFlavor
variable in let
and uses the variable to retrieve the chocolate cake flavor:
db.cakeFlavors.findOne[ { $expr: { $eq: [ "$flavor", "$$targetFlavor" ] } }, { _id: 0 }, { let : { targetFlavor: "chocolate" } } ]
Output:
To see all available query options, see FindOptions.