analyzeShardKey and Workload Evidence for Prospective Keys

Learning objectives

1. analyzeShardKey turns key choice into measurable hypotheses

MongoDB 7.0+ provides analyzeShardKey for both sharded and unsharded collections in a replica-set/sharded deployment. It can return keyCharacteristics (cardinality, most-common-value frequency, uniqueness, monotonicity) and readWriteDistribution (how sampled reads/writes would target ranges under the candidate). The second family depends on representative query sampling; a synthetic five-second sample cannot stand in for a real production cycle.

2. Create candidate indexes and a skewed workload fixture

const app=db.getSiblingDB("atlasmart");sh.enableSharding("atlasmart", "atlasmart-shard17-l3-a");app.orders_analysis.drop();const docs=[];for (let i=1;i<=1200;i++) {  const tenant = i<=420 ? "mega" : `t${String(((i-421)%39)+1).padStart(2,"0")}`;  docs.push({orderId:`o-${String(i).padStart(5,"0")}`,tenantId:tenant,region:["EU","US","APAC"][i%3],createdSeq:i,status:i%4?"paid":"open"});}app.orders_analysis.insertMany(docs);app.orders_analysis.createIndex({region:1});app.orders_analysis.createIndex({tenantId:1});app.orders_analysis.createIndex({createdSeq:1});app.orders_analysis.createIndex({tenantId:1,orderId:1});printjson(app.orders_analysis.getIndexes());

3. Turn on sampling, run representative query shapes, and observe sampling state

const app=db.getSiblingDB("atlasmart");printjson(app.orders_analysis.configureQueryAnalyzer({mode:"full",samplesPerSecond:20}));for (let i=0;i<120;i++) {  app.orders_analysis.findOne({tenantId:i%3===0?"mega":"t07",status:"paid"});  if (i%4===0) app.orders_analysis.find({region:"EU"}).limit(5).toArray();  if (i%5===0) app.orders_analysis.findOne({orderId:`o-${String((i%100)+1).padStart(5,"0")}`});  if (i%6===0) app.orders_analysis.updateOne({tenantId:"mega",orderId:`o-${String((i%100)+1).padStart(5,"0")}`},{$set:{touched:true}});}sleep(1500);printjson(db.getSiblingDB("admin").aggregate([  {$currentOp:{allUsers:true,localOps:false}},  {$match:{desc:/query analyzer/i}},  {$project:{desc:1,ns:1,samplesPerSecond:1,sampledReadsCount:1,sampledWritesCount:1,startTime:1}}]).toArray());

The exact number of sampled operations can vary. The evidence you need is that sampling is enabled for the intended namespace and that the workload window contains the query shapes you intend to evaluate. For production, sample long enough to capture normal, peak, batch, and tenant-skew patterns.

4. Compare prospective keys with one consistent summary

const app=db.getSiblingDB("atlasmart");function summarize(name, result) {  const k=result.keyCharacteristics || {};  const r=result.readDistribution || {};  const w=result.writeDistribution || {};  printjson({    candidate:name,    distinct:k.numDistinctValues,    hottest:k.mostCommonValues?.[0],    monotonicity:k.monotonicity,    readSamples:r.sampleSize?.total,    singleShardReads:r.percentageOfSingleShardReads,    scatterReads:r.percentageOfScatterGatherReads,    writeSamples:w.sampleSize?.total,    singleShardWrites:w.percentageOfSingleShardWrites,    scatterWrites:w.percentageOfScatterGatherWrites  });}for (const [name,key] of [  ["region",{region:1}],  ["tenant",{tenantId:1}],  ["createdSeq",{createdSeq:1}],  ["tenant+order",{tenantId:1,orderId:1}],]) {  const result=app.orders_analysis.analyzeShardKey(key,{keyCharacteristics:true,readWriteDistribution:true,sampleRate:1});  summarize(name,result);}

Directional expectations: region has low cardinality; tenantId exposes the hot mega value; createdSeq should show monotonic behavior for this insertion pattern; and {tenantId,orderId} offers many distinct values while aligning with tenant-scoped order lookups. The exact sampled read/write percentages are workload evidence, not constants.

5. Controlled failure: remove the supporting index

const app=db.getSiblingDB("atlasmart");app.orders_analysis.dropIndex({region:1});try {  printjson(app.orders_analysis.analyzeShardKey({region:1},{keyCharacteristics:true,readWriteDistribution:false,sampleRate:1}));} catch (e) {  print(`Expected supporting-index error: ${e.codeName || e.message}`);}app.orders_analysis.createIndex({region:1});printjson(app.orders_analysis.configureQueryAnalyzer({mode:"off"}));

6. Production judgment

Store analyzer output beside workload metadata: sampling window, traffic mix, collection size, candidate indexes, tenant skew, read/write ratio, and deployment version. Re-run when workload or distribution changes. Analyzer metrics narrow the decision space; they do not estimate your future p99, operational skill, zone design, or resharding cost.

Bridge. Lesson 4 takes one key with a geographic prefix and uses zones to turn logical ranges into placement policy.

Authoritative references

• Choose a Shard Key — Cardinality, frequency, monotonicity, query patterns, and shard-key tradeoffs.
• Troubleshoot Shard Keys — Hot ranges, uneven load, jumbo/indivisible ranges, and scatter/gather symptoms.
• analyzeShardKey — Key-characteristic and sampled read/write-distribution metrics.
• configureQueryAnalyzer — Query sampling for prospective shard-key analysis.
• Hashed Indexes for Sharding — Write distribution and range-query limitations.
• Zones — Zone membership, non-overlapping zone ranges, prefix requirements, and balancing behavior.
• addShardToZone — Associate shards with zone labels.
• Change a Shard Key — Refine versus reshard decision boundary.
• Refine a Shard Key — Append suffix fields without changing existing shard-key field types.
• reshardCollection — Full shard-key change, redistribution phases, demo mode, and abort/commit boundaries.
• unshardCollection — MongoDB 8.0+ consolidation of a sharded collection onto one shard.
• moveCollection — MongoDB 8.0+ relocation of an unsharded collection between shards.
• MongoDB Sharding — Routing, ranges, balancer behavior, and mongos-only client access.
• MongoDB 8.3 Release Notes — Current 8.3 release and sharding/DDL changes.
• mongosh Release Notes — mongosh 2.10.0 baseline.
• PyMongo Release Notes — PyMongo 4.17 baseline.