• Reference >
• mongo Shell Methods >
• Collection Methods >
• db.collection.findOne()

db.collection.findOne()

Definition

db.collection.findOne(query, projection)

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.

The projection parameter takes a document of the following form:

copy

{ 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 not explicitly specified in the projection parameter.
• 0 or false to exclude.

The projection argument cannot mix include and exclude specifications, with the exception of excluding the _id field.

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.

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

←   db.collection.findAndModify() db.collection.findOneAndDelete()  →

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