PlanCache.list()

On this page本页内容

Definition定义

PlanCache.list(<pipeline>)

New in version 4.4.在版本4.4中新增。

Returns an array of plan cache entries for a collection.返回集合的计划缓存项数组。

The method is only available from the plan cache object of a specific collection; i.e.该方法仅在特定集合的计划缓存对象中可用；即。

db.collection.getPlanCache().list(<pipeline>)
Parameter参数Type类型Description描述
pipelineArray

Optional. 可选。Aggregation pipeline聚合管道 to filter/process the query shapes.筛选/处理查询形状。

You can run this method from a mongod or mongos instance. 您可以从mongod或mongos实例运行此方法。When run on a sharded cluster, the method returns plan cache entry information from a single member in each shard replica set. 当在分片集群上运行时，该方法从每个分片副本集中的单个成员返回计划缓存条目信息。This member is identified with the shard and host fields. 此成员由shard和host字段标识。See also Read Preference.另请参见读取首选项。

The method PlanCache.list() wraps the $planCacheStats aggregation pipeline. 方法PlanCache.list()包装了$planCacheStats聚合管道。That is,那就是，

db.collection.getPlanCache().list([<stage1>, <stage2>, ...] )

is equivalent to等于

db.collection.aggregate([ <$planCacheStats stage>, <stage1>, <stage2>, ... ]).toArray();

For details on the output, see $planCacheStats output.有关输出的详细信息，请参阅$planCacheStats输出。

Not all queries automatically place a query plan in the cache. 并非所有查询都会自动在缓存中放置查询计划。PlanCache.list() returns an empty array if there are currently no query shapes with cached query plans.如果当前没有具有缓存查询计划的查询形状，则返回空数组。

Tip提示

Consideration注意事项

Restrictions限制

PlanCache.list() is not allowed in transactions.不允许事务中使用。

Query Hash and Query Shapes查询哈希和查询形状

To help identify slow queries with the same query shape, starting in MongoDB 4.2, each query shape is associated with a queryHash. 为了帮助识别具有相同查询形状的慢速查询，从MongoDB 4.2开始，每个查询形状都与一个queryHash相关联。The queryHash is a hexadecimal string that represents a hash of the query shape and is dependent only on the query shape.queryHash是一个十六进制字符串，表示查询形状的哈希，它仅依赖于查询形状。

Note注意

As with any hash function, two different query shapes may result in the same hash value. 与任何哈希函数一样，两个不同的查询形状可能会导致相同的哈希值。However, the occurrence of hash collisions between different query shapes is unlikely.然而，不同查询形状之间不太可能发生哈希冲突。

The query optimizer only caches the plans for those query shapes that can have more than one viable plan.查询优化器只缓存那些可以有多个可行计划的查询形状的计划。

Each entry in the plan cache is associated with a queryHash.计划缓存中的每个条目都与一个queryHash相关联。

Read Preference读取首选项

PlanCache.list() observes the read preference in selecting the host(s) from which to return the plan cache information.在选择要从中返回计划缓存信息的主机时，观察读取首选项。

Applications may target different members of a replica set. 应用程序可能针对副本集的不同成员。As such, each replica set member might receive different read commands and have plan cache information that differs from other members. 因此，每个副本集成员可能接收不同的读取命令，并具有不同于其他成员的计划缓存信息。Nevertheless, running PlanCache.list() on a replica set or a sharded cluster obeys the normal read preference rules. 然而，在副本集或分片集群上运行PlanCache.list()会遵守正常的读取首选项规则。That is, on a replica set, the operation gathers plan cache information from just one member of replica set, and on a sharded cluster, the operation gathers plan cache information from just one member of each shard replica set.也就是说，在副本集上，操作仅从副本集的一个成员集合计划缓存信息，而在分片集群上，操作只从每个分片副本集的其中一个成员采集计划缓存信息。

Required Access所需访问权限

On systems running with authorization, the user must have the planCacheRead privilege for the collection.在使用authorization运行的系统上，用户必须具有集合的planCacheRead权限。

