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

# explain (database command)

## Definition

The [`explain`](https://www.mongodb.com/docs/manual/reference/command/explain.md#mongodb-dbcommand-dbcmd.explain) command provides information on the execution of the following commands: [`aggregate`](https://www.mongodb.com/docs/manual/reference/command/aggregate.md#mongodb-dbcommand-dbcmd.aggregate), [`count`](https://www.mongodb.com/docs/manual/reference/command/count.md#mongodb-dbcommand-dbcmd.count), [`distinct`](https://www.mongodb.com/docs/manual/reference/command/distinct.md#mongodb-dbcommand-dbcmd.distinct), [`find`](https://www.mongodb.com/docs/manual/reference/command/find.md#mongodb-dbcommand-dbcmd.find), [`findAndModify`](https://www.mongodb.com/docs/manual/reference/command/findandmodify.md#mongodb-dbcommand-dbcmd.findAndModify), [`delete`](https://www.mongodb.com/docs/manual/reference/command/delete.md#mongodb-dbcommand-dbcmd.delete), [`mapReduce`](https://www.mongodb.com/docs/manual/reference/command/mapreduce.md#mongodb-dbcommand-dbcmd.mapReduce), and [`update`.](https://www.mongodb.com/docs/manual/reference/command/update.md#mongodb-dbcommand-dbcmd.update)

**Tip:**

In [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#std-program-mongosh), this command can also be run through the [`db.collection.explain()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#mongodb-method-db.collection.explain) and
[`cursor.explain()`](https://www.mongodb.com/docs/manual/reference/method/cursor.explain.md#mongodb-method-cursor.explain) helper methods.

Helper methods are convenient for [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#std-program-mongosh) users, but they may not return the same level of information as database commands.  In cases where the convenience is not needed or the additional return fields are required, use the database command.

**Note:**

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

## Compatibility

This command 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.

## Syntax

The command has the following syntax:

```javascript
db.runCommand(
   {
     explain: <command>,
     verbosity: <string>,
     comment: <any>
   }
)
```

## Command Fields

The command takes the following fields:

| Field | Type | Description |
| --- | --- | --- |
| `explain` | document | A document specifying the command for which to return the execution information. For details on the specific command document, see [`aggregate`](https://www.mongodb.com/docs/manual/reference/command/aggregate.md#mongodb-dbcommand-dbcmd.aggregate), [`count`](https://www.mongodb.com/docs/manual/reference/command/count.md#mongodb-dbcommand-dbcmd.count), [`distinct`](https://www.mongodb.com/docs/manual/reference/command/distinct.md#mongodb-dbcommand-dbcmd.distinct), [`find`](https://www.mongodb.com/docs/manual/reference/command/find.md#mongodb-dbcommand-dbcmd.find), [`findAndModify`](https://www.mongodb.com/docs/manual/reference/command/findandmodify.md#mongodb-dbcommand-dbcmd.findAndModify), [`delete`](https://www.mongodb.com/docs/manual/reference/command/delete.md#mongodb-dbcommand-dbcmd.delete), [`mapReduce`](https://www.mongodb.com/docs/manual/reference/command/mapreduce.md#mongodb-dbcommand-dbcmd.mapReduce), and [`update`.](https://www.mongodb.com/docs/manual/reference/command/update.md#mongodb-dbcommand-dbcmd.update) |
| `verbosity` | string | Optional. A string specifying the mode in which to run [`explain`](https://www.mongodb.com/docs/manual/reference/command/explain.md#mongodb-dbcommand-dbcmd.explain). The mode affects the behavior of [`explain`](https://www.mongodb.com/docs/manual/reference/command/explain.md#mongodb-dbcommand-dbcmd.explain) and determines the amount of information to return. The possible modes are: `"queryPlanner"`; `"executionStats"`; `"allPlansExecution"` (Default) For more information on the modes, see [explain behavior.](https://www.mongodb.com/docs/manual/reference/command/explain.md#std-label-explain-command-behavior) |
| `comment` | any | Optional. A user-provided comment to attach to this command. Once set, this comment appears alongside records of this command in the following locations: [mongod log messages](https://www.mongodb.com/docs/manual/reference/log-messages.md#std-label-log-messages-ref), in the `attr.command.cursor.comment` field.; [Database profiler](https://www.mongodb.com/docs/manual/reference/database-profiler.md#std-label-profiler) output, in the [`command.comment`](https://www.mongodb.com/docs/manual/reference/database-profiler.md#mongodb-data-system.profile.command) field.; [`currentOp`](https://www.mongodb.com/docs/manual/reference/command/currentop.md#mongodb-dbcommand-dbcmd.currentOp) output, in the [`command.comment`](https://www.mongodb.com/docs/manual/reference/command/currentop.md#mongodb-data-currentOp.command) field. A comment can be any valid [BSON type](https://www.mongodb.com/docs/manual/reference/bson-types.md#std-label-bson-types) (string, integer, object, array, etc). If you specify `explain` without a `comment`, it inherits any `comment` in the command specified to `explain`. |

**Note:**

The default verbosity of `explain` and [`db.collection.explain()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#mongodb-method-db.collection.explain) differs. `explain` defaults to `allPlansExecution` while `db.collection.explain()` defaults to `queryPlanner`.

## Behavior

### Verbosity Modes

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

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

### Explain and Write Operations

For write operations, the [`explain`](https://www.mongodb.com/docs/manual/reference/command/explain.md#mongodb-dbcommand-dbcmd.explain) command 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.

### Stable API

The [Stable API](https://www.mongodb.com/docs/manual/reference/stable-api.md#std-label-stable-api) V1 supports the following verbosity modes for the `explain` command:

- [allPlansExecution](https://www.mongodb.com/docs/manual/reference/command/explain.md#std-label-ex-allPlansExecution)

- [executionStats](https://www.mongodb.com/docs/manual/reference/command/explain.md#std-label-ex-executionStats)

- [queryPlanner](https://www.mongodb.com/docs/manual/reference/command/explain.md#std-label-ex-queryPlanner)

**Warning:**

MongoDB does not guarantee any specific output format from the [`explain`](https://www.mongodb.com/docs/manual/reference/command/explain.md#mongodb-dbcommand-dbcmd.explain) command, even when using the Stable API.

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

## Output

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

The following [`explain`](https://www.mongodb.com/docs/manual/reference/command/explain.md#mongodb-dbcommand-dbcmd.explain) command runs in `"queryPlanner"` verbosity mode to return the query planning information for a [`count`](https://www.mongodb.com/docs/manual/reference/command/count.md#mongodb-dbcommand-dbcmd.count) command:

```javascript
db.runCommand(
   {
     explain: { count: "movies", query: { year: { $gt: 2000 } } },
     verbosity: "queryPlanner"
   }
)

```

### `executionStats` Mode

The following [`explain`](https://www.mongodb.com/docs/manual/reference/command/explain.md#mongodb-dbcommand-dbcmd.explain) operation runs in `"executionStats"` verbosity mode to return the query planning and execution information for a [`count`](https://www.mongodb.com/docs/manual/reference/command/count.md#mongodb-dbcommand-dbcmd.count) command:

```javascript
db.runCommand(
   {
      explain: { count: "movies", query: { year: { $gt: 2000 } } },
      verbosity: "executionStats"
   }
)

```

### `allPlansExecution` Mode

By default, [`explain`](https://www.mongodb.com/docs/manual/reference/command/explain.md#mongodb-dbcommand-dbcmd.explain) runs in `"allPlansExecution"` verbosity mode. The following [`explain`](https://www.mongodb.com/docs/manual/reference/command/explain.md#mongodb-dbcommand-dbcmd.explain) command 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 an [`update`](https://www.mongodb.com/docs/manual/reference/command/update.md#mongodb-dbcommand-dbcmd.update) command:

**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.runCommand(
   {
     explain: {
        update: "movies",
        updates: [
           {
               q: { year: 2000, rated: "PG" },
               u: { $set: { available: true } }
           }
        ]
     }
   }
)

```