$querySettings (aggregation)

On this page

Definition

Syntax
Command Fields
Examples
Learn More

Definition

$querySettings

New in version 8.0.

Returns query settings previously added with setQuerySettings. The settings apply to the entire cluster. The cluster retains the settings after shutdown.

Syntax

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

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 output. You'll see an example in the next section. For output details, see Query Shape. Default is `false`.

Examples

The following examples create a collection, add query settings, and return the settings:

Create the example collection and indexes

Run:

// 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.

Add the query settings

The following setQuerySettings example adds query settings:

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

Return the query settings

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

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:

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

Learn More

Back

$project

$queryStats