- Reference >
- Database Commands >
- Diagnostic Commands >
- explain
explain¶
On this page
Definition¶
- explain¶
New in version 3.0.
The explain command provides information on the execution of the following commands: count, group, delete, and update.
Although MongoDB provides the explain command, the preferred method for running explain is to use the db.collection.explain() helper.
Note
The shell helpers(), db.collection.explain() and cursor.explain(), are the only available mechanisms for explaining db.collection.find() operations.
The explain command has the following syntax:
{ explain: <command>, verbosity: <string> }
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 count, group, delete, and update.
For find() operations, see db.collection.explain().
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.
Possible modes are: “queryPlanner”, “executionStats”, and “allPlansExecution”. For more information on the modes, see explain behavior.
By default, explain runs in “allPlansExecution” mode.
Behavior¶
The behavior of explain and the amount of information returned depend on the verbosity mode.
queryPlanner Mode¶
MongoDB runs the query optimizer to choose the winning plan for the operation under evaluation. explain returns the queryPlanner information for the evaluated <command>.
executionStats Mode¶
MongoDB runs the query optimizer to choose the winning plan, executes the winning plan to completion, and returns statistics describing the execution of the winning plan.
For write operations, explain returns information about the update or delete operations that would be performed, but does not apply the modifications to the database.
explain returns the queryPlanner and executionStats information for the evaluated <command>. However, executionStats does not provide query execution information for the rejected plans.
allPlansExecution Mode¶
By default, explain runs in "allPlansExecution" verbosity mode.
MongoDB runs the query optimizer 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.
For write operations, explain returns information about the update or delete operations that would be performed, but does not apply the modifications to the database.
explain returns the queryPlanner and executionStats information for the evaluated <command>. The executionStats includes the completed query execution information for the winning plan.
If the query optimizer considered more than one plan, executionStats information also includes the partial execution information captured during the plan selection phase for both the winning and rejected candidate plans.
Examples¶
queryPlanner Mode¶
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"
}
)
executionStats Mode¶
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"
}
)
allPlansExecution Mode¶
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 } }
}
]
}
}
)
Output¶
explain operations can return information regarding:
- 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; and
- serverInfo, which provides information on the MongoDB instance.
The verbosity mode (i.e. queryPlanner, executionStats, allPlansExecution) determines whether the results include executionStats and whether executionStats includes data captured during plan selection.
For details on the output, see Explain Results.
Thank you for your feedback!
We're sorry! You can Report a Problem to help us improve this page.