Operation rejection filters

Published reference · snapshot 2026-10-20 · skill mongodb-expert/references/operation-rejection-filters.md

Also known as: $querySettings and operation rejection filters

Source-anchored research for Operation rejection filters. Run status: COMPLETED.

These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.

Definitions

An operation rejection filter is a query shape whose query settings carry `reject: true`. An admin creates it with `setQuerySettings`. MongoDB 8.0 introduced it. After that, the server rejects every new `find`, `distinct` or `aggregate` execution that has the shape. (high confidence) [source]
Operation rejection filters are not available on Atlas Free (M0) or Flex clusters. The manual lists `setQuerySettings`, `removeQuerySettings` and `$querySettings` as unsupported there. For unsupported commands on those tiers, Atlas returns '<command> is not allowed or the syntax is incorrect, see the Atlas documentation for more information.' (high confidence) (verified as of 2026-10-20) [source]
An operation rejection filter is a query shape whose query setting `reject` is `true`. MongoDB 8.0 introduced it. An administrator creates it with the `setQuerySettings` command, and the server then rejects new `find`, `distinct`, and `aggregate` operations that have that query shape. MongoDB states the purpose as preventing an operation from causing excessive cluster workload. (high confidence) [source]

Structure and components

A filter has no client, user or application selector. The documented `settings` fields contain no such scope, and settings apply to all executions of the shape on the cluster. A filter therefore also rejects legitimate callers of the same shape. (low confidence) (verified as of 2026-10-20) [source]
The filter matches on query shape, not on literal values. Queries that differ only in literal values share one shape, so one filter rejects all of them. A different filter structure, sort, projection, namespace, or aggregation pipeline stage makes a different shape, and the filter does not cover it. `$querySettings` with `showDebugQueryShape: true` shows the shape with literals replaced by placeholders such as `?date`. (high confidence) [source]
A filter is blunt. It matches the whole shape, so it also rejects cheap and legitimate calls that share the shape. The documented settings fields (`indexHints`, `queryFramework`, `reject`, `comment`, and in 9.0 `queryKnobs` and `maxTimeMS`) include no condition on literal values, user, or client. The foojay walkthrough states the focus is entirely on the query's structure. (medium confidence) [source]

How it works

In 9.0 a client can pass a `querySettings` document inline on `find`, `distinct` or `aggregate`. The document applies to that one execution and is not stored. If the shape also has stored cluster settings, MongoDB merges the two, and the stored value wins when both set the same field. (medium confidence) (verified as of 2026-10-20) [source]
When you give `removeQuerySettings` a query shape, the literal values need not match. The manual's example: stored settings for `find x=1` are deleted by passing `find x=100`. (medium confidence) [source]
Do not assume a stored `queryShapeHash` survives a version change, migration or topology change. The manual expects the same shape to give the same hash on every node and on replica sets and sharded clusters. It also tells you to verify the hash before reusing it across clusters, versions or migrations. SERVER-104636 (fixed in 8.2.0-rc0 and 8.0.14) stopped serializing `_internalOutputSortKeyMetadata` into the shape because it made the hash deviate from the original 8.0.4 hash. (medium confidence) (verified as of 2026-10-20) [source]
If you set a filter by hash string, `$querySettings` output has no `representativeQuery` at first. The Atlas Query Profiler flow sets filters by hash. From MongoDB 8.3, with FCV 8.3 or later, the server backfills `representativeQuery` asynchronously, on a best-effort basis, the next time a matching query runs. (medium confidence) (verified as of 2026-10-20) [source]
The filter blocks only new operations. Queries already in progress when you set `reject: true` are not rejected. (medium confidence) [source]
List active filters with `db.aggregate([{ $querySettings: { showDebugQueryShape: true } }, { $match: { 'settings.reject': true } }])`. Put `$querySettings` first in the pipeline. Each result carries `queryShapeHash`, `settings`, and `representativeQuery`, plus `debugQueryShape` when `showDebugQueryShape` is `true`. (high confidence) [source]
Lift a filter with `removeQuerySettings`, passing either the query shape hash string or the query shape. When you pass a query shape, the field values do not have to match the original. To keep the entry and re-enable the shape instead, run `setQuerySettings` again with `reject: false` alongside at least one other setting. (high confidence) [source]

