Database Manual / Reference / Query Language / Aggregation Stages

$querySettings (aggregation stage)（聚合阶段）

Definition定义

$querySettings

New in version 8.0.在版本8.0中新增。

Returns query settings previously added with setQuerySettings. The settings apply to the entire cluster. The cluster retains the settings after shutdown.返回以前使用setQuerySettings添加的查询设置。这些设置适用于整个集群。集群在关闭后保留设置。

Syntax语法

If you use multiple pipeline stages, put $querySettings first in the pipeline.如果使用多个管道阶段，请将$querySettings放在管道的第一位。

db.aggregate( [
   { $querySettings: { showDebugQueryShape: <boolean> } },
   // Add any additional pipeline stages after $querySettings在$querySettings之后添加任何其他管道阶段
   ...
] )

Command Fields命令字段

$querySettings takes this field:接受此字段：

Field字段Type类型Necessity必要性Description描述
showDebugQueryShapeboolean布尔值Optional可选

If true, $querySettings returns a debugging version of the query shape output. 如果为true，$querySettings将返回查询形状输出的调试版本。You'll see an example in the next section. For output details, see Query Shape.您将在下一节中看到一个示例。有关输出详细信息，请参阅查询形状。

Default is false.默认值为false。

Examples示例

MongoDB Shell

The following examples create a collection, add query settings, and return the settings:以下示例创建集合、添加查询设置并返回设置：

1

Create the example collection and indexes创建示例集合和索引

Run:运行：

// Create pizzaOrders collection创建pizzaorders集合
db.pizzaOrders.insertMany( [
   { _id: 0, type: "pepperoni", totalNumber: 5,
   orderDate: new Date( "2024-01-15T12:00:00Z" ) },
   { _id: 1, type: "cheese", totalNumber: 15,
   orderDate: new Date( "2024-01-23T11:12:32Z" ) },
   { _id: 2, type: "vegan", totalNumber: 20,
   orderDate: new Date( "2024-03-20T10:01:12Z" ) }
] )

// Create ascending index on orderDate field在orderDate字段上创建升序索引
db.pizzaOrders.createIndex( { orderDate: 1 } )

// Create ascending index on totalNumber field在totalNumber字段上创建升序索引
db.pizzaOrders.createIndex( { totalNumber: 1 } )

The indexes have the default names orderDate_1 and totalNumber_1.索引的默认名称为orderDate_1和totalNumber_1。

2

Add the query settings添加查询设置

The following setQuerySettings example adds query settings:以下setQuerySettings示例添加了查询设置：

db.adminCommand( {
   setQuerySettings: {
      find: "pizzaOrders",
      filter: {
         orderDate: { $gt: ISODate( "2024-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"
   }
} )

The comment field is available starting in MongoDB 8.1 (and 8.0.4).comment字段从MongoDB 8.1（和8.0.4）开始可用。

3

Return the query settings返回查询设置

The following example uses a $querySettings stage in an aggregation pipeline to return query settings:以下示例使用聚合管道中的$querySettings阶段返回查询设置：

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

Because showDebugQueryShape is true, the debugQueryShape document is included in the output. You can use the queryShapeHash identifier to locate the query settings. 因为showDebugQueryShape为true，所以debugQueryShape文档包含在输出中。您可以使用queryShapeHash标识符来定位查询设置。queryShapeHash and debugQueryShape are highlighted in this output:queryShapeHash和debugQueryShape在此输出中突出显示：

[
   {
      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'
      },
      debugQueryShape: {
         cmdNs: { db: 'test', coll: 'pizzaOrders' },
         command: 'find',
         filter: { orderDate: { '$gt': '?date' } },
         sort: { totalNumber: 1 }
      }
   }
]
Node.js

The Node.js examples on this page use the sample_mflix database from the Atlas sample datasets. 本页上的Node.js示例使用Atlas示例数据集中的sample_mflix数据库。To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see Get Started in the MongoDB Node.js driver documentation.要了解如何创建免费的MongoDB Atlas集群并加载示例数据集，请参阅MongoDB Node.js驱动程序文档中的入门。

To use the MongoDB Node.js driver to add a $querySettings stage to an aggregation pipeline, use the $querySettings operator in a pipeline object.要使用MongoDB Node.js驱动程序将$querySettings阶段添加到聚合管道中，请在管道对象中使用$querySettings运算符。

To use the $querySettings stage, you must first add indexes and querySettings to the collection.要使用$querySettings阶段，您必须首先将索引和querySettings添加到集合中。

The following code inserts two indexes on the movies collection:以下代码在movies集合上插入两个索引：

const year = collection.createIndex({ year: 1 });  
const title = collection.createIndex({ title: 1 });

The following code adds query settings to the movies collection:以下代码将查询设置添加到movies集合中：

const command = {
  setQuerySettings: {
    find: "movies",
    filter: { year: { $gt: 2011 } },
    sort: { title: 1 },
    $db: "sample_mflix"
  },
  settings: {
    indexHints: {
      ns: { db: "sample_mflix", coll: "movies" },
      allowedIndexes: [ "year_1" ]
    },
    queryFramework: "classic",
    comment: "Index hint for year_1 index to improve query performance"
  }
};

const adminDb = client.db("admin");
const result = adminDb.command(command);

The following example creates a pipeline stage that returns the previously added query settings for the movies collection. 以下示例创建了一个管道阶段，该阶段返回之前为movies集合添加的查询设置。The example sets the showDebugQueryShape option to true to include the debugQueryShape document in the output. The example then runs the aggregation pipeline:该示例将showDebugQueryShape选项设置为true，以在输出中包含debugQueryShape文档。然后，该示例运行聚合管道：

const pipeline = [ { $querySettings: {showDebugQueryShape: true} } ];

const cursor = adminDb.aggregate(pipeline);
return cursor;

Learn More了解更多