Examples示例

Note注意
  • Not all queries automatically place a query plan in the cache. 并非所有查询都会自动在缓存中放置查询计划。PlanCache.list() returns an empty array if there are currently no query shapes with cached query plans.如果当前没有具有缓存查询计划的查询形状，则返回空数组。
  • For details on the output, see $planCacheStats output.有关输出的详细信息，请参阅$planCacheStats输出。

The examples in this section use the following orders collection:本节中的示例使用以下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" }
] )

Create the following indexes on the collection:在集合上创建以下索引：

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

Index { item: 1, price: 1 } is a partial index and only indexes documents with price field greater than or equal to NumberDecimal("10").索引{ item: 1, price: 1 }是部分索引，仅索引price字段大于或等于NumberDecimal("10")的文档。

Run some queries against the collection:对集合运行一些查询：

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" } )

Return Information for All Entries in the Query Cache返回查询缓存中所有条目的信息

The following returns the query shapes that have cached plans for the orders collection:以下返回已缓存orders集合计划的查询形状：

db.orders.getPlanCache().list()

The method returns an array of the query shapes currently in the cache. 该方法返回缓存中当前查询形状的数组。In the example, the orders collection had cached query plans associated with the following shapes:在该示例中，orders集合缓存了与以下形状关联的查询计划：

[
   {
      "createdFromQuery" : {
         "query" : { "quantity" : { "$gte" : 5 }, "type" : "apparel" },
         "sort" : { },
         "projection" : { }
      },
      "queryHash" : "4D151C4C",
      "planCacheKey" : "DD67E353",
      "isActive" : false,
      "works" : NumberLong(4),
      "cachedPlan" : {
         "stage" : "FETCH",
         "filter" : { "type" : { "$eq" : "apparel" } },
         "inputStage" : {
            "stage" : "IXSCAN",
            "keyPattern" : { "quantity" : 1 },
            "indexName" : "quantity_1",
            "isMultiKey" : false,
            "multiKeyPaths" : { "quantity" : [ ] },
            "isUnique" : false,
            "isSparse" : false,
            "isPartial" : false,
            "indexVersion" : 2,
            "direction" : "forward",
            "indexBounds" : { "quantity" : [ "[5.0, inf.0]" ] }
         }
      },
      "timeOfCreation" : ISODate("2020-02-06T15:57:18.219Z"),
      "creationExecStats" : [
         {
            "nReturned" : 2,
            "executionTimeMillisEstimate" : 0,
            "totalKeysExamined" : 3,
            "totalDocsExamined" : 3,
            "executionStages" : {
               "stage" : "FETCH",
               "filter" : { "type" : { "$eq" : "apparel" } },
               "nReturned" : 2,
               "executionTimeMillisEstimate" : 0,
               "works" : 4,
               ...
            }
         },
         {
            "nReturned" : 2,
            "executionTimeMillisEstimate" : 0,
            "totalKeysExamined" : 3,
            "totalDocsExamined" : 2,
            "executionStages" : {
               "stage" : "FETCH",
               "nReturned" : 2,
               "executionTimeMillisEstimate" : 0,
               "works" : 4,
               ...
            }
         }
      ],
      "candidatePlanScores" : [
         1.5002,
         1.5002
      ],
      "indexFilterSet" : false,
      "estimatedSizeBytes" : NumberLong(3160),   // Available starting in MongoDB 5.0, 4.4.3, 4.2.12, 4.0.23, 3.6.23
      "host" : "mongodb1.example.net:27018",
      "shard" : "shardA"
                         // Available if run on sharded cluster
   },
   {
      "createdFromQuery" : {
         "query" : { "quantity" : { "$gte" : 20 } },
         "sort" : { },
         "projection" : { }
      },
      "queryHash" : "23B19B75",
      "planCacheKey" : "6F23F858",
      "isActive" : false,
      "works" : NumberLong(1),
      ...
   },
   {
      "createdFromQuery" : {
         "query" : { "item" : "abc", "price" : { "$gte" : NumberDecimal("5") } },
         "sort" : { },
         "projection" : { }
      },
      "queryHash" : "117A6B10",
      "planCacheKey" : "A1824628",
      "isActive" : false,
      "works" : NumberLong(4),
      ...
   },
   {
      "createdFromQuery" : {
         "query" : { "item" : "abc", "price" : { "$gte" : NumberDecimal("10") } },
         "sort" : { },
         "projection" : { }
      },
      "queryHash" : "117A6B10",
      "planCacheKey" : "2E6E536B",
      "isActive" : false,
      "works" : NumberLong(3),
      ...
   }
]

