db.collection.explain()

Verbosity Modes

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

Explain and Write Operations

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

Restrictions

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.

explain() Mechanics

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:

• 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().

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

help()

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.

queryPlanner Mode

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 } } )

executionStats Mode

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" }
)

allPlansExecution Mode

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:

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

Explain find() with Modifiers

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 in the mongo shell:

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

Iterate the explain().find() Return Cursor

db.collection.explain().find() returns a cursor to the explain results. If run interactively in the mongo shell, the mongo shell 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();