How-to and procedures

To list active filters, run an aggregation whose first stage is `{ $querySettings: { showDebugQueryShape: true } }` and whose next stage is `{ $match: { 'settings.reject': true } }`. `showDebugQueryShape: true` adds a literal-free `debugQueryShape`. Put `$querySettings` first in the pipeline. (high confidence) [source]
To remove a filter, run `removeQuerySettings` with the `queryShapeHash` string or with a query shape document. (high confidence) [source]
To see rejections in the server log, raise `systemLog.component.query.rejected.verbosity`. SERVER-86871 (fixed in 8.0.0-rc0) put rejection logging in its own component because logging by default would be noisy. Master source logs 'Query rejected by QuerySettings' with the shape hash, namespace and redacted command at debug level 2. (medium confidence) (verified as of 2026-10-20) [source]
Set a filter by hash when you only have a log or profiler entry. `setQuerySettings` accepts an existing `queryShapeHash` string and a `settings` document. For hash-created settings, `representativeQuery` is absent from `$querySettings` output at first. With FCV 8.3 or later, MongoDB backfills it asynchronously on a best-effort basis. (low confidence) (verified as of 2026-10-20) [source]

Problems, failure modes and limitations

A rejected client sees `MongoServerError: Query rejected by admin query settings`. The server error is `QueryRejectedBySettings`, code 411, which `error_codes.yml` lists with no categories. The server source throws it with that exact message. The manual shows the message but does not state the code. (high confidence) [source]
Rejection is one field in the query settings document that also holds index hints. Index filters (`planCacheSetFilter`) are deprecated since MongoDB 8.0 in favour of query settings, because index filters do not persist and are hard to create on every node. (high confidence) [source]
Rejection runs inside the query settings lookup. SERVER-100956 (open on 2026-10-20) says this forced the lookup code to know which aggregation stages cannot be rejected, and proposes a separate `QueryRejector` class. SERVER-134532 (fixed in 9.1.0-rc0) moved the stage rule to `Pipeline::canBeRejected()` and a `StageConstraints::RejectRequirement`. (medium confidence) (verified as of 2026-10-20) [source]
The `queryShapeHash` appears in `$querySettings` output, `explain`, the database profiler (`system.profile.queryShapeHash`), `$currentOp`, the slow query log and `$queryStats`. In Atlas, the Query Profiler under Query Insights shows it. (high confidence) [source]
To lift a filter but keep the other settings, run `setQuerySettings` again with `reject: false` plus at least one other setting. If the `settings` document holds only `reject: false`, the command returns an error, so run `removeQuerySettings` instead. The server source treats `reject: false` as a default value, which is why that document counts as empty. (high confidence) [source]
mdbkit, an MIT-licensed community project that says it is not affiliated with MongoDB, prints a `setQuerySettings` command 'to pin or block that shape without a code change (8.0+)' for a slow query shape. It never runs the command. (low confidence) (verified as of 2026-10-20) [source]
Admin stages cannot be rejected. SERVER-87052 (fixed in 8.0.0-rc0) says at least `$querySettings`, `$planCacheStats`, `$collStats`, `$indexStats`, `$listSampledQueries`, `$listSearchIndexes`, `$listSessions`, `$queryStats`, `$currentOp`, `$listCatalog`, `$listLocalSessions` and `$operationMetrics` must ignore `reject`. It also says `setQuerySettings` must fail if a representative query contains one. SERVER-134532 (fixed in 9.1.0-rc0) replaced the hard-coded `rejectionIncompatibleStages` list with a per-stage constraint. Master source also exempts whole commands. The manual does not document the list. (medium confidence) (verified as of 2026-10-20) [source]
Open bug SERVER-135301 (created 2026-09-19, status Needs Scheduling): a whole-cluster change stream (`$changeStream: { allChangesForCluster: true }`) runs against `admin.$cmd.aggregate`. The `admin` database counts as internal, so the settings lookup returns default settings and drops inline settings, including `reject`, with no error. (low confidence) (verified as of 2026-10-20) [source]
`explain` shows stored settings under `querySettings` in the winning plan's shard entry. In the tutorial, `explain` on a shape with `reject: true` returns a plan, not the rejection error, and shows `querySettings: { reject: true }`. (medium confidence) [source]
A rejected operation fails with error name `QueryRejectedBySettings` and message `Query rejected by admin query settings`. In mongosh it prints as `MongoServerError[QueryRejectedBySettings]: Query rejected by admin query settings`. The tutorial documents the message and gives no numeric error code. (high confidence) [source]
Rejection filters persist across restarts and are cluster-wide settings. The older index filters set with `planCacheSetFilter` do not persist, and MongoDB deprecated them in 8.0 in favor of query settings. (high confidence) [source]
As of 2026-10-20, the docs mark `setQuerySettings`, `removeQuerySettings`, and `$querySettings` as supported on MongoDB Atlas, MongoDB Enterprise, and MongoDB Community, and as not supported on Atlas M0 and Flex clusters. The tutorial says you cannot set an operation rejection filter on Atlas Free or Flex clusters. (high confidence) (verified as of 2026-10-20) [source]
If the `settings` document contains only `reject: false`, `setQuerySettings` returns an error. If it also holds other fields such as `indexHints` or `comment`, the call re-enables the shape. When no other setting remains, call `removeQuerySettings`. The server stores simplified settings and drops `reject: false`. (high confidence) [source]
The `queryShapeHash` for an existing query can be read from `explain` output, `$querySettings` output, the database profiler, slow query logs, or the Atlas Query Profiler. (high confidence) [source]
Incident workflow from the tutorial: spot the costly query with Atlas Monitoring, Atlas Alerts, the Atlas Query Profiler, or the `slow-ops` log message. Take its `queryShapeHash`. Set `reject: true`. Confirm with `explain`. Fix the query with an index or a rewrite. Deploy the updated application. The tutorial ends by removing the filter and confirming the query runs again. (medium confidence) [source]
Add a `comment` when you block a shape, for example `comment: 'Will be rejected'` or an incident ticket id. The comment shows in `$querySettings` output, `explain()` output, and slow query logs. The field exists from 8.0.4 and 8.1. You cannot remove a comment, but you can overwrite it or delete the whole entry with `removeQuerySettings`. (medium confidence) [source]
Version history from the docs, as of 2026-10-20 (current docs are 9.0): 8.0 introduced rejection filters, `setQuerySettings`, `removeQuerySettings`, and `$querySettings`. 8.0.4 and 8.1 added `comment`. 8.3 backfills `representativeQuery` for hash-created settings and raises the representative-query storage limit above 16 MB. 9.0 adds `queryKnobs` and `maxTimeMS`. The docs list no 8.2 change. The `reject` wording is identical on the 8.0 and current setQuerySettings pages. (medium confidence) (verified as of 2026-10-20) [source]
SERVER-87052 (fixed in 8.0.0-rc0, resolved 2024-03-27) says an administrator could reject administrative and internal commands through query settings, for example `$querySettings`, `$collStats`, `$indexStats`, `$queryStats`, and `$currentOp`. The ticket asked that these stages ignore `reject` and that `setQuerySettings` fail when `reject: true` targets them. The page does not confirm the final behavior. (low confidence) [source]

