Navigation

db.collection.explain()

On this page

  • Description
  • Behavior
  • Output
  • Examples
db.collection.explain()
Important
mongosh Method

This is a mongosh method. This is not the documentation for Node.js or other programming language specific driver methods.

In most cases, mongosh methods work the same way as the legacy mongo shell methods. However, some legacy methods are unavailable in mongosh.

For the legacy mongo shell documentation, refer to the documentation for the corresponding MongoDB Server release:

For MongoDB API drivers, refer to the language specific MongoDB driver documentation.

Returns information on the query plan for the following methods:

Starting in MongoDB 3.0
Starting in MongoDB 3.2
Starting in MongoDB 4.4

To use db.collection.explain(), append one of the aforementioned methods to db.collection.explain():

db.collection.explain().<method(...)>

For example,

db.products.explain().remove( { category: "apparel" }, { justOne: true } )

For more examples, see Examples. See also db.collection.explain().help().

The db.collection.explain() method has the following parameter:

Parameter
Type
Description
verbosity
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" (Default)
  • "executionStats"
  • "allPlansExecution"

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 behavior of db.collection.explain() and the amount of information returned depend on the verbosity mode.

For write operations, db.collection.explain() returns information about the write operation that would be performed but does not actually modify the database.

Starting in MongoDB 4.2, you cannot run the explain command/db.collection.explain() in executionStats mode or allPlansExecution mode for an aggregation pipeline that contains the $out stage. Instead, you can either:

  • run the explain in queryPlanner mode or
  • run the explain in executionStats mode or allPlansExecution mode but without the $out stage to return information for the stages that precede the $out stage.

The db.collection.explain() method wraps the explain command and is the preferred way to run explain.

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

db.collection.explain().aggregate() is equivalent to passing the explain option to the db.collection.aggregate() method.

To see the list of operations supported by db.collection.explain(), run:

db.collection.explain().help()

db.collection.explain().find() returns a cursor, which allows for the chaining of query modifiers. To see the list of query modifiers supported by db.collection.explain().find() as well as cursor-related methods, run:

db.collection.explain().find().help()

You can chain multiple modifiers to db.collection.explain().find(). For an example, see Explain find() with Modifiers.

db.collection.explain() operations can return information regarding:

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.

By default, db.collection.explain() runs in "queryPlanner" verbosity mode.

The following example runs db.collection.explain() in "queryPlanner" verbosity mode to return the query planning information for the specified count() operation:

db.products.explain().count( { quantity: { $gt: 50 } } )

The following example runs db.collection.explain() in "executionStats" verbosity mode to return the query planning and execution information for the specified find() operation:

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

The following example runs db.collection.explain() in "allPlansExecution" verbosity mode. The db.collection.explain() returns the queryPlanner and executionStats for all considered plans for the specified update() operation:

Note

The execution of this explain will not modify data but runs the query predicate of the update operation. For candidate plans, MongoDB returns the execution information captured during the plan selection phase.

db.products.explain("allPlansExecution").update(
{ quantity: { $lt: 1000}, category: "apparel" },
{ $set: { reorder: true } }
)

db.collection.explain().find() construct allows for the chaining of query modifiers. For example, the following operation provides information on the find() method with sort() and hint() query modifiers.

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

For a list of query modifiers available, run the following in mongosh:

db.collection.explain().find().help()

db.collection.explain().find() returns a cursor to the explain results. If run interactively in mongosh, mongosh automatically iterates the cursor using the .next() method. For scripts, however, you must explicitly call .next() (or its alias .finish()) to return the results:

var explainResult = db.products.explain().find( { category: "apparel" } ).next();
Give Feedback

On this page

  • Description
  • Behavior
  • Output
  • Examples