setQuerySettings（数据库命令）

定义

setQuerySettings

8.0版本新增。

setQuerySettings 定义 find、distinct 和 aggregate 命令使用的查询设置。

您可以使用查询设置添加索引提示，定义操作拒绝筛选器，并为集群上给定查询结构的所有执行设立其他字段。集群的查询设置在重启后仍然存在。

查询优化器在查询规划期间使用查询设置作为附加input。查询设置中的索引提示会限制规划器可用的索引设立，但不保证规划器一定会使用索引。规划器仍然可以选择集合扫描作为给定查询结构哈希的获胜计划。

集群查询设置优先于作为命令字段传递的查询设置或索引提示。如果匹配的查询设置已包含索引提示，MongoDB将忽略命令字段中的索引提示。

索引提示不会影响查询结构。

有关提示和查询设置的更多信息，请参阅查询设置事务语法。

注意

要删除查询设置，请使用removeQuerySettings。要查看当前查询设置，请使用聚合管道中的 $querySettings 阶段。

查询设置和索引过滤器

从MongoDB 8.0 开始，索引过滤器已弃用。请改用查询设置。

查询设置的功能比索引过滤器更多。索引过滤器不是持久性的，您无法轻松地为所有集群节点创建索引过滤器。

兼容性

此命令可用于以下环境中托管的部署：

MongoDB Atlas：用于云中 MongoDB 部署的完全托管服务

重要

M0 和 Flex 集群不支持此命令。有关更多信息，请参阅不支持的命令。

MongoDB Enterprise：基于订阅、自我管理的 MongoDB 版本
MongoDB Community：源代码可用、免费使用且可自行管理的 MongoDB 版本

语法

可以使用这一部分中所示的两种语法规范之一添加或更新查询设置。

通过传入查询来设置查询设置

在如下语法中，您需要提供：

与 find、distinct 或 aggregate 命令的字段相同。请参阅页面上的语法部分，以了解可以包含在 setQuerySettings 中的字段的命令。
一个 $db 字段，用于为查询设置指定数据库。
带有 indexHints 和其他字段的 settings 文档。

db.adminCommand( {
   setQuerySettings: {
      <fields>,  // Provide fields for
                 // find, distinct, or aggregate command
      $db: <string>  // Provide a database name
   },
   // Provide a settings document with indexHints and other fields
   settings: {
      indexHints: [ {
         ns: { db: <string>, coll: <string> },
         allowedIndexes: <array>
      }, ... ],
      queryFramework: <string>,
      reject: <boolean>,
      comment: <BSON type>,
      queryKnobs: <document>,
      maxTimeMS: <non-negative integer>
   }
} )

传入查询结构哈希，以设置查询设置

可以在 setQuerySettings 中提供现有的查询结构哈希字符串，以及包含 indexHints 和其他字段的更新后的 settings 文档：

db.adminCommand( {
   setQuerySettings: <string>,  // Provide an existing query shape hash string
   // Provide a settings document with indexHints and other fields
   settings: {
      indexHints: [ {
         ns: { db: <string>, coll: <string> },
         allowedIndexes: <array>
      }, ... ],
      queryFramework: <string>,
      reject: <boolean>,
      comment: <BSON type>,
      queryKnobs: <document>,
      maxTimeMS: <non-negative integer>
   }
} )

查询结构哈希是一个唯一标识查询结构的字符串。查询结构哈希的一个示例是 "F42757F1AEB68B4C5A6DE6182B29B01947C829C926BCC01226BDA4DDE799766C"。

在当前支持的版本中，相同的查询结构预计会跨节点和部署类型生成相同的查询结构哈希。要学习；了解哈希在节点、部署类型和集群之间的行为方式，请参阅查询形状哈希稳定性。

要获取查询结构哈希字符串，请执行以下任一操作：

在一个聚合管道中使用一个 $querySettings 阶段，并检查 queryShapeHash 字段。
检查数据库分析器输出。
查看慢查询日志。

如果使用哈希字符串设立查询设置，则 $querySettings聚合阶段输出最初不存在 representativeQuery字段。

从MongoDB 8.3 开始，如果FCV为 8.3 或更高版本， MongoDB将回填您使用查询结构哈希设立的查询设置的 representativeQuery字段。当MongoDB运行与查询结构匹配的查询时，它会安排回填。回填不需要您执行任何动作。

回填会尽力异步运行，以限制对查询的性能影响。不保证在匹配查询首次运行时回填查询设置。如果回填未完成， MongoDB会在下次运行匹配查询时再次尝试回填。

