# Documentdb Sharding

> 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…

- **Type:** Skill
- **Install:** `agentstack add skill-azure-documentdb-agent-kit-sharding`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Azure](https://agentstack.voostack.com/s/azure)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Azure](https://github.com/Azure)
- **Source:** https://github.com/Azure/documentdb-agent-kit/tree/main/skills/sharding

## Install

```sh
agentstack add skill-azure-documentdb-agent-kit-sharding
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](sharding-when-to-shard.md) — 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.
- [sharding-shard-key-selection](sharding-shard-key-selection.md) — Read-heavy → pick the most frequent query filter to localize to one physical shard. Write-heavy → pick the highest-cardinality, evenly-distributed field. Avoid hot keys (monotonic IDs, timestamps, tenant IDs with skew).
- [sharding-logical-vs-physical](sharding-logical-vs-physical.md) — Mental model: logical shards are unbounded in count and size; physical shards are bounded by the cluster's compute/storage budget. Multiple logical shards map to one physical shard, never the reverse. Cross-shard transactions are supported but not free.
- [sharding-scaling-out-vs-up](sharding-scaling-out-vs-up.md) — Scale up (bigger tier / storage SKU) grows per-shard capacity without rebalancing; scale out (more physical shards) rebalances logical shards across the new layout. Read-heavy benefits from a bigger tier; write-heavy benefits from more shards or a bigger storage SKU.
- [sharding-hot-partition-diagnosis](sharding-hot-partition-diagnosis.md) — Symptoms (uneven CPU / IOPS / storage across shards) and remediation: reshard, change the key, or add a secondary high-cardinality field.
- [sharding-how-to-commands](sharding-how-to-commands.md) — `sh.shardCollection` / `db.adminCommand({ shardCollection: "db.collection", key: {...} })`, `sh.reshardCollection`, and the requirement to create an explicit index on the shard key (with `enableLargeIndexKeys: true`).
- [sharding-logical-shard-size-budget](sharding-logical-shard-size-budget.md) — Keep individual logical shards **below 4 TB** for best performance, even though the service imposes no hard cap.

## Quick decision flow

```
collection's expected size or throughput ≤ one physical shard's budget?
  ├─ yes → leave unsharded. Scale up if needed.
  └─ no  → shard.
            ├─ read-heavy?  → key = most frequent query filter
            └─ write-heavy? → key = highest-cardinality, evenly distributed field
```

## References

- [Sharding for horizontal scalability in Azure DocumentDB](https://learn.microsoft.com/azure/documentdb/partitioning)
- [Compute and storage in Azure DocumentDB](https://learn.microsoft.com/azure/documentdb/compute-storage)
- Related: `indexing/` (index on the shard key), `query-optimization/` (single-shard vs scatter-gather queries), `high-availability/` (replica sets within each physical shard)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Azure](https://github.com/Azure)
- **Source:** [Azure/documentdb-agent-kit](https://github.com/Azure/documentdb-agent-kit)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-azure-documentdb-agent-kit-sharding
- Seller: https://agentstack.voostack.com/s/azure
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.