explain
On this page
Definition
explain
The
explain
command provides information on the execution of the following commands:aggregate
,count
,distinct
,find
,findAndModify
,delete
,mapReduce
, andupdate
.Tip
In the
mongo
Shell, this command can also be run through thedb.collection.explain()
andcursor.explain()
helper methods.Helper methods are convenient for
mongo
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.The
explain
command has the following syntax:{ explain: <command>, verbosity: <string>, comment: <any> } The command takes the following fields:
FieldTypeDescriptionexplain
documentverbosity
stringOptional. A string specifying the mode in which to run
explain
. The mode affects the behavior ofexplain
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
anyOptional. 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, in the
attr.command.cursor.comment
field.Database profiler output, in the
command.comment
field.currentOp
output, in thecommand.comment
field.
A comment can be any valid BSON type (string, integer, object, array, etc).
Note
If you specify
explain
without acomment
, it inherits anycomment
in the command specified toexplain
.
Behavior
Verbosity Modes
The behavior of explain
and the amount of information
returned depend on the verbosity
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>
.
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.
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.
Explain and Write Operations
For write operations, the explain
command returns
information about the write operation that would be performed but does
not actually modify the database.
Restrictions
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:
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; andserverInfo
, 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.