Docs Home → MongoDB Manual

explain

On this page本页内容

Definition定义

explain

The explain command provides information on the execution of the following commands: aggregate, count, distinct, find, findAndModify, delete, mapReduce, and update.

Tip

In mongosh, this command can also be run through the db.collection.explain() and cursor.explain() helper methods.

Helper methods are convenient for mongosh users, but they may not return the same level of information as database commands. In cases where the convenience is not needed or the additional return fields are required, use the database command.

Syntax语法

The command has the following syntax:该命令具有以下语法：

db.runCommand(
   {
     explain: <command>,
     verbosity: <string>,
     comment: <any>
   }
)

Command Fields命令字段

The command takes the following fields:该命令包含以下字段：

Field字段Type类型Description描述
explaindocumentA document specifying the command for which to return the execution information. 指定返回执行信息的命令的文档。For details on the specific command document, see aggregate, count, distinct, find, findAndModify, delete, mapReduce, and update.
verbositystringOptional.可选的。A string specifying the mode in which to run explain. The mode affects the behavior of explain and determines the amount of information to return.指定运行explain的模式的字符串。该模式影响explain的行为，并决定返回的信息量。
The possible modes are: 可能的模式有：
  • "queryPlanner"
  • "executionStats"
  • "allPlansExecution" (Default)
For more information on the modes, see explain behavior. 有关模式的详细信息，请参阅解释行为。
commentanyOptional.可选的。
A user-provided comment to attach to this command. Once set, this comment appears alongside records of this command in the following locations: 要附加到此命令的用户提供的注释。设置后，此注释将与此命令的记录一起显示在以下位置： A comment can be any valid BSON type (string, integer, object, array, etc). 注释可以是任何有效的BSON类型（字符串、整数、对象、数组等）。
Note
If you specify explain without a comment, it inherits any comment in the command specified to explain.

Behavior行为

Verbosity Modes详细模式

The behavior of explain and the amount of information returned depend on the verbosity mode.explain的行为和返回的信息量取决于详细程度模式。

queryPlanner Mode模式executionStats Mode模式allPlansExecution Mode (Default)模式（默认）

MongoDB runs the query optimizer to choose the winning plan for the operation under evaluation. MongoDB运行查询优化器来为正在评估的操作选择获胜计划。explain returns the queryPlanner information for the evaluated <command>.

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.MongoDB运行查询优化器来选择获胜计划，执行获胜计划直到完成，并返回描述获胜计划执行情况的统计信息。

For write operations, explain returns information about the update or delete operations that would be performed, but does not apply the modifications to the database.对于写入操作，explain返回有关将要执行的更新或删除操作的信息，但不将修改应用于数据库。

explain returns the queryPlanner and executionStats information for the evaluated <command>. However, executionStats does not provide query execution information for the rejected plans.

By default, explain runs in "allPlansExecution" verbosity mode.

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.MongoDB运行查询优化器来选择获胜计划，并执行获胜计划直至完成。在"allPlansExecution"模式下，MongoDB返回描述获胜计划执行情况的统计信息，以及在计划选择过程中捕获的其他候选计划的统计信息。

For write operations, explain returns information about the update or delete operations that would be performed, but does not apply the modifications to the database.对于写入操作，explain返回有关将要执行的更新或删除操作的信息，但不将修改应用于数据库。

explain returns the queryPlanner and executionStats information for the evaluated <command>. 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.

Explain and Write Operations解释和编写操作

For write operations, the explain command 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.

Output输出

explain operations can return information regarding:操作可以返回关于以下内容的信息：

  • explainVersion, the output format version (for example, "1");
  • command, which details the command being explained;
  • 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; and
  • 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.

Examples实例

queryPlanner Mode

The following explain command runs in "queryPlanner" verbosity mode to return the query planning information for a count command:

db.runCommand(
   {
     explain: { count: "products", query: { quantity: { $gt: 50 } } },
     verbosity: "queryPlanner"
   }
)

executionStats Mode

The following explain operation runs in "executionStats" verbosity mode to return the query planning and execution information for a count command:

db.runCommand(
   {
      explain: { count: "products", query: { quantity: { $gt: 50 } } },
      verbosity: "executionStats"
   }
)

allPlansExecution Mode

By default, explain runs in "allPlansExecution" verbosity mode. The following explain command returns the queryPlanner and executionStats for all considered plans for an update command:

Note

The execution of this explain will not modify data but runs the query predicate of the update operation. For candidate plans, MongoDB returns the execution information captured during the plan selection phase.执行此解释不会修改数据，而是运行更新操作的查询谓词。对于候选计划，MongoDB返回在计划选择阶段捕获的执行信息。

db.runCommand(
   {
     explain: {
        update: "products",
        updates: [
           {
               q: { quantity: 1057, category: "apparel" },
               u: { $set: { reorder: true } }
           }
        ]
     }
   }
)