planCacheSetFilter

On this page本页内容

Definition定义

planCacheSetFilter

Set an index filter for a collection. 为集合设置索引筛选器。If an index filter already exists for the query shape, the command overrides the previous index filter.如果查询形状已经存在索引筛选器，则该命令将覆盖上一个索引筛选器。

The command has the following syntax:该命令具有以下语法：

db.runCommand(
   {
      planCacheSetFilter: <collection>,
      query: <query>,
      sort: <sort>,
      projection: <projection>,
      indexes: [ <index1>, <index2>, ...],
      comment: <any>
   }
)

The planCacheSetFilter command has the following field:planCacheSetFilter命令具有以下字段：

Field字段Type类型Description描述
planCacheSetFilterstringThe name of the collection.集合的名称。
querydocument

The query predicate associated with the index filter. 与索引筛选器关联的查询谓词。Together with the sort and the projection, the query predicate make up the query shape for the specified index filter.query谓词与sort和projection一起构成指定索引筛选器的查询形状。

Only the structure of the predicate, including the field names, are significant; the values in the query predicate are insignificant. 只有谓词的结构（包括字段名）才有意义；查询谓词中的值无关紧要。As such, query predicates cover similar queries that differ only in the values.因此，查询谓词涵盖了仅在值上不同的类似查询。

sortdocumentOptional. 可选。The sort associated with the filter. 与筛选器关联的排序。Together with the query and the projection, the sort make up the query shape for the specified index filter. sort与query和projection一起构成指定索引筛选器的查询形状。
projectiondocumentOptional. 可选。The projection associated with the filter. 与筛选器关联的投影。Together with the query and the sort, the projection make up the query shape for the specified index filter. projection与query和sort一起构成指定索引筛选器的查询形状。
indexesarray

An array of index filters for the specified query shape.指定查询形状的索引筛选器数组。

Specify the index filters as either:将索引筛选器指定为：

  • an array of index specification documents, e.g. 一系列索引规范文档，例如：[ { x : 1 }, ... ]
  • an array of index names, e.g. 索引名数组，例如：[ "x_1", ... ]

Because the query optimizer chooses among the collection scan and these indexes, if the specified indexes are non-existent or hidden, the optimizer will choose the collection scan.由于查询优化器在集合扫描和这些索引之间进行选择，如果指定的索引不存在或隐藏，那么优化器将选择集合扫描。

In cases of multiple indexes with the same key pattern, you must specify the index by name.如果多个索引具有相同的键模式，则必须按名称指定索引。

commentany

Optional. 可选。A user-provided comment to attach to this command. 用户提供了附加到此命令的注释。Once set, this comment appears alongside records of this command in the following locations:设置后，此注释将与此命令的记录一起显示在以下位置：

A comment can be any valid BSON type(string, integer, object, array, etc).注释可以是任何有效的BSON类型（字符串、整数、对象、数组等）。

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

Index filters only exist for the duration of the server process and do not persist after shutdown; however, you can also clear existing index filters using the planCacheClearFilters command.索引筛选器仅在服务器进程期间存在，并且在关闭后不存在；但是，也可以使用planCacheClearFilters命令清除现有索引筛选器。

Required Access所需访问权限

A user must have access that includes the planCacheIndexFilter action.用户必须具有包含planCacheIndexFilter操作的访问权限。

Examples示例

Set Filter on Query Shape Consisting of Predicate Only对仅包含谓词的查询形状设置筛选器

The following example creates an index filter on the orders collection such that for queries that consist only of an equality match on the status field without any projection and sort, the query optimizer evaluates only the two specified indexes and the collection scan for the winning plan:以下示例在orders集合上创建一个索引筛选器，以便对于仅包含status字段上的相等匹配而没有任何投影和排序的查询，查询优化器仅评估两个指定的索引和获胜计划的集合扫描：

db.runCommand(
   {
      planCacheSetFilter: "orders",
      query: { status: "A" },
      indexes: [
         { cust_id: 1, status: 1 },
         { status: 1, order_date: -1 }
      ]
   }
)

In the query predicate, only the structure of the predicate, including the field names, are significant; the values are insignificant. 在查询谓词中，只有谓词的结构（包括字段名）是重要的；这些值无关紧要。As such, the created filter applies to the following operations:因此，创建的筛选器适用于以下操作：

db.orders.find( { status: "D" } )
db.orders.find( { status: "P" } )

To see whether MongoDB will apply an index filter for a query shape, check the indexFilterSet field of either the db.collection.explain() or the cursor.explain() method.要查看MongoDB是否将为查询形状应用索引筛选器，请检查db.collection.explain()或cursor.explain()方法的indexFilterSet字段。

Set Filter on Query Shape Consisting of Predicate, Projection, and Sort在由谓词、投影和排序组成的查询形状上设置筛选器

The following example creates an index filter for the orders collection. 以下示例为orders集合创建索引筛选器。The filter applies to queries whose predicate is an equality match on the item field, where only the quantity field is projected and an ascending sort by order_date is specified.该筛选器适用于谓词与item字段相等匹配的查询，其中仅投影quantity字段，并指定了按order_date升序排序。

db.runCommand(
   {
      planCacheSetFilter: "orders",
      query: { item: "ABC" },
      projection: { quantity: 1, _id: 0 },
      sort: { order_date: 1 },
      indexes: [
         { item: 1, order_date: 1 , quantity: 1 }
      ]
   }
)

For the query shape, the query optimizer will only consider indexed plans which use the index { item: 1, order_date: 1, quantity: 1 }.对于查询形状，查询优化器将只考虑使用索引{ item: 1, order_date: 1, quantity: 1 }的索引计划。

Tip提示
←  planCacheListFiltersAuthentication Commands →