documentdb-sharding

name	documentdb-sharding
description	Horizontal sharding (partitioning) for Azure DocumentDB collections — when to shard vs stay single-shard, how to pick a shard key for read-heavy vs write-heavy workloads, the logical/physical shard mental model, scaling out vs scaling up, hot-partition diagnosis, and the `sh.shardCollection` / `sh.reshardCollection` commands. Use when deciding whether to shard a collection, choosing or changing a shard key, sizing a cluster, or troubleshooting uneven storage / throughput across physical shards.
license	MIT

Sharding — Azure DocumentDB

Azure DocumentDB shards collections horizontally by hashing a shard key from each document and bucketing documents into logical shards, which the service then maps onto physical shards (the actual nodes that store data and serve traffic). The service hides the placement: you pick a shard key, the service handles the hash range and rebalancing.

The decisions that you own:

1. Whether to shard at all. Sharding is not the default and is not always the right answer — single-shard clusters scale up vertically and avoid the cross-shard tax.
2. What to shard on. The shard key is the single biggest determinant of long-term performance. It can be changed later (sh.reshardCollection), but only at significant cost once the collection is large.
3. How big each physical shard should be. The cluster tier and storage SKU set the CPU / memory / IOPS budget per physical shard, and that's what your shard key needs to fit inside.

Rules

• sharding-when-to-shard — Default to single-shard. Shard only when a collection's storage or transaction volume can exceed one physical shard's budget (e.g., > 32 TB on the largest storage SKU). Sharded and unsharded collections can coexist.