db.collection.findOne()¶

On this page

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:

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

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

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