解释（数据库命令）

定义

explain: explain命令提供有关执行以下命令的信息：aggregate 、count 、distinct 、find 、findAndModify 、、delete mapReduce和update 。
提示
在 mongosh 中，此命令也可通过 db.collection.explain() 和 cursor.explain() 助手方法来运行。
辅助方法对 mongosh 用户来说很方便，但它们返回的信息级别可能与数据库命令不同。如果不需要方便性或需要额外的返回字段，请使用数据库命令。
注意
使用 explain 会忽略所有现有的计划缓存条目，并防止 MongoDB 查询计划器创建新的计划缓存条目。

兼容性

此命令可用于以下环境中托管的部署：

MongoDB Atlas：用于云中 MongoDB 部署的完全托管服务

注意

所有 MongoDB Atlas 集群都支持此命令。有关 Atlas 对所有命令的支持的信息，请参阅不支持的命令。

MongoDB Enterprise：基于订阅、自我管理的 MongoDB 版本
MongoDB Community：源代码可用、免费使用且可自行管理的 MongoDB 版本

必需的访问权限

要使用 explain，您必须有权运行根本的命令。

语法

该命令具有以下语法：

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

命令字段

该命令接受以下字段：

字段	类型	说明
`explain`	文档	指定要返回其执行信息的命令的文档。有关特定命令文档的详细信息，请参阅 `aggregate`、`count`、`distinct`、`find`、`findAndModify`、`delete`、`mapReduce` 和 `update`。
`verbosity`	字符串	可选。一个字符串，指定运行`explain` 的模式。该模式会影响`explain` 的行为并决定要返回的信息量。可能的模式： `"queryPlanner"` `"executionStats"` `"allPlansExecution"` （默认）有关模式的更多信息，请参阅解释行为。
`comment`	any	可选。用户提供的待附加到该命令的注释。设置后，该注释将与该命令的记录一起出现在以下位置： mongod 日志消息，位于 `attr.command.cursor.comment` 字段中。 `command.comment` 字段中的数据库分析器输出。 `currentOp` 输出，在 `command.comment` 字段。注释可以是任何有效的 BSON 类型（字符串、整型、对象、数组等）。如果您指定 `explain` 而不指定 `comment`，它将继承指定给 `explain` 命令中的任何 `comment`。

注意

explain 和 db.collection.explain() 的默认详细程度不同。explain 默认为 allPlansExecution，而 db.collection.explain() 默认为 queryPlanner。

行为

Verbosity 模式

explain的行为和返回的信息量取决于verbosity 模式。

MongoDB运行查询优化器，为正在评估的操作选择获胜计划。返回已评估的explainqueryPlanner 的<command> 信息。

MongoDB 运行查询优化器来选择获胜计划并执行获胜计划直至完成，并返回描述获胜计划执行情况的统计信息。

对于写入操作，explain 会返回有关将执行的更新或删除操作的信息，但不会将修改应用数据库。

explain 返回已评估的 <command> 的 queryPlanner 和 executionStats 信息。但是，executionStats 并未提供被拒绝计划的查询执行信息。

默认下，explain 在"allPlansExecution" 详细模式下运行。

MongoDB 运行查询优化器来选择优胜计划并执行该计划直至完成。在 "allPlansExecution" 模式下，MongoDB 返回描述优胜计划执行情况的统计信息以及在计划选择期间捕获的其他候选计划的统计信息。

对于写入操作，explain 会返回有关将执行的更新或删除操作的信息，但不会将修改应用数据库。

explain返回已评估的queryPlanner 和executionStats <command>信息。executionStats 包括获胜计划的已完成查询执行信息。

如果查询优化器考虑了多个计划，executionStats 信息则还包括在计划选择阶段为获胜和被拒计划收集的部分执行信息。

解释和写入操作

对于写入操作，explain 命令会返回将要执行的写入操作的相关信息，但不会实际修改数据库。

Stable API

稳定的 API 版本 1 支持 explain 命令的以下详细模式：

allPlansExecution
executionStats
查询规划器

警告

MongoDB不保证命令的任何特定输出格式，即使使用 Stableexplain API时也是如此。

限制

对于包含阶段的 aggregation pipelineexplaindb.collection.explain()，无法在executionStats 模式或allPlansExecution$out 模式下运行命令/ 。相反，您可以：

在 queryPlanner 模式下运行 explain，或者
在 executionStats模式或 allPlansExecution 模式下运行解释，但排除 $out 阶段，以返回 $out 阶段之前的阶段信息。

输出

explain 操作可以返回以下信息：

explainVersion，输出格式版本（例如 "1"）。
command，其中详细说明了要解释的命令。
queryShapeHash，从MongoDB 8.0 开始，是一个十六进制 string，具有查询结构的哈希值。有关详情，请参阅查询结构、查询结构哈希和 explain.queryShapeHash。
queryPlanner，其详细说明了查询优化器选择的计划，并列出了被拒绝的计划。
executionStats，其中详细说明了获胜计划的执行情况以及被拒计划。
serverInfo，提供有关 MongoDB 实例的信息。
serverParameters，其中详细说明了内部参数。

详细模式（例如 queryPlanner、executionStats、allPlansExecution ）决定了结果是否包括 executionStats，以及 executionStats 是否包括计划选择期间捕获的数据。

解释输出会受到 BSON 文档的最大嵌套深度的限制，即 100 级嵌套。解释超出限制的输出会被截断。

有关输出的详细信息，请参阅解释结果。

示例

`queryPlanner` 模式

以下explain 命令在"queryPlanner" 详细模式下运行，返回count 命令的查询计划信息：

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

`executionStats` 模式

以下 explain 操作在 "executionStats" 详细程度模式下运行，以返回 count 命令的查询计划和执行信息：

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

`allPlansExecution` 模式

默认下，explain 以"allPlansExecution" 详细模式运行。以下explain 命令会返回命令的所有考虑计划的和queryPlanner executionStatsupdate：

注意

执行该解释不会修改数据，但会运行更新操作的查询谓词。对于候选计划，MongoDB 会返回在计划选择阶段捕获的执行信息。

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