Comparisons and alternatives

Create a filter with this template: `db.adminCommand({ setQuerySettings: { find: 'orders', filter: { status: 'open' }, sort: { total: 1 }, $db: 'shop' }, settings: { reject: true } })`. The reply carries `queryShapeHash`, `settings`, and `representativeQuery`. You can pass an existing query shape hash string as the `setQuerySettings` value instead of a query document. (high confidence) [source]

Facts and statements

The manual scopes `setQuerySettings`, and so operation rejection filters, to the `find`, `distinct` and `aggregate` commands. It names no other command. (high confidence) (verified as of 2026-10-20) [source]
A filter matches by query shape, not by literal values. Executions that differ only in literal values share one `queryShapeHash`, and the filter rejects all of them. A different filter, sort, projection, namespace or aggregation stage makes a different shape that the filter does not match. For `aggregate`, the shape covers the entire pipeline. (high confidence) [source]
A filter blocks only new executions. The manual says queries already in progress are not rejected. SERVER-85876 specifies that incoming commands are killed with a `uassert` right after the query settings lookup, and the current server source checks `reject` at that point. (high confidence) [source]
Filters are cluster-wide and persistent. The settings apply to the query shape on the entire cluster, and the cluster keeps them across restarts. (high confidence) [source]
As of the 9.0 manual (2026-10-20), the `settings` document of `setQuerySettings` accepts `indexHints`, `queryFramework`, `reject`, `comment`, `queryKnobs` and `maxTimeMS`. `comment` arrived in 8.1 and 8.0.4. `queryKnobs` and `maxTimeMS` arrived in 9.0 and need FCV 9.0 or later. (high confidence) (verified as of 2026-10-20) [source]
In the current server source, the router service looks up and merges settings and runs the rejection check. The shard service reuses the settings that the router forwarded, for internal or direct clients. This is master source on 2026-10-20. It is not confirmed for the 8.0 or 9.0 release branches. (low confidence) (verified as of 2026-10-20) [source]
The query settings hash is used to build the plan cache key. SERVER-89071 (fixed in 8.0.0-rc2 and 8.1.0-rc0) added the `reject` flag to that hash. Before the fix the hash ignored it. The manual says the same hashing applies to `queryKnobs`, which change the plan cache key. (medium confidence) [source]
Access: the `querySettings` privilege action, new in 8.0, lets a user run `setQuerySettings`, `removeQuerySettings` and the `$querySettings` stage. The Atlas resilience guide says `setQuerySettings` needs the `atlasAdmin` role. (medium confidence) (verified as of 2026-10-20) [source]
Intended workflow: spot the inefficient query in Atlas Monitoring, Atlas Alerts, the Query Profiler, the Real Time Performance Panel or the logs. Copy its `queryShapeHash`. Set `reject: true` on that shape. Fix the query with an index or a rewrite. Deploy the fixed application. Then re-enable or remove the setting. (high confidence) [source]
The documented purpose is to stop one inefficient query from using excessive cluster resources while the fix is prepared, with no application change and no wait for application teams. Mydbops, an independent consultancy, makes the same point in a June 2024 pre-release preview. (high confidence) [source]
The Atlas resilience guide names two more uses: prioritise important workloads during overload by rejecting less important queries, and give a cluster near its maximum resource use time to recover. (low confidence) [source]
The Atlas resilience guide groups rejection filters, 'to reactively mitigate expensive queries', with the `defaultMaxTimeMS` cluster-level read timeout, 'for proactive protection against expensive read operations'. Both are 8.0 features. A Mydbops preview lists the two side by side. (medium confidence) [source]
Besides rejection, 9.0 adds two per-shape controls. `maxTimeMS` is documented for capping one regressed shape without changing application code. `queryKnobs` overrides internal server parameters for one shape, for example `{ noTableScan: true }` for the `notablescan` parameter. (medium confidence) (verified as of 2026-10-20) [source]
Treat a filter as temporary containment, not a fix. The manual says to 'temporarily reject' a shape, then fix the query, deploy, and re-enable the setting. A filter left in place keeps rejecting the shape for every client on the cluster. (medium confidence) [source]
SERVER-85880 (fixed in 8.0.0-rc0) added two rejection counters: `QuerySettingsRejectCount` in the query settings metrics and `RejectedQueriesCount` in the command metrics. The ticket does not give the `serverStatus` field paths. (low confidence) (verified as of 2026-10-20) [source]
Some queries can never carry a filter. The server skips query settings for `find` commands eligible for the IDHACK fast path (`_id` equality lookups), for queries with encryption information, for internal databases (`admin`, `local`, `config`) and for system collections. `setQuerySettings` refuses representative queries on internal databases and system collections. (medium confidence) (verified as of 2026-10-20) [source]
Amazon DocumentDB's supported-API page, which covers the MongoDB 8.0 API, lists `planCacheSetFilter`, `planCacheListFilters` and `planCacheClearFilters` for 5.0 and 8.0. It does not list `setQuerySettings`, `removeQuerySettings` or `$querySettings`. Do not assume rejection filters on MongoDB-compatible services. (low confidence) (verified as of 2026-10-20) [source]
Query settings apply to every node of the deployment. The query shapes page says you can apply the same settings to a shape on every node. Mydbops says the settings replicate to all members of the replica set. (medium confidence) [source]
Only `find`, `distinct`, and `aggregate` commands carry query settings, so only those command types can be rejected by a filter. (high confidence) [source]
One privilege action, `querySettings` (new in 8.0), authorizes `setQuerySettings`, `removeQuerySettings`, and the `$querySettings` stage. The privilege-actions page states no resource scope for it and names no built-in role that includes it. (medium confidence) [source]
The tutorial runs `explain` after setting the filter and shows `querySettings: { reject: true }` in the output. The setQuerySettings page shows `explain` output carrying `querySettings` for index-hint settings as well. Use `explain` to confirm a filter attached to the shape you meant. (medium confidence) [source]
Treat a filter as a temporary brake, not a fix. The tutorial says to temporarily reject all operations for a shape. It lists the follow-up as resolving the performance problem with an index or query rewrite, then deploying the updated application. (low confidence) [source]
Do not reuse a hash-keyed setting across clusters, MongoDB versions, or after a migration without checking the hash. MongoDB says the same query shape is 'expected to produce' the same `queryShapeHash` on every node and on replica sets and sharded clusters in current supported versions. It tells you to verify that the hash still matches in the target deployment. (medium confidence) (verified as of 2026-10-20) [source]
Do not copy syntax from pre-release third-party posts. The Mydbops article of 2024-06-14, written before the 8.0 release, shows `setQuerySetting` with `Settings: { Reject: true }`. The shipped command is `setQuerySettings` with lowercase `settings: { reject: true }`. (medium confidence) [source]
COMPASS-8914 (filed 2025-02-03, closed 2025-05-20 as 'Works as Designed', no fix version) reports that a query rejected in mongosh with `QueryRejectedBySettings` still ran in Compass. The ticket records no explanation. Test a filter from the exact client and query form you want to stop. (low confidence) [source]
Before 8.0.5 and 8.1.0-rc0 (SERVER-92461), the `setQuerySettings` reply still contained `reject: false` or an empty `comment` that the server had dropped from the stored settings. On older builds, read stored state with `$querySettings`, not the reply. (low confidence) [source]
Percona Server for MongoDB 8.0.4-1 (released 2024-12-17) ships the 8.0 query settings feature. Percona's release notes call query settings persistent and the replacement for index filters. Percona's blog says query shapes can 'reject some harmful query patterns'. Neither Percona page shows `setQuerySettings` syntax or `reject`, so use the upstream MongoDB docs as the syntax reference. (medium confidence) [source]
SERVER-130061 (fixed in 9.0.0-rc1, resolved 2026-07-03) enables `featureFlagAllowUserFacingQuerySettings` by default. Users can then pass `querySettings` inline on `find`, `aggregate`, and `distinct` as non-persisted runtime hints. The ticket discusses validating `indexHints` and `queryKnobs` and does not mention `reject`. (low confidence) (verified as of 2026-10-20) [source]

