MongoDB / Advanced: distributed and recoverable operations / Lesson 15

Sharding and routing design

Choose shard keys from distribution, query targeting and lifecycle requirements. Understand scatter/gather work, unique-index scope and the cost of moving data.

About 4 min readContent reviewed 2026-10-25

On this page

Lesson goals

Explain shard, router and key responsibilities.
Evaluate range, hashed and compound key tradeoffs.

Sharding distributes data and operational responsibility

A sharded cluster distributes collection data across shards, with routers coordinating client operations and metadata identifying ownership. Each shard is commonly a replica set, so replication and sharding solve different dimensions of the system. Adding shards does not automatically split a hot single document or make every query targeted. Query fan-out, migrations, indexes and consistency choices still consume resources. Begin from data volume, tenant distribution, read shapes and write hotspots rather than treating sharding as a button that fixes every latency problem.

Compare keys without changing a cluster

These local objects describe two candidate shard-key patterns, not commands that enable sharding. A tenant-plus-time range key can align some tenant queries but may concentrate writes or create uneven tenants. A hashed component can improve distribution for suitable values while weakening useful contiguous range targeting. Cardinality, frequency and monotonic behavior matter together. The example prints only the proposed structures; it performs no cluster operation and no topology change. Real selection requires representative distribution and query evidence plus a reviewed migration plan.

javascript Illustrative mongosh; results are reasoned, not measured.

const tenantTime = { tenantId: 1, createdAt: 1 };
const hashedTenant = { tenantId: 'hashed' };
printjson(tenantTime);
printjson(hashedTenant);

Expected output

{ tenantId: 1, createdAt: 1 }
{ tenantId: "hashed" }

These are local design values only. No sharding administration command is issued.

The key must fit the query boundary

A query containing a useful shard-key equality or range can be targeted according to the key and routing metadata. A query missing the relevant key may contact many shards even when each shard has a good local index. A hashed key does not preserve ordinary value ranges as adjacent hashed ranges. Tenant isolation predicates remain necessary for authorization and can also assist routing when they align with the chosen key. Never remove required results or invent a tenant condition merely to make a plan look targeted.

Inspect the intended tenant range

The read below is a query pattern for a synthetic sharded collection whose shard key begins with tenantId. Its time interval is half-open and uses BSON dates with explicit UTC literals. Explain can reveal how work is distributed, but the actual shard count and chosen local access paths depend on a prepared fixture. A matching key prefix is a reason to investigate targeting, not a fabricated guarantee that exactly one shard is contacted after every split or migration. No deployment is contacted here.

javascript Illustrative mongosh; results are reasoned, not measured.

db.getSiblingDB('quay_lab').shipments.find({
  tenantId: 'training-a',
  createdAt: { $gte: ISODate('2026-10-01T00:00:00Z'), $lt: ISODate('2026-11-01T00:00:00Z') }
}).explain('queryPlanner');

Review router and per-shard plan context on an isolated deployment. No exact topology or timings are supplied.

Uniqueness and resharding are topology-aware

Unique indexes on sharded collections have shard-key-related restrictions; a unique index generally needs the shard key as a prefix under supported rules. If _id is not the shard key, its ordinary unique index does not by itself enforce global _id uniqueness across all shards, so the application needs a global identity strategy. Key refinement and resharding have distinct purposes and version-specific prerequisites. Balancing and migrations move data and can affect latency. Review backups, concern settings, collision rules and rollback evidence before any cluster restructuring.

Common errors and fixes

Adding shards does not relieve one hot document

Why it happens: The bottleneck remains one indivisible update target.
How to fix it: Revisit the document and contention model before topology expansion.
Prevent it next time: Measure hotspot distribution and atomicity requirements together.

A query fans out despite local indexes

Why it happens: Its predicates do not usefully constrain the routing key.
How to fix it: Inspect shard targeting and align legitimate query/model requirements.
Prevent it next time: Evaluate common queries before choosing a shard key.

A supposedly global unique key conflicts only locally

Why it happens: Sharded uniqueness restrictions were overlooked.
How to fix it: Design a supported global key strategy and audit existing data.
Prevent it next time: Review shard-key prefixes and _id scope before migration.

Check your understanding

1. A large tenant owns most writes. Does hashing tenantId alone necessarily distribute that tenant’s documents across shards?

Show worked solution

No. Equal tenantId values hash to the same key value, so hashing does not split one repeated tenant value into independent distribution. Analyze cardinality, frequency and additional key components against the actual query and write pattern. A key that spreads distinct tenants can still leave one dominant tenant hot. Choose a supported design from evidence rather than the word hashed.

2. Why can a query without a shard-key predicate remain expensive even with an index on every shard?