Docs Menu
Docs Home
/
MongoDB Manual
/
Reference
/
mongosh Methods
/
Collection Methods

db.collection.findOne()

On this page

  • Definition
  • Behavior
  • Examples

Definition

db.collection.findOne(query, projection, options)

Important

mongosh Method

This page documents a mongosh method. This is not the documentation for database commands or language-specific drivers, such as Node.js.

For the database command, see the find command.

For MongoDB API drivers, refer to the language-specific MongoDB driver documentation.

For the legacy mongo shell documentation, refer to the documentation for the corresponding MongoDB Server release:

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.
options
document

Optional. Specifies additional options for the query. These options modify query behavior and how results are returned. To see available options, see FindOptions.

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 db.collection.findOne() disconnects before the operation completes, MongoDB marks db.collection.findOne() for termination using killOp.

Projection

Important

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:

{ field1: <value>, field2: <value> ... }
Projection
Description
<field>: <1 or true>
Specifies the inclusion of a field. Non-zero integers are also treated as true.
<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.) Non-zero integers are also treated as true.
<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:

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

Use Variables in let Option

You can specify query options to modify query behavior and indicate how results are returned.

For example, to define variables that you can access elsewhere in the findOne method, use the let option. To filter results using a variable, you must access the variable within the $expr operator.

Create a collection cakeFlavors:

db.cakeFlavors.insertMany( [
   { _id: 1, flavor: "chocolate" },
   { _id: 2, flavor: "strawberry" },
   { _id: 3, flavor: "cherry" }
] )

The following example defines a targetFlavor variable in let and uses the variable to retrieve the chocolate cake flavor:

db.cakeFlavors.findOne(
   { $expr: { $eq: [ "$flavor", "$$targetFlavor" ] } },
   { _id: 0 },
   { let : { targetFlavor: "chocolate" }
} )

Output:

{ flavor: 'chocolate' }

To see all available query options, see FindOptions.

Back

db.collection.findAndModify()