- Reference >
- Explain Results
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 scan
- IXSCAN for scanning index keys
- FETCH for retrieving documents
- SHARD_MERGE for merging results 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>,
"isEOF" : <boolean>,
...
"inputStage" : {
"stage" : <STAGE2>,
...
"nReturned" : <int>,
"executionTimeMillisEstimate" : <int>,
"keysExamined" : <int>,
"docsExamined" : <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 (see explain.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 towards explain.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 system yield its locks.
- explain.executionStats.executionStages.isEOF¶
Specifies whether the execution stage has reached end of stream:
- If true or 1, the execution stage has reached end-of-stream.
- If false or 0, the stage may still have results to return. For example, consider a query with a limit whose execution stages consists of a LIMIT stage with an input stage of IXSCAN for the query. If the query returns more than the specified limit, the LIMIT stage will report isEOF: 1, but its underlying IXSCAN stage will report isEOF: 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, see Sharded 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, and
- BtreeCursor <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 Complex Plan 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.
In previous versions of MongoDB, cursor.explain() returned the scanAndOrder field to specify whether MongoDB could use the index order to return sorted results.
Thank you for your feedback!
We're sorry! You can Report a Problem to help us improve this page.