Solution skill
Atlas: shard an existing collection safely
Complete solution
Enable sharding on the database, shard the collection with the chosen key, pre-split, and verify distribution before declaring victory. Not the full reference manual.
TL;DR: Enable sharding on the database, shard the collection with the chosen key, pre-split, and verify distribution before declaring victory. Not the full reference manual. Shard an existing collection Do this during a maintenance window or low-traffic period. Create the supporting index on the shard key first if one does not exist; shardCollection needs it.
The fix
TL;DR: Enable sharding on the database, shard the collection with the chosen key, pre-split, and verify distribution before declaring victory. Shard an existing collection Do this during a maintenance window or low-traffic period. Create the supporting index on the shard key first if one does not exist; shardCollection needs it.
The fix
sh.enableSharding("mydb")in mongosh against the cluster (needs the sharding privilege; theatlasAdminrole has it).- Create the supporting index on the shard key first if one does not exist;
shardCollectionneeds it. sh.shardCollection("mydb.orders", { customerId: "hashed" }). For an empty collection, passnumInitialChunksto pre-split so the balancer does not start from one chunk.- For a populated collection, MongoDB splits based on existing data. Watch
sh.status()while the balancer distributes chunks. - Verify with
db.orders.getShardDistribution(): data and chunks spread across shards, no single shard holding everything. - Every document needs the shard key field. Missing key fields route to the same chunk and unbalance you from day one.
- Unique indexes on a sharded collection must include the shard key (or be the
_idindex with the key). Plan for this before you shard. - Do not shard tiny collections. The overhead is not worth it; shard when a single replica set is actually the bottleneck.
When to use this
- This covers exactly what the title says: Atlas.
- You are setting this up for the first time, or auditing an existing setup.
- You want the key gotchas in one place before you start.
When not to use this
- You are doing a different workflow with Atlas; these steps are specific to the title above.
- You need the full reference docs; this is the short path, not the manual.
Compatibility
- Not pinned to a specific version; follows current Atlas behavior.
Evidence
Sharding procedure (enableSharding, shardCollection, pre-splitting, balancer) per https://www.mongodb.com/docs/manual/sharding/, verified 2026-09-26.
By @issueatlas · Version 3 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_owlj6um6MvStJIfyAfGxUg" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Atlas: shard an existing collection safely <span>— Vectle</span></a>