Explain Results
On this page
Changed in version 3.0.
MongoDB provides the db.collection.explain()
method, the cursor.explain()
method, and the explain
command to return information on query plans and execution statistics of the query plans.
The explain
results present the query plans as a tree of stages. Each stage passes its results (i.e. documents or index keys) to the parent node. The leaf nodes access the collection or the indices. The internal nodes manipulate the documents or the index keys that result from the child nodes. The root node is the final stage from which MongoDB derives the result set.
Stages are descriptive of the operation; e.g.
COLLSCAN
for a collection scanIXSCAN
for scanning index keysFETCH
for retrieving documentsSHARD_MERGE
for merging results from shardsSHARDING_FILTER
for filtering out orphan documents from shards
Explain Output
The following sections presents a list of some key fields returned by the explain
operation.
NOTE
- The list of fields is not meant to be exhaustive, but is meant to highlight some key field changes from earlier versions of explain.
- The output format is subject to change between releases.
queryPlanner
queryPlanner
information details the plan selected by the query optimizer.
For unsharded collections, explain
returns the following information:
{ "queryPlanner" : { "plannerVersion" : <int>, "namespace" : <string>, "indexFilterSet" : <boolean>, "parsedQuery" : { ... }, "winningPlan" : { "stage" : <STAGE1>, ... "inputStage" : { "stage" : <STAGE2>, ... "inputStage" : { ... } } }, "rejectedPlans" : [ <candidate plan 1>, ... ] }
explain.
queryPlanner
Contains information on the selection of the query plan by the query optimizer.
explain.queryPlanner.
namespace
A string that specifies the namespace (i.e., <database>.<collection>
) against which the query is run.
explain.queryPlanner.
indexFilterSet
A boolean that specifies whether MongoDB applied an index filter for the query shape.
explain.queryPlanner.
winningPlan
A document that details the plan selected by the query optimizer. MongoDB presents the plan as a tree of stages; i.e. a stage can have an inputStage
or, if the stage has multiple child stages, inputStages
.
explain.queryPlanner.winningPlan.
stage
A string that denotes the name of the stage.
Each stage consists of information specific to the stage. For instance, an IXSCAN
stage will include the index bounds along with other data specific to the index scan. If a stage has a child stage or multiple child stages, the stage will have an inputStage or inputStages.
explain.queryPlanner.winningPlan.
inputStage
A document that describes the child stage, which provides the documents or index keys to its parent. The field is present if the parent stage has only one child.
explain.queryPlanner.winningPlan.
inputStages
An array of documents describing the child stages. Child stages provide the documents or index keys to the parent stage. The field is present if the parent stage has multiple child nodes. For example, stages for $or expressions or index intersection consume input from multiple sources.
explain.queryPlanner.
rejectedPlans
Array of candidate plans considered and rejected by the query optimizer. The array can be empty if there were no other candidate plans.
For sharded collections, the winning plan includes the shards
array which contains the plan information for each accessed shard. For details, see Sharded Collection.
executionStats
The returned executionStats
information details the execution of the winning plan.
You must run the explain in executionStats or allPlansExecution verbosity mode in order for executionStats
to be present in the results.
To include partial execution data captured during plan selection, you must run in allPlansExecution
mode.
For unsharded collections, explain
returns the following information:
"executionStats" : { "executionSuccess" : <boolean>, "nReturned" : <int>, "executionTimeMillis" : <int>, "totalKeysExamined" : <int>, "totalDocsExamined" : <int>, "executionStages" : { "stage" : <STAGE1> "nReturned" : <int>, "executionTimeMillisEstimate" : <int>, "works" : <int>, "advanced" : <int>, "needTime" : <int>, "needYield" : <int>, "saveState" : <int>, "restoreState" : <int>, "isEOF" : <boolean>, ... "inputStage" : { "stage" : <STAGE2>, ... "nReturned" : <int>, "executionTimeMillisEstimate" : <int>, "keysExamined" : <int>, "docsExamined" : <int>, "saveState" : <int>, "restoreState" : <int>, ... "inputStage" : { ... } } }, "allPlansExecution" : [ { <partial executionStats1> }, { <partial executionStats2> }, ... ] }
explain.
executionStats
Contains statistics that describe the completed query execution for the winning plan. For write operations, completed query execution refers to the modifications that would be performed, but does not apply the modifications to the database.
explain.executionStats.
nReturned
Number of documents that match the query condition. nReturned
corresponds to the n
field returned by cursor.explain()
in earlier versions of MongoDB.
explain.executionStats.
executionTimeMillis
Total time in milliseconds required for query plan selection and query execution. executionTimeMillis
corresponds to the millis
field returned by cursor.explain()
in earlier versions of MongoDB.
explain.executionStats.
totalKeysExamined
Number of index entries scanned. totalKeysExamined
corresponds to the nscanned
field returned by cursor.explain()
in earlier versions of MongoDB.
explain.executionStats.
totalDocsExamined
Number of documents scanned. In earlier versions of MongoDB, totalDocsExamined
corresponds to the nscannedObjects
field returned by cursor.explain()
in earlier versions of MongoDB.
explain.executionStats.
executionStages
Details the completed execution of the winning plan as a tree of stages; i.e. a stage can have an inputStage
or multiple inputStages
.
Each stage consists of execution information specific to the stage.
explain.executionStats.executionStages.
works
Specifies the number of “work units” performed by the query execution stage. Query execution divides its work into small units. A “work unit” might consist of examining a single index key, fetching a single document from the collection, applying a projection to a single document, or doing a piece of internal bookkeeping.
explain.executionStats.executionStages.
advanced
The number of intermediate results returned, or advanced, by this stage to its parent stage.
explain.executionStats.executionStages.
needTime
The number of work cycles that did not advance an intermediate result to its parent stage (seeexplain.executionStats.executionStages.advanced
). For instance, an index scan stage may spend a work cycle seeking to a new position in the index as opposed to returning an index key; this work cycle would count towardsexplain.executionStats.executionStages.needTime
rather than explain.executionStats.executionStages.advanced
.
explain.executionStats.executionStages.
needYield
The number of times that the storage layer requested that the query stage suspend processing and yield its locks.
explain.executionStats.executionStages.
saveState
The number of times that the query stage suspended processing and saved its current execution state, for example in preparation for yielding its locks.
explain.executionStats.executionStages.
restoreState
The number of times that the query stage restored a saved execution state, for example after recovering locks that it had previously yielded.
explain.executionStats.executionStages.
isEOF
Specifies whether the execution stage has reached end of stream:
- If
true
or1
, the execution stage has reached end-of-stream. - If
false
or0
, the stage may still have results to return. For example, consider a query with a limit whose execution stages consists of aLIMIT
stage with an input stage ofIXSCAN
for the query. If the query returns more than the specified limit, theLIMIT
stage will reportisEOF: 1
, but its underlyingIXSCAN
stage will reportisEOF: 0
.
explain.executionStats.executionStages.inputStage.
keysExamined
For query execution stages that scan an index (e.g. IXSCAN), keysExamined
is the total number of in-bounds and out-of-bounds keys that are examined in the process of the index scan. If the index scan consists of a single contiguous range of keys, only in-bounds keys need to be examined. If the index bounds consists of several key ranges, the index scan execution process may examine out-of-bounds keys in order to skip from the end of one range to the beginning of the next.
Consider the following example, where there is an index of field x
and the collection contains 100 documents with x
values 1 through 100:
db.keys.find( { x : { $in : [ 3, 4, 50, 74, 75, 90 ] } } ).explain( "executionStats" )
The query will scan keys 3
and 4
. It will then scan the key 5
, detect that it is out-of-bounds, and skip to the next key 50
.
Continuing this process, the query scans keys 3, 4, 5, 50, 51, 74, 75, 76, 90, and 91. Keys 5
, 51
, 76
, and 91
are out-of-bounds keys that are still examined. The value of keysExamined
is 10.
explain.executionStats.executionStages.inputStage.
docsExamined
Specifies the number of documents scanned during the query execution stage.
Present for the COLLSCAN
stage, as well as for stages that retrieve documents from the collection (e.g. FETCH
)
explain.executionStats.
allPlansExecution
Contains partial execution information captured during the plan selection phase for both the winning and rejected plans. The field is present only if explain
runs in allPlansExecution
verbosity mode.
For sharded collections, explain
also includes the execution statistics for each accessed shard. For details, seeSharded Collection.
serverInfo
For unsharded collections, explain
returns the following information for the MongoDB instance:
"serverInfo" : { "host" : <string>, "port" : <int>, "version" : <string>, "gitVersion" : <string> }
For sharded collections, explain
returns the serverInfo
for each accessed shard. For details, see Sharded Collection.
Sharded Collection
For sharded collections, explain
returns the core query planner and server information for each accessed shard in the shards
field:
{ "queryPlanner" : { ... "winningPlan" : { ... "shards" : [ { "shardName" : <shard>, <queryPlanner information for shard>, <serverInfo for shard> }, ... ], }, }, "executionStats" : { ... "executionStages" : { ... "shards" : [ { "shardName" : <shard>, <executionStats for shard> }, ... ] }, "allPlansExecution" : [ { "shardName" : <string>, "allPlans" : [ ... ] }, ... ] } }
explain.queryPlanner.winningPlan.
shards
Array of documents that contain queryPlanner
and serverInfo
for each accessed shard.
explain.executionStats.executionStages.
shards
Array of documents that contain executionStats
for each accessed shard.
Compatibility Changes
Changed in version 3.0.
The format and fields of the explain
results have changed from previous versions. The following lists some key differences.
Collection Scan vs. Index Use
If the query planner selects a collection scan, the explain result includes a COLLSCAN
stage.
If the query planner selects an index, the explain result includes a IXSCAN
stage. The stage includes information such as the index key pattern, direction of traversal, and index bounds.
In previous versions of MongoDB, cursor.explain()
returned the cursor
field with the value of:
BasicCursor
for collection scans, andBtreeCursor <index name> [<direction>]
for index scans.
For more information on execution statistics of collection scans versus index scans, see Analyze Query Performance.
Covered Queries
When an index covers a query, MongoDB can both match the query conditions and return the results using only the index keys; i.e. MongoDB does not need to examine documents from the collection to return the results.
When an index covers a query, the explain result has an IXSCAN
stage that is not a descendant of a FETCH
stage, and in the executionStats, the totalDocsExamined
is 0
.
In earlier versions of MongoDB, cursor.explain()
returned the indexOnly
field to indicate whether the index covered a query.
Index Intersection
For an index intersection plan, the result will include either an AND_SORTED
stage or an AND_HASH
stage with an inputStages
array that details the indexes; e.g.:
{ "stage" : "AND_SORTED", "inputStages" : [ { "stage" : "IXSCAN", ... }, { "stage" : "IXSCAN", ... } ] }
In previous versions of MongoDB, cursor.explain()
returned the cursor
field with the value of ComplexPlan
for index intersections.
$or
Expression
If MongoDB uses indexes for an $or
expression, the result will include the OR
stage with an inputStages
array that details the indexes; e.g.:
{ "stage" : "OR", "inputStages" : [ { "stage" : "IXSCAN", ... }, { "stage" : "IXSCAN", ... }, ... ] }
In previous versions of MongoDB, cursor.explain()
returned the clauses
array that detailed the indexes.
Sort Stage
If MongoDB can use an index scan to obtain the requested sort order, the result will not include a SORT
stage. Otherwise, if MongoDB cannot use the index to sort, the explain
result will include a SORT
stage.
Prior to MongoDB 3.0, cursor.explain()
returned the scanAndOrder
field to specify whether MongoDB could use the index order to return sorted results.
← Write Operation PerformanceAnalyze Query Performance →
© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.