文档菜单
文档首页
/
MongoDB 手册
/
聚合操作
/
参考
/
阶段

$planCacheStats

本页

  • 定义
  • 考虑因素
  • 管道
  • 限制
  • 访问控制
  • 编辑
  • 读取偏好
  • 输出
  • 示例
  • 查询缓存中所有条目的返回信息
  • 为查询哈希查找缓存条目详情

定义

$planCacheStats

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

$planCacheStats阶段必须是管道中的第一个阶段。该阶段具有以下语法

{
   $planCacheStats: {
      allHosts: <boolean>
   }
}

$planCacheStats聚合阶段具有以下选项

选项
描述
allHosts

配置如何将$planCacheStats聚合阶段的目标节点定位在分片集群中。

  • 如果 true，mongos 将 $planCacheStats 聚合阶段广播到所有节点（主节点和从节点），每个受影响的分片都包含目标集合的一个或多个块。

  • 如果 false，则 $planCacheStats 聚合阶段遵循 读取偏好，并且只从目标副本集主节点检索计划缓存。

如果将 allHosts 设置为 true，副本集和独立服务器在解析管道时将返回错误。此选项仅适用于分片集群。

默认值：false

新功能在版本中7.1.

提示

另请参阅

查询计划

注意事项

管道

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

限制

访问控制

在启用了 authorization 的系统上，用户必须对集合拥有 planCacheRead 权限。

红action

当使用 可查询加密 时，$planCacheStats 阶段会省略对加密集合的操作，尽管操作被正常缓存。

读取偏好

当 allHosts 选项设置为 false 时，$planCacheStats 会遵循 读取偏好，从选择主机（群）返回计划缓存信息。

应用程序可能针对复制集的不同成员。因此，每个复制集成员可能会收到不同的读取命令，并且计划缓存信息可能与其他成员不同。尽管如此，在复制集或分片集群上运行 $planCacheStats 仍遵循正常的读取偏好规则。也就是说，在复制集上，操作只从复制集的一个成员收集计划缓存信息，在分片集群上，操作只从每个分片副本集的一个成员收集计划缓存信息。

输出

已更改在版本中7.0.

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

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

{
   "version" : 1,
   "createdFromQuery" : <document>,
   "planCacheShapeHash" : <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>,
   "querySettings" : <document>,
   "host" : <string>,
   "shard" : <string>
}

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

字段
描述
version

指示用于完成查询的查询引擎的数字。

createdFromQuery

包含导致此缓存条目具体查询的文档。例如

{
  "query" : <document>,
  "sort" : <document>,
  "projection" : <document>
}
isActive

一个布尔值，指示条目是活动状态还是非活动状态。

  • 如果处于活动状态，查询规划器目前正在使用此条目生成查询计划。

  • 如果处于非活动状态，查询规划器目前正在不使用此条目生成查询计划。

参见 计划缓存条目状态。

planCacheShapeHash

代表查询形状的哈希值的十六进制字符串。参见 explain.queryPlanner.planCacheShapeHash。

从MongoDB 8.0开始，现有的queryHash字段重命名为planCacheShapeHash。如果您正在使用早期版本的MongoDB，您将看到queryHash而不是planCacheShapeHash。

planCacheKey

代表用于查找与该查询关联的计划缓存条目的键的哈希值的十六进制字符串。计划缓存键是计划缓存查询形状和该形状当前可用索引的函数。参见 explain.queryPlanner.planCacheKey。

cachedPlan

缓存计划的详细信息。包括在cachedPlan中的字段取决于查询是否使用经典引擎或基于插槽的查询执行引擎完成。有关查询计划更多信息，请参阅explain.queryPlanner。

works

查询执行计划在查询规划器评估候选计划时的试用期间执行的“工作单元”数量。有关更多信息，请参阅explain.executionStats.executionStages.works。

timeOfCreation
条目创建的时间。
creationExecStats

执行状态文档数组。数组包含每个候选计划的文档。

有关执行状态详细信息，请参阅explain.executionStats。

candidatePlanScores

creationExecStats数组中列出的候选计划的分数数组。

indexFilterSet

一个布尔值，指示是否为索引过滤器存在计划缓存查询形状。

estimatedSizeBytes

计划缓存条目估计字节数。

querySettings

新功能在版本中8.0.

包含先前使用setQuerySettings设置的查询设置的文档：

querySettings: {
   indexHints: [ {
      ns: { db: <string>, coll: <string> },
      allowedIndexes: <array>
   }, ... ],
   queryFramework: <string>
}

