Docs Menu
Docs Home
/
MongoDB Manual
/ / /

$querySettings (aggregation)

On this page

  • Definition
  • Syntax
  • Command Fields
  • Examples
  • Learn More
$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.

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

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

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

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

1

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.

2

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

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 }
}
}
]

Back

$project