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.explain命令提供了以下命令的执行信息：aggregate、count、distinct、find、findAndModify、delete、mapReduce和update。

Although MongoDB provides the explain command, the preferred method for running explain is to use the db.collection.explain() and cursor.explain() helpers.尽管MongoDB提供了explain命令，但运行explain的首选方法是使用db.collection.explain()和cursor.explain()。

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

{
   explain: <command>,
   verbosity: <string>,
   comment: <any>
}

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. 有关特定命令文档的详细信息，请参阅aggregate、count、distinct、find、findAndModify、delete、mapReduce和update。
verbositystring

Optional. 可选。A string specifying the mode in which to run explain. 指定运行explain的模式的字符串。The mode affects the behavior of explain and determines the amount of information to return.该模式影响explain行为并决定要返回的信息量。

The possible modes are:可能的模式有：

  • "queryPlanner"
  • "executionStats"
  • "allPlansExecution" (Default)

For more information on the modes, see explain behavior.有关模式的详细信息，请参阅解释行为。

commentany

Optional. 可选。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.如果指定explain而没有comment，它将继承指定explain的命令中的任何comment。

Behavior行为

Verbosity Modes详细模式

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

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>.返回已求值<command>的queryPlanner信息。

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>. explain返回已求值<command>的queryPlanner和executionStats信息。However, executionStats does not provide query execution information for the rejected plans.但是，executionStats不提供被拒绝计划的查询执行信息。

By default, explain runs in "allPlansExecution" verbosity mode.默认情况下，explain以"allPlansExecution"详细模式运行。

MongoDB runs the query optimizer to choose the winning plan and executes the winning plan to completion. MongoDB运行查询优化器来选择获胜计划，并执行获胜计划直至完成。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.在"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>. explain返回已求值<command>的queryPlanner和executionStats信息。The executionStats includes the completed query execution information for the winning plan.executionStats包括获胜计划的已完成查询执行信息。

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.如果查询优化器考虑了多个计划，executionStats信息还包括在计划选择阶段为获胜和被拒绝的候选计划捕获的部分执行信息。

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.对于写操作，explain命令返回有关将要执行但实际上不修改数据库的写操作的信息。

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. 从MongoDB 4.2开始，对于包含$out阶段的聚合管道，不能在executionStats模式或allPlansExecution模式下运行explain命令/db.collection.explain()。Instead, you can either:相反，您可以：

  • run the explain in queryPlanner mode or在queryPlanner模式或
  • 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.在executionStats模式或allPlansExecution模式下运行解释，但不使用$out阶段，以返回$out阶段之前的阶段的信息。

Output输出

explain operations can return information regarding:操作可以返回以下信息：

  • explainVersion, the output format version (for example, "1");，输出格式版本（例如，“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，提供MongoDB实例的信息；和
  • 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.详细模式（即queryPlanner、executionStats、allPlansExecution）确定结果是否包括executionStats以及executionStats是否包括在计划选择期间捕获的数据。

Explain output is limited by the maximum Nested Depth for BSON Documents, which is 100 levels of nesting. 解释输出受限于BSON文档的最大嵌套深度，即100层嵌套。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:以下explain命令以"queryPlanner"详细模式运行，以返回count命令的查询计划信息：

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:以下explain操作以"executionStats"详细模式运行，以返回count命令的查询计划和执行信息：

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

allPlansExecution Mode

By default, explain runs in "allPlansExecution" verbosity mode. 默认情况下，explain以"allPlansExecution"详细模式运行。The following explain command returns the queryPlanner and executionStats for all considered plans for an update command:以下explain命令返回更新命令的所有考虑计划的queryPlanner和executionStats：

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 } }
           }
        ]
     }
   }
)
←  driverOIDTestfeatures →