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

<!--
Tab options on this page. Append to the .md URL to filter:
  ?tabs=<id,...>   select specific tabs (e.g. ?tabs=nodejs,shell)
  ?allTabs=true    include every tab
  (no param)       default: one tab per tabset

Available tabs:
  other tabs: queryplanner, executionstats, allplans
-->

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

## Description

Returns information on the query plan for the following methods:

- [`aggregate()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.aggregate.md#mongodb-method-db.collection.aggregate)

- [`count()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.count.md#mongodb-method-db.collection.count)

- [`find()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.find.md#mongodb-method-db.collection.find)

- [`distinct()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.distinct.md#mongodb-method-db.collection.distinct)

- [`findAndModify()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.findandmodify.md#mongodb-method-db.collection.findAndModify)

Returns information on [`mapReduce()`.](https://www.mongodb.com/docs/manual/reference/method/db.collection.mapreduce.md#mongodb-method-db.collection.mapReduce)

To use [`db.collection.explain()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#mongodb-method-db.collection.explain), append one of the aforementioned methods to [`db.collection.explain()`:](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#mongodb-method-db.collection.explain)

```none
db.collection.explain().<method(...)>
```

For example,

```javascript
db.movies.explain().remove( { rated: "PG" }, { justOne: true } )

```

For more examples, see [Examples](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#std-label-explain-method-examples). See also [db.collection.explain().help().](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#std-label-explain-method-help)

### Parameters

The [`db.collection.explain()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#mongodb-method-db.collection.explain) method has the following parameter:

| Parameter | Type | Description |
| --- | --- | --- |
| `verbosity` | string | Optional. Specifies the verbosity mode for the explain output. The mode affects the behavior of `explain()` and determines the amount of information to return. The possible modes are: `"queryPlanner"` (Default); `"executionStats"`; `"allPlansExecution"` For backwards compatibility with earlier versions of [`cursor.explain()`](https://www.mongodb.com/docs/manual/reference/method/cursor.explain.md#mongodb-method-cursor.explain), MongoDB interprets `true` as `"allPlansExecution"` and `false` as `"queryPlanner"`. For more information on the modes, see [Verbosity Modes.](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#std-label-explain-method-verbosity) |

**Note:**

`db.collection.explain()` defaults to `queryPlanner`, unlike the [`explain`](https://www.mongodb.com/docs/manual/reference/command/explain.md#mongodb-dbcommand-dbcmd.explain) command, which defaults to `allPlansExecution`.

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

## Required Access

To use `explain`, you must have permission to run the underlying command.

## Behavior

**Note:**

Using `explain` ignores all existing plan cache entries and prevents the MongoDB query planner from creating a new plan cache entry.

### Verbosity Modes

The behavior of [`db.collection.explain()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#mongodb-method-db.collection.explain) and the amount of information returned depend on the `verbosity` mode.

### queryPlanner Mode (Default)

By default, [`db.collection.explain()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#mongodb-method-db.collection.explain) runs in `queryPlanner` verbosity mode.

MongoDB runs the [query optimizer](https://www.mongodb.com/docs/manual/core/query-plans.md#std-label-read-operations-query-optimization) to choose the winning plan for the operation under evaluation. [`db.collection.explain()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#mongodb-method-db.collection.explain) returns the [`queryPlanner`](https://www.mongodb.com/docs/manual/reference/explain-results.md#mongodb-data-explain.queryPlanner) information for the evaluated method.

### Explain and Write Operations

For write operations, [`db.collection.explain()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#mongodb-method-db.collection.explain) returns information about the write operation that would be performed but does not actually modify the database.

**Changed in version 9.0**

If you explain a write operation against a database that doesn't exist on a sharded cluster, the operation doesn't create the database.

### Restrictions

You cannot run the [`explain`](https://www.mongodb.com/docs/manual/reference/command/explain.md#mongodb-dbcommand-dbcmd.explain) command/[`db.collection.explain()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#mongodb-method-db.collection.explain) in `executionStats` mode or `allPlansExecution` mode for an [`aggregation pipeline`](https://www.mongodb.com/docs/manual/reference/method/db.collection.aggregate.md#mongodb-method-db.collection.aggregate) that contains the [`$out`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/out.md#mongodb-pipeline-pipe.-out) stage. Instead, you can either:

- run the explain in `queryPlanner` mode or

- run the explain in `executionStats` mode or `allPlansExecution` mode but without the [`$out`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/out.md#mongodb-pipeline-pipe.-out) stage to return information for the stages that precede the [`$out`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/out.md#mongodb-pipeline-pipe.-out) stage.

### `explain()` Mechanics

The [`db.collection.explain()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#mongodb-method-db.collection.explain) method wraps the [`explain`](https://www.mongodb.com/docs/manual/reference/command/explain.md#mongodb-dbcommand-dbcmd.explain) command and is the preferred way to run [`explain`.](https://www.mongodb.com/docs/manual/reference/command/explain.md#mongodb-dbcommand-dbcmd.explain)

[`db.collection.explain().find()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#mongodb-method-db.collection.explain) is similar to [`db.collection.find().explain()`](https://www.mongodb.com/docs/manual/reference/method/cursor.explain.md#mongodb-method-cursor.explain) with the following key differences:

- The [`db.collection.explain().find()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#mongodb-method-db.collection.explain) construct allows for the additional chaining of query modifiers. For list of query modifiers, see [db.collection.explain().find().help().](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#std-label-explain-method-help)

- The [`db.collection.find().explain()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#mongodb-method-db.collection.explain) returns the `explain()` information on the query plan.

[`db.collection.explain().aggregate()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#mongodb-method-db.collection.explain) is equivalent to passing the [explain](https://www.mongodb.com/docs/manual/reference/method/db.collection.aggregate.md#std-label-example-aggregate-method-explain-option) option to the [`db.collection.aggregate()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.aggregate.md#mongodb-method-db.collection.aggregate) method.

### `help()`

To see the list of operations supported by [`db.collection.explain()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#mongodb-method-db.collection.explain), run:

```javascript
db.collection.explain().help()
```

[`db.collection.explain().find()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#mongodb-method-db.collection.explain) returns a cursor, which allows for the chaining of query modifiers. To see the list of query modifiers supported by [`db.collection.explain().find()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#mongodb-method-db.collection.explain) as well as cursor-related methods, run:

```javascript
db.collection.explain().find().help()
```

You can chain multiple modifiers to `db.collection.explain().find()`. For an example, see [Explain `find()` with Modifiers.](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#std-label-explain-find-modifiers)

### Sharded Clusters

**New in version 8.3**

If you run `db.collection.explain()` against a database that does not exist on a sharded cluster, the execution stage reaches the end-of-stream and the operation does not create the database. For more information on end-of-stream execution stats, see [`explain.executionStats.executionStages.isEOF`.](https://www.mongodb.com/docs/manual/reference/explain-results.md#mongodb-data-explain.executionStats.executionStages.isEOF)

## Output

[`db.collection.explain()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#mongodb-method-db.collection.explain) operations can return information regarding:

- `explainVersion`, the output format version (for example, `"1"`).

- `command`, which details the command being explained.

- `queryShapeHash`, starting in MongoDB 8.0, which is a hexadecimal string with the hash of a [query shape](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-query-shape). For details, see [Query Shapes](https://www.mongodb.com/docs/manual/core/query-shapes.md#std-label-query-shapes), [Query Shape Hash](https://www.mongodb.com/docs/manual/reference/explain-results.md#std-label-explain-output-query-shape-hash), and [`explain.queryShapeHash`.](https://www.mongodb.com/docs/manual/reference/explain-results.md#mongodb-data-explain.queryShapeHash)

- [`queryPlanner`](https://www.mongodb.com/docs/manual/reference/explain-results.md#std-label-queryPlanner), which details the plan selected by the [query optimizer](https://www.mongodb.com/docs/manual/core/query-plans.md#std-label-read-operations-query-optimization) and lists the rejected plans.

- [`executionStats`](https://www.mongodb.com/docs/manual/reference/explain-results.md#std-label-executionStats), which details the execution of the winning plan and the rejected plans.

- [`serverInfo`](https://www.mongodb.com/docs/manual/reference/explain-results.md#std-label-serverInfo), which provides information on the MongoDB instance.

- `serverParameters`, which details internal parameters.

The verbosity mode (i.e. `queryPlanner`, `executionStats`, `allPlansExecution`) determines whether the results include [`executionStats`](https://www.mongodb.com/docs/manual/reference/explain-results.md#std-label-executionStats) and whether [`executionStats`](https://www.mongodb.com/docs/manual/reference/explain-results.md#std-label-executionStats) includes data captured during [plan selection.](https://www.mongodb.com/docs/manual/core/query-plans.md#std-label-query-plans-query-optimization)

Explain output is limited by the maximum [Nested Depth for BSON Documents](https://www.mongodb.com/docs/manual/reference/limits.md#mongodb-limit-Nested-Depth-for-BSON-Documents), which is 100 levels of nesting. Explain output that exceeds the limit is truncated.

For details on the output, see [Explain Results.](https://www.mongodb.com/docs/manual/reference/explain-results.md#std-label-explain-results)

## Examples

### `queryPlanner` Mode

By default, [`db.collection.explain()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#mongodb-method-db.collection.explain) runs in `"queryPlanner"` verbosity mode.

The following example runs [`db.collection.explain()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#mongodb-method-db.collection.explain) in `"queryPlanner"` verbosity mode to return the query planning information for the specified [`count()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.count.md#mongodb-method-db.collection.count) operation:

```javascript
db.movies.explain().count( { year: { $gt: 2000 } } )

```

### `executionStats`  Mode

The following example runs [`db.collection.explain()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#mongodb-method-db.collection.explain) in `"executionStats"` verbosity mode to return the query planning and execution information for the specified [`find()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.find.md#mongodb-method-db.collection.find) operation:

```javascript
db.movies.explain("executionStats").find(
   { year: { $gt: 2000 }, rated: "PG" }
)

```

### `allPlansExecution` Mode

The following example runs [`db.collection.explain()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#mongodb-method-db.collection.explain) in `"allPlansExecution"` verbosity mode. [`db.collection.explain()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#mongodb-method-db.collection.explain) returns the [`queryPlanner`](https://www.mongodb.com/docs/manual/reference/explain-results.md#mongodb-data-explain.queryPlanner) and [`executionStats`](https://www.mongodb.com/docs/manual/reference/explain-results.md#mongodb-data-explain.executionStats) for all considered plans for the specified [`findAndModify()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.findandmodify.md#mongodb-method-db.collection.findAndModify) operation:

**Note:**

The execution of this explain will *not* modify data but runs the query predicate of the update operation. For candidate plans, MongoDB returns the execution information captured during the [plan selection phase.](https://www.mongodb.com/docs/manual/core/query-plans.md#std-label-query-plans-query-optimization)

```javascript
db.movies.explain( "allPlansExecution" ).findAndModify( {
   query: { rated: "PG", year: { $gt: 2000 } },
   sort: { year: 1 },
   update: { $inc: { "imdb.votes": 1 } }
} )

```

### Explain `find()` with Modifiers

[`db.collection.explain().find()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#mongodb-method-db.collection.explain) construct allows for the chaining of query modifiers. For example, the following operation provides information on the [`find()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.find.md#mongodb-method-db.collection.find) method with [`sort()`](https://www.mongodb.com/docs/manual/reference/method/cursor.sort.md#mongodb-method-cursor.sort) and [`hint()`](https://www.mongodb.com/docs/manual/reference/method/cursor.hint.md#mongodb-method-cursor.hint) query modifiers.

```javascript
db.movies.explain("executionStats").find(
   { year: { $gt: 2000 }, rated: "PG" }
).sort( { year: -1 } ).hint( { rated: 1, year: -1 } )

```

For a list of query modifiers available, run the following in [`mongosh`:](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh)

```javascript
db.collection.explain().find().help()
```

### Access the `explain()` Results with `finish()` Method

The [`db.collection.explain().find()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#mongodb-method-db.collection.explain) returns the `explain()` results. If run interactively in [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh) you can use the `.finish()` method to access the query plan:

```javascript
db.movies.explain().find( { rated: "PG" } ).finish().queryPlanner.winningPlan

```