Docs Menu

Docs HomeLaunch & Manage MongoDBMongoDB Atlas

Retrieve Query Plan and Execution Statistics

On this page

  • Syntax
  • Verbosity
  • Explain Response
  • Limitations
  • Examples
  • queryPlanner
  • executionStats

Important

You can run Atlas Search queries with explain in mongosh. However, this feature is not available for MongoDB Compass.

The Atlas Search query returns information about the $search query plan and execution statistics when the query is run with the explain method. When you run a query with explain, Atlas Search returns a BSON document containing information about how the query was run.

Tip

See also:

db.<myCollection>.explain("<verbosity>").aggregate([
{
$search: {
"<operator>": {
"<operator-options>"
}
}
}
])

Verbosity mode controls the behavior of explain and the amount of information returned. Value can be one of the following:

queryPlanner (default)
Information about the query plan. Does not include the stats field, which contains execution statistics for the query.
Information about the query plan including the stats field, which contains execution statistics for the query.
Information about the query plan including the stats field, which contains execution statistics for the query.

Tip

See also:

The explain response is a BSON document with keys and values describing the execution statistics for the query. The explain document in the result set contains the following fields:

Option
Type
Necessity
Purpose
path
string
Optional
Path to the operator, only if it isn't the root.
type
string
Required
Name of the Lucene Query that the Atlas Search operator created. See Lucene Query Structured Summary for more information.
analyzer
string
Optional
Atlas Search analyzer used with the query.
args
document
Required
Lucene query information. See Lucene Query Structured Summary for more information.
stats
document
Optional
Explain Timing Breakdown for the query if explain ran with executionStats or allPlansExecution verbosity.

You can't run facet queries with explain.

The following examples use the movies collection in the sample_mflix database.

Tip

If you've already loaded the sample dataset, follow the Get Started with Atlas Search tutorial to create an index definition and run Atlas Search queries.

The following example uses the text operator to query the title field with the queryPlanner verbosity mode.

db.movies.explain("queryPlanner").aggregate([
{
$search: {
"text": {
"path": "title",
"query": "yark",
"fuzzy": {
"maxEdits": 1,
"maxExpansions": 100,
}
}
}
}
])

The query returns the following results. To learn more about the explain response elements, see Explain Response.

{
"stages" : [
{
"$_internalSearchMongotRemote" : {
"mongotQuery" : {
"text" : {
"path" : "title",
"query" : "yark",
"fuzzy" : {
"maxEdits" : 1,
"maxExpansions" : 100
}
}
},
"explain" : {
"type" : "BooleanQuery",
"args" : {
"must" : [ ],
"mustNot" : [ ],
"should" : [
{
"type" : "BoostQuery",
"args" : {
"query" : {
"type" : "TermQuery",
"args" : {
"path" : "title",
"value" : "ark"
}
},
"boost" : 0.6666666269302368
}
},
{
"type" : "BoostQuery",
"args" : {
"query" : {
"type" : "TermQuery",
"args" : {
"path" : "title",
"value" : "yard"
}
},
"boost" : 0.75
}
},
{
"type" : "BoostQuery",
"args" : {
"query" : {
"type" : "TermQuery",
"args" : {
"path" : "title",
"value" : "mark"
}
},
"boost" : 0.75
}
},
{
"type" : "BoostQuery",
"args" : {
"query" : {
"type" : "TermQuery",
"args" : {
"path" : "title",
"value" : "park"
}
},
"boost" : 0.75
}
},
{
"type" : "BoostQuery",
"args" : {
"query" : {
"type" : "TermQuery",
"args" : {
"path" : "title",
"value" : "dark"
}
},
"boost" : 0.75
}
},
{
"type" : "BoostQuery",
"args" : {
"query" : {
"type" : "TermQuery",
"args" : {
"path" : "title",
"value" : "york"
}
},
"boost" : 0.75
}
}
],
"filter" : [ ],
"minimumShouldMatch" : 0
}
}
}
},
{
"$_internalSearchIdLookup" : { }
}
],
"serverInfo" : {
"host" : "atlas-example-shard-00-01.mongodb.net",
"port" : 27017,
"version" : "4.4.3",
"gitVersion" : "913d6b62acfbb344dde1b116f4161360acd8fd13"
},
"ok" : 1,
"$clusterTime" : {
"clusterTime" : Timestamp(1612457287, 1),
"signature" : {
"hash" : BinData(0,"kzn7hY7NOduVIqcfx+40ENKbMKQ="),
"keyId" : NumberLong("1234567890123456789")
}
},
"operationTime" : Timestamp(1612457287, 1)
}

For queries that specify a $limit stage in the pipeline, the explain results include the mongotDocsRequested metric, which shows the number of documents that mongod requested from mongot.

Example

{
"mongotQuery": {},
"explain": {},
"limit": <int>,
"sortSpec": {},
"mongotDocsRequested": <int>,
}

The following example uses the autocomplete operator to query the title field with the executionStats verbosity mode.

db.movies.explain("executionStats").aggregate([
{
"$search": {
"autocomplete": {
"path": "title",
"query": "pre",
"fuzzy": {
"maxEdits": 1,
"prefixLength": 1,
"maxExpansions": 256
}
}
}
}
])

The query returns the following results. To learn more about the explain response elements, see Explain Response.

{
"stages" : [
{
"$_internalSearchMongotRemote" : {
"mongotQuery" : {
"autocomplete" : {
"path" : "title",
"query" : "pre",
"fuzzy" : {
"maxEdits" : 1,
"prefixLength" : 1,
"maxExpansions" : 256
}
}
},
"explain" : {
"type" : "MultiTermQueryConstantScoreWrapper",
"args" : {
"queries" : [
{
"type" : "DefaultQuery",
"args" : {
"queryType" : "AutomatonQuery"
},
"stats" : {
"context" : {
"millisElapsed" : NumberDouble(0)
},
"match" : {
"millisElapsed" : NumberDouble(0)
},
"score" : {
"millisElapsed" : NumberDouble(0)
}
}
}
]
},
"stats" : {
"context" : {
"millisElapsed" : NumberDouble(0.816418),
"invocationCounts" : {
"createWeight" : NumberLong(1),
"createScorer" : NumberLong(2)
}
},
"match" : {
"millisElapsed" : NumberDouble(3.849778),
"invocationCounts" : {
"nextDoc" : NumberLong(656)
}
},
"score" : {
"millisElapsed" : NumberDouble(0.035349),
"invocationCounts" : {
"score" : NumberLong(655)
}
}
}
}
},
"nReturned" : NumberLong(0),
"executionTimeMillisEstimate" : NumberLong(20)
},
{
"$_internalSearchIdLookup" : { },
"nReturned" : NumberLong(0),
"executionTimeMillisEstimate" : NumberLong(20)
}
],
"serverInfo" : {
"host" : "atlas-example-shard-00-01.mongodb.net",
"port" : 27017,
"version" : "4.4.3",
"gitVersion" : "913d6b62acfbb344dde1b116f4161360acd8fd13"
},
"ok" : 1,
"$clusterTime" : {
"clusterTime" : Timestamp(1612454116, 1),
"signature" : {
"hash" : BinData(0,"OY+SMPmdK//g6rFZkvSCQr3c3hM="),
"keyId" : NumberLong("1234567890123456789")
}
},
"operationTime" : Timestamp(1612454116, 1)
}
←  Run Atlas Search QueriesLucene Query Structured Summary →