Query shape and queryShapeHash stability
Parent: Operation rejection filters · Published reference · snapshot 2026-10-31
↓ Facts as markdownall context files
Source-anchored research for Query shape 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.
Structure and components
- Studio 3T documentation describes its Query hash column using system.profile.queryHash, whereas Quorum’s October 26, 2026 guide groups MongoDB 8.0+ profiler entries by queryShapeHash. Treat the field name as part of the grouping definition when comparing tooling. (medium confidence) [source]
- Studio 3T's documentation describes grouping by Exact query using field names and values, and by Query shape using logical structure while ignoring values. That page specifically identifies system.profile.queryHash as its grouping hash; it does not establish that the displayed Query hash is MongoDB's newer queryShapeHash. (medium confidence) [source]
How it works
- The MongoDB repository describes replacing literals with canonical BSON-type representatives when hashing. Its examples give numeric predicates with different values the same shape, but distinguish a numeric predicate from a string predicate on the same field. (low confidence) (verified as of 2026-10-30) [source]
- For migration workflows, prefer a representative query when available and verify the resulting target shape hash. Percona documents representativeQuery-based import; MongoDB cautions against assuming a saved hash still matches after migration. (medium confidence) [source]
- SERVER-93622 records divergent queryShapeHash values and duplicate query-settings entries when repeatedly setting the same representative aggregate query containing $merge and let variables. The historical issue lists fixes in 8.0.4 and 8.1.0-rc0; it is evidence of a past exception, not proof that current versions remain affected. (low confidence) [source]
- Percona's ClusterSync migration guide instructs operators to reapply query settings using representativeQuery when present and otherwise use queryShapeHash. Its fallback needs MongoDB's separate target-hash verification guidance before cross-cluster reuse. (medium confidence) (verified as of 2026-10-13) [source]
Comparisons and alternatives
- Shape grouping abstracts literal values: structurally identical commands such as findOne({x:24}) and findOne({x:53}) share a shape. Studio 3T documents this distinction as query-shape grouping versus exact-query grouping. (medium confidence) [source]
- Before reusing queryShapeHash across clusters, MongoDB versions, or a migration, verify that it still matches in the target deployment. Retaining a representative query enables checking the intended shape instead of relying only on an opaque stored hash. (medium confidence) [source]
Facts and statements
- MongoDB 8.0 renamed the older queryHash to planCacheShapeHash and introduced the broader queryShapeHash. Percona profiler output shows all three fields, with queryHash equal to planCacheShapeHash and different from queryShapeHash. (medium confidence) [source]
- The documented expectation is that a shape produces the same queryShapeHash across deployment nodes and across replica-set and sharded deployment types. The documentation still requires checking the target hash across clusters, MongoDB versions, and migrations. (high confidence) (verified as of 2026-10-14) [source]
- Profiler records can expose queryShapeHash for shape-based grouping. MongoDB documents profiler output as a source for the hash, and Percona supplies a concrete profiler record containing it. (medium confidence) [source]
- SERVER-93881 introduced repeated-command explain checks expecting equal queryShapeHash values and links the $merge/let stability bug. These tests support repeatability checks; they do not establish an unconditional compatibility guarantee for every future release. (low confidence) [source]
- The find command IDL defines internal originalQueryShapeHash as the hash of the first query entering the query system; its example preserves the router-observed query hash on a shard request. The internal stability annotation is not a public API guarantee. (low confidence) [source]
- A shared shape does not guarantee a shared execution cost. Shape normalization groups differing literal values, while Percona describes uneven value distributions causing cached-plan inefficiency and replanning. Compare execution metrics as well as identifiers. (medium confidence) [source]
- A query shape includes structural specifications such as filter, sort, projection, namespace, and aggregation pipeline stages. Changing a literal value can preserve the shape; changing the sort field or namespace can change it. (high confidence) [source]
- MongoDB 8.0 introduced a broader query-shape model. The pre-existing shape was renamed plan cache query shape, and queryHash was renamed planCacheShapeHash; queryShapeHash identifies the newer model and is a different field. (high confidence) [source]
Children
- Canonical BSON literal serialization (frontier)
- Shape hash regression testing (frontier)
- Router-to-shard original shape propagation (frontier)
Frontier under this node: Canonical BSON literal serialization, Router-to-shard original shape propagation, Shape hash regression testing