Docs Menu

Docs HomeDevelop ApplicationsMongoDB Manual

explain

On this page

  • Definition
  • Behavior
  • Output
  • Examples
explain

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

Although MongoDB provides the explain command, the preferred method for running explain is to use the db.collection.explain() and cursor.explain() helpers.

The explain command has the following syntax:

{
explain: <command>,
verbosity: <string>,
comment: <any>
}

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, count, distinct, find, findAndModify, delete, mapReduce, and update.
verbosity
string

Optional. A string specifying the mode in which to run explain. The mode affects the behavior of 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.

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:

A comment can be any valid BSON type (string, integer, object, array, etc).

Note

If you specify explain without a comment, it inherits any comment in the command specified to explain.

The behavior of explain and the amount of information returned depend on the verbosity mode.

For write operations, the explain command returns information about the write operation that would be performed but does not actually modify the database.

Starting in MongoDB 4.2, you cannot run the explain command/db.collection.explain() in executionStats mode or allPlansExecution mode for an aggregation pipeline that contains the $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 stage to return information for the stages that precede the $out stage.

explain operations can return information regarding:

  • explainVersion, the output format version (for example, "1");

  • command, which details the command being explained;

  • 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; and

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

The following explain command runs in "queryPlanner" verbosity mode to return the query planning information for a count command:

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

The following explain operation runs in "executionStats" verbosity mode to return the query planning and execution information for a count command:

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

By default, explain runs in "allPlansExecution" verbosity mode. The following explain command returns the queryPlanner and executionStats for all considered plans for an 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.

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