Docs 菜单
Docs 主页
/ /
管理
Docs 主页
/ /
数据库命令
/
管理
Docs 主页
/
开发中
/
参考
/
数据库命令
/
管理

setQuerySettings（数据库命令）

定义

setQuerySettings

8.0版本新增。

可以使用查询设置添加索引提示、定义操作拒绝过滤器以及设置其他字段。这些设置将应用于整个集群上的查询结构。在关闭之后，集群将保留这些设置。

例如，使用查询设置，可以对一个集群中的一个查询结构的所有执行使用一个索引。

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

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

从 MongoDB 8.0 开始，使用查询设置而不是索引过滤器。从 MongoDB 8.0 开始，弃用了索引过滤器。

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

查询设置的优先级高于索引提示。当匹配查询设置包含索引提示时， MongoDB会忽略作为命令字段传递的索引提示。索引提示不会影响查询结构。有关提示和查询设置的更多信息，请参阅 查询设置事务语法。

注意

要删除查询设置，请使用 removeQuerySettings。要获取查询设置，请在一个聚合管道中使用一个 $querySettings 阶段。

语法

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

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

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

  • 与 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>
   }
} )

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

可以在 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>
   }
} )

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

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

如果使用哈希字符串设置查询设置，$querySettings聚合阶段输出中不会有 representativeQuery 字段。

提示

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

命令字段

该命令使用以下字段：

字段
字段类型
必要性
说明

setQuerySettings

文档或字符串

必需

可以提供以下任一项：

  • 与 find、distinct 或 aggregate 命令中的字段相同的字段，以及一个包含与原始命令相关联的数据库的 $db 字段。

  • 一个用于唯一标识查询结构的现有查询结构哈希字符串。查询结构哈希的一个示例是 "F42757F1AEB68B4C5A6DE6182B29B01947C829C926BCC01226BDA4DDE799766C"`。

indexHints.ns

文档

Optional

索引提示的命名空间。只在指定了可选索引提示时需要。

db

字符串

必需

用于索引提示的数据库的名称。

coll

字符串

必需

索引提示的集合的名称。

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() 命令输出和慢查询日志中。

从MongoDB 8.1（和 8.0.4）开始提供。

示例

以下示例将创建一个集合，并为不同的命令添加查询设置。对于在集群中运行的查询结构的所有执行，这些示例使用一个索引。

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: { type: "pepperoni"} ,
      $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: { size: "medium" } },
         { $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

获得技能徽章

免费掌握“查询优化”！

了解详情

在此页面上