MongoDB Sharding

What You’ll Learn

Sharding lets MongoDB spread a large collection across multiple machines so no single server holds all the data or handles all the traffic. This guide explains the architecture, how to choose a shard key, and the admin commands you run from mongos.

Definition and Usage

Sharding is MongoDB’s approach to horizontal scaling: instead of making one server bigger (vertical scaling), you add more servers and partition data so each shard stores a subset of documents.

Each shard is usually a replica set (primary + secondaries) for high availability. A sharded cluster also includes config servers (cluster metadata) and one or more mongos routers. On MongoDB Atlas, you can enable sharding on a cluster without managing these components yourself.

Sharding is an operational scaling topic—distinct from aggregation pipeline stages or query operators, but essential when datasets outgrow a single replica set.

🏗️ Sharded cluster components

A typical flow: the app sends find({ userId: "U42" }) to mongos → mongos consults config metadata → routes the query to the shard owning the chunk where userId: "U42" lives → returns merged results to the client.

📝 Syntax

Sharding setup runs on a mongos connection with cluster admin privileges. The two core steps are enabling sharding on a database, then sharding a collection with a shard key:

// 1) Enable sharding on a database
sh.enableSharding("<database>");

// 2) Shard a collection with a shard key index
sh.shardCollection(
  "<database>.<collection>",
  { <shardKeyField>: 1 }          // ranged (ascending)
  // { <shardKeyField>: "hashed" }  // hashed
);

// 3) Inspect cluster state
sh.status();

Syntax Rules

• Run on mongos — sh.* helpers are unavailable on a standalone mongod.
• Shard key index required — the collection must have an index that starts with the shard key fields before sh.shardCollection.
• Immutable choice — the shard key cannot be changed on a sharded collection; plan before sharding.
• Hashed vs ranged — hashed keys spread writes evenly; ranged keys preserve range queries on the prefix.
• Unique indexes — must include the shard key as a prefix (except _id alone on non-sharded collections).
• Empty or small collections — easiest to shard before heavy traffic; large live migrations need more planning.

// Connect: mongosh "mongodb://mongos-host:27017"

sh.enableSharding("shop");
sh.shardCollection("shop.orders", { orderId: "hashed" });
sh.status(true);

Examples Gallery

An e-commerce shop.orders collection—enable sharding, pick keys, and verify cluster health. Commands assume a connected mongos shell.

use shop;

db.orders.insertMany([
  { orderId: "ORD-1001", customerId: "C10", region: "US", amount: 49.99, createdAt: ISODate("2025-06-01") },
  { orderId: "ORD-1002", customerId: "C22", region: "EU", amount: 120.00, createdAt: ISODate("2025-06-02") },
  { orderId: "ORD-1003", customerId: "C10", region: "US", amount: 15.50, createdAt: ISODate("2025-06-03") },
  { orderId: "ORD-1004", customerId: "C88", region: "APAC", amount: 300.00, createdAt: ISODate("2025-06-04") }
]);

// Index before sharding (required)
db.orders.createIndex({ orderId: 1 });

// Run on mongos with clusterAdmin role
sh.enableSharding("shop");

/* MongoDB marks the shop database as sharding-enabled.
   Individual collections are sharded separately next. */
sh.status();

sharding version: { ... }
databases:
  { _id: "shop", partitioned: true, ... }

// Hashed keys distribute inserts across shards
sh.shardCollection("shop.orders", { orderId: "hashed" });

// Targeted lookup by full shard key
db.orders.find({ orderId: "ORD-1002" });

/* orderId values hash to different chunks →
   writes spread evenly; ideal for UUID/order-id workloads */

Collection shop.orders sharded.
Chunks distributed across shardA, shardB, ...

// New collection — choose key BEFORE sharding
db.events.createIndex({ region: 1, createdAt: 1 });

sh.shardCollection("shop.events", { region: 1, createdAt: 1 });

// Targeted query (uses shard key prefix)
db.events.find({
  region: "US",
  createdAt: { $gte: ISODate("2025-06-01"), $lt: ISODate("2025-07-01") }
});

/* mongos routes to shard(s) owning US + June chunks only */

Range queries on { region, createdAt }
→ targeted shard routing (not scatter-gather)

sh.status(true);

sh.getBalancerState();   // true when balancer migrates chunks
sh.isBalancerRunning();  // in-progress migration check

// Per-collection chunk distribution
use config;
db.chunks.find({ ns: "shop.orders" }).countDocuments();

• Each shard listed with replica set members
• Chunk counts roughly balanced
• Balancer enabled (unless maintenance window)
• No jumbo chunks blocking splits

📝 Notes

• Shard key is permanent for a sharded collection—design and load-test before production sharding.
• Monotonic keys (auto-increment, timestamps alone) on ranged sharding can create a hot shard; prefer hashed keys or compound keys with high-cardinality leading fields.
• Scatter-gather queries without the shard key do not scale linearly—every shard must participate.
• Each shard is a replica set—sharding adds scale; replication within each shard adds failover.
• Transactions across many shards are supported but have higher overhead than single-shard transactions.
• Atlas handles mongos, config servers, and balancer for you on sharded tiers—ideal for learning without building a full cluster locally.
• Previous topic: Replication. Next: Aggregation Stages.

💡 Best Practices