db.collection.findOne()

Definition

• db.collection.findOne(query, projection)

mongo Shell Method

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

Returns one document that satisfies the specified query criteria onthe collection or view. If multiple documentssatisfy the query, this method returns the first document accordingto the natural order which reflects the order of documentson the disk. In capped collections,natural order is the same as insertion order. If no documentsatisfies the query, the method returns null.

ParameterTypeDescriptionquerydocumentOptional. Specifies query selection criteria using query operators.projectiondocumentOptional. Specifies the fields to return using projection operators. Omit this parameter to return all fields in the matching document.

The projection parameter takes a document of the following form:

{ field1: <boolean>, field2: <boolean> ... }

The <boolean> can be one of the following include or exclude values:

• 1 or true to include. The findOne()method always includes the _id field even if the field is notexplicitly specified in the projection parameter.
• 0 or false to exclude.The projection argument cannot mix include and excludespecifications, with the exception of excluding the _id field.

Returns:One document that satisfies the criteria specified as the firstargument to this method. If you specify a projectionparameter, findOne() returns a documentthat only contains the projection fields. The _idfield is always included unless you explicitly exclude it.Although similar to the find() method,the findOne() method returns a documentrather 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 marksthe db.collection.findOne() for termination (i.e. killOp on theoperation).

Examples

With Empty Query Specification

The following operation returns a single document fromthe bios collection:

db.bios.findOne()

With a Query Specification

The following operation returns the first matching document from thebios collection where eitherthe field first in the embedded document name starts with the letterG or where the field birth is less than newDate('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. Theparameter 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 fieldcontains the element OOP and returns all fields except the _idfield, the first field in the name embedded document, and thebirth 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 offindOne() because a single document isreturned. You have access to the document directly:

var myDocument = db.bios.findOne();
 
if (myDocument) {
   var myName = myDocument.name;
 
   print (tojson(myName));
}