analyzeShardKey query sampling and candidate-key scoring
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 query sampling and candidate-key scoring. 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
- Inspect numOrphanDocs before trusting characteristic metrics: orphan documents are included for performance reasons. Monotonicity based on record-ID correlation can also be misleading after chunk migrations because recipient insertion order need not preserve client insertion order. (low confidence) [source]
How-to and procedures
- Use numDistinctValues and mostCommonValues.frequency relative to numDocsSampled to assess candidate data distribution. Many repeated values restrict splitting and can concentrate storage and operations even when the collection is large. (high confidence) [source]
Problems, failure modes and limitations
- SERVER-91030 documents a historical failure mode in which cardinality/frequency analysis with readConcern available can miss documents after data movement because shard-version checks and shard filtering are skipped. The issue does not establish which current releases remain exposed. (low confidence) [source]
- Read and write distribution estimates depend on representative query samples. MongoDB warns that collecting a representative workload may require several days; an analysis of an atypical short interval cannot establish candidate quality for the full workload. (medium confidence) [source]
Comparisons and alternatives
- Score routing suitability using single-shard, multi-shard and scatter-gather percentages, then inspect numReadsByRange and numWritesByRange for skew. These are separate dimensions of suitability; the documented output is a set of metrics rather than a universal scalar cost score. (medium confidence) [source]
- Collect a representative workload before comparing candidates; several days may be needed. Compare data distribution with query targeting, rather than accepting high cardinality alone as evidence of a good key. (high confidence) [source]
- Read/write distribution analysis can evaluate a candidate without its final sharding index. Key-characteristic calculation requires a supporting index, whose requirements differ from shardCollection; index availability must be checked separately before actually sharding. (medium confidence) [source]
- SERVER-119912 reports that the key-characteristic passes can scan the supporting index despite a small sampleSize: sample selection limits retained values rather than necessarily limiting index keys visited. Treat small sampleSize as insufficient evidence of cheap execution. The issue was updated on 2026-09-29 and is a historical implementation report, not a verified statement about every release. (low confidence) (verified as of 2026-09-29) [source]
- analyzeShardKey evaluates existing or candidate shard keys through separate key-characteristic and read/write-distribution metrics. Candidate comparison should consider cardinality, frequent values, monotonicity and routing together; these outputs are diagnostic dimensions rather than a documented monetary-savings score. The comparison guidance is an inference from the output schema and worked examples. (medium confidence) [source]
Facts and statements
- analyzeShardKey evaluates an existing or candidate key on either a sharded or unsharded collection. Its output separates keyCharacteristics (cardinality, frequency and monotonicity) from readDistribution and writeDistribution (routing patterns and range hotness). (high confidence) [source]
- Document sampling and workload sampling are different inputs: sampleRate or sampleSize controls documents used for key characteristics; configureQueryAnalyzer collects query samples used for read/write distribution. sampleRate and sampleSize are mutually exclusive. (high confidence) [source]
- Analysis does not block application reads or writes, but that does not establish negligible resource consumption. MongoDB and Alibaba recommend secondary or secondaryPreferred read preference to reduce production impact. (medium confidence) [source]
- MongoDB performance-test task SERVER-68763 explicitly varies collection size, presence of query samples, concurrent analyzer commands and concurrent YCSB workload. It supplies a useful test design but does not publish a universal overhead percentage on the issue page. (low confidence) [source]
- Query samples occupy internal storage and expire through a TTL index controlled by queryAnalysisSampleExpirationSecs. Inspect sampled command counts with $listSampledQueries and disable query analysis after enough representative samples have been collected. (low confidence) [source]
- Document sampling and query sampling control different evidence: analyzeShardKey sampleRate or sampleSize selects collection documents for key characteristics; configureQueryAnalyzer collects workload queries for distribution analysis. Increasing document sampleSize does not itself collect more query samples. (medium confidence) [source]
- For candidate screening, inspect numDistinctValues and mostCommonValues.frequency relative to numDocsSampled. In Percona’s worked example, hashed badgeId has approximately 9.99 million distinct sampled values and maximum reported frequency three, while created has approximately 955 thousand distinct values and is classified monotonic. These are dataset-specific observations, not production savings estimates. (medium confidence) [source]
- Routing metrics distinguish single-shard, multishard and scatter-gather operations. A multishard read can benefit from parallelism, so minimizing every multishard percentage is not a universally valid scoring rule. (low confidence) [source]
- A monotonicity result can be unknown for clustered collections, unsuitable supporting indexes or compound hashed keys whose hashed field is not first. Chunk migrations can also invalidate insertion-order correlation, so treat a monotonicity classification after migration cautiously. (low confidence) [source]
- SERVER-119912 reports that both monotonicity and cardinality/frequency calculations scan the supporting index even with a small sampleSize. SERVER-107799 independently describes intentionally using index scans for precision and calls their cost nontrivial on large collections. A smaller retained sample therefore must not be assumed to yield proportionally less I/O in the reported implementation. (medium confidence) (verified as of 2026-09-29) [source]
- The cached tracker pages show SERVER-119912 closed as a duplicate, with successor SERVER-120246 unresolved in Backlog and no fix version. Closing the original issue is not evidence that proportional-to-sampleSize execution shipped; verify the deployed release before relying on that optimization. (medium confidence) (verified as of 2026-09-29) [source]
- SERVER-107799 explains that sampled documents for readWriteDistribution define approximate range boundaries, whereas document samples for keyCharacteristics target greater precision. Range-level hotness counts are estimates over these boundaries and should not be mistaken for measured CPU, disk or billing utilization per physical shard. The utilization distinction is an inference from the stated calculation. (low confidence) [source]
Children
- Representative workload windows for candidate-key comparison (frontier)
- Range-hotness and scatter-gather weighting (frontier)
- Supporting-index scan cost of shard-key analysis (frontier)
Frontier under this node: Range-hotness and scatter-gather weighting, Representative workload windows for candidate-key comparison, Supporting-index scan cost of shard-key analysis