querySettings字段

字段
类型
描述
indexHints.ns
文档

索引提示的命名空间。

db
字符串
索引提示的数据库名称。
coll
字符串
索引提示的集合名称。
indexHints.allowedIndexes
数组
索引提示的索引数组。有关更多详细信息，请参阅索引和hint()。
queryFramework
字符串

查询框架字符串可以是

host

返回计划缓存信息的mongod实例的主机名和端口号。

在分片集群上运行时，该操作将从每个分片副本集中的单个成员返回计划缓存条目信息。该成员通过分片和主机字段进行识别。另请参阅编辑。

shard

从其中检索$planCacheStats缓存的分片名称。

仅在运行在分片集群上时可用。

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

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

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

字段
描述
version

指示用于完成查询的查询引擎的数字。

planCacheShapeHash

代表查询形状的哈希值的十六进制字符串。参见 explain.queryPlanner.planCacheShapeHash。

从MongoDB 8.0开始，现有的queryHash字段重命名为planCacheShapeHash。如果您正在使用早期版本的MongoDB，您将看到queryHash而不是planCacheShapeHash。

planCacheKey

代表用于查找与该查询关联的计划缓存条目的键的哈希值的十六进制字符串。计划缓存键是计划缓存查询形状和该形状当前可用索引的函数。参见 explain.queryPlanner.planCacheKey。

isActive

一个布尔值，指示条目是活动状态还是非活动状态。

  • 如果处于活动状态，查询规划器目前正在使用此条目生成查询计划。

  • 如果处于非活动状态，查询规划器目前正在不使用此条目生成查询计划。

参见 计划缓存条目状态。

works

查询执行计划在查询规划器评估候选计划时的试用期间执行的“工作单元”数量。有关更多信息，请参阅explain.executionStats.executionStages.works。

cachedPlan

缓存计划的详细信息。包括在cachedPlan中的字段取决于查询是否使用经典引擎或基于插槽的查询执行引擎完成。有关查询计划更多信息，请参阅explain.queryPlanner。

indexFilterSet

一个布尔值，指示是否为索引过滤器存在计划缓存查询形状。

estimatedSizeBytes

计划缓存条目估计字节数。

querySettings

新功能在版本中8.0.

包含先前使用setQuerySettings设置的查询设置的文档：

querySettings: {
   indexHints: [ {
      ns: { db: <string>, coll: <string> },
      allowedIndexes: <array>
   }, ... ],
   queryFramework: <string>
}

querySettings字段

字段
类型
描述
indexHints.ns
文档

索引提示的命名空间。

db
字符串
索引提示的数据库名称。
coll
字符串
索引提示的集合名称。
indexHints.allowedIndexes
数组
索引提示的索引数组。有关更多详细信息，请参阅索引和hint()。
queryFramework
字符串

查询框架字符串可以是

host

返回计划缓存信息的mongod实例的主机名和端口号。

在分片集群上运行时，该操作将从每个分片副本集中的单个成员返回计划缓存条目信息。该成员通过分片和主机字段进行识别。另请参阅编辑。

示例

本节中的示例使用以下orders集合

db.orders.insertMany( [
   { "_id" : 1, "item" : "abc", "price" : NumberDecimal("12"), "quantity" : 2, "type": "apparel" },
   { "_id" : 2, "item" : "jkl", "price" : NumberDecimal("20"), "quantity" : 1, "type": "electronics" },
   { "_id" : 3, "item" : "abc", "price" : NumberDecimal("10"), "quantity" : 5, "type": "apparel" },
   { "_id" : 4, "item" : "abc", "price" : NumberDecimal("8"), "quantity" : 10, "type": "apparel" },
   { "_id" : 5, "item" : "jkl", "price" : NumberDecimal("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: NumberDecimal("10")} } }
);

注意

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

对集合执行一些查询

db.orders.find( { item: "abc", price: { $gte: NumberDecimal("10") } } )
db.orders.find( { item: "abc", price: { $gte: NumberDecimal("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'
     }
   ],

警告

从MongoDB 8.0开始，现有的queryHash字段重命名为planCacheShapeHash。如果您正在使用早期版本的MongoDB，您将看到queryHash而不是planCacheShapeHash。

另请参阅 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'
  }
]

警告

从MongoDB 8.0开始，现有的queryHash字段重命名为planCacheShapeHash。如果您正在使用早期版本的MongoDB，您将看到queryHash而不是planCacheShapeHash。

另请参阅 planCacheKey 和 planCacheShapeHash。

返回

$out

下一页

$project