# analyzeShardKey workload sampling > Source-anchored research for analyzeShardKey workload sampling. Run status: COMPLETED. Parent: [Shard key selection for query isolation](https://llms-explorer.com/tree/shard-key-selection-for-query-isolation/) · 5 facets · 19 facts · page: https://llms-explorer.com/tree/analyzeshardkey-workload-sampling/ ## Definitions - A reported multi-shard read is not a measured fixed number of contacted shards: MongoDB says this category includes reads that could target one shard depending on data placement, and large reads may benefit from parallel execution. Treat targeting percentages as evidence about routing, not a direct latency benchmark. (low confidence) — [source](https://www.mongodb.com/docs/manual/reference/command/analyzeShardKey.md) ## How it works - readDistribution and writeDistribution report routing categories and range hotness. Compare single-shard, multi-shard and scatter-gather percentages together with range activity when evaluating query isolation. (medium confidence) — [source](https://www.mongodb.com/docs/manual/reference/command/analyzeShardKey.md) - Percona demonstrates key-characteristic analysis with readWriteDistribution: false and describes workload query sampling separately. Key statistics can therefore be useful even when workload distribution has not been measured. (medium confidence) — [source](https://www.percona.com/blog/5-changes-you-should-know-in-mongodb-7-0/) - For query-isolation evaluation, inspect percentageOfSingleShardReads/Writes, percentageOfScatterGatherReads/Writes and numReadsByRange/numWritesByRange together. MongoDB advises avoiding high scatter-gather percentages and strongly skewed range counts because they indicate routing overhead or likely hot shards. (low confidence) — [source](https://www.mongodb.com/docs/manual/reference/command/analyzeShardKey.md) ## How-to and procedures - Enable configureQueryAnalyzer on the collection, exercise the workload, then run analyzeShardKey for each candidate. Analysis can precede sharding and can also evaluate an existing sharded collection. (medium confidence) — [source](https://www.mongodb.com/docs/manual/reference/command/analyzeShardKey.md) ## Problems, failure modes and limitations - Read/write distribution quality depends on how representative the sampled workload is. MongoDB documents that some applications require several days of sampling; a short or atypical capture cannot establish that the results represent normal traffic. (medium confidence) — [source](https://www.mongodb.com/docs/manual/reference/command/analyzeShardKey.md) - SERVER-119912 reports that keyCharacteristics passes scan the supporting index even with small sampleSize; its closure is a duplicate of optimization task SERVER-120246, not evidence of a shipped fix. Treat this as a reported implementation limitation, not a guarantee about every release. (medium confidence) (verified as of 2026-09-29) — [source](https://jira.mongodb.org/browse/SERVER-119912) - MongoDB engineering reports that document sampling used to estimate range boundaries can produce insufficient distinct values even for a high-cardinality key. Distribution analysis can fail because of this sampling stage; the report alone does not establish that the candidate key has poor cardinality. (medium confidence) (verified as of 2026-08-27) — [source](https://jira.mongodb.org/browse/SERVER-118017) ## Facts and statements - The two sampling controls serve different inputs: analyzeShardKey sampleRate and sampleSize select collection documents for key-characteristic metrics, while configureQueryAnalyzer samplesPerSecond controls workload query collection. Increasing the document sample alone does not collect workload queries. (medium confidence) — [source](https://www.mongodb.com/docs/manual/reference/command/analyzeShardKey.md) - Distribution sampleSize totals count sampled queries and report counts by command type. The documented read types are find, aggregate, count and distinct; the write types are update, delete and findAndModify. This output is not an inventory of every operation type, and does not list inserts. (medium confidence) — [source](https://www.mongodb.com/docs/manual/reference/command/analyzeShardKey.md) - Without sampled queries, workload distribution results are unavailable or zero-valued. Such output does not establish that traffic is well targeted; verify that sampling captured the relevant operation types. (medium confidence) — [source](https://www.mongodb.com/docs/manual/reference/command/analyzeShardKey.md) - The documented enablement example uses mode: "full" with samplesPerSecond: 5; mode: "off" disables collection sampling. $listSampledQueries can inspect captured operations and count them by command type. (low confidence) — [source](https://www.mongodb.com/docs/manual/reference/command/configureQueryAnalyzer.md) - Query samples live in an internal collection with a TTL index and are automatically deleted according to queryAnalysisSampleExpirationSecs. Dropping or renaming a collection disables sampling and requires reconfiguration for subsequent capture. (low confidence) — [source](https://www.mongodb.com/docs/manual/reference/command/configureQueryAnalyzer.md) - analyzeShardKey permits concurrent collection reads and writes, but non-blocking execution does not establish negligible resource cost. Secondary read preference is documented to reduce production impact; MongoDB also designed concurrent-workload performance tests. (medium confidence) — [source](https://www.alibabacloud.com/help/en/mongodb/product-overview/features-of-mongodb-7-0) - analyzeShardKey can evaluate a candidate or existing shard key for an unsharded or sharded collection; read/write distribution uses sampled workload queries collected through configureQueryAnalyzer. (medium confidence) — [source](https://www.mongodb.com/docs/manual/reference/command/analyzeShardKey.md) - A practical workflow is to enable query sampling with mode: "full" and samplesPerSecond, run representative workload, then analyze candidate keys. The analyzer can be disabled with mode: "off" after enough samples have been collected. (medium confidence) — [source](https://www.mongodb.com/docs/manual/reference/command/configureQueryAnalyzer.md) - Read and write distribution output describes query routing patterns and hotness of candidate shard-key ranges. It complements the cardinality, frequency and monotonicity metrics in keyCharacteristics. (medium confidence) — [source](https://www.mongodb.com/docs/manual/reference/command/analyzeShardKey.md) - Monitor query sampling with $currentOp and inspect stored samples using $listSampledQueries. Grouping those samples by cmdName lets an operator check the mix of captured commands before interpreting distribution results. (low confidence) — [source](https://www.mongodb.com/docs/manual/reference/command/configureQueryAnalyzer.md) - analyzeShardKey does not block collection reads or writes. MongoDB and Alibaba Cloud recommend secondary or secondaryPreferred read preference to reduce production impact; non-blocking behavior alone does not establish zero resource overhead. (medium confidence) — [source](https://www.mongodb.com/docs/manual/reference/command/analyzeShardKey.md)