For details on the output, see $planCacheStats output.有关输出的详细信息，请参阅$planCacheStats输出。

List Query Shapes列出查询形状

MongoDB 4.4 removes the deprecated planCacheListQueryShapes command and its helper method PlanCache.listQueryShapes().MongoDB 4.4删除了不推荐使用的planCacheListQueryShapes命令及其助手方法planCache.ListQueryShapes()。

As an alternative, you can use the PlanCache.list() to obtain a list of all of the query shapes for which there is a cached plan. 或者，您可以使用PlanCache.list()获取具有缓存计划的所有查询形状的列表。For example, the following operation passes in a pipeline with a $project stage to only output the createdFromQuery field and the queryHash field.例如，以下操作传递到带有$project阶段的管道中，以仅输出createdFromQuery字段和queryHash字段。

db.orders.getPlanCache().list( [ { $project: {createdFromQuery: 1, queryHash: 1 } } ] )

The operation returns the following query shapes:该操作返回以下查询形状：

[
   { "createdFromQuery" : { "query" : { "quantity" : { "$gte" : 5 }, "type" : "apparel" }, "sort" : { }, "projection" : { } }, "queryHash" : "4D151C4C" },
   { "createdFromQuery" : { "query" : { "quantity" : { "$gte" : 20 } }, "sort" : { }, "projection" : { } }, "queryHash" : "23B19B75" },
   { "createdFromQuery" : { "query" : { "item" : "abc", "price" : { "$gte" : NumberDecimal("5") } }, "sort" : { }, "projection" : { } }, "queryHash" : "117A6B10" },
   { "createdFromQuery" : { "query" : { "item" : "abc", "price" : { "$gte" : NumberDecimal("10") } }, "sort" : { }, "projection" : { } }, "queryHash" : "117A6B10" }
]

For details on the output, see $planCacheStats output.有关输出的详细信息，请参阅$planCacheStats输出。

Find Cache Entry Details for a Query Shape查找查询形状的缓存项详细信息

To return plan cache information for a particular query shape, pass in a pipeline with a $match on the planCacheKey field.要返回特定查询形状的计划缓存信息，请在planCacheKey字段上传递带有$match的管道。

db.orders.getPlanCache().list([ { $match: { planCacheKey: "DD67E353"} } ] )

The operation returns the following:该操作返回以下结果：

