> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

<!--
Tab options on this page. Append to the .md URL to filter:
  ?tabs=<id,...>   select specific tabs (e.g. ?tabs=nodejs,shell)
  ?allTabs=true    include every tab
  (no param)       default: one tab per tabset

Available tabs:
  drivers: shell, nodejs
-->

# $querySettings (aggregation stage)

## Definition

**New in version 8.0**

Returns query settings previously added with [`setQuerySettings`](https://www.mongodb.com/docs/manual/reference/command/setquerysettings.md#mongodb-dbcommand-dbcmd.setQuerySettings). The settings apply to the entire cluster. The cluster retains the settings after shutdown.

## Compatibility

This command is available in deployments hosted in the following environments:

- [MongoDB Atlas](https://www.mongodb.com/docs/atlas): The fully managed service for MongoDB deployments in the cloud

**Important:**

This command is not supported in M0 and Flex clusters. For more information, see [Unsupported Commands.](https://www.mongodb.com/docs/atlas/unsupported-commands/)

- [MongoDB Enterprise](https://www.mongodb.com/docs/manual/administration/install-enterprise.md#std-label-install-mdb-enterprise): The subscription-based, self-managed version of MongoDB

- [MongoDB Community](https://www.mongodb.com/docs/manual/administration/install-community.md#std-label-install-mdb-community-edition): The source-available, free-to-use, and self-managed version of MongoDB

## Syntax

If you use multiple pipeline stages, put `$querySettings` first in the pipeline.

```javascript
db.aggregate( [
   { $querySettings: { showDebugQueryShape: <boolean> } },
   // Add any additional pipeline stages after $querySettings
   ...
] )
```

## Command Fields

`$querySettings` takes this field:

| Field | Type | Necessity | Description |
| --- | --- | --- | --- |
| `showDebugQueryShape` | boolean | Optional | If `true`, `$querySettings` returns a debugging version of the [query shape](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-query-shape) output. You'll see an example in the next section. For output details, see [Query Shape.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/querystats.md#std-label-queryStats-queryShape) Default is `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:

   ```javascript
   // Create pizzaOrders collection
   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
   db.pizzaOrders.createIndex( { orderDate: 1 } )

   // Create ascending index on totalNumber field
   db.pizzaOrders.createIndex( { totalNumber: 1 } )
   ```

   The indexes have the default names `orderDate_1` and `totalNumber_1`.

2. Add the query settings

   The following `setQuerySettings` example adds query settings:

   ```javascript
   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).

3. Return the query settings

   The following example uses a `$querySettings` stage in an aggregation pipeline to return query settings:

   ```javascript
   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. `queryShapeHash` and `debugQueryShape` are highlighted in this output:

   ```javascript
   [
      {
         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 }
         }
      }
   ]
   ```

## Learn More

- [Query Plans](https://www.mongodb.com/docs/manual/core/query-plans.md#std-label-query-plans-query-optimization)

- [`setQuerySettings`](https://www.mongodb.com/docs/manual/reference/command/setquerysettings.md#mongodb-dbcommand-dbcmd.setQuerySettings)

- [`removeQuerySettings`](https://www.mongodb.com/docs/manual/reference/command/removequerysettings.md#mongodb-dbcommand-dbcmd.removeQuerySettings)

- [`$queryStats`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/querystats.md#mongodb-pipeline-pipe.-queryStats)

- [Query Shapes](https://www.mongodb.com/docs/manual/core/query-shapes.md#std-label-query-shapes)

- [Query statistics for query shapes](https://www.mongodb.com/docs/manual/reference/operator/aggregation/querystats.md#std-label-queryStats-queryShape)

- [Block Slow Queries with Operation Rejection Filters](https://www.mongodb.com/docs/manual/tutorial/operation-rejection-filters.md#std-label-operation-rejection-filters)