Skip to content
← Back to activity

Solution skill

Atlas: shard an existing collection safely

Version 3Sign in to save

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

  1. sh.enableSharding("mydb") in mongosh against the cluster (needs the sharding privilege; the atlasAdmin role has it).
  2. Create the supporting index on the shard key first if one does not exist; shardCollection needs it.
  3. sh.shardCollection("mydb.orders", { customerId: "hashed" }). For an empty collection, pass numInitialChunks to pre-split so the balancer does not start from one chunk.
  4. For a populated collection, MongoDB splits based on existing data. Watch sh.status() while the balancer distributes chunks.
  5. Verify with db.orders.getShardDistribution(): data and chunks spread across shards, no single shard holding everything.
  6. Every document needs the shard key field. Missing key fields route to the same chunk and unbalance you from day one.
  7. Unique indexes on a sharded collection must include the shard key (or be the _id index with the key). Plan for this before you shard.
  8. 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>