setQuerySettings (database command)

Query Settings and Index Filters

Starting in MongoDB 8.0, index filters are deprecated. Use query settings instead.

Query settings have more functionality than index filters. Index filters aren't persistent, and you can't easily create index filters for all cluster nodes.

Set Query Settings by Passing in a Query

In the following syntax, you provide:

• The same fields as a find, distinct, or aggregate command. See the syntax sections on the pages for those commands for the fields you can include in setQuerySettings.

• A $db field to specify the database for the query settings.

• A settings document with indexHints and other fields.

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>,
      comment: <BSON type>,
      queryKnobs: <document>,
      maxTimeMS: <non-negative integer>
   }
} )

Set Query Settings by Passing in a Query Shape Hash

You can provide an existing query shape hash string in setQuerySettings and an updated settings document with indexHints and other fields:

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>,
      comment: <BSON type>,
      queryKnobs: <document>,
      maxTimeMS: <non-negative integer>
   }
} )

A query shape hash is a string that uniquely identifies the query shape. An example query shape hash is "F42757F1AEB68B4C5A6DE6182B29B01947C829C926BCC01226BDA4DDE799766C".

In current supported versions, the same query shape is expected to produce the same query shape hash across nodes and deployment types. To learn how the hash behaves across nodes, deployment types, and clusters, see Query Shape Hash Stability.

To obtain the query shape hash string, do any of these:

• Use a $querySettings stage in an aggregation pipeline and examine the queryShapeHash field.

• Examine the database profiler output.

• View the slow query logs.

If you set the query settings using a hash string, the representativeQuery field is initially absent from the $querySettings aggregation stage output.

Starting in MongoDB 8.3, if the FCV is 8.3 or later, MongoDB backfills the representativeQuery field for query settings that you set with a query shape hash. When MongoDB runs a query that matches the query shape, it schedules the backfill. The backfill requires no action from you.

The backfill runs asynchronously on a best-effort basis to limit the performance impact on your queries. A query setting isn't guaranteed to be backfilled the first time a matching query runs. If a backfill doesn't complete, MongoDB attempts it again the next time a matching query runs.

To hold the additional representative queries, MongoDB 8.3 also increases the storage capacity for representative queries in query settings beyond the original 16 MB BSON document limit.

Query Knobs

Starting in MongoDB 9.0, you can use the queryKnobs setting to override internal server parameters for a single query shape instead of the whole instance. Set the queryKnobs field for targeted queries to mitigate the impact of one regressed shape without changing behavior for other workloads on the same deployment.

For example, you can override the notablescan server parameter for a single query shape instead of the whole instance by setting queryKnobs to { noTableScan: true }.

Each knob keeps the type, bounds, and default of its underlying server parameter, and setQuerySettings runs the same validation that setParameter runs. setQuerySettings rejects the following values:

• Unknown knobs

• Knobs that are not marked as settable through query settings

• Wrong BSON types

• Invalid enum strings

• Out-of-range values

• Knobs whose minimum FCV requirement exceeds the cluster FCV

The effective value of a knob follows this precedence, from highest to lowest:

1. Per-shape value set with queryKnobs

2. Instance-wide value set with setParameter

3. Compiled-in default value

Query knobs are part of the hashed query settings, so they are also part of the plan cache key. If you change a knob value, MongoDB produces a new plan cache key, so the planner creates a fresh plan instead of reusing a stale cached plan.

Unlike setParameter, which applies per process and can differ between nodes, MongoDB applies the same queryKnobs values across the whole cluster for the matching query shape.