explain

Definition

explain

The explain command provides information on the execution of the following commands: aggregate, count, distinct, find, findAndModify, delete, mapReduce, and update.

Although MongoDB provides the explain command, the preferred method for running explain is to use the db.collection.explain() and cursor.explain() helpers.

The explain command has the following syntax:

{
   explain: <command>,
   verbosity: <string>,
   comment: <any>
}

The command takes the following fields:

Field	Type	Description
explain	document	A document specifying the command for which to return the execution information. For details on the specific command document, see aggregate, count, distinct, find, findAndModify, delete, mapReduce, and update.
verbosity	string	Optional. A string specifying the mode in which to run explain. The mode affects the behavior of explain 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	any	Optional. 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 the command.comment field. A comment can be any valid BSON type (string, integer, object, array, etc). Note If you specify explain without a comment, it inherits any comment in the command specified to explain.

Behavior

Output

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; and

• serverParameters, 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

db.runCommand(
   {
     explain: { count: "products", query: { quantity: { $gt: 50 } } },
     verbosity: "queryPlanner"
   }
)

db.runCommand(
   {
      explain: { count: "products", query: { quantity: { $gt: 50 } } },
      verbosity: "executionStats"
   }
)

db.runCommand(
   {
     explain: {
        update: "products",
        updates: [
           {
               q: { quantity: 1057, category: "apparel" },
               u: { $set: { reorder: true } }
           }
        ]
     }
   }
)