Navigation

db.collection.findOne()

On this page

Definition

db.collection.findOne(query, projection)

mongo Shell Method

This page documents the mongo shell method, and does not refer to the MongoDB Node.js driver (or any other driver) method. For corresponding MongoDB driver API, refer to your specific MongoDB driver documentation instead.

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.

Parameter Type Description
query document Optional. Specifies query selection criteria using query operators.
projection 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.
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 the projection fields. The _id field is always included unless you explicitly exclude it.

Although similar to the find() method, the findOne() method returns a document rather than a cursor.

Behavior

Client Disconnection

Starting in MongoDB 4.2, if the client that issued the db.collection.findOne() disconnects before the operation completes, MongoDB marks the db.collection.findOne() for termination (i.e. killOp on the operation).

Projection

Language Consistency

Starting in MongoDB 4.4, as part of making find and findAndModify projection consistent with aggregation’s $project stage,

The projection parameter determines which fields are returned in the matching documents. The projection parameter takes a document of the following form:

copy 
{ field1: <value>, field2: <value> ... }
Projection Description
<field>: <1 or true> Specifies the inclusion of a field.
<field>: <0 or false> Specifies the exclusion of a field.
"<field>.$": <1 or true> With the use of the $ array projection operator, you can specify the projection to return the first element that match the query condition on the array field; e.g. "arrayField.$" : 1. (Not available for views.)
<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,

  • If you specify a non-numeric, non-boolean literal (such as a literal string or an array or an operator expression) for the projection value, the field is projected with the new value; e.g.:
    • { field: [ 1, 2, 3, "$someExistingField" ] }
    • { field: "New String Value" }
    • { field: { status: "Active", total: { $sum: "$existingArray" } } }
  • To project a literal value for a field, use the $literal aggregation expression; e.g.:
    • { field: { $literal: 5 } }
    • { field: { $literal: true } }
    • { field: { $literal: { fieldWithValue0: 0, fieldWithValue1: 1 } } }

In versions 4.2 and earlier, any specification value (with the exception of the previously unsupported document value) is treated as either true or false to indicate the inclusion or exclusion of the field.

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:

copy 
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'):

copy 
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:

copy 
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:

copy 
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:

copy 
var myDocument = db.bios.findOne();

if (myDocument) {
   var myName = myDocument.name;

   print (tojson(myName));
}

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.