- Reference >
mongo
Shell Methods >- Cursor Methods >
- cursor.explain()
cursor.explain()¶
On this page
Definition¶
-
cursor.
explain
(verbose)¶ Provides information on the query plan. The query plan is the plan the server uses to find the matches for a query. This information may be useful when optimizing a query. The
explain()
method returns a document that describes the process used to return the query results.The
explain()
method has the following form:The
explain()
method has the following parameter:Parameter Type Description verbose
Boolean Optional. Specifies the level of detail to include in the output. If true
or1
, includes theallPlans
andoldPlan
fields in the output.For an explanation of output, see Explain on Queries on Sharded Collections and Core Explain Output Fields.
The
explain()
method runs the actual query to determine the result. Although there are some differences between running the query withexplain()
and running without, generally, the performance will be similar between the two. So, if the query is slow, theexplain()
operation is also slow.Additionally, the
explain()
operation reevaluates a set of candidate query plans, which may cause theexplain()
operation to perform differently than a normal query. As a result, these operations generally provide an accurate account of how MongoDB would perform the query, but do not reflect the length of these queries.To determine the performance of a particular index, you can use
hint()
and in conjunction withexplain()
, as in the following example:When you run
explain()
withhint()
, the query optimizer does not reevaluate the query plans.Note
In some situations, the
explain()
operation may differ from the actual query plan used by MongoDB in a normal query. Theexplain()
operation evaluates the set of query plans and reports on the winning plan for the query. In normal operations the query optimizer caches winning query plans and uses them for similar related queries in the future. As a result MongoDB may sometimes select query plans from the cache that are different from the plan displayed usingexplain()
.See also
$explain
- Optimization Strategies for MongoDB page for information regarding optimization strategies.
- Analyze Performance of Database Operations tutorial for information regarding the database profile.
- Current Operation Reporting
Explain Results¶
Explain on Queries on Unsharded Collections¶
For queries on unsharded collections, explain()
returns the following core information.
For details on the fields, see Core Explain Output Fields.
Explain on $or
Queries¶
Queries with the $or
operator can use separate indexes on
each clause of the $or
expression. If the query is indexed,
explain()
contains
output for each clause as well
as the cumulative data for the entire query:
For details on the fields, see $or Query Output Fields and Core Explain Output Fields.
Explain on Queries on Sharded Collections¶
For queries on sharded collections, explain()
returns
information for each shard the query accesses. For queries on
unsharded collections, see Core Explain Output Fields.
For queries on a sharded collection, the output contains the Core Explain Output Fields for each accessed shard and cumulative shard information:
For details on these fields, see Core Explain Output Fields for each accessed shard and Sharded Collections Output Fields.
Explain Output Fields¶
Core Explain Output Fields¶
This section explains output for queries on collections that are not sharded. For queries on sharded collections, see Explain on Queries on Sharded Collections.
-
explain.
cursor
¶ cursor
is a string that reports the type of cursor used by the query operation:BasicCursor
indicates a full collection scan.BtreeCursor
indicates that the query used an index. The cursor includes name of the index. When a query uses an index, the output ofexplain()
includesindexBounds
details.GeoSearchCursor
indicates that the query used a geospatial index.
For
BtreeCursor
cursors, MongoDB will append the name of the index to the cursor string. Additionally, depending on how the query uses an index, MongoDB may append one or both of the following strings to the cursor string:reverse
indicates that query transverses the index from the highest values to the lowest values (e.g. “right to left”.)multi
indicates that the query performed multiple look-ups. Otherwise, the query uses the index to determine a range of possible matches.
-
explain.
isMultiKey
¶ isMultiKey
is a boolean. Whentrue
, the query uses a multikey index, where one of the fields in the index holds an array.
-
explain.
n
¶ n
is a number that reflects the number of documents that match the query selection criteria.
-
explain.
nscannedObjects
¶ Specifies the total number of documents scanned during the query. The
nscannedObjects
may be lower thannscanned
, such as if the index covers a query. SeeindexOnly
. Additionally, thenscannedObjects
may be lower thannscanned
in the case of multikey index on an array field with duplicate documents.
-
explain.
nscanned
¶ Specifies the total number of documents or index entries scanned during the database operation. You want
n
andnscanned
to be close in value as possible. Thenscanned
value may be higher than thenscannedObjects
value, such as if the index covers a query. SeeindexOnly
.
-
explain.
nscannedObjectsAllPlans
¶ New in version 2.2.
nscannedObjectsAllPlans
is a number that reflects the total number of documents scanned for all query plans during the database operation.
-
explain.
nscannedAllPlans
¶ New in version 2.2.
nscannedAllPlans
is a number that reflects the total number of documents or index entries scanned for all query plans during the database operation.
-
explain.
scanAndOrder
¶ scanAndOrder
is a boolean that istrue
when the query cannot use the order of documents in the index for returning sorted results: MongoDB must sort the documents after it receives the documents from a cursor.If
scanAndOrder
isfalse
, MongoDB can use the order of the documents in an index to return sorted results.
-
explain.
indexOnly
¶ indexOnly
is a boolean value that returnstrue
when the query is covered by the index indicated in thecursor
field. When an index covers a query, MongoDB can both match the query conditions and return the results using only the index because:- all the fields in the query are part of that index, and
- all the fields returned in the results set are in the same index.
-
explain.
nYields
¶ nYields
is a number that reflects the number of times this query yielded the read lock to allow waiting writes execute.
-
explain.
nChunkSkips
¶ nChunkSkips
is a number that reflects the number of documents skipped because of active chunk migrations in a sharded system. Typically this will be zero. A number greater than zero is ok, but indicates a little bit of inefficiency.
-
explain.
indexBounds
¶ indexBounds
is a document that contains the lower and upper index key bounds. This field resembles one of the following:
-
explain.
allPlans
¶ allPlans
is an array that holds the list of plans the query optimizer runs in order to select the index for the query. Displays only when the<verbose>
parameter toexplain()
istrue
or1
.
$or
Query Output Fields¶
Sharded Collections Output Fields¶
-
explain.
clusteredType
¶ clusteredType
is a string that reports the access pattern for shards. The value is:
-
explain.
shards
¶ shards
contains fields for each shard in the cluster accessed during the query. Each field holds the Core Explain Output Fields for that shard.
-
explain.
millisShardTotal
¶ millisShardTotal
is a number that reports the total time in milliseconds for the query to run on the shards.
-
explain.
millisShardAvg
¶ millisShardAvg
is a number that reports the average time in millisecond for the query to run on each shard.
-
explain.
numQueries
¶ numQueries
is a number that reports the total number of queries executed.