db.collection.findOne()
On this page
Definition
db.collection.findOne(query, projection)
Important
mongosh Method
This is a
mongosh
method. This is not the documentation forNode.js
or other programming language specific driver methods.In most cases,
mongosh
methods work the same way as the legacymongo
shell methods. However, some legacy methods are unavailable inmongosh
.For the legacy
mongo
shell documentation, refer to the documentation for the corresponding MongoDB Server release:For MongoDB API drivers, refer to the language specific MongoDB driver documentation.
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.
ParameterTypeDescriptionquery
documentOptional. Specifies query selection criteria using query operators.projection
documentOptional. Specifies the fields to return using projection operators. Omit this parameter to return all fields in the matching document. For details, see Projection.Returns: 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 theprojection
fields. The_id
field is always included unless you explicitly exclude it.Although similar to the
find()
method, thefindOne()
method returns a document rather than a cursor.
Behavior
Client Disconnection
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
.
Projection
Important
Language Consistency
Starting in MongoDB 4.4, as part of making
find()
and
findAndModify()
projection consistent with
aggregation's $project
stage,
The
find()
andfindAndModify()
projection can accept aggregation expressions and syntax.MongoDB enforces additional restrictions with regards to projections. See 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:
{ field1: <value>, field2: <value> ... }
Projection | Description |
---|---|
<field>: <1 or true> | Specifies the inclusion of a field. Non-zero integers are also
treated as true . |
<field>: <0 or false> | Specifies the exclusion of a field. |
"<field>.$": <1 or true> | |
<field>: <array projection> | Using the array projection operators $elemMatch ,
$slice , specifies the array element(s) to include,
thereby excluding those elements that do not meet the
expressions. (Not available for views.) |
<field>: <$meta expression> | Using the $meta operator expression, specifies the
inclusion of available per-document metadata . (Not available for views.) |
<field>: <aggregation expression> | 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. |
Embedded Field Specification
For fields in an embedded documents, you can specify the field using either:
dot notation; e.g.
"field.nestedfield": <value>
nested form; e.g.
{ field: { nestedfield: <value> } }
(Starting in MongoDB 4.4)
_id
Field Projection
The _id
field is included in the returned documents by default unless
you explicitly specify _id: 0
in the projection to suppress the field.
Inclusion or Exclusion
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:
Examples
With Empty Query Specification
The following operation returns a single document from the bios collection:
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')
:
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:
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:
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
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)); }