Atlas Query Shape Insights
Parent: MongoDB Explain Plans, Query Planner and Plan Cache · Published reference · snapshot 2026-10-23 · skill mongodb-cohort-2b640565deb6-pending
↓ Facts as markdownall context files
Source-anchored research for Atlas Query Shape Insights. 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
- Percona independently advises checking custom $queryStats consumers before a MongoDB 9.0 upgrade because output structure and serialization changed. Its analysis emphasizes that read-only visibility can miss write-heavy resource use; this scopes the older Atlas 8.x read-only shape view. (medium confidence) (verified as of 2026-10-09) [source]
How it works
- An 8.x-to-9.0 upgrade can change Query Shape Insights totals because the collection method changes. Datadog query-shape metrics expose samplingstrategy and samplingrate tags to distinguish rate-limited collection from random sampling. (medium confidence) (verified as of 2026-10-14) [source]
- The Query Shape Insights summaries API deprecates P50/P90/P99 execution-time series and fields because values may be inaccurate. [redacted] explains that deriving percentiles from lastExecMicros was incorrect and requests native execution-time histograms. Do not treat these legacy percentiles as reliable latency distributions. (high confidence) (verified as of 2026-10-23) [source]
- The MongoDB query-stats implementation groups executions in an in-memory store, with dimensions beyond query shape. Specifying batchSize can create a separate entry even when the query shape is the same; bounded LRU partitions can evict old entries. Raw store entries should not be assumed to correspond one-to-one to Atlas shape rows. (low confidence) [source]
Measurements and reference values
- Collection is version-dependent: Atlas 8.x records up to 100 read queries per second per host and excludes writes; Atlas 9.0+ randomly samples 1% of reads and writes by default. Values describe collected operations, not complete workload totals, and rare shapes may be absent. (high confidence) (verified as of 2026-10-14) [source]
Problems, failure modes and limitations
- Atlas Query Shape Insights aggregates structurally similar queries and ranks shapes by total execution time; it complements Query Profiler, which exposes individual slow operations. Use the shape view to prioritize workload patterns, then investigate individual operations. (high confidence) [source]
Comparisons and alternatives
- Atlas documents warn that field names in redacted query shapes can still contain PII. Users without the specified roles see query shape hashes instead of truncated or full shapes. (low confidence) (verified as of 2026-10-14) [source]
Facts and statements
- Query Shape Insights requires an Atlas dedicated cluster (M10 or above) running MongoDB 8.0 or later. The documented analysis window is seven days, with up to five shapes charted at once. (high confidence) (verified as of 2026-10-14) [source]
- The Atlas Datadog integration exports query-shape metrics, including execution count, execution time and documents examined/returned. Operators enable query-shape metrics in Atlas Datadog Settings and can correlate exported metrics using the queryshapehash tag. (high confidence) (verified as of 2026-10-14) [source]
- The summaries endpoint supports programmatic retrieval of query-shape statistics. MongoDB describes a workflow that pivots from shape-level findings to Query Profiler with collection and operation filters, then to Performance Advisor for index recommendations. (medium confidence) (verified as of 2026-10-23) [source]
Children
- Query shape hash correlation (frontier)
- Query-shape metric sampling (frontier)
- Execution-time percentile accuracy (frontier)
Frontier under this node: Execution-time percentile accuracy, Query shape hash correlation, Query-shape metric sampling