> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# Shard a Global Collection for Global Writes

**Important:**

The feature described on this page is not currently supported on Atlas Infinite clusters during public preview. For the features supported in public preview, see [Public Preview Availability.](https://www.mongodb.com/docs/atlas/infinite/atlas-infinite-landing/#public-preview-availability)

**Important: Feature unavailable in Flex Clusters**

Flex clusters don't support this feature at this time. To learn more, see [Atlas Flex Limitations.](https://www.mongodb.com/docs/atlas/reference/flex-limitations.md#std-label-flex-cluster-limitations)

## Shard a Global Collection for Global Writes in the Atlas UI

Sharding a collection through the Atlas UI is an exception that applies only to Global Writes collections. For all other collections, you must shard using [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh) or application code. To learn more, see [Shard a Collection.](https://www.mongodb.com/docs/atlas/atlas-ui/collections.md#std-label-atlas-ui-shard-collection)

**Note:**

- Global writes are only supported on global clusters, which require an `M30+` cluster tier.

- When Global Writes are enabled, Global Clusters do not support dedicated search nodes.

- You can use the Atlas UI to shard a global collection only for global clusters with [Atlas-Managed Sharding](https://www.mongodb.com/docs/atlas/tutorial/create-global-cluster/#select-your-sharding-configuration) enabled.

- This document assumes prior knowledge of sharding semantics. Review the [Sharding documentation](https://www.mongodb.com/docs/manual/sharding/) before continuing with this tutorial.

In sharded clusters, you can create [zones](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-zone) of sharded data based on the [shard key](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-shard-key). Your zones can segment data based on geographic area. To learn more about sharding based on geographic area, see [Segmenting Data by Location.](https://www.mongodb.com/docs/manual/tutorial/sharding-segmenting-data-by-location/)

The Atlas UI supports sharding Global Write collections for only global clusters that use [Atlas-Managed Sharding](https://www.mongodb.com/docs/atlas/tutorial/create-global-cluster/#select-your-sharding-configuration). To shard non-Global-Write collections or Global Write collections that use Self-Managed Sharding, you must use [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh) or application code. To learn more, see [Deploy a Sharded Cluster.](https://www.mongodb.com/docs/manual/tutorial/deploy-shard-cluster/)

### Required Access

You must have the [`Project Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Project-Owner)  or [`Organization Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Organization-Owner) role for the cluster's Atlas project to shard a collection for Global Writes in the Atlas UI.

### Considerations

Before starting this procedure, review:

- [Compatibility requirements](https://www.mongodb.com/docs/atlas/shard-global-collection.md#std-label-global-writes-collections) for a Global Cluster.

- [Atlas Limits](https://www.mongodb.com/docs/atlas/reference/limitations.md#std-label-atlas-limitations) for Global Cluster shard keys.

On Atlas Core clusters, you can configure [Online Archive](https://www.mongodb.com/docs/atlas/online-archive/overview.md#std-label-online-archive-overview) to move infrequently accessed data from your Atlas cluster to a MongoDB-managed read-only federated database instance instead of sharding your collection or upgrading your cluster tier. On Atlas Infinite clusters, Online Archive is not supported in public preview. To learn more about Online Archive, see [Manage Online Archives in Atlas.](https://www.mongodb.com/docs/atlas/online-archive/manage-online-archive.md#std-label-manage-online-archive)

After selecting a shard key via the Atlas UI, Atlas attempts to shard the target collection. During this period, ensure that no user manually shards the collection. If Atlas detects that the target collection was sharded with a different key than the one selected via the Atlas UI, Atlas stops the procedure and displays a warning for that collection in the Atlas UI. You can click Unmanage Collection to clear the warning. This action removes the collection from Atlas management while leaving the underlying collection and the manually chosen shard key intact.

#### Update the Shard Key Value

You can update a document's shard key value unless the shard key field is the immutable `_id` field. To learn more, see [Change a Document's Shard Key Value.](https://www.mongodb.com/docs/manual/core/sharding-shard-key/#change-a-document-s-shard-key-value)

In MongoDB earlier to 6.0, you can't update the value of a shard key field in an existing document in a Global Writes-enabled collection.

**Important: Shard Key Values and Global Clusters**

In all MongoDB versions, you can't [reshard a collection](https://www.mongodb.com/docs/manual/core/sharding-reshard-a-collection/) on a Global Cluster. To learn more, see [Sharding Collections for Global Writes.](https://www.mongodb.com/docs/atlas/shard-global-collection.md#std-label-global-writes-collections)

### Procedure

To shard a collection in a Global Cluster:

1. In Atlas, go to the Data Explorer page for your project.

   If it's not already displayed, select the organization that contains your project from the  Organizations menu in the navigation bar.

   If it's not already displayed, select your project from the Projects menu in the navigation bar.

   In the sidebar, click Data Explorer under the Database heading.

   The [Data Explorer](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fmetrics%2FreplicaSet%2F%3Creplset%3E%2Fexplorer) displays.

   IMPORTANT: You can also click the name of a cluster to open the Cluster sidebar, and then click Data Explorer under the Shortcuts heading.

2. Click the collection that you want to shard.

3. Click the Global Writes tab.

4. Enter the second field of the compound shard key in Second shard key field.

5. Expand Advanced Shard Key Configuration section to specify how to shard the collection.

   You can choose one of the following options:

   | Default | Atlas uses the document that specifies the field or fields as the [shard key.](https://www.mongodb.com/docs/manual/core/sharding-shard-key/) |
   | --- | --- |
   | Use unique index as the shard key | Atlas uses the underlying index to enforce a unique constraint on the shard key of the Global Collection. |
   | Use hashed index as the shard key | Atlas distributes the sharded data evenly by hashing the second field of the shard key. You can optionally select Pre-split data for even distribution to specify whether to perform initial chunk creation and distribution for an empty or non-existing collection based on the defined zones and zone ranges for the collection. If you select the Pre-split data for even distribution option, you can also specify the minimum number of chunks to create initially when sharding an empty collection with a [hashed shard key](https://www.mongodb.com/docs/manual/core/hashed-sharding/). Initial chunk distribution allows Atlas to setup zoned sharding quickly. The number of chunks the Atlas creates depends on the number of zones that you define. By default, Atlas creates one chunk per location code and distributes chunks evenly across all shards. |

   To learn more about these options, see [Global Cluster Sharding Reference.](https://www.mongodb.com/docs/atlas/shard-global-collection.md#std-label-global-cluster-sharding)

6. Click Shard Collection.

Atlas displays the compound shard key near the top of the Global Writes tab after configuring the collection.

## Global Cluster Sharding Reference

The following sections describe [sharding](https://www.mongodb.com/docs/manual/sharding/) behavior and how to enable sharding for [Manage Global Clusters.](https://www.mongodb.com/docs/atlas/global-clusters.md#std-label-global-clusters)

### Sharding Collections for Global Writes

For global clusters with [Atlas-Managed Sharding](https://www.mongodb.com/docs/atlas/tutorial/create-global-cluster/#select-your-sharding-configuration) enabled, unsharded collections must meet the following compatibility requirements *prior to sharding* to use 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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code (`"US"`, `"DE"`, `"IN"`) *or* a supported [ISO-3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) subdivision code (`"US-DC"`, `"DE-BE"`, `"IN-DL"`). Documents that don't match this criteria can't be routed to any shard in the cluster. To view the complete list of currently supported country or subdivision codes, see [https://cloud.mongodb.com/static/atlas/country\_iso\_codes.txt.](https://cloud.mongodb.com/static/atlas/country_iso_codes.txt)

A shard key on the `location` field alone might 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](https://www.mongodb.com/docs/manual/core/index-compound/) to facilitate the efficient distribution of sharded data across the cluster. Atlas Global Cluster shard keys share the same restrictions as MongoDB shard keys. The following Atlas Global Cluster limitations apply:

- The first field of the compound shard key must be `location` and *can't* be hashed.

- There can only be one secondary shard key field in a compound shard key.

- The secondary shard key field of a compound shard key *can* be hashed.

- The secondary shard key field *can't* be an array.

To learn more about:

- Choosing a secondary shard key field and the effect of shard key choices on data distribution, see [Choosing a Shard Key.](https://www.mongodb.com/docs/manual/core/sharding-choose-a-shard-key.md#std-label-sharding-shard-key-selection)

- Shard key limitations, see [Shard Key Limitations.](https://www.mongodb.com/docs/manual/reference/limits.md#std-label-limits-shard-keys)

- Available hashed sharding options, see [Hashed Sharding Options.](https://www.mongodb.com/docs/atlas/shard-global-collection.md#std-label-global-writes-initial-chunks)

**Important: Changing the Shard Key**

After sharding, what you can modify depends on the version of MongoDB that you run:

| MongoDB Version | Modify Shard Key Keys | Modify Shard Key Values |
| --- | --- | --- |
| MongoDB 7.0 | Yes, add fields to a key using the [Atlas UI](https://www.mongodb.com/docs/atlas/atlas-ui.md#std-label-atlas-ui) only. | Yes |
| MongoDB 8.0 | Yes, add fields to a key using the [Atlas UI](https://www.mongodb.com/docs/atlas/atlas-ui.md#std-label-atlas-ui) only. | Yes |

In all MongoDB versions, you can't [reshard a collection](https://www.mongodb.com/docs/manual/core/sharding-reshard-a-collection/) on a Global Cluster.

The [Atlas UI](https://www.mongodb.com/docs/atlas/atlas-ui.md#std-label-atlas-ui) supports creating sharded collections with specific validations for Global Writes. To learn more, see [Shard a Global Collection for Global Writes in the Atlas UI.](https://www.mongodb.com/docs/atlas/shard-global-collection.md#std-label-de-shard-collection-for-global-writes)

You can also use [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh) to execute the [`sh.shardCollection()`](https://www.mongodb.com/docs/manual/reference/method/sh.shardCollection.md#mongodb-method-sh.shardCollection). After sharding the collection, you must use the [Atlas UI](https://www.mongodb.com/docs/atlas/atlas-ui.md#std-label-atlas-ui) to enable Global Writes for that collection.

WARNING: If you shard a collection that already has a MongoDB Search index, you might experience a brief period of incomplete search results while the index is building on a shard. Also, if you add a shard for an already sharded collection that contains a MongoDB Search index, your search queries against that collection might return incomplete results until the initial sync process completes on the added shards. To learn more, see [initial sync process.](https://www.mongodb.com/docs/search/performance/index-performance.md#std-label-troubleshoot-initial-sync)

To learn more about sharding collections via the Atlas UI, see [Shard a Global Collection for Global Writes in the Atlas UI.](https://www.mongodb.com/docs/atlas/shard-global-collection.md#std-label-de-shard-collection-for-global-writes)

#### Hashed Sharding Options

Shard keys use [hashed sharding](https://www.mongodb.com/docs/manual/core/hashed-sharding/) and pre-split data for even distribution.

Atlas distributes the sharded data evenly by hashing the second field of the shard key if you perform one of the following actions:

- Enable the use of the hashed index shard keys by selecting Use hashed index as the shard key in the [Atlas UI.](https://www.mongodb.com/docs/atlas/shard-global-collection.md#std-label-de-shard-collection-for-global-writes)

- Set `isCustomShardKeyHashed` through the [API.](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-creategroupclusterglobalwritemanagednamespace)

You can optionally specify whether to perform initial chunk creation and distribution for an empty or non-existing collection. This action is based on the defined zones and zone ranges for the collection. To do this, perform one of the following actions:

- Select Pre-split data for even distribution in the [Atlas UI.](https://www.mongodb.com/docs/atlas/shard-global-collection.md#std-label-de-shard-collection-for-global-writes)

- Set `presplitHashedZone` using the [API.](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-creategroupclusterglobalwritemanagednamespace)

When you create a sharded collection using a compound hashed shard key for Global Clusters, Atlas creates at least 1 chunk per location [code](https://cloud.mongodb.com/static/atlas/country_iso_codes.txt) and attempts to distribute chunks evenly across shards in the cluster.

You can also specify the minimum number of chunks to create initially when sharding an empty collection with a [hashed shard key](https://www.mongodb.com/docs/manual/core/hashed-sharding/) using the [Atlas UI](https://www.mongodb.com/docs/atlas/shard-global-collection.md#std-label-de-shard-collection-for-global-writes) or by setting the `numInitialChunks` parameter through the [API.](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-creategroupclusterglobalwritemanagednamespace)

**Note:**

If you specify the number of chunks per shard, Atlas creates at least the minimum number of chunks that you specified, with the same number of chunks per location code. If you specify the minimum number of chunks, Atlas sets up zoned sharding quickly, especially if you already know how to geographically distribute your data before sharding.

### 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.

1. Click See Details to learn about the error and the namespace where the error occurred. A modal window appears with the complete error message and a Fix Now button.

2. Click Close and navigate to the collection in the Atlas UI. You can also click the Fix Now button to go to the Atlas UI for that Atlas cluster.

3. Click the Global Writes tab for the collection mentioned in the error message.

4. Click Unmanage Collection to cancel the global writes sharding operation. You must have the [`Project Data Access Admin`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Project-Data-Access-Admin) role to cancel the sharding operation.

After you make any necessary changes to the collection as indicated by the error message, you can start the sharding process again.

Possible errors include:

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 collection is already sharded.

If the collection has already been manually sharded, the operation fails.

The collection has a custom default collation.

A [custom default collation](https://www.mongodb.com/docs/manual/reference/collation/) on the collection may cause a sharding error.

#### Global Cluster Write Operations

For each document in a write operation, MongoDB uses the `location` field of the shard key (if included) to determine the zone to route the data to. MongoDB selects a shard associated to that zone as the target for writing the document, facilitating geographically isolated and segmented data storage.

**Warning:**

If a shard key isn't included in the write operation, or a shard key is included, but the `location` field isn't present, the write operation will succeed, but the resulting documents will not be distributed.

MongoDB can guarantee this behavior only for inserted documents that meet the criteria defined in [Sharding Collections for Global Writes](https://www.mongodb.com/docs/atlas/shard-global-collection.md#std-label-global-writes-collections). Specifically, MongoDB can route a document whose `location` field doesn't conform to [ISO-3166-1 alpha 2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) *or* [ISO-3166-2](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code (`"US"`, `"DE"`, `"IN"`) *or* a supported [ISO-3166-2](https://en.wikipedia.org/wiki/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 that maps to the `location` value or values specified in the query.

- For read operations that don't include the `location` value , or if the `location` value doesn't correspond to a supported [ISO-3166-1 alpha 2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code or [ISO-3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) subdivision code, MongoDB must broadcast the read operation to every zone in the cluster.

- For Global Writes zones that 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](https://www.mongodb.com/docs/manual/core/read-preference/) of [`nearest`.](https://www.mongodb.com/docs/manual/core/read-preference.md#mongodb-readmode-nearest)

**Important:**

Secondary reads might return stale data depending on the level of replication lag between the secondary node and the primary.

To learn more, see [MongoDB Read Preference](https://www.mongodb.com/docs/manual/core/read-preference/) and [MongoDB Query Routing.](https://www.mongodb.com/docs/manual/core/sharded-cluster-query-router/)

### Sharding Collections without Global Writes

Global Writes clusters support the same [Ranged](https://www.mongodb.com/docs/manual/core/ranged-sharding/) and [Hashed](https://www.mongodb.com/docs/manual/core/hashed-sharding/) sharding strategies as a standard Atlas sharded cluster. For sharded collections whose shard keys and document schema don't support Global Writes, MongoDB distributes the sharded data evenly across the available shards in the cluster with respect to the chosen [shard key](https://www.mongodb.com/docs/manual/core/sharding-shard-key/). Consider using a separate sharded cluster for data that can't take advantage of Global Writes.

You can't modify a collection to support Global Writes after sharding. We recommend that you choose a shard key that will allow you to use Global Writes for a collection in the future.

**See also:**

To learn more about Global Writes sharding requirements, see [Sharding Collections for Global Writes.](https://www.mongodb.com/docs/atlas/shard-global-collection.md#std-label-global-writes-collections)

### 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](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary-shard). Use [`sh.status()`](https://www.mongodb.com/docs/manual/reference/method/sh.status.md#mongodb-method-sh.status) from [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh) to determine the primary shard for the database.