Explain a query

Visual Explain draws the server’s plan for a query as a chain of blocks: how the documents are found (a collection scan or an index scan), filtered, sorted and projected, until the Result block. In full mode it also shows how many documents each stage passed on, how long it took and roughly how much data it read. It is the quickest way to spot a missing index or a filter that runs too late.

Explain a find query

1. Open the collection (for example acme_store.orders) and type your query in the query bar, for example { "status": "shipped" } with the sort { "created_at": -1 }. See Query for the query bar.
2. Below the query bar, switch to the Explain tab. The plan is drawn at once. With the Explain tab in front, running the query explains the new one too.
3. Read the diagram from right to left: the first stage is on the right, arrows lead left to Result. A scan points down to a Collection block (acme_store.orders) or an Index block (acme_store.orders.status_1).
4. Click Run full explain (light-bulb icon) for the figures. Stop cancels it, on the server too.

The default (brief) explain does not run the query: it is fast and safe on any collection. Run full explain runs the query to measure it, which can take as long as the query itself.

Explain an aggregation

In the Aggregation Editor, open the Explain tab at the bottom, or press F8 (Explain pipeline). Only the stages that are included are explained. Stages that write ($out, $merge) are never explained, so explaining a pipeline never writes anything; the explained pipeline lists what was left out.

Visual Explain also opens from a query result of IntelliShell (Explain Query) and from the Query Profiler (Explain plan).

Read the figures

A filter applied inside a scan is drawn as its own Filter block, so you can see how many documents were examined (the arrow in) and how many matched (the arrow out). On a sharded cluster, each shard has its own branch with its own figures.

Actions

Tips

• A Collection scan feeding a Filter that keeps few documents is the classic sign of a missing index. Add one (see Manage indexes) and explain again: you should see an Index scan instead.
• A Sort stage after a scan means the sort is done in memory. An index whose order matches the sort removes it.
• Compare the documents examined with the documents returned: a large gap means the index is not selective enough.
• An index hint set in the query is respected by the explain.

Troubleshooting