Navigation

Atlas Replica Set Tags

Feature unavailable in Free and Shared-Tier Clusters

This feature is not available for M0 (Free Tier), M2, and M5 clusters. To learn more about which features are unavailable, see Atlas M0 (Free Tier), M2, and M5 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 desired node types and regions. These tags sets allow you to customize read preferences for a replica set, thus improving cluster performance and reliability.

To use replica set tags in your connection string and direct queries to desired nodes, set the tag in your the readPreferenceTags connection string option. For examples, see Use Cases and Examples.

Replica Set Tag Descriptions

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

Tag Name Description Example
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 for each cloud provider, refer to the cloud provider’s reference page:

{"region" : "US_EAST_2"}
Node Type

Node type.

Possible values are:

  • ELECTABLE
  • READ_ONLY
  • ANALYTICS

For more information, see Node Types.

{"nodeType" : "ANALYTICS"}

Node Types

The following table describes the possible nodeType values in your replica set tags.

Node Type Description
ELECTABLE Nodes eligible to be elected primary. ELECTABLE nodes correspond to Electable nodes for high availability in the cluster creation UI.
READ_ONLY Read-only nodes. READ_ONLY nodes correspond to Read-only nodes for optimal local reads in the cluster creation UI.
ANALYTICS Read-only analytics nodes. ANALYTICS nodes correspond to Analytics nodes for workload isolation in the cluster creation UI.

To learn how to configure these node types for your cluster, see High Availability and Workload Isolation Options.

See also

For details on how these replica set tags correspond to BI Connector for Atlas read preferences, refer to the BI Connector cluster options section of the Create a Cluster Page.

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.

Note

Each of the following example connection strings employ the readConcernLevel=local connection string option. Specifying a read concern of local ensures that secondary reads on sharded clusters do not return orphaned documents. 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 or reporting, you may want to isolate the application’s queries from the rest of your operational workload by connecting exclusively to analytics nodes.

In this case, the following connection string forces your application to only connect to analytic nodes:

mongodb+srv://<USERNAME>:<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 option of secondary and readPreferenceTag option of { nodeType : ANALYTICS } limit the application connections to analytic nodes.

Isolate Normal Application Secondary Reads from Analytics Nodes

In conjunction with the previous example, you may want to ensure that normal application reads from secondary nodes are isolated from the workload on analytics nodes.

In this case, the following connection string disallows the application from reading from analytics nodes and forces it to read from secondary nodes:

mongodb+srv://<USERNAME>:<PASSWORD>@foo-q8x1v.mycluster.com/test?readPreference=secondary&readPreferenceTags=nodeType:ELECTABLE&readPreferenceTags=nodeType:READ_ONLY&readConcernLevel=local

The connection string options appear in the following order:

  • readPreference=secondary
  • readPreferenceTags=nodeType:ELECTABLE
  • readPreferenceTags=nodeType:READ_ONLY
  • readConcernLevel=local

Order matters when using multiple readPreferenceTags. The readPreferenceTags are tried in order until a match is found. Once found, that specification is used to find all eligible matching members and any remaining readPreferenceTags are ignored.

In this example, the application first tries to connect to an ELECTABLE node. If there are no ELECTABLE nodes available, the application tries to connect to a READ_ONLY node.

Target Local Reads for Geographically-Distributed Applications

You can utilize Atlas replica set tags to target local reads to specific regions for globally distributed applications. Prior to the introduction of these tags, local reads for globally distributed applications relied on correctly calculating the nearest read preference. With Atlas 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 US_EAST_1 region, followed by the US_EAST_2 region:

mongodb+srv://<USERNAME>:<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

The read preference tags of { provider : AWS } and corresponding region tags dictate the specific regions within AWS that the connection prioritizes. The final (empty) readPreferenceTags= option allows the application to connect to any eligible member regardless of provider or region, thus ensuring a fallback option if the specified AWS regions are unavailable.

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

See also

For additional information and use cases for various read preferences, refer to the Read Preference page in the MongoDB Manual.

Built-In Custom Write Concerns for Multi-Region Clusters

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

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:

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