Docs 菜单
Docs 主页
/
MongoDB Manual
/
聚合操作
/
参考
/
阶段(Stages)

$planCacheStats

在此页面上

  • 定义
  • Considerations
  • 管道
  • 限制
  • 访问控制
  • 日志校订
  • 读取偏好
  • 输出
  • 示例
  • 返回查询缓存中所有条目的信息
  • 查找查询哈希的缓存条目详细信息

定义

$planCacheStats

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

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

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

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

选项
说明
allHosts

配置$planCacheStats聚合阶段如何以分片集群中的节点为目标。

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

  • 如果为false ，则$planCacheStats聚合阶段遵循读取偏好（read preference），仅从目标副本集主节点检索计划缓存。

如果将allHosts设为true ，则副本集和独立运行的实例会在管道解析期间返回错误。该选项仅适用于分片集群。

默认： false

版本 7.1 中的新增内容。

提示

另请参阅：

查询计划

Considerations

管道

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

限制

  • $planCacheStats 不允许：

  • $planCacheStats 需要读关注（read concern）级别"local" 。

访问控制

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

日志校订

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

读取偏好

当allHosts选项设立为false时， $planCacheStats在选择要返回计划缓存信息的托管时会遵循读取偏好（read preference）。

应用程序可能针对副本集的不同节点。因此，每个副本集节点可能会接收不同的读取命令，并具有与其他节点不同的计划缓存信息。但是，在副本集或分片集群上运行 $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

string表示 查询结构 的哈希值的十六进制 。请参阅explain.queryPlanner.planCacheShapeHash 。

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

planCacheKey

一个十六进制string ，表示用于查找与此查询关联的计划缓存条目的键的哈希值。 计划缓存键是计划缓存查询结构和该结构当前可用索引的函数。 请参阅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
字符串

查询框架string可以是：

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

string表示 查询结构 的哈希值的十六进制 。请参阅explain.queryPlanner.planCacheShapeHash 。

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

planCacheKey

一个十六进制string ，表示用于查找与此查询关联的计划缓存条目的键的哈希值。 计划缓存键是计划缓存查询结构和该结构当前可用索引的函数。 请参阅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
字符串

查询框架string可以是：

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