Navigation
This is an upcoming (i.e. in progress) version of the manual.

db.collection.findOne()

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

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> ... }

The <value> can be any of the following:

  • 1 or true to include the field in the return documents.
  • 0 or false to exclude the field.
  • Expression using a Projection Operators.

Note

For the _id field, you do not have to explicitly specify _id: 1 to return the _id field. The findOne() method always returns the _id field unless you specify _id: 0 to suppress the field.

A projection cannot contain both include and exclude specifications, except for the exclusion of the _id field. In projections that explicitly include fields, the _id field is the only field that you can explicitly exclude.

Path Collision Errors in Embedded Fields

Starting in MongoDB 4.4, you cannot specify both an embedded document and a field within that embedded document in the same projection.

The following projection document fails with a Path collision error because it attempts to project both the embedded size document and the size.uom field:

db.inventory.findOne( {}, { size: 1, "size.uom": 1 } )

The error occurs regardless of the order in which the parent document and embedded field are specified. The following example fails with the same error:

db.inventory.findOne( {}, { "size.uom": 1, size: 1 } )

In MongoDB versions prior to 4.4, the operation does not result in an error. The result depends on the order in which the fields are specified in the projection document.

  • If the parent document is specified before the embedded field, the operation only returns the embedded field.

    The projection document { size: 1, "size.uom": 1 } produces the same result as the document { "size.uom": 1 }.

  • If the embedded field is specified before the parent document the operation returns the entire size document.

    The projection document { "size.uom": 1, size: 1 } produces the same result as the document { size: 1 }.

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));
}