cursor.explain()

Definition

• cursor.explain(verbosity)

mongo Shell Method

This page documents the mongo shell method, and doesnot refer to the MongoDB Node.js driver (or any other driver)method. For corresponding MongoDB driver API, refer to your specificMongoDB driver documentation instead.

Changed in version 3.0: The parameter to the method and the output format have changed in3.0.

Provides information on the query plan for thedb.collection.find() method.

The explain() method has the following form:

db.collection.find().explain()

The explain() method has the following parameter:

ParameterTypeDescriptionverbosestringOptional. Specifies the verbosity mode for the explain output. The mode affectsthe behavior of explain() and determines the amount ofinformation to return. The possible modes are: "queryPlanner","executionStats", and "allPlansExecution".

Default mode is "queryPlanner".

For backwards compatibility with earlier versions ofcursor.explain(), MongoDB interprets true as"allPlansExecution" and false as "queryPlanner".

For more information on the modes, seeVerbosity Modes.

Changed in version 3.0.

The explain() method returns a document with thequery plan and, optionally, the execution statistics.

Behavior

Verbosity Modes

The behavior of cursor.explain() and the amount ofinformation returned depend on the verbosity mode.

queryPlanner Mode

By default, cursor.explain() runs in queryPlannerverbosity mode.

MongoDB runs the query optimizer to choosethe winning plan for the operation under evaluation. cursor.explain() returnsthe queryPlanner information for the evaluatedmethod.

executionStats Mode

MongoDB runs the query optimizer to choosethe winning plan, executes the winning plan to completion, and returnsstatistics describing the execution of the winning plan.

cursor.explain() returns the queryPlanner andexecutionStats information for the evaluatedmethod. However, executionStats does notprovide query execution information for the rejected plans.

allPlansExecution Mode

MongoDB runs the query optimizer to choose the winning plan and executes thewinning plan to completion. In "allPlansExecution" mode, MongoDBreturns statistics describing the execution of the winning plan as wellas statistics for the other candidate plans captured during planselection.

cursor.explain() returns the queryPlanner andexecutionStats information for the evaluatedmethod. The executionStats includes thecompleted query execution information for the winning plan.

If the query optimizer considered more than one plan,executionStats information also includes the _partial_execution information captured during the plan selection phase for both the winning and rejectedcandidate plans.

db.collection.explain().find()

db.collection.explain().find() is similar todb.collection.find().explain() with thefollowing key differences:

• The db.collection.explain().find() construct allows for theadditional chaining of query modifiers. For list of query modifiers,see db.collection.explain().find().help().
• The db.collection.explain().find() returns a cursor, whichrequires a call to .next(), or its alias .finish(), to returnthe explain() results.

See db.collection.explain() for more information.

Example

The following example runs cursor.explain() in“executionStats” verbosity modeto return the query planning and execution information for thespecified db.collection.find() operation:

db.products.find(
   { quantity: { $gt: 50 }, category: "apparel" }
).explain("executionStats")

Output

cursor.explain() operations can return information regarding:

• queryPlanner, which details the plan selected by thequery optimizer and lists the rejectedplans;
• executionStats, which details the execution of the winningplan and the rejected plans; and
• serverInfo, which provides information on theMongoDB instance.

The verbosity mode (i.e. queryPlanner, executionStats,allPlansExecution) determines whether the results includeexecutionStats and whether executionStats includes datacaptured during plan selection.

For details on the output, see Explain Results.