Query shapes and queryShapeHash stability
Parent: Operation rejection filters · Published reference · snapshot 2026-10-31
↓ Facts as markdownall context files
Source-anchored research for Query shapes and queryShapeHash stability. 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
- Query shapes include structural specifications such as filters, sorts, projections, namespace and pipeline stages. The documented date-filter examples retain their hashes when only the date literal changes; changing the sort field changes the shape. (low confidence) [source]
- For a single routed request, mongos and mongod can see different command shapes because mongos modifies the command. The server's originalQueryShapeHash field carries the hash of the first query entering the system, allowing the original shape to be distinguished from a shard-local shape. (high confidence) (verified as of 2026-09-25) [source]
- Percona migration guidance prefers an exported representativeQuery for identifying settings on the destination, falling back to queryShapeHash when absent. MongoDB separately requires verifying a reused hash on the destination; retaining the representative query makes that check practical. (high confidence) (verified as of 2026-10-13) [source]
- MongoDB documents obtaining queryShapeHash from database profiler output and inspecting hashes with explain. The independent mdbkit maintainer documents displaying queryShapeHash separately from planCacheShapeHash, supporting correlation only when the field and command shape match. (high confidence) [source]
Comparisons and alternatives
- Index hints do not affect query shape. A hash therefore identifies a workload shape rather than proving which index or execution plan was used. (low confidence) [source]
Facts and statements
- MongoDB 8.0 distinguishes the new queryShapeHash from planCacheShapeHash, the renamed older queryHash; these identify different shape definitions and should not be treated as interchangeable identifiers. (high confidence) (verified as of 2026-10-14) [source]
- In the current documentation snapshot, the same query shape is expected to yield the same queryShapeHash across deployment nodes and across replica-set and sharded deployments. The documentation still requires checking the target hash before cross-cluster, cross-version or post-migration reuse. (high confidence) (verified as of 2026-10-14) [source]
- SERVER-93881 introduced repeated-command queryShapeHash equality testing and links a separate aggregate-merge/let-variable stability fix. This is evidence that hash stability has needed explicit regression coverage, not a promise of invariance across all releases. (low confidence) [source]
- The University of Sydney study describes predicate-value abstraction for cache shapes while plan generation and evaluation use concrete values. Shape grouping therefore removes information relevant to individual executions; the study examined MongoDB 7.0.1 and does not establish queryShapeHash stability in MongoDB 8.x. (low confidence) [source]
- Mydbops reports a production MongoDB 7.0.14 incident in which array-valued query variations generated many queryHash values and excessive plan-cache entries. This concerns legacy queryHash and SBE behavior, and should not be presented as direct evidence that modern queryShapeHash is unstable. (low confidence) [source]
- SERVER-93622 documents repeated query-settings operations on an aggregate containing $merge with let variables producing divergent hashes and duplicate settings entries. The historical ticket lists fixes in 8.0.4 and 8.1.0-rc0; it does not establish that current releases retain that defect. (low confidence) [source]
- MongoDB's documented hash form is setQuerySettings: <hash string>. Percona's migration page instead shows setQuerySettings: {queryShapeHash: "A19F4D5C"}; that example conflicts with the official syntax and should not be copied as a verified hash-based invocation. (high confidence) (verified as of 2026-10-13) [source]
Children
- No children recorded.