$planCacheStats

定义

$planCacheStats

返回集合的计划缓存信息。该阶段为每个计划缓存条目返回一个文档。

$planCacheStats 阶段必须是管道中的第一阶段。该阶段以空文档作为参数，其语法如下：

{ $planCacheStats: { } }

提示

查询计划

Considerations

管道

$planCacheStats 必须是聚合管道的第一阶段。

限制

$planCacheStats 不允许：
- 事务
- $facet 聚合阶段
$planCacheStats 需要读关注（read concern）级别"local" 。

访问控制

在使用 authorization 运行的系统上，用户必须具有该集合的 planCacheRead 权限。

日志校订

使用 Queryable Encryption 时， $planCacheStats 阶段会省略针对加密集合的操作，即使这些操作被正常缓存。

读取偏好

$planCacheStats 在选择要从中返回计划缓存信息的主机时观察读取偏好（read preference）。

应用程序可能针对副本集的不同节点。因此，每个副本集节点可能会接收不同的读取命令，并具有与其他节点不同的计划缓存信息。但是，在副本集或分片集群上运行 $planCacheStats 遵循正常的读取偏好规则。换言之，在副本集上，该操作仅从副本集的一个节点收集计划缓存信息，而在分片集群上，该操作仅从每个分片副本集的一个节点收集计划缓存信息。

输出

在版本7.0中进行了更改。

$planCacheStats 的输出取决于用于完成查询的查询引擎。$planCacheStats 的 version 字段的值指示使用了哪个查询引擎：

1 指示使用了经典引擎。
2 表示使用了基于槽位的查询执行引擎。

注意

从版本 7.0.17 开始，对于补丁版本的 7.0，默认不再启用基于插槽的查询执行引擎。如果您希望查询使用基于插槽的查询执行引擎，请升级到版本 8.0，默认下处于启用状态。

对于使用经典执行引擎的查询， $planCacheStats会返回类似于以下内容的文档：

