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

# Query using Pre-Defined Replica Set Tags

**Note:**

This feature is available for `M10` clusters or higher. To learn more about which features are available for Free clusters, see [Atlas Free Cluster Limits](https://www.mongodb.com/docs/atlas/reference/free-shared-limitations.md#std-label-atlas-free-tier), and for Flex clusters, see [Atlas Flex Limitations.](https://www.mongodb.com/docs/atlas/reference/flex-limitations.md#std-label-flex-cluster-limitations)

Atlas clusters are configured with pre-defined replica set tags for different member types in the cluster. You can utilize these pre-defined replica set tags to direct queries from specific applications to specific node types, regions, and availability zones. These pre-defined replica set tags allow you to customize [read preferences](https://www.mongodb.com/docs/manual/core/read-preference/) for a replica set, thus improving cluster performance and reliability.

**Note:**

This page applies to both Atlas Infinite and Atlas Core.

**Note:**

These pre-defined replica set tags differ from the [resource tags](https://www.mongodb.com/docs/atlas/tags.md#std-label-configure-resource-tags) that you provide and manage. You can't change these replica set tags that Atlas provides.

To use pre-defined replica set tags in your connection string and direct queries to specific nodes, use the following connection string options:

- `readPreference`

- `readPreferenceTags`

- `readConcernLevel`

For examples, see [Use Cases and Examples.](https://www.mongodb.com/docs/atlas/reference/replica-set-tags.md#std-label-repl-set-tag-examples)

## Pre-Defined Replica Set Tag Descriptions

The following table describes the pre-defined replica set tags that Atlas provides.

| Pre-Defined Tag Name | Description | Example |
| --- | --- | --- |
| Availability Zone | AWS (Amazon Web Services) availability zone ID, Google Cloud fully-qualified name for a zone, or Azure (Microsoft Azure) zone number. Azure (Microsoft Azure) supports availability zones only in a subset of regions. Atlas provides pre-defined availability zone tags for Azure (Microsoft Azure) only for regions that support availability zones. To learn more, see [Microsoft Azure.](https://www.mongodb.com/docs/atlas/reference/microsoft-azure.md#std-label-microsoft-azure) For more information about the possible `availabilityZone` values for each cloud provider, see the cloud provider's documentation: [AWS](http://docs.aws.amazon.com/ram/latest/userguide/working-with-az-ids.html); [GCP](https://cloud.google.com/compute/docs/regions-zones); [Azure](https://docs.microsoft.com/en-us/azure/reliability/availability-zones-overview) | AWS (Amazon Web Services): `{"availabilityZone" : "us-east-1a"}`; Google Cloud: `{"availabilityZone" : "us-east1-b"}`; Azure (Microsoft Azure): `{"availabilityZone" : "1"}` |
| Node Type | Node type. Possible values are: `ELECTABLE`; `READ_ONLY`; `ANALYTICS` For more information, see [Node Types.](https://www.mongodb.com/docs/atlas/reference/replica-set-tags.md#std-label-repl-set-node-types) | `{"nodeType" : "ANALYTICS"}` |
| Provider | Cloud provider on which the node is provisioned. Possible values are: `AWS`; `GCP`; `AZURE` | `{"provider" : "AWS"}` |
| Region | Cloud region in which the node resides. For a complete list of possible `region` values, see the reference page for your cloud provider: [AWS](https://www.mongodb.com/docs/atlas/reference/amazon-aws.md#std-label-amazon-aws); [GCP](https://www.mongodb.com/docs/atlas/reference/google-gcp.md#std-label-google-gcp); [Azure](https://www.mongodb.com/docs/atlas/reference/microsoft-azure.md#std-label-microsoft-azure) | `{"region" : "US_EAST_2"}` |
| Workload Type | Pre-defined replica set tag to distribute your workload evenly among your non-analytics (electable or read-only) nodes. Possible values are: `OPERATIONAL` | `{"workloadType" : "OPERATIONAL"}` |
| Disk State | State of your disk. Possible value: `READY` For more information, see [Disk States.](https://www.mongodb.com/docs/atlas/reference/replica-set-tags.md#std-label-repl-set-disk-states) | `{"diskState" : "READY"}` |

### Disk States

The following table describes the possible `diskState` values in your pre-defined replica set tags.

| Disk State | Description |
| --- | --- |
| `READY` | Only target warm nodes. You can run queries without experiencing increased or unpredictable latency. |

For an example of this replica set tag, see [Reduce Secondary Disk Warming Impact.](https://www.mongodb.com/docs/atlas/reference/replica-set-tags.md#std-label-reduce-secondary-disk-warming-example)

### Node Types

The following table describes the possible `nodeType` values in your pre-defined replica set tags.

| Node Type | Description |
| --- | --- |
| `ELECTABLE` | Read from nodes eligible to be elected [primary](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary). `ELECTABLE` nodes correspond to Electable nodes for high availability in the cluster creation UI. |
| `READ_ONLY` | Read from read-only nodes. `READ_ONLY` nodes correspond to Read-only nodes for optimal local reads in the cluster creation UI. |
| `ANALYTICS` | Read from read-only [analytics nodes](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-analytics-node). `ANALYTICS` nodes correspond to Analytics nodes for workload isolation in the cluster creation UI. |

To learn how to configure electable, read-only, and analytics nodes for your cluster, see [Configure High Availability and Workload Isolation.](https://www.mongodb.com/docs/atlas/cluster-config/multi-cloud-distribution.md#std-label-create-cluster-multi-region)

## Use Cases and Examples

Consider the following scenarios where utilizing pre-defined replica set tags would be beneficial, and see the corresponding sample connection strings.

**Important: High Availability for Analytics Node Queries**

For reads targeting analytic nodes with tags like `readPreferenceTags=nodeType:ANALYTICS`, resilience is crucial when node availability fluctuates. Without fallback tags, queries may fail during:

- Initial sync during data compaction

- Disk scale-down events

- Any NVMe (non-volatile memory express) cluster tier changes

To mitigate these risks, ensure your connection string includes *multiple read
preference tags* to provide fallback options so Atlas can route analytic reads to available nodes during such events. For example:

```none
db+srv://<db_username>:<db_password>@foo-q8x1v.mycluster.com/test?readPreference=secondary&readPreferenceTags=nodeType:ANALYTICS&readPreferenceTags=&readConcernLevel=local
```

In this example:

1. The application first tries to connect to a node tagged `nodeType:ANALYTICS`.

2. If no such nodes are available, the final empty `readPreferenceTags=` allows the application to connect to any available secondary node.

Each of the following example connection strings employ the `readConcernLevel=local` connection string option. Specifying a [read concern of local](https://www.mongodb.com/docs/manual/reference/read-concern-local/) ensures that secondary reads on sharded clusters do not return [orphaned documents](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-orphaned-document). You do not need to specify this option when connecting to non-sharded replica sets.

### Use Analytics Nodes to Isolate Workloads

If an application performs complex or long-running operations, such as ETL (Extract Transform Load) or reporting, you may want to isolate the application's queries from the rest of your operational workload by connecting exclusively to analytics nodes.

Consider the following connection string:

```none
mongodb+srv://<db_username>:<db_password>@foo-q8x1v.mycluster.com/test?readPreference=secondary&readPreferenceTags=nodeType:ANALYTICS&readConcernLevel=local
```

The connection string options appear in the following order:

- `readPreference=secondary`

- `readPreferenceTags=nodeType:ANALYTICS`

- `readConcernLevel=local`

The [readPreference](https://www.mongodb.com/docs/manual/reference/read-preference/) option of `secondary` and [readPreferenceTag](https://www.mongodb.com/docs/manual/core/read-preference/#tag-sets) option of `{ nodeType : ANALYTICS }` limit the application connections to analytic nodes.

#### Isolate Normal Application Secondary Reads from Analytics Nodes

You may want to isolate regular application reads from the workload on analytics nodes.

Consider the following connection string:

```none
mongodb+srv://<db_username>:<db_password>@foo-q8x1v.mycluster.com/test?readPreference=secondary&readPreferenceTags=workloadType:OPERATIONAL&readConcernLevel=local
```

The connection string options appear in the following order:

- `readPreference=secondary`

- `readPreferenceTags=workloadType:OPERATIONAL`

- `readConcernLevel=local`

The specified options prevent your application from reading from analytics nodes. The application must read from `operational`, or non-analytics, nodes.

### Target Local Reads for Geographically-Distributed Applications

Use pre-defined replica set tags to target local reads to specific regions for globally distributed applications. Prior to the introduction of these pre-defined replica set tags, local reads for globally distributed applications relied on correctly calculating the [nearest](https://www.mongodb.com/docs/manual/reference/read-preference/#nearest) read preference. With pre-defined replica set tags, specifying appropriate geographic tags in combination with a read preference mode of `nearest` provides more consistent behavior.

The following connection string prioritizes connections to the AWS (Amazon Web Services) `US_EAST_1` region, followed by the `US_EAST_2` region:

```none
mongodb+srv://<db_username>:<db_password>@foo-q8x1v.mycluster.com/test?readPreference=nearest&readPreferenceTags=provider:AWS,region:US_EAST_1&readPreferenceTags=provider:AWS,region:US_EAST_2&readPreferenceTags=&readConcernLevel=local
```

The connection string options appear in the following order:

- `readPreference=nearest`

- `readPreferenceTags=provider:AWS,region:US_EAST_1`

- `readPreferenceTags=provider:AWS,region:US_EAST_2`

- `readPreferenceTags=`

- `readConcernLevel=local`

Atlas considers each read preference tag in the order you specify them. After Atlas matches a node to a tag, it finds all eligible nodes that match that tag. Atlas then ignores any following `readPreferenceTags`.

In this example, the application first tries to connect to a node in AWS (Amazon Web Services) region `US_EAST_1`. If there no nodes in that region are available, the application tries to connect to a node in AWS (Amazon Web Services) region `US_EAST_2`.

The final (empty) `readPreferenceTags=` provides a fallback option. With an empty `readPreferenceTags=` option, the application can connect to any available node regardless of provider or region.

These options help ensure that the application connects to the closest geographic region for reduced latency and improved performance.

**Note:**

You can further target reads based on availability zones.

**See also:**

For additional information and use cases for various read preferences, refer to the [Read Preference page in the MongoDB Manual.](https://www.mongodb.com/docs/manual/reference/read-preference/#use-cases)

### Reduce Secondary Disk Warming Impact

When Atlas adds or replaces a node in your cluster, it performs [disk pre-warming](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-initialize.html) by default. During the disk pre-warming process, the newly created storage volume undergoes a period of heavy IOPS (Input/Output Operations per Second) usage. This slows down read operations made against this node. Therefore, during the disk pre-warming process, Atlas keeps the pre-warming node hidden by default, preventing it from participating in any read operations.

If you prefer that a newly added or replaced node becomes immediately active and visible, you can choose to [disable fast disk pre-warming](https://www.mongodb.com/docs/atlas/cluster-additional-settings.md#std-label-disk-pre-warming) and prevent read operations on a warming node by using a connection string as in the following example:

```none
mongodb+srv://<db_username>:<db_password>@foo-q8x1v.mycluster.com/test?readPreference=secondary&readPreferenceTags=diskState:READY&readConcernLevel=local
```

The connection string options appear in the following order:

- `readPreference=secondary`

- `readPreferenceTags=diskState:READY`

- `readConcernLevel=local`

The [readPreference](https://www.mongodb.com/docs/manual/reference/read-preference/) option of `secondary` and [readPreferenceTag](https://www.mongodb.com/docs/manual/core/read-preference/#tag-sets) option of `{ diskState : READY }` tells Atlas to only target warm nodes.

### Retrieve Availability Zones

Atlas provides pre-defined replica set tags for availability zones by default. These tags include the AWS (Amazon Web Services) availability zone ID, Google Cloud fully-qualified name for a zone, or Azure (Microsoft Azure) zone number. You can check the availability zone of a node by using the [`rs.conf()`](https://www.mongodb.com/docs/manual/reference/method/rs.conf.md#mongodb-method-rs.conf) shell method or by viewing the last ping of the cluster node.

**Example:**

```sh
...

"tags": {
          "availabilityZone": "use2-az2",

...
```

## Built-In Custom Write Concerns

Atlas provides built-in custom write concerns for multi-region clusters. Write concern describes the level of acknowledgment requested from MongoDB for write operations to a cluster.

Atlas's built-in custom write concerns can help improve data consistency by ensuring your operations are propagated to a set number of regions to succeed.

To use a custom write concern, specify the write concern in the [write concern document](https://www.mongodb.com/docs/manual/reference/write-concern.md#std-label-write-concern) of your operation.

Atlas provides the following custom write concerns for multi-region clusters:

| Write Concern | Tags | Description |
| --- | --- | --- |
| `twoRegions` | `{ region: 2 }` | Write operations must be acknowledged by at least two regions in your cluster. |
| `threeRegions` | `{ region: 3 }` | Write operations must be acknowledged by at least three regions in your cluster. |
| `twoProviders` | `{ provider: 2 }` | Write operations must be acknowledged by at least two regions in your cluster with distinct cloud providers. |

**Example:**

Consider a multi-region cluster across three regions: **us-east-1**, **us-east-2**, and **us-west-1**. You want to have write operations propagate to all three regions in your cluster before Atlas accepts them.

The following operation inserts a document and requires that the operation be propagated to all three regions due to the `{ w: "threeRegions" }` write concern object:

```javascript
db.employees.insertOne(
  { name: "Bob Smith", company: "MongoDB" },
  { writeConcern: { w: "threeRegions", j: true } }
)
```