Docs Home → MongoDB Manual

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描述
pipelineArrayOptional.可选的。Aggregation pipeline to filter/process the query shapes. 用于筛选/处理查询形状的聚合管道。

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

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

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.并非所有查询都会自动将查询计划放入缓存中。如果当前没有缓存查询计划的查询形状，PlanCache.list()将返回一个空数组。

Tip

See also: 另请参阅：

Consideration考虑

Restrictions限制

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

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输出。