为了容纳额外的代表性查询， MongoDB 8.3 还在查询设置中增加了代表性查询的存储容量，超出了原始 16 MB BSON文档的限制。

提示

在这两种语法变体中，您都可以提供一个 indexHints 文档数组。如果只提供一个 indexHints 文档，可以省略数组括号。

命令字段

setQuerySettings 命令中的 settings文档包含以下字段：

字段	字段类型	必要性	说明
`setQuerySettings`	文档或字符串	必需	可以提供以下任一项：与 `find`、`distinct` 或 `aggregate` 命令中的字段相同的字段，以及一个包含与原始命令相关联的数据库的 `$db` 字段。一个用于唯一标识查询结构的现有查询结构哈希字符串。查询结构哈希的一个示例是 "F42757F1AEB68B4C5A6DE6182B29B01947C829C926BCC01226BDA4DDE799766C"`。
`indexHints.ns`	文档	Optional	索引提示的命名空间。只在指定了可选索引提示时需要。
`indexHints.ns.db`	字符串	可选的	索引提示的数据库名称。指定 `indexHints.ns` 时为必填项。
`indexHints.ns.coll`	字符串	可选的	索引提示的集合名称。指定 `indexHints.ns` 时为必填项。
`indexHints.allowedIndexes`	阵列	Optional	索引提示的索引数组。索引提示可以是以下内容之一：索引名称索引键模式 `$natural` 提示有关更多详细信息，请参阅索引和 `hint()`。
`queryFramework`	字符串	Optional	可以将查询框架字符串设置为： `classic` 以使用经典引擎。 `sbe` ，以使用基于槽的查询执行引擎。有关详细信息，请参阅基于槽的查询执行引擎。
`reject`	布尔	Optional	如果为 `true`：系统将拒绝具有匹配的查询结构的新查询，查询响应将说明查询被拒绝。系统不会拒绝当前正在执行的任何查询。默认值为 `false`。要启用一个查询结构，请为此查询结构再次运行 `setQuerySettings`，并将 `reject` 设置为 `false`。如果将 `reject` 设置为 `true`，然后使用 `setQuerySettings` 恢复为 `false`，则：如果您的 `settings` 文档不为空，`setQuerySettings` 将启用查询结构。如果您的 `settings` 文档只包含 `reject: false`，`setQuerySettings` 将返回一个错误。相反，请使用 `removeQuerySettings` 命令删除设置，然后使用 `setQuerySettings` 添加查询设置。
`comment`	BSON 类型	Optional	评论可以是任何有效的BSON类型。示例：字符串、对象等。您可以使用注释提供有关查询设置的其他信息。示例，要添加一个字符串来说明添加查询设置的原因，请使用 `comment: "Index hint for orderDate_1 index to improve query performance"`。要更新评论，请再次运行`setQuerySettings` 并使用 `comment: { body: { msg: "Updated comment" } }`。您无法删除注释，但可以将其设立为带有空格字符的字符串。您可以使用`removeQuerySettings` 删除查询设置。注释显示在`$querySettings` 聚合管道阶段输出、explain() 命令输出和慢查询日志中。版本 8.1 中的新增内容：（以及 8.0.4）。
`queryKnobs`	文档	Optional	`{ <knobName>: <value> }` 对的文档，仅覆盖此查询结构的内部服务器参数，而不是使用 `setParameter` 覆盖实例范围的内部服务器参数。每个旋钮都保留其根本的服务器参数的类型、边界和默认。与其他 `setQuerySettings` 字段设立时替换整个值不同，`queryKnobs` 会与现有旋钮值合并。 `setQuerySettings` 更改 `queryKnobs`文档中包含的旋钮，并保持所有其他旋钮不变。 `queryKnobs: {}` 结果为空操作。要删除单个旋钮而不影响其他旋钮，请将该旋钮的值设立为 `null`。 9.0版本新增。
`maxTimeMS`	non-negative integer	Optional	设置执行查询结构的时间限制（以毫秒为单位）。使用此设置可在不更改应用程序程序代码的情况下限制单个回归形状或解除过紧的客户端超时。如果在查询设置中省略 `maxTimeMS`，则操作的超时时间将遵循命令级 `maxTimeMS` 选项和 `defaultMaxTimeMS`集群参数。将 `maxTimeMS` 设置为 `0` 会清除 `maxTimeMS`查询设置，并且操作会回退到命令级别和集群默认值。使用 `setQuerySettings`设立的`maxTimeMS` 值优先于命令中提供的 `maxTimeMS` 值。 9.0版本新增。

查询旋钮

9.0版本新增。

从MongoDB 9.0 开始，您可以使用 queryKnobs 设置覆盖单个查询结构（而不是整个实例）的内部服务器参数。为定向查询设置queryKnobs字段，以减轻一种回归形状的影响，而无需更改同一部署中其他工作负载的行为。

示例，您可以通过将 queryKnobs 设置为 { noTableScan: true } 来覆盖单个查询结构（而不是整个实例）的 notablescan服务器参数。

每个旋钮都保留其根本的服务器参数的类型、边界和默认，并且 setQuerySettings 运行与 setParameter 运行相同的验证。 setQuerySettings 拒绝以下值：

未知旋钮
未标记为可通过查询设置进行设置的旋钮
错误的BSON 类型
无效的枚举字符串
超出范围的值
最低FCV要求超过集群FCV的旋钮

旋钮的有效值遵循以下优先顺序，从最高到最低：

每个形状的值设立为 queryKnobs
实例范围的值设立 setParameter
编译时默认值

查询旋钮是哈希查询设置的一部分，因此也是计划缓存键的一部分。如果更改旋钮值， MongoDB会生成新的计划缓存键，因此规划器会创建新计划，而不是重复使用过时的缓存计划。

与 setParameter（按进程应用且可能因节点而异）不同， MongoDB在整个集群中应用相同的 queryKnobs 值来匹配查询结构。

重要

当您将FCV从 9.0 降级到早期版本时，迁移会更新存储的查询设置。迁移会删除最小FCV超过目标版本的每个旋钮，并删除仍仅包含默认值的所有设置条目。重新升级到 9.0 不会恢复已删除的旋钮。您必须使用 setQuerySettings 重新应用它们。

示例

以下示例创建一个集合并为不同命令添加查询设置。对于集群上查询结构的所有执行，这些示例将查询规划器限制为使用提示索引或集合扫描。

创建示例集合和索引

运行：

 // Create pizzaOrders collection
 db.pizzaOrders.insertMany( [
   { _id: 0, type: "pepperoni", size: "small", price: 19,
     totalNumber: 10, orderDate: ISODate( "2023-03-13T08:14:30Z" ) },
   { _id: 1, type: "pepperoni", size: "medium", price: 20,
     totalNumber: 20, orderDate: ISODate( "2023-03-13T09:13:24Z" ) },
   { _id: 2, type: "pepperoni", size: "large", price: 21,
     totalNumber: 30, orderDate: ISODate( "2023-03-17T09:22:12Z" ) },
   { _id: 3, type: "cheese", size: "small", price: 12,
     totalNumber: 15, orderDate: ISODate( "2023-03-13T11:21:39.736Z" ) },
   { _id: 4, type: "cheese", size: "medium", price: 13,
     totalNumber: 50, orderDate: ISODate( "2024-01-12T21:23:13.331Z" ) },
   { _id: 5, type: "cheese", size: "large", price: 14,
     totalNumber: 10, orderDate: ISODate( "2024-01-12T05:08:13Z" ) },
   { _id: 6, type: "vegan", size: "small", price: 17,
     totalNumber: 10, orderDate: ISODate( "2023-01-13T05:08:13Z" ) },
   { _id: 7, type: "vegan", size: "medium", price: 18,
     totalNumber: 10, orderDate: ISODate( "2023-01-13T05:10:13Z" ) }
] )
 // Create ascending index on orderDate field
 db.pizzaOrders.createIndex( { orderDate: 1 } )
 // Create ascending index on totalNumber field
 db.pizzaOrders.createIndex( { totalNumber: 1 } )

索引的默认名称为 orderDate_1 和 totalNumber_1。

为 find 命令添加查询设置

如下示例将为 find 命令添加查询设置。此示例将为 find 命令提供 setQuerySettings 中的字段，并包含 allowedIndexes 中的 orderDate_1 索引。

db.adminCommand( {
   setQuerySettings: {
      find: "pizzaOrders",
      filter: {
         orderDate: { $gt: ISODate( "2023-01-20T00:00:00Z" ) }
      },
      sort: {
         totalNumber: 1
      },
      $db: "test"
   },
   settings: {
      indexHints: {
         ns: { db: "test", coll: "pizzaOrders" },
         allowedIndexes: [ "orderDate_1" ]
      },
      queryFramework: "classic",
      comment: "Index hint for orderDate_1 index to improve query performance"
   }
} )

（可选）验证查询设置

运行此 explain 命令：

db.pizzaOrders.explain().find( { orderDate: { $gt: ISODate(
"2023-01-20T00:00:00Z" ) } } ).sort( { totalNumber: 1 } )

截断的如下输出显示了所设定的查询设置：

queryPlanner: {
   winningPlan: {
     stage: 'SINGLE_SHARD',
     shards: [
       {
         explainVersion: '1',
         ...
         namespace: 'test.pizzaOrders',
         indexFilterSet: false,
         parsedQuery: { orderDate: { '$gt': ISODate('2023-01-20T00:00:00.000Z') } },
         querySettings: {
           indexHints: {
             ns: { db: 'test', coll: 'pizzaOrders' },
             allowedIndexes: [ 'orderDate_1' ]
           },
           queryFramework: 'classic',
           comment: 'Index hint for orderDate_1 index to improve query performance'
         },
         ...
       }
     ...
     ]
   }
}

（可选）运行查询

如下示例将运行查询：

db.pizzaOrders.find(
   { orderDate: { $gt: ISODate( "2023-01-20T00:00:00Z" ) } } ).sort( { totalNumber: 1 }
)

在查询规划期间，查询优化器使用查询设置作为附加输入，这样会影响为运行查询而选择的计划。

查询输出：

[
   {
      _id: 0,
      type: 'pepperoni',
      size: 'small',
      price: 19,
      totalNumber: 10,
      orderDate: ISODate('2023-03-13T08:14:30.000Z')
   },
   {
      _id: 5,
      type: 'cheese',
      size: 'large',
      price: 14,
      totalNumber: 10,
      orderDate: ISODate('2024-01-12T05:08:13.000Z')
   },
   {
      _id: 3,
      type: 'cheese',
      size: 'small',
      price: 12,
      totalNumber: 15,
      orderDate: ISODate('2023-03-13T11:21:39.736Z')
   },
   {
      _id: 1,
      type: 'pepperoni',
      size: 'medium',
      price: 20,
      totalNumber: 20,
      orderDate: ISODate('2023-03-13T09:13:24.000Z')
   },
   {
      _id: 2,
      type: 'pepperoni',
      size: 'large',
      price: 21,
      totalNumber: 30,
      orderDate: ISODate('2023-03-17T09:22:12.000Z')
   },
   {
      _id: 4,
      type: 'cheese',
      size: 'medium',
      price: 13,
      totalNumber: 50,
      orderDate: ISODate('2024-01-12T21:23:13.331Z')
   }
]

（可选）获取查询设置

如下示例使用一个聚合管道中的 $querySettings 阶段获取查询设置：

db.aggregate( [
   { $querySettings: {} }
] )

截断后的输出，包括 queryShapeHash 字段：

[
   {
      queryShapeHash: 'AB8ECADEE8F0EB0F447A30744EB4813AE7E0BFEF523B0870CA10FCBC87F5D8F1',
      settings: {
         indexHints: [
            {
               ns: { db: 'test', coll: 'pizzaOrders' },
               allowedIndexes: [ 'orderDate_1' ]
            }
         ],
         queryFramework: 'classic',
         comment: 'Index hint for orderDate_1 index to improve query performance'
      },
      representativeQuery: {
         find: 'pizzaOrders',
         filter: { orderDate: { '$gt': ISODate('2023-01-20T00:00:00.000Z') } },
         sort: { totalNumber: 1 },
         '$db': 'test'
      }
   }
]

为不同的命令添加查询设置

如下示例将为 distinct 命令添加查询设置：

db.adminCommand( {
   setQuerySettings: {
      distinct: "pizzaOrders",
      key: "totalNumber",
      query: { totalNumber: 10, orderDate :{ '$gt': ISODate('2023-01-20T00:00:00.000Z') } } ,
      $db: "test"
   },
   settings: {
      indexHints: {
         ns: { db: "test", coll: "pizzaOrders" },
         allowedIndexes: [ "orderDate_1" ]
      },
      queryFramework: "classic",
      comment: "Index hint for orderDate_1 index to improve query performance"
   }
} )

为聚合命令添加查询设置

如下示例将为 aggregate 命令添加查询设置：

db.adminCommand( {
   setQuerySettings: {
      aggregate: "pizzaOrders",
      pipeline: [
         { $match: { totalNumber: 10, orderDate :{ '$gt': ISODate('2023-01-20T00:00:00.000Z') } } },
         { $group: {
            _id: "$type",
            totalMediumPizzaOrdersGroupedByType: { $sum: "$totalNumber" }
         } }
      ],
      $db: "test"
   },
   settings: {
      indexHints: {
         ns: { db: "test", coll: "pizzaOrders" },
         allowedIndexes: [ "totalNumber_1" ]
      },
      queryFramework: "classic",
      comment: "Index hint for totalNumber_1 index to improve query performance"
   }
} )

了解详情

后退

setDefaultRWConcern

来年

setUserWriteBlockMode