explain (database command)

Definition

explain

The explain command provides information on the execution of the following commands: aggregate, count, distinct, find, findAndModify, delete, mapReduce, and update.

Tip

In mongosh, this command can also be run through the db.collection.explain() and cursor.explain() helper methods.

Helper methods are convenient for 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: The fully managed service for MongoDB deployments in the cloud

• MongoDB Enterprise: The subscription-based, self-managed version of MongoDB

• MongoDB Community: 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:

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

Command Fields

The command takes the following fields:

Behavior

Output

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. For details, see Query Shapes, Query Shape Hash, and explain.queryShapeHash.

• queryPlanner, which details the plan selected by the query optimizer and lists the rejected plans.

• executionStats, which details the execution of the winning plan and the rejected plans.

• 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 and whether executionStats includes data captured during plan selection.

Explain output is limited by the maximum 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.

Examples

db.runCommand(
   {
     explain: { count: "products", query: { quantity: { $gt: 50 } } },
     verbosity: "queryPlanner"
   }
)

db.runCommand(
   {
      explain: { count: "products", query: { quantity: { $gt: 50 } } },
      verbosity: "executionStats"
   }
)

db.runCommand(
   {
     explain: {
        update: "products",
        updates: [
           {
               q: { quantity: 1057, category: "apparel" },
               u: { $set: { reorder: true } }
           }
        ]
     }
   }
)