queryKnobs and per-command querySettings
Parent: MongoDB Advanced Explain: Aggregation, Sharded Plans, Loose Index Scans and the 8.3 Cost-Based Ranker · Published reference · snapshot 2026-10-30
↓ Facts as markdownall context files
Source-anchored research for queryKnobs and per-command querySettings. 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.
How it works
- SERVER-134528 excludes internalQueryStatsRateLimit and internalQueryStatsCacheSize from per-shape overrides because their state is node-global or store-wide. Per-query sampling is consequently not a general replacement for query-stats configuration or database profiling controls. (low confidence) (verified as of 2026-10-27) [source]
- Percona ClusterSync does not automatically migrate persistent query settings. Its documented migration step exports settings using the $querySettings stage and reapplies them on the destination. When comparing query performance after migration, verify stored settings as well as per-command tuning; this source does not establish support for MongoDB 9.0 queryKnobs. (low confidence) (verified as of 2026-10-13) [source]
- MongoDB 9.0 explain.queryKnobs reports explicit knob values with their source, including querySettings or setParameter. Settings-based knobs appear even when equal to the default; unset knobs are omitted. Inspect this output to verify the effective tuning used for an execution. (low confidence) (verified as of 2026-10-24) [source]
Problems, failure modes and limitations
- SERVER-88133 reports an observability gap: executions of the same shape with and without query settings collapse into one $queryStats entry, mixing execution metrics. Adding applied settings to the telemetry key remains an unresolved proposal, so an aggregated entry cannot establish that every execution used a tested per-command setting. (low confidence) (verified as of 2026-10-23) [source]
Comparisons and alternatives
- MongoDB 9.0 permits a querySettings document directly on find, distinct, and aggregate commands as non-persisted settings for that execution. This differs from setQuerySettings, which persists settings for a query shape across the cluster. Stored cluster settings take precedence over conflicting command settings. (medium confidence) (verified as of 2026-10-30) [source]
Facts and statements
- MongoDB 9.0 queryKnobs overrides eligible internal server parameters for one query shape. A per-shape override wins over setParameter, which wins over the compiled default. This supports targeted mitigation of a regressed shape without changing all workloads. (medium confidence) (verified as of 2026-10-30) [source]
- queryKnobs does not expose every server parameter. Validation rejects unknown or unexposed names, invalid types, invalid enum values, out-of-range values, and knobs requiring a higher FCV. Inline user settings use the same validation primitives as stored settings; internal forwarded settings skip repeated validation. (medium confidence) (verified as of 2026-10-30) [source]
- NoSQLBooster documents that stored cluster settings take precedence over per-execution settings for the same field; inline settings therefore do not guarantee an override of persistent policy. (low confidence) (verified as of 2026-10-26) [source]
- setQuerySettings merges queryKnobs by individual knob: omitted knobs retain their values, an empty object makes no change, and a null value removes that knob. The merge consumes the removal sentinel before persistence; removing all knobs drops the queryKnobs field. (medium confidence) (verified as of 2026-10-30) [source]
- Query knob values participate in hashed query settings and the plan cache key. Changing a knob produces a different cache key and a fresh plan. A new plan cache key therefore need not mean that the query shape itself changed. (low confidence) (verified as of 2026-10-30) [source]
- Downgrading FCV removes stored knobs requiring a newer FCV. Re-upgrading does not restore them; administrators must reapply them. (low confidence) (verified as of 2026-10-30) [source]
- SERVER-134528 is marked Fixed for 9.1.0 release candidates, resolved October 20, 2026. SERVER-134995 says the resulting read-side queryStatsSampleRate override works, but separately tracks unfinished write-command eligibility. This is not evidence that MongoDB 9.0 supports all sampling overrides. (medium confidence) (verified as of 2026-10-27) [source]
- NoSQLBooster 11.2 documents the per-command querySettings form in its find, aggregate, distinct, and runCommand editor helpers and adds a fluent querySettings aggregation method for inspecting stored settings. This is primary evidence of client tooling support, not an independent implementation test of server semantics. (low confidence) (verified as of 2026-10-26) [source]
- The MongoDB find command IDL declares querySettings as an optional QuerySettings field with internal stability. Its presence in source code alone does not establish public support in an older server version. (low confidence) (verified as of 2026-10-30) [source]
- Write-side sampling overrides remain separately tracked: SERVER-134995 is unresolved and states that insert, update, delete, and findAndModify do not yet install query-settings overrides. Its description explicitly defers exposing queryStatsWriteCmdSampleRate to avoid accepted settings having no runtime effect. (low confidence) (verified as of 2026-10-23) [source]
Children
- No children recorded.