Children

$querySettings stage and query settings inspection (frontier)
Atlas Query Profiler and Operation Throttling metrics (frontier)
Atlas Query Profiler and slow-ops logs for shape discovery (frontier)
Index filters (planCacheSetFilter) deprecation and migration to query settings (frontier)
Inline user-facing querySettings (9.0) (frontier)
Per-shape maxTimeMS and queryKnobs (9.0) (frontier)
Per-shape queryKnobs and maxTimeMS (9.0) (frontier)
Query settings: index hints and queryFramework (persistent query settings) (frontier)
Query shape and queryShapeHash stability (frontier)
Query shapes and queryShapeHash stability (frontier)
defaultMaxTimeMS cluster-level read timeout (frontier)
maxEstimatedScanBytes collection-scan rejection (9.0) (frontier)
setQuerySettings index hints and queryFramework (frontier)

Frontier under this node: $querySettings stage and query settings inspection, Atlas Query Profiler and Operation Throttling metrics, Atlas Query Profiler and slow-ops logs for shape discovery, Index filters (planCacheSetFilter) deprecation and migration to query settings, Inline user-facing querySettings (9.0), Per-shape maxTimeMS and queryKnobs (9.0), Per-shape queryKnobs and maxTimeMS (9.0), Query settings: index hints and queryFramework (persistent query settings), Query shape and queryShapeHash stability, Query shapes and queryShapeHash stability, defaultMaxTimeMS cluster-level read timeout, maxEstimatedScanBytes collection-scan rejection (9.0), setQuerySettings index hints and queryFramework

← the whole tree · 3D view· how to read this page