Docs Home → Develop Applications → MongoDB Manual
explain![](/docs/v5.2/assets/link.svg)
On this page
Definition![](/docs/v5.2/assets/link.svg)
explain
The
explain
command provides information on the execution of the following commands:aggregate
,count
,distinct
,find
,findAndModify
,delete
,mapReduce
, andupdate
.Although MongoDB provides the
explain
command, the preferred method for runningexplain
is to use thedb.collection.explain()
andcursor.explain()
helpers.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![](/docs/v5.2/assets/link.svg)
Verbosity Modes![](/docs/v5.2/assets/link.svg)
The behavior of explain
and the amount of information
returned depend on the verbosity
mode.
Explain and Write Operations![](/docs/v5.2/assets/link.svg)
For write operations, the explain
command returns
information about the write operation that would be performed but does
not actually modify the database.
Restrictions![](/docs/v5.2/assets/link.svg)
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:
Output![](/docs/v5.2/assets/link.svg)
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; andserverParameters
, 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![](/docs/v5.2/assets/link.svg)
queryPlanner
Mode![](/docs/v5.2/assets/link.svg)
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![](/docs/v5.2/assets/link.svg)
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![](/docs/v5.2/assets/link.svg)
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 } } } ] } } )