analyzeShardKey and query sampling
Parent: Shard Key Design and Resharding as Cost Levers · Published reference · snapshot 2026-10-30
↓ Facts as markdownall context files
Source-anchored research for analyzeShardKey and query sampling. 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
- Operators can inspect query-sampling progress with $currentOp and inspect captured queries with $listSampledQueries. Inspecting captured command types helps check what the workload sample contains. (medium confidence) [source]
How it works
- Representative query sampling can require several days. The mongosh example evaluates keys using seven days of sampled workload, so a short or quiet interval should not be assumed to characterize a full application cycle. (medium confidence) [source]
- SERVER-119912 reports that key-characteristic passes scan the supporting index even when sampleSize is small. SERVER-107799 independently explains the deliberate index-scan approach for these metrics. A small sampleSize therefore should not be treated as a guarantee of proportionally small scan cost; confirm behavior on the deployed build. (medium confidence) (verified as of 2026-09-29) [source]
Problems, failure modes and limitations
- Atlas Shard Key Advisor documentation specifies five query samples per second, seven-day sample retention, and manual disabling when sampling is no longer needed. Its UI sampling rate cannot be adjusted through Shard Key Advisor. (low confidence) (verified as of 2026-10-30) [source]
- SERVER-119912 reports index scans proportional to collection size despite a smaller sampleSize for key-characteristic analysis. Treat this as an implementation warning, not proof about every release; the issue names no affected versions or shipped fix. (low confidence) (verified as of 2026-09-29) [source]
Comparisons and alternatives
- analyzeShardKey accepts a candidate key for an unsharded or sharded collection, or the current key of a sharded collection. It reports metrics rather than performing the sharding change. (medium confidence) [source]
Facts and statements
- MongoDB introduced analyzeShardKey and configureQueryAnalyzer in 7.0 to support shard-key evaluation; Percona also included these commands in its 7.0 release line, and ApsaraDB documents the analysis workflow for its users. (medium confidence) [source]
- Document sampling and query sampling are distinct: sampleRate or sampleSize controls the documents used for key characteristics, while configureQueryAnalyzer collects operations for read/write distribution. Key-characteristic analysis can run without query sampling. (high confidence) [source]
- Key-characteristic metrics include cardinality, frequency and monotonicity. Read/write distribution metrics describe routing patterns and the hotness of candidate-key ranges; they require sampled application queries. (medium confidence) [source]
- analyzeShardKey does not block collection reads or writes. MongoDB and Alibaba recommend secondary or secondaryPreferred read preference to reduce production impact; non-blocking operation does not establish negligible resource consumption. (high confidence) [source]
- SERVER-107799 records that random document sampling for range boundaries did not always yield the expected representative sample and could interfere with read/write distribution output. This issue concerns boundary construction, distinct from collecting application-query samples. (low confidence) (verified as of 2025-08-11) [source]
- Historical engineering work motivating document sampling reported analysis taking hours on collections with hundreds of millions of documents and high-cardinality keys. This is historical evidence of analysis overhead, not a latency forecast for current deployments. (low confidence) [source]
- MongoDB introduced analyzeShardKey in 7.0 for evaluating existing or prospective shard keys; its output separates key characteristics from read/write distribution. (high confidence) [source]
- Routing metrics require sampled operations. A zero or absent distribution result without samples is not evidence that production queries have zero routing cost. (low confidence) [source]
- configureQueryAnalyzer enables collection sampling with mode full and samplesPerSecond, and disables it with mode off. Operators can inspect captured operations with $listSampledQueries and monitor sampling through $currentOp. (low confidence) [source]
- Sampling consumes storage: MongoDB keeps sampled queries in an internal TTL-indexed collection and expires them according to queryAnalysisSampleExpirationSecs. Disable sampling after collecting sufficient evidence. (low confidence) [source]
- MongoDB ties routing-metric quality to workload representativeness and warns that some applications need several days of query sampling; there is no universal adequate collection window. (low confidence) [source]