cursor.explain()

On this page

Definition

Behavior
Example
Output

This version of the documentation is archived and no longer supported. View the current documentation to learn how to upgrade your version of MongoDB.

Definition

cursor.explain(verbosity)

Important

mongo Shell Method

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

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

The explain() method has the following form:

db.collection.find().explain()

The explain() method has the following parameter:

Parameter	Type	Description
`verbose`	string	Optional. Specifies the verbosity mode for the explain output. The mode affects the behavior of `explain()` and determines the amount of information to return. The possible modes are: `"queryPlanner"`, `"executionStats"`, and `"allPlansExecution"`. Default mode is `"queryPlanner"`. For backwards compatibility with earlier versions of `cursor.explain()`, MongoDB interprets `true` as `"allPlansExecution"` and `false` as `"queryPlanner"`. For more information on the modes, see Verbosity Modes.

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

Behavior

Verbosity Modes

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

`queryPlanner` Mode

By default, cursor.explain() runs in queryPlanner verbosity mode.

MongoDB runs the query optimizer to choose the winning plan for the operation under evaluation. cursor.explain() returns the queryPlanner information for the evaluated method.

`executionStats` Mode

MongoDB runs the query optimizer to choose the winning plan, executes the winning plan to completion, and returns statistics describing the execution of the winning plan.

cursor.explain() returns the queryPlanner and executionStats information for the evaluated method. However, executionStats does not provide query execution information for the rejected plans.

`allPlansExecution` Mode

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

cursor.explain() returns the queryPlanner and executionStats information for the evaluated method. The executionStats includes the completed 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 rejected candidate plans.

`db.collection.explain().find()`

db.collection.explain().find() is similar to db.collection.find().explain() with the following key differences:

The db.collection.explain().find() construct allows for the additional chaining of query modifiers. For list of query modifiers, see db.collection.explain().find().help().
The db.collection.find().explain() returns a cursor, which requires a call to .next(), or its alias .finish(), to return the explain() results. If run interactively in the mongo shell, the mongo shell automatically calls .finish() to return the results. For scripts, however, you must explicitly call .next(), or .finish(), to return the results. For list of cursor-related methods, see db.collection.explain().find().help().

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

Example

The following example runs cursor.explain() in "executionStats" verbosity mode to return the query planning and execution information for the specified 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 the query optimizer and lists the rejected plans;
executionStats, which details the execution of the winning plan and the rejected plans; and
serverInfo, which provides information on the MongoDB instance.

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

For details on the output, see Explain Results.

Back

cursor.count()

cursor.forEach()