setQuerySettings

在此页面上

定义

语法
命令字段
举例
了解详情

定义

setQuerySettings

8.0版本新增。

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

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

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

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

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

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

注意

要删除查询设置，请使用 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>
   }
} )

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

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

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

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

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

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

提示

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

命令字段

该命令使用以下字段：

字段

字段类型（文档、字符串……）

必要性

说明

setQuerySettings

文档或字符串‎

必需

可以提供以下任一项：

与 find、distinct 或 aggregate 命令中的字段相同的字段，以及一个包含与原始命令相关联的数据库的 $db 字段。
一个用于唯一标识查询结构的现有查询结构哈希字符串。查询结构哈希的一个示例是 "F42757F1AEB68B4C5A6DE6182B29B01947C829C926BCC01226BDA4DDE799766C"`。

indexHints.ns

文档

Optional

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

`db`	字符串	必需	用于索引提示的数据库的名称。
`coll`	字符串	必需	索引提示的集合的名称。

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 添加查询设置。

举例

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

创建示例集合和索引

运行：

 // 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"
   }
} )

（可选）验证查询设置

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

（可选）运行查询

如下示例将运行查询：

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'
      },
      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: { type: "pepperoni"} ,
      $db: "test"
   },
   settings: {
      indexHints: {
         ns: { db: "test", coll: "pizzaOrders" },
         allowedIndexes: [ "orderDate_1" ]
      },
      queryFramework: "classic"
   }
} )

为聚合命令添加查询设置

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

了解详情

后退

setDefaultRWConcern

来年

setUserWriteBlockMode

setQuerySettings.leafygreen-ui-m0pgrr{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.leafygreen-ui-a30zj9{color:#889397;vertical-align:middle;margin-top:-2px;}.css-1l4s55v{margin-top:-175px;position:absolute;padding-bottom:2px;}

定义

注意

语法

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

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

提示

命令字段

举例

创建示例集合和索引

为 find 命令添加查询设置

（可选）验证查询设置

（可选）运行查询

（可选）获取查询设置

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

为聚合命令添加查询设置

了解详情

setQuerySettings