Navigation
This version of the manual is no longer supported.

Explain Output

This document explains the output of the $explain operator and the mongo shell method explain().

Explain Output

The Core Explain Output fields display information for queries on non-sharded collections. For queries on sharded collections, explain() returns this information for each shard the query accesses.

{
  "cursor" : "<Cursor Type and Index>",
  "isMultiKey" : <boolean>,
  "n" : <num>,
  "nscannedObjects" : <num>,
  "nscanned" : <num>,
  "nscannedObjectsAllPlans" : <num>,
  "nscannedAllPlans" : <num>,
  "scanAndOrder" : <boolean>,
  "indexOnly" : <boolean>,
  "nYields" : <num>,
  "nChunkSkips" : <num>,
  "millis" : <num>,
  "indexBounds" : { <index bounds> },
  "allPlans" : [
                 { "cursor" : "<Cursor Type and Index>",
                   "n" : <num>,
                   "nscannedObjects" : <num>,
                   "nscanned" : <num>,
                   "indexBounds" : { <index bounds> }
                 },
                  ...
               ],
  "oldPlan" : {
                "cursor" : "<Cursor Type and Index>",
                "indexBounds" : { <index bounds> }
              }
  "server" : "<host:port>",
}

$or Queries

Queries with $or operator execute each clause of the $or expression in parallel and can use separate indexes on the individual clauses. If the query uses indexes on any or all of the query’s clause, explain() contains output for each clause as well as the cumulative data for the entire query:

{
   "clauses" : [
                  {
                     <core explain output>
                  },
                  {
                     <core explain output>
                  },
                  ...
               ],
   "n" : <num>,
   "nscannedObjects" : <num>,
   "nscanned" : <num>,
   "nscannedObjectsAllPlans" : <num>,
   "nscannedAllPlans" : <num>,
   "millis" : <num>,
   "server" : "<host:port>"
}

Sharded Collections

For queries on a sharded collection, the output contains the Core Explain Output for each accessed shard and cumulative shard information:

{
   "clusteredType" : "<Shard Access Type>",
   "shards" : {

                "<shard1>" : [
                               {
                                 <core explain output>
                               }
                             ],
                "<shard2>" : [
                               {
                                <core explain output>
                               }
                             ],
                ...
              },
   "millisShardTotal" : <num>,
   "millisShardAvg" : <num>,
   "numQueries" : <num>,
   "numShards" : <num>,
   "cursor" : "<Cursor Type and Index>",
   "n" : <num>,
   "nChunkSkips" : <num>,
   "nYields" : <num>,
   "nscanned" : <num>,
   "nscannedAllPlans" : <num>,
   "nscannedObjects" : <num>,
   "nscannedObjectsAllPlans" : <num>,
   "millis" : <num>
}

Fields

Core Explain Output

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 of explain() includes indexBounds details.
  • GeoSearchCursor indicates that the query used a geospatial index.
explain.isMultiKey

isMultiKey is a boolean. When true, 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 than nscanned, such as if the index covers a query. See indexOnly. Additionally, the nscannedObjects may be lower than nscanned 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 and nscanned to be close in value as possible. The nscanned value may be higher than the nscannedObjects value, such as if the index covers a query. See indexOnly.

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 is true when the query cannot use the index for returning sorted results.

When true, MongoDB must sort the documents after it retrieves them from either an index cursor or a cursor that scans the entire collection.

explain.indexOnly

indexOnly is a boolean value that returns true when the the query is covered by the index indicated in the cursor 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.millis

millis is a number that reflects the time in milliseconds to complete the query.

explain.indexBounds

indexBounds is a document that contains the lower and upper index key bounds. This field resembles one of the following:

"indexBounds" : {
                    "start" : { <index key1> : <value>, ...  },
                    "end" : { <index key1> : <value>, ... }
                },
"indexBounds" : { "<field>" : [ [ <lower bound>, <upper bound> ] ],
                  ...
                }
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 to explain() is true or 1.

explain.oldPlan

New in version 2.2.

oldPlan is a document value that contains the previous plan selected by the query optimizer for the query. Displays only when the <verbose> parameter to explain() is true or 1.

explain.server

New in version 2.2.

server is a string that reports the MongoDB server.

$or Query Output

explain.clauses

clauses is an array that holds the Core Explain Output information for each clause of the $or expression. clauses is only included when the clauses in the $or expression use indexes.

Sharded Collections Output

explain.clusteredType

clusteredType is a string that reports the access pattern for shards. The value is:

  • ParallelSort, if the mongos queries shards in parallel.
  • SerialServer, if the mongos queries shards sequentially.
explain.shards

shards is a document value that contains the shards accessed during the query and individual Core Explain Output for each 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.

explain.numShards

numShards is a number that reports the total number of shards queried.