[
   {
      "createdFromQuery" : {
         "query" : {
            "quantity" : {
               "$gte" : 5
            },
            "type" : "apparel"
         },
         "sort" : {
         },
         "projection" : {
         }
      },
      "queryHash" : "4D151C4C",
      "planCacheKey" : "DD67E353",
      "isActive" : false,
      "works" : NumberLong(4),
      "cachedPlan" : {
         "stage" : "FETCH",
         "filter" : {
            "type" : {
               "$eq" : "apparel"
            }
         },
         "inputStage" : {
            "stage" : "IXSCAN",
            "keyPattern" : {
               "quantity" : 1
            },
            "indexName" : "quantity_1",
            "isMultiKey" : false,
            "multiKeyPaths" : {
               "quantity" : [ ]
            },
            "isUnique" : false,
            "isSparse" : false,
            "isPartial" : false,
            "indexVersion" : 2,
            "direction" : "forward",
            "indexBounds" : {
               "quantity" : [
                  "[5.0, inf.0]"
               ]
            }
         }
      },
      "timeOfCreation" : ISODate("2020-02-11T17:14:33.873Z"),
      "creationExecStats" : [
         {
            "nReturned" : 2,
            "executionTimeMillisEstimate" : 0,
            "totalKeysExamined" : 3,
            "totalDocsExamined" : 3,
            "executionStages" : {
               "stage" : "FETCH",
               "filter" : {
                  "type" : {
                     "$eq" : "apparel"
                  }
               },
               "nReturned" : 2,
               "executionTimeMillisEstimate" : 0,
               "works" : 4,
               "advanced" : 2,
               "needTime" : 1,
               "needYield" : 0,
               "saveState" : 0,
               "restoreState" : 0,
               "isEOF" : 1,
               "docsExamined" : 3,
               "alreadyHasObj" : 0,
               "inputStage" : {
                  "stage" : "IXSCAN",
                  "nReturned" : 3,
                  "executionTimeMillisEstimate" : 0,
                  "works" : 4,
                  "advanced" : 3,
                  "needTime" : 0,
                  "needYield" : 0,
                  "saveState" : 0,
                  "restoreState" : 0,
                  "isEOF" : 1,
                  "keyPattern" : {
                     "quantity" : 1
                  },
                  "indexName" : "quantity_1",
                  "isMultiKey" : false,
                  "multiKeyPaths" : {
                     "quantity" : [ ]
                  },
                  "isUnique" : false,
                  "isSparse" : false,
                  "isPartial" : false,
                  "indexVersion" : 2,
                  "direction" : "forward",
                  "indexBounds" : {
                     "quantity" : [
                        "[5.0, inf.0]"
                     ]
                  },
                  "keysExamined" : 3,
                  "seeks" : 1,
                  "dupsTested" : 0,
                  "dupsDropped" : 0
               }
            }
         },
         {
            "nReturned" : 2,
            "executionTimeMillisEstimate" : 0,
            "totalKeysExamined" : 3,
            "totalDocsExamined" : 2,
            "executionStages" : {
               "stage" : "FETCH",
               "nReturned" : 2,
               "executionTimeMillisEstimate" : 0,
               "works" : 4,
               "advanced" : 2,
               "needTime" : 1,
               "needYield" : 0,
               "saveState" : 0,
               "restoreState" : 0,
               "isEOF" : 1,
               "docsExamined" : 2,
               "alreadyHasObj" : 0,
               "inputStage" : {
                  "stage" : "IXSCAN",
                  "nReturned" : 2,
                  "executionTimeMillisEstimate" : 0,
                  "works" : 4,
                  "advanced" : 2,
                  "needTime" : 1,
                  "needYield" : 0,
                  "saveState" : 0,
                  "restoreState" : 0,
                  "isEOF" : 1,
                  "keyPattern" : {
                     "quantity" : 1,
                     "type" : 1
                  },
                  "indexName" : "quantity_1_type_1",
                  "isMultiKey" : false,
                  "multiKeyPaths" : {
                     "quantity" : [ ],
                     "type" : [ ]
                  },
                  "isUnique" : false,
                  "isSparse" : false,
                  "isPartial" : false,
                  "indexVersion" : 2,
                  "direction" : "forward",
                  "indexBounds" : {
                     "quantity" : [
                        "[5.0, inf.0]"
                     ],
                     "type" : [
                        "[\"apparel\", \"apparel\"]"
                     ]
                  },
                  "keysExamined" : 3,
                  "seeks" : 2,
                  "dupsTested" : 0,
                  "dupsDropped" : 0
               }
            }
         }
      ],
      "candidatePlanScores" : [
         1.5002,
         1.5002
      ],
      "indexFilterSet" : false,
      "estimatedSizeBytes" : NumberLong(3160),   // Available starting in MongoDB 5.0, 4.4.3, 4.2.12, 4.0.23, 3.6.23
      "host" : "mongodb1.example.net:27018",
      "shard" : "shardA"
                         // Available if run on sharded cluster
   }
]

For details on the output, see $planCacheStats output.有关输出的详细信息，请参阅$planCacheStats输出。

←  PlanCache.help()Bulk Operation Methods →