{   "version" : 1,   "createdFromQuery" : <document>,   "queryHash" : <hexadecimal string>,   "planCacheKey" : <hexadecimal string>,   "isActive" :  <boolean>,   "works" : <NumberLong>,   "cachedPlan" : {      "stage" : <STAGE1>,      "filter" : <document>,      "inputStage" : {         "stage" : <STAGE2>,         ...      }   },   "timeOfCreation" : <date>,   "creationExecStats" : [   // Exec Stats Document for each candidate plan      {         "nReturned" : <num>,         "executionTimeMillisEstimate" : <num>,         "totalKeysExamined" : <num>,         "totalDocsExamined" :<num>,         "executionStages" : {            "stage" : <STAGE A>,            ...            "inputStage" : {               "stage" : <STAGE B>,               ...            }         }      },      ...   ],   "candidatePlanScores" : [      <number>,      ...   ],   "indexFilterSet" : <boolean>,   "estimatedSizeBytes" : <num>,   "host" : <string>,   "shard" : <string>}

每个文档都包含各种查询计划和执行统计信息，包括：

字段	说明
`version`	指示用于完成查询的查询引擎的数字。 `1` 指示使用了经典引擎。 `2` 表示使用了基于槽位的查询执行引擎。
`createdFromQuery`	包含生成此缓存条目的特定查询的文档。例如： `{ "query" : <document>, "sort" : <document>, "projection" : <document>}`
`isActive`	表示条目处于活跃还是非活跃状态的布尔值。如果处于活动状态，则查询规划器当前使用该条目生成查询计划。如果处于非活动状态，则查询规划器当前没有使用该条目来生成查询计划。查看规划缓存条目状态。
`queryHash`	string表示查询结构的哈希值的十六进制。请参阅`explain.queryPlanner.queryHash` 。
`planCacheKey`	一个十六进制string ，表示用于查找与此查询关联的计划缓存条目的键的哈希值。计划缓存键是查询结构和该结构当前可用索引的函数。请参阅`explain.queryPlanner.planCacheKey` 。
`cachedPlan`	已缓存计划的详细信息。 `cachedPlan`中包含的字段因查询是使用经典引擎还是基于插槽的查询执行引擎完成而异。有关查询计划的详细信息，请参阅`explain.queryPlanner` 。
`works`	在查询规划器评估候选计划的试用期内，查询执行计划执行的“工作单元”数量。有关更多信息，请参阅`explain.executionStats.executionStages.works` 。
`timeOfCreation`	创建条目的时间。
`creationExecStats`	执行统计文档的数组。该数组包含每个候选计划的文档。有关执行统计的详细信息，请参阅 `explain.executionStats`。
`candidatePlanScores`	`creationExecStats` 数组中列出的候选计划的得分数组。
`indexFilterSet`	一个布尔值，表示查询结构是否存在索引过滤。
`estimatedSizeBytes`	计划缓存条目的估计大小（以字节为单位）。
`host`	返回计划缓存信息的 `mongod` 实例的主机名和端口。在分分片集群上运行时，该操作会从每个分分片副本集的单个成员返回计划缓存条目信息。该成员通过分分片和托管字段进行标识。另请参阅日志校订。
`shard`	`$planCacheStats` 从中检索缓存条目的分片的名称。仅当在分片集群上运行时才可用。

对于使用基于槽的查询执行引擎的查询， $planCacheStats会返回类似于以下内容的文档：

{   "version" : 2,   "queryHash" : <hexadecimal string>,   "planCacheKey" : <hexadecimal string>,   "isActive" :  <boolean>,   "works" : <NumberLong>,   "cachedPlan" : {      "slots" : <string>,      "stages": <string>   },   "indexFilterSet" : <boolean>,   "estimatedSizeBytes" : <num>,   "host" : <string>}

每个文档都包含各种查询计划和执行统计信息，包括：

字段	说明
`version`	指示用于完成查询的查询引擎的数字。 `1` 指示使用了经典引擎。 `2` 表示使用了基于槽位的查询执行引擎。
`queryHash`	string表示查询结构的哈希值的十六进制。请参阅`explain.queryPlanner.queryHash` 。
`planCacheKey`	一个十六进制string ，表示用于查找与此查询关联的计划缓存条目的键的哈希值。计划缓存键是查询结构和该结构当前可用索引的函数。请参阅`explain.queryPlanner.planCacheKey` 。
`isActive`	表示条目处于活跃还是非活跃状态的布尔值。如果处于活动状态，则查询规划器当前使用该条目生成查询计划。如果处于非活动状态，则查询规划器当前没有使用该条目来生成查询计划。查看规划缓存条目状态。
`works`	在查询规划器评估候选计划的试用期内，查询执行计划执行的“工作单元”数量。有关更多信息，请参阅`explain.executionStats.executionStages.works` 。
`cachedPlan`	已缓存计划的详细信息。 `cachedPlan`中包含的字段因查询是使用经典引擎还是基于插槽的查询执行引擎完成而异。有关查询计划的详细信息，请参阅`explain.queryPlanner` 。
`indexFilterSet`	一个布尔值，表示查询结构是否存在索引过滤。
`estimatedSizeBytes`	计划缓存条目的估计大小（以字节为单位）。
`host`	返回计划缓存信息的 `mongod` 实例的主机名和端口。在分分片集群上运行时，该操作会从每个分分片副本集的单个成员返回计划缓存条目信息。该成员通过分分片和托管字段进行标识。另请参阅日志校订。

示例

本部分中的示例使用以下 orders 集合：

db.orders.insertMany( [    { "_id" : 1, "item" : "abc", "price" : Decimal128("12"), "quantity" : 2, "type": "apparel" },    { "_id" : 2, "item" : "jkl", "price" : Decimal128("20"), "quantity" : 1, "type": "electronics" },    { "_id" : 3, "item" : "abc", "price" : Decimal128("10"), "quantity" : 5, "type": "apparel" },    { "_id" : 4, "item" : "abc", "price" : Decimal128("8"), "quantity" : 10, "type": "apparel" },    { "_id" : 5, "item" : "jkl", "price" : Decimal128("15"), "quantity" : 15, "type": "electronics" }] )

在集合上创建以下索引：

db.orders.createIndex( { item: 1 } );db.orders.createIndex( { item: 1, quantity: 1 } );db.orders.createIndex( { quantity: 1 } );db.orders.createIndex( { quantity: 1, type: 1 } );db.orders.createIndex(    { item: 1, price: 1 },    { partialFilterExpression: { price: { $gte: Decimal128("10")} } });

注意

索引 { item: 1, price: 1 } 是部分索引，仅索引 price 字段大于或等于 Decimal128("10") 的文档。

对集合运行一些查询：

db.orders.find( { item: "abc", price: { $gte: Decimal128("10") } } )db.orders.find( { item: "abc", price: { $gte: Decimal128("5") } } )db.orders.find( { quantity: { $gte: 20 } } )db.orders.find( { quantity: { $gte: 5 }, type: "apparel" } )

前面的查询是使用基于插槽的查询执行引擎完成的。

返回查询缓存中所有条目的信息

以下聚合管道使用 $planCacheStats 返回有关集合的计划缓存条目的信息：

db.orders.aggregate( [    { $planCacheStats: { } }] )

输出：

[  {                                             // Plan Cache Entry 1    version: '2',    planCacheShapeHash: '478AD696',    planCacheKey: '21AE23AD',    isActive: true,    works: Long("7"),    timeOfCreation: ISODate("2023-05-22T20:33:49.031Z"),    cachedPlan: {      ...    },    indexFilterSet: false,    isPinned: false,    estimatedSizeBytes: Long("8194"),    host: 'mongodb1.example.net:27018'  },  {                                             // Plan Cache Entry 2        version: '2',        planCacheShapeHash: '3D8AFDC6',        planCacheKey: '1C2C4360',        isActive: true,        works: Long("6"),        timeOfCreation: ISODate("2023-05-22T20:33:50.584Z"),        cachedPlan: {          ...        },        indexFilterSet: false,        isPinned: false,        estimatedSizeBytes: Long("11547"),        host: 'mongodb1.example.net:27018'      },      {                                          // Plan Cache Entry 3        version: '2',        planCacheShapeHash: '27285F9B',        planCacheKey: '20BB9404',        isActive: true,        works: Long("1"),        timeOfCreation: ISODate("2023-05-22T20:33:49.051Z"),        cachedPlan: {          ...        },        indexFilterSet: false,        isPinned: false,        estimatedSizeBytes: Long("7406"),        host: 'mongodb1.example.net:27018'      },      {                                          // Plan Cache Entry 4        version: '2',        planCacheShapeHash: '478AD696',        planCacheKey: 'B1435201',        isActive: true,        works: Long("5"),        timeOfCreation: ISODate("2023-05-22T20:33:49.009Z"),        cachedPlan: {          ...        },        indexFilterSet: false,        isPinned: false,        estimatedSizeBytes: Long("7415"),        host: 'mongodb1.example.net:27018'      }

另请参阅 planCacheKey 。

查找查询哈希的缓存条目详细信息

要返回特定查询哈希的计划缓存信息，可以在$planCacheStats阶段之后跟上针对planCacheKey字段的$match 。

下面的聚合管道使用 $planCacheStats 和 $match 阶段来返回特定查询哈希值的特定信息：

db.orders.aggregate( [    { $planCacheStats: { } },    { $match: { planCacheKey: "B1435201"} }] )

输出：

[  {    version: '2',    planCacheShapeHash: '478AD696',    planCacheKey: 'B1435201',    isActive: true,    works: Long("5"),    timeOfCreation: ISODate("2023-05-22T20:33:49.009Z"),    cachedPlan: {      slots: '$$RESULT=s11 env: { s3 = 1684787629009 (NOW), s6 = Nothing, s5 = Nothing, s1 = TimeZoneDatabase(Asia/Kuwait...Etc/UCT) (timeZoneDB), s10 = {"item" : 1, "price" : 1}, s2 = Nothing (SEARCH_META) }',      stages: '[2] nlj inner [] [s4, s7, s8, s9, s10] \n' +        '    left \n' +        '        [1] cfilter {(exists(s5) && exists(s6))} \n' +        '        [1] ixseek s5 s6 s9 s4 s7 s8 [] @"358822b7-c129-47b7-ad7f-40017a51b03c" @"item_1_price_1" true \n' +        '    right \n' +        '        [2] limit 1 \n' +        '        [2] seek s4 s11 s12 s7 s8 s9 s10 none none [] @"358822b7-c129-47b7-ad7f-40017a51b03c" true false \n'    },    indexFilterSet: false,    isPinned: false,    estimatedSizeBytes: Long("7415"),    host: 'mongodb1.example.net:27018'  }]

另请参见 planCacheKey 和 queryHash。

要使用MongoDB Node.js驱动程序将 $planCacheStats 阶段添加到聚合管道，请在管道对象中使用 $planCacheStats操作符。

返回查询缓存中所有条目的信息

以下示例创建了一个管道阶段，该阶段返回有关集合的计划缓存条目的信息。然后，该示例运行聚合管道：

const pipeline = [{ $planCacheStats: {} }];
const cursor = collection.aggregate(pipeline);return cursor;

查找查询哈希的缓存条目详细信息

要返回特定查询哈希的计划缓存信息，请包含一个 $match 阶段，用于检查 planCacheKey字段中的特定查询哈希。

以下示例创建一个管道，返回查询哈希值 "B1435201" 的信息。然后，该示例运行聚合管道：

const pipeline = [ $planCacheStats: {} },  { $match: { planCacheKey: "B1435201"} }];
const cursor = collection.aggregate(pipeline);return cursor;