Docs Menu
Docs Home
MongoDB Manual
/ /

Create Ranges in a Sharded Cluster

On this page

  • Learn More

In most situations a sharded cluster will create/split and distribute ranges automatically without user intervention. However, in a limited number of cases, MongoDB cannot create enough ranges or distribute data fast enough to support the required throughput.


Starting in MongoDB 6.0, you cannot pre-split ranges by creating empty ranges and have the balancer automatically distribute the ranges. Instead, do any of these:

For example, if you want to ingest a large volume of data into a cluster that is unbalanced, or where the ingestion of data will lead to data imbalance, such as with monotonically increasing or decreasing shard keys. Pre-splitting the ranges of an empty sharded collection can help with the throughput in these cases.

Alternatively, by defining the zones and zone ranges before sharding an empty or a non-existing collection, the shard collection operation creates ranges for the defined zone ranges as well as any additional ranges to cover the entire range of the shard key values and performs an initial range distribution based on the zone ranges. For more information, see Empty Collection.


Only pre-split ranges for an empty collection. Manually splitting ranges for a populated collection can lead to unpredictable range ranges and sizes as well as inefficient or ineffective balancing behavior.

To split empty ranges manually, you can run the split command:


To create ranges for documents in the myapp.users collection using the email field as the shard key, use the following operation in mongosh:

for ( var x=97; x<97+26; x++ ){
for ( var y=97; y<97+26; y+=6 ) {
var prefix = String.fromCharCode(x) + String.fromCharCode(y);
db.adminCommand( { split: "myapp.users", middle: { email : prefix } } );

This assumes a collection size of 100 million documents.

← Data Partitioning with Chunks

On this page