对于 AI 代理：可在 https://www.mongodb.com/zh-cn/docs/llms.txt 获取文档索引—通过在任何 URL 路径后添加 .md 可获取所有页面的 Markdown 版本。
Docs 菜单
Docs 主页
/
开发中
/
数据库命令
Docs 主页
/
开发中
/
数据库命令
Docs 主页
/
开发中
/
数据库命令

setQuerySettings（数据库命令）

定义

setQuerySettings

8.0版本新增。

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

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

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

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

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

For more information about hints and query settings, see Query Settings Syntax.

注意

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

查询设置和索引过滤器

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

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

兼容性

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

  • MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

重要

This command is not supported in M0 and Flex clusters. For more information, see Unsupported Commands.

语法

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

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

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

  • 与 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"。

在当前支持的版本中，相同的查询结构预计会在不同节点和部署类型中产生相同的查询结构哈希。要了解哈希在节点、部署类型和集群中的行为，请参阅查询结构哈希稳定性。

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

如果使用哈希 string 设置查询设置，$querySettings 聚合阶段输出中初始不存在 representativeQuery 字段。

从 MongoDB 8.3 开始，如果 特征兼容性版本 为 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

可以将查询框架字符串设置为：

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 会与现有的 knob 值合并。setQuerySettings 会更改您包含在 queryKnobs 文档中的 knob，而不会更改所有其他 knob。

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 types

  • 无效的枚举字符串

  • 超出范围的值

  • 配置参数，其最低特征兼容性版本要求超出集群特征兼容性版本

配置项有效值的优先级从高到低依次为：

  1. 每个形状的值设置，使用 queryKnobs

  2. 设置的实例级值 setParameter

  3. 编译后的默认值

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

与 setParameter 不同（后者按进程应用，且可能在不同节点之间有所不同），MongoDB 对整个集群中匹配查询结构的相同 queryKnobs 值应用相同的设置。

重要

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

示例

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

1

创建示例集合和索引

运行：

 // 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。

2

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

（可选）验证查询设置

运行此 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'
         },
         ...
       }
     ...
     ]
   }
}
4

（可选）运行查询

如下示例将运行查询：

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')
   }
]
5

（可选）获取查询设置

如下示例使用一个聚合管道中的 $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'
      }
   }
]
6

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

如下示例将为 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"
   }
} )
7

为聚合命令添加查询设置

如下示例将为 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
获得技能徽章

免费掌握“查询优化”！

了解详情
给本页内容打分

在此页面上