Navigation
This version of the documentation is archived and no longer supported.

cursor.explain()

cursor.explain()

The cursor.explain() method provides information on the query plan. The query plan is the plan the server uses to find the matches for a query. This information may be useful when optimizing a query.

Parameters:
  • verbose (boolean) – Specifies the level of detail to include in the output. If true or 1, include the allPlans and oldPlan fields in the output document.
Returns:

A document that describes the process used to return the query results.

Retrieve the query plan by appending explain() to a find() query, as in the following example:

db.products.find().explain()

For details on the output, see Explain Output.

explain runs the actual query to determine the result. Although there are some differences between running the query with explain and running without, generally, the performance will be similar between the two. So, if the query is slow, the explain operation is also slow.

Additionally, the explain operation reevaluates a set of candidate query plans, which may cause the explain operation to perform differently than a normal query. As a result, these operations generally provide an accurate account of how MongoDB would perform the query, but do not reflect the length of these queries.

To determine the performance of a particular index, you can use hint() and in conjunction with explain(), as in the following example:

db.products.find().hint( { type: 1 } ).explain()

When you run explain with hint(), the query optimizer does not reevaluate the query plans.

Note

In some situations, the explain() operation may differ from the actual query plan used by MongoDB in a normal query.

The explain() operation evaluates the set of query plans and reports on the winning plan for the query. In normal operations the query optimizer caches winning query plans and uses them for similar related queries in the future. As a result MongoDB may sometimes select query plans from the cache that are different from the plan displayed using explain.

See also