cursor.explain(verbosity)
This page documents a mongosh method. This is not the documentation for a language-specific driver, such as Node.js.
For MongoDB API drivers, refer to the language-specific MongoDB driver documentation.
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
Necessity
Type
Description
verbose
Optional
String
Determines the amount of information to include in the explain output. The possible verbosity modes are:
allPlansExecution
executionStats
queryPlanner (Default)
For backwards compatibility with earlier versions of 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.
This method is available in deployments hosted in the following environments:
MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud
This command is supported in all MongoDB Atlas clusters. For information on Atlas support for all commands, see Unsupported Commands.
MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB
To use explain, you must have permission to run the underlying command.
Using explain ignores all existing plan cache entries and prevents the MongoDB query planner from creating a new plan cache entry.
The behavior of cursor.explain() and the amount of information returned depend on the verbosity 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.
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.
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() 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 the explain() information on the query plan.
See db.collection.explain() for more information.
cursor.explain() operations can return information regarding:
explainVersion, the output format version (for example, "1").
command, which details the command being explained.
queryShapeHash, starting in MongoDB 8.0, which is a hexadecimal string with the hash of a query shape. For details, see Query Shapes, Query Shape Hash, and explain.queryShapeHash.
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.
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.
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")RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4