Query-settings representative-query backfill and FCV boundaries
Parent: MongoDB query planner, plan cache, query settings and hints · Published reference · snapshot 2026-10-27
↓ Facts as markdownall context files
Source-anchored research for Query-settings representative-query backfill and FCV boundaries. 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
- When setQuerySettings receives a query-shape hash string, representativeQuery is initially absent from $querySettings output; inspection and migration must accommodate entries without that field. (medium confidence) (verified as of 2026-10-14) [source]
- Backfill is asynchronous and best effort. The first matching execution need not populate representativeQuery; if backfill does not complete, a later matching execution triggers another attempt. (high confidence) (verified as of 2026-10-14) [source]
- In the inspected master implementation, settings lookup schedules backfill when BackfillCoordinator::shouldBackfill permits it, then returns the query settings. Representative-query upserts use a separate collection and catch DBException failures. (low confidence) (verified as of 2026-10-27) [source]
- Percona ClusterSync documentation requires manual query-settings migration after replication finalization. It directs users to identify exported settings by representativeQuery when present and queryShapeHash otherwise. (low confidence) (verified as of 2026-08-20) [source]
Problems, failure modes and limitations
- MongoDB 8.3 expands representative-query storage beyond the original 16 MB BSON document limit; this statement concerns representative-query storage capacity, not a general increase to BSON document limits. (medium confidence) (verified as of 2026-10-14) [source]
- Downgrading to a version without expanded representative-query capacity restores the 16 MB limit and can lose some representative queries. (low confidence) (verified as of 2026-10-14) [source]
Facts and statements
- Automatic representative-query backfill starts in MongoDB 8.3 and requires FCV 8.3 or later; a matching query execution schedules the work without user action. (high confidence) (verified as of 2026-10-14) [source]
- The inspected MongoDB master interface exposes dedicated representative-query collection creation and upsert methods. Its downgradeQuerySettings contract derives migrations from feature flags enabled at targetFCV; this development-branch interface alone does not establish released-version behavior. (low confidence) (verified as of 2026-10-27) [source]
- SERVER-129203 describes representativeQuery being stored separately in config.queryShapeRepresentativeQueries under featureFlagPQSBackfill, with insert replies including it and update replies omitting it. The issue was resolved Won't Fix with no fix version; its desired consistent reply is not evidence of shipped behavior. (low confidence) (verified as of 2026-09-08) [source]
Children
- No children recorded.