> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# db.collection.findOne() (mongosh method)

## Definition

Returns one document that satisfies the specified query criteria on the collection or [view.](https://www.mongodb.com/docs/manual/core/views.md#std-label-views-landing-page)

The returned document may vary depending on the number of documents that match the query criteria, and the [query plan](https://www.mongodb.com/docs/manual/core/query-plans.md#std-label-query-plans-query-optimization) used:

| Number of matching documents | Query plan | Result |
| --- | --- | --- |
| 0 | Any | The method returns `null` |
| 1 | Any | The method returns the document that satisfies the specified query criteria. |
| 2 or more | Collection Scan | The method returns the first document according to the [natural order](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-natural-order). In [capped collections](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-capped-collection), natural order is the same as insertion order. |
| 2 or more | Index Scan | The method returns the first document retrieved from the index. |

**Important:**

If the query plan changes to use a different index, the method may return a different document. If your use case requires that a particular record is chosen consistently, you must use the `options` document to specify a sort. For details on using `findOne()` with an `options` document, see the [example.](https://www.mongodb.com/docs/manual/reference/method/db.collection.findone.md#std-label-findOne-with-options)

If you specify a `projection` parameter, [`findOne()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.findone.md#mongodb-method-db.collection.findOne) returns a document that only contains the `projection` fields. The `_id` field is always included unless you explicitly exclude it.

**Note:**

Although similar to the [`find()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.find.md#mongodb-method-db.collection.find) method, `findOne()` returns a document rather than a cursor.

## Compatibility

This method is available in deployments hosted in the following environments:

- [MongoDB Atlas](https://www.mongodb.com/docs/atlas): The fully managed service for MongoDB deployments in the cloud

**Note:**

This command is supported in all MongoDB Atlas clusters. For information on Atlas support for all commands, see [Unsupported Commands.](https://www.mongodb.com/docs/atlas/unsupported-commands/)

- [MongoDB Enterprise](https://www.mongodb.com/docs/manual/administration/install-enterprise.md#std-label-install-mdb-enterprise): The subscription-based, self-managed version of MongoDB

- [MongoDB Community](https://www.mongodb.com/docs/manual/administration/install-community.md#std-label-install-mdb-community-edition): The source-available, free-to-use, and self-managed version of MongoDB

## Syntax

`db.collection.findOne()` has the following form:

```javascript
db.collection.findOne( <query>, <projection>, <options> )
```

`db.collection.findOne()` takes the following parameters:

| Parameter | Type | Description |
| --- | --- | --- |
| `query` | document | Optional. Specifies query selection criteria using [query operators.](https://www.mongodb.com/docs/manual/reference/mql/query-predicates.md#std-label-query-projection-operators-top) |
| `projection` | document | Optional. Specifies the fields to return using [projection operators](https://www.mongodb.com/docs/manual/reference/mql/query-predicates.md#std-label-query-projection-operators-top). Omit this parameter to return all fields in the matching document. For details, see [Projection.](https://www.mongodb.com/docs/manual/reference/method/db.collection.findone.md#std-label-findOne-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.](https://mongodb.github.io/node-mongodb-native/4.0//interfaces/findoptions.html) |

## Behavior

### Client Disconnection

If the client that issued `findOne()` disconnects before the operation completes, MongoDB marks `findOne()` for termination using [`killOp`.](https://www.mongodb.com/docs/manual/reference/command/killop.md#mongodb-dbcommand-dbcmd.killOp)

### Projection

**Important: Language Consistency**

As part of making [`find()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.find.md#mongodb-method-db.collection.find) and [`findAndModify()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.findandmodify.md#mongodb-method-db.collection.findAndModify) projection consistent with aggregation's [`$project`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project) stage:

- The [`find()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.find.md#mongodb-method-db.collection.find) and [`findAndModify()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.findandmodify.md#mongodb-method-db.collection.findAndModify) projection can accept [aggregation expressions and syntax.](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions)

- MongoDB enforces additional restrictions with regards to projections. See [Projection Restrictions](https://www.mongodb.com/docs/manual/reference/limits.md#mongodb-limit-Projection-Restrictions) for details.

The `projection` parameter determines which fields are returned in the matching documents. The `projection` parameter takes a document of the following form:

```javascript
{ field1: <value>, field2: <value> ... }
```

| Projection | Description |
| --- | --- |
| `<field>: <1 or true>` | Specifies the inclusion of a field. If you specify a non-zero integer for the projection value, the operation treats the value as `true`. |
| `<field>: <0 or false>` | Specifies the exclusion of a field. |
| `"<field>.$": <1 or true>` | Uses the [`$`](https://www.mongodb.com/docs/manual/reference/operator/projection/positional.md#mongodb-projection-proj.-) array projection operator to return the first element that matches the query condition on the array field. If you specify a non-zero integer for the projection value, the operation treats the value as `true`. Not available for [views.](https://www.mongodb.com/docs/manual/core/views.md#std-label-views-landing-page) |
| `<field>: <array projection>` | Uses the array projection operators ([`$elemMatch`](https://www.mongodb.com/docs/manual/reference/operator/projection/elemmatch.md#mongodb-projection-proj.-elemMatch), [`$slice`](https://www.mongodb.com/docs/manual/reference/operator/projection/slice.md#mongodb-projection-proj.-slice)) to specify the array elements to include. Not available for [views.](https://www.mongodb.com/docs/manual/core/views.md#std-label-views-landing-page) |
| `<field>: <$meta expression>` | Uses the [`$meta`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/meta.md#mongodb-expression-exp.-meta) operator expression to specify the inclusion of available [`per-document metadata`.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/meta.md#mongodb-expression-exp.-meta) Not available for [views.](https://www.mongodb.com/docs/manual/core/views.md#std-label-views-landing-page) |
| `<field>: <aggregation expression>` | Specifies the value of the projected field. With the use of [aggregation expressions and syntax](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions), including the use of literals and aggregation variables, you can project new fields or project existing fields with new values. 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, for example:`{ 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`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/literal.md#mongodb-expression-exp.-literal) aggregation expression; for example:`{ field: { $literal: 5 } }`; `{ field: { $literal: true } }`; `{ field: { $literal: { fieldWithValue0: 0, fieldWithValue1: 1 } } }` |

**Note:**

You can specify projection in two ways for [`find()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.find.md#mongodb-method-db.collection.find) and [`findOne()`:](https://www.mongodb.com/docs/manual/reference/method/db.collection.findone.md#mongodb-method-db.collection.findOne)

- Setting the `projection` parameter

- Setting the `options` parameter to `projection`

If you specify both parameters, the `projection` parameter takes precedence. To use `options.projection`, set the `projection` parameter to `null` or `undefined`.

#### Embedded Field Specification

For fields in an embedded documents, you can specify the field using either:

- [dot notation](https://www.mongodb.com/docs/manual/core/document.md#std-label-document-dot-notation-embedded-fields), for example `"field.nestedfield": <value>`

- nested form, for example `{ field: { nestedfield: <value> } }`

#### `_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.

## Examples

The examples on this page use data from the [sample\_mflix dataset](https://www.mongodb.com/docs/manual/sample-data/sample-mflix.md#std-label-sample-mflix). For details on how to load this dataset into your self-managed MongoDB deployment, see [Load the Sample Dataset](https://www.mongodb.com/docs/manual/sample-data/load-sample-data-local.md#std-label-sample-dataset-local). If you made any modifications to the sample databases, you may need to drop and recreate the databases to run the examples on this page.

### With Empty Query Specification

The following operation returns a single document from the `movies` collection in the `sample_mflix` database:

```javascript
db.movies.findOne()

```

### With a Query Specification

The following operation returns the first matching document from the `movies` collection where either the `title` field starts with the letter "T" **or** the `year` field is less than 1950:

```javascript
db.movies.findOne(
   {
      $or: [
            { title: /^T/ },
            { year: { $lt: 1950 } }
            ]
   }
)

```

### 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 `movies` collection and returns only the `title`, `genres`, and `imdb` fields:

```javascript
db.movies.findOne(
   { },
   { title: 1, genres: 1, imdb: 1 }
)

```

#### Return All but the Excluded Fields

The following operation returns a document in the `movies` collection where the `cast` array contains `"Al Pacino"`. The projection returns all fields *except* the `_id` field, the `votes` field in the `imdb` embedded document, and the `fullplot` field:

```javascript
db.movies.findOne(
   { cast: 'Al Pacino' },
   { _id: 0, 'imdb.votes': 0, fullplot: 0 }
)

```

### With an Option

The following operation uses the `sort` option to return the first matching document from the *sorted* `movies` collection. In this example, the collection is sorted by `year` in ascending order.

```javascript
db.movies.findOne(
   { },
   { },
   { sort: { year: 1 } }
)

```

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

```javascript
var myDocument = db.movies.findOne();

if (myDocument) {
   var myTitle = myDocument.title;
   print(myTitle);
}

```

### 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`](https://www.mongodb.com/docs/manual/reference/operator/query/expr.md#mongodb-query-op.-expr) operator.

The following example defines a `targetTitle` variable in `let` and uses the variable to retrieve the movie titled `"The Godfather"`:

```javascript
db.movies.findOne(
   { $expr: { $eq: [ "$title", "$$targetTitle" ] } },
   { _id: 0, title: 1, year: 1 },
   { let : { targetTitle: "The Godfather" } }
)

```

**Output:**

```javascript
{ year: 1972, title: 'The Godfather' }
```