文档菜单
文档首页
/
MongoDB 手册
/
参考
/
数据库命令
/
管理

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 聚合阶段输出中不会有 representativeQuery 字段。

提示

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

命令字段

命令包含以下字段

字段
字段类型（文档，字符串等）
必要性
描述
setQuerySettings
文档或字符串
必需

您可以选择提供

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

  • 一个现有的查询形状哈希字符串，它唯一地标识查询形状。一个示例查询形状哈希是 "F42757F1AEB68B4C5A6DE6182B29B01947C829C926BCC01226BDA4DDE799766C"`。

indexHints.ns
文档
可选

索引提示的命名空间。仅当指定可选索引提示时才需要。

db
字符串
必需
索引提示的数据库名称。
coll
字符串
必需
索引提示的集合名称。
indexHints.allowedIndexes
数组
可选

索引提示的索引数组。索引提示可以是以下之一

  • 索引名称

  • 索引键模式

  • $natural 提示

有关更多详细信息，请参阅 索引 和 hint()。

queryFramework
字符串
可选

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

reject
布尔类型
可选

如果 true

  • 具有匹配查询形状的新查询将被拒绝，并且查询响应状态表明查询被拒绝。

  • 目前正在进行中的任何查询不会被拒绝。

默认值为 false。

要启用查询形状，请再次运行 setQuerySettings 对查询形状进行设置，并将 reject 设置为 false。如果您使用 setQuerySettings 将 reject 设置为 true，然后再将其设置回 false，则

  • 如果您的 settings 文档不为空，则 setQuerySettings 启用查询形状。

  • 如果您的 settings 文档只包含 reject: false，则 setQuerySettings 返回错误。相反，请使用 removeQuerySettings 命令删除设置，然后使用 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命令添加查询设置。该示例在setQuerySettings中提供了find命令的字段，并在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"
   }
} )
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'
         },
         ...
       }
     ...
     ]
   }
}
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'
      },
      representativeQuery: {
         find: 'pizzaOrders',
         filter: { orderDate: { '$gt': ISODate('2023-01-20T00:00:00.000Z') } },
         sort: { totalNumber: 1 },
         '$db': 'test'
      }
   }
]
6

为 distinct 命令添加查询设置

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

为 aggregate 命令添加查询设置

以下示例为 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