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

# cursor.explain() (mongosh method)

## Definition

**Important: mongosh Method**

This page documents a [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh) method. This is *not* the documentation for a language-specific driver, such as Node.js.

For MongoDB API drivers, refer to the language-specific [MongoDB driver documentation.](https://www.mongodb.com/docs/drivers/)

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

The `explain()` method has the following form:

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

The `explain()` method has the following parameter:

| Parameter | Necessity | Type | Description |
| --- | --- | --- | --- |
| `verbose` | Optional | String | Determines the amount of information to include in the explain output. The possible verbosity modes are: `allPlansExecution`; `executionStats`; `queryPlanner` (*Default*) For backwards compatibility with earlier versions of `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/cursor.explain.md#std-label-explain-cursor-method-verbosity) |

The [`explain()`](https://www.mongodb.com/docs/manual/reference/method/cursor.explain.md#mongodb-method-cursor.explain) method returns a document with the query plan and, optionally, the execution statistics.

**Note:**

`cursor.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 [`cursor.explain()`](https://www.mongodb.com/docs/manual/reference/method/cursor.explain.md#mongodb-method-cursor.explain) and the amount of information returned depend on the `verbosity` mode.

#### `queryPlanner` Mode

By default, [`cursor.explain()`](https://www.mongodb.com/docs/manual/reference/method/cursor.explain.md#mongodb-method-cursor.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. [`cursor.explain()`](https://www.mongodb.com/docs/manual/reference/method/cursor.explain.md#mongodb-method-cursor.explain) returns the [`queryPlanner`](https://www.mongodb.com/docs/manual/reference/explain-results.md#mongodb-data-explain.queryPlanner) information for the evaluated method.

#### `executionStats` 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, executes the winning plan to completion, and returns statistics describing the execution of the winning plan.

[`cursor.explain()`](https://www.mongodb.com/docs/manual/reference/method/cursor.explain.md#mongodb-method-cursor.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) information for the evaluated method. However, [`executionStats`](https://www.mongodb.com/docs/manual/reference/explain-results.md#mongodb-data-explain.executionStats) does not provide query execution information for the rejected plans.

#### `allPlansExecution` Mode

MongoDB runs the [query optimizer](https://www.mongodb.com/docs/manual/core/query-plans.md) to choose the winning plan and executes the winning plan to completion. In `"allPlansExecution"` mode, MongoDB returns statistics describing the execution of the winning plan as well as statistics for the other candidate plans captured during [plan selection.](https://www.mongodb.com/docs/manual/core/query-plans.md#std-label-query-plans-query-optimization)

[`cursor.explain()`](https://www.mongodb.com/docs/manual/reference/method/cursor.explain.md#mongodb-method-cursor.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) information for the evaluated method. The [`executionStats`](https://www.mongodb.com/docs/manual/reference/explain-results.md#mongodb-data-explain.executionStats) includes the *completed* query execution information for the *winning plan*.

If the query optimizer considered more than one plan, [`executionStats`](https://www.mongodb.com/docs/manual/reference/explain-results.md#mongodb-data-explain.executionStats) information also includes the *partial* execution information captured during the [plan selection phase](https://www.mongodb.com/docs/manual/core/query-plans.md#std-label-query-plans-query-optimization) for both the winning and rejected candidate plans.

### `db.collection.explain().find()`

[`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.

See [`db.collection.explain()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#mongodb-method-db.collection.explain) for more information.

### Sharded Clusters

**New in version 8.3**

If you run `cursor.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

[`cursor.explain()`](https://www.mongodb.com/docs/manual/reference/method/cursor.explain.md#mongodb-method-cursor.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)

## Example

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

```javascript
db.products.find(
   { quantity: { $gt: 50 }, category: "apparel" }
).explain("executionStats")
```