- Clusters >
- Global Clusters >
- Global Cluster Sharding Reference
Global Cluster Sharding Reference¶
On this page
The following sections describe sharding behavior and how to enable sharding for Global Clusters.
Sharding Collections for Global Writes¶
Unsharded collections must meet the following compatibility requirements prior to sharding to utilize Global Writes when sharded:
- Every document in the collection must include a
location
field. - The value of the
location
field must be either an ISO-3166-1 alpha 2 country code ("US"
,"DE"
,"IN"
) or a supported ISO-3166-2 subdivision code ("US-DC"
,"DE-BE"
,"IN-DL"
). Documents that do not match this criteria can be routed to any shard in the cluster. To view the complete list of currently supported country or subdivision codes, visit https://cloud.mongodb.com/static/atlas/country_iso_codes.txt.
For collections that meet the stated requirements, you must shard the collection using the following pattern:
A shard key on the location
field alone may result in bottlenecks,
especially for workloads where a subset of countries or subdivisions
receive the majority of write operations. Atlas Global Writes
requires a compound shard key
to facilitate efficient distribution of sharded data across the cluster.
Atlas Global Cluster shard keys share the same restrictions as
MongoDB shard keys; for example, the secondary shard key field cannot
be an array.
For guidance on choosing a secondary shard key field and the effect of shard key choice on data distribution, see Choosing a Shard Key. For complete documentation on shard key limitations, see Shard Key Limitations.
Important
You cannot easily change the shard key after sharding, nor can you modify the value of shard key fields in any document in the sharded collection.
The Atlas Data Explorer supports creating sharded collections with specific validations for Global Writes. For complete documentation, see Shard a Collection for Global Writes in Data Explorer.
You can also use the mongo
shell to execute the
sh.shardCollection()
. After sharding
the collection, you must use the Atlas Data Explorer
to enable Global Writes for that collection. For complete
documentation on sharding collections via the Data Explorer,
see Shard a Collection for Global Writes in Data Explorer.
Error Handling¶
If Atlas encounters an error while sharding a collection for global writes, a message appears in the banner at the top of the screen.

Click the See Details button for more information about the error. A modal window appears with the complete error message and a Fix Now button:

Clicking the Fix Now button takes you to the Data Explorer, where you can request to cancel the sharding operation. After making any necessary changes to the collection as indicated by the error message, you can start the sharding process again.
Possible errors include the following:
- An index already exists on the custom shard key. If the field chosen as the second part of the compound shard key is already indexed, the sharding operation may fail.
- The shard key field is not present. All documents in the collection must contain both the shard key fields.
- The collection is already sharded. If the collection has already been manually sharded, the operation will fail.
- The collection has a custom default collation. A custom default collation on the collection may cause a sharding error.
Global Cluster Write Operations¶
Each write to a sharded collection must include the shard key for the
operation to succeed. For each document in a write operation, MongoDB
uses the location
field of the shard key to determine the zone to
which to route the data. MongoDB selects a shard associated to that zone
as the target for writing the document, facilitating geographically
isolated and segmented data storage.
MongoDB can only guarantee this behavior for inserted documents that
meet the criteria defined in Sharding Collections for Global Writes.
Specifically, MongoDB can route a document whose location
field does
not conform to
ISO-3166-1 alpha 2 or
ISO-3166-2 to any shard
in the cluster.
Global Cluster Read Operations¶
MongoDB query routing depends on whether the read operation
includes the full shard key and that the location
value
corresponds to a supported
ISO-3166-1 alpha 2
country code ("US"
, "DE"
, "IN"
) or a supported
ISO-3166-2
subdivision code ("US-DC"
, "DE-BE"
, "IN-DL"
).
For queries that do include the full shard key and whose location
value meets the requirements for Global Writes, MongoDB targets
the read operation to the zone which maps to the location
value or
values specified in the query.
For read operations that do not include the full shard key, or if the
location
value does not correspond to a supported
ISO-3166-1 alpha 2
country code or ISO-3166-2
subdivision code,
MongoDB must broadcast the read operation to every zone in the cluster.
For Global Writes zones which have Read-only nodes
in geographically distant regions, clients in those regions can
query the local Read-only node for that zone by specifying
the full shard key as part of the query and issuing the
read operation with a Read Preference
of nearest
.
Important
Secondary reads may return stale data depending on the level of replication lag between the secondary node and the primary. For complete documentation on MongoDB read preference, see Read Preference.
See also
For more information on MongoDB query routing, see mongos.
Sharding Collections without Global Writes¶
Global Writes clusters support the same Ranged and Hashed sharding strategies as a standard Atlas sharded cluster. For sharded collections whose shard keys and document schema do not support Global Writes, MongoDB distributes the sharded data evenly across the available shards in the cluster with respect to the chosen shard key. Consider using a separate sharded cluster for data that cannot take advantage of Global Writes functionality.
You cannot modify a collection to support Global Writes after sharding. Consider whether you might want to use Global Writes for a collection in the future before choosing an incompatible shard key. For more information on Global Writes sharding requirements, see Sharding Collections for Global Writes.
Unsharded Collections in Global Write Clusters¶
Global Clusters provide the same support for unsharded
collections as a standard Atlas sharded cluster. For each database
in the cluster, MongoDB stores its unsharded collections on a
primary shard. Use sh.status()
from
the mongo
shell to determine the primary shard for the
database.
Important
Atlas does not support the movePrimary
command for
moving the primary shard for a database. If you require assistance
with changing the primary shard of a database, contact Atlas
support by clicking the Support link in the left hand
navigation of the Atlas UI.