Specify Read Preference for a MongoDB Cluster¶

On this page

Overview
- When To Specify Read Preference
Procedure

Overview¶

You can configure the read preference for a linked MongoDB Atlas cluster to control the type of replica set member that MongoDB Realm routes database read requests to. You can also specify a tag set to target specific members of the replica set.

By default, Realm uses a read preference of primary, which routes all read requests through the primary node of a replica set.

When To Specify Read Preference¶

The default read preference (primary) should be sufficient for most use cases. Consider specifying a cluster read preference when you need to do the following:

Read from a specific secondary that has a custom configuration, such as an analytics node with special indexes optimized for reporting workloads.
Read from a node in a specific region of a globally distributed replica set.
Maintain read availability during a replica set failover, i.e., continue to read potentially stale data when there is no primary node.

Procedure¶

Realm UI
Realm CLI

1

Navigate to the Cluster Configuration Screen¶

You can configure the read preference for a linked cluster from the cluster’s configuration screen in the Realm UI. To get to the configuration screen, click Clusters beneath MongoDB Clusters in the left-hand navigation and then select the cluster for which you want to configure read preference.

2

Specify a Cluster Read Preference¶

On the cluster configuration screen, select a mode from the Read Preference dropdown.

The following read preference modes are available:

Mode	Description
primary	Realm routes all read operations to the current replica set primary node. This is the default read preference mode.
primaryPreferred	Realm routes all read operations to the current replica set primary node if it’s available. If the primary is unavailable, such as during an automatic failover, read requests are routed to a secondary node instead.
secondary	Realm routes all read operations to one of the current replica set secondary nodes.
secondaryPreferred	Realm routes all read operations to one of the replica set’s available secondary nodes. If no secondary is available, read requests are routed to the replica set primary instead.
nearest	Realm routes read operations to the replica set member that has the lowest network latency relative to the client.

3

Specify Read Preference Tags¶

If you specify a read preference other than primary, you can also specify one or more read preference tags. To serve a read request, a replica set member must include all of the specified read preference tags in its node configuration.

Atlas Cluster Tag Sets

MongoDB Atlas clusters are configured with pre-defined tag sets for each member node depending on the member’s type. For detailed information on which tags are defined nodes in an Atlas cluster, see Atlas Replica Set Tags.

To specify a read preference tag, click Add Tag and then enter the tag’s Key and Value in the new row of the Read Preference Tags table.

4

Save the Cluster Configuration¶

Once you have specified a Read Preference and any Read Preference Tags, click Save. Once saved, MongoDB Realm routes all incoming database read requests for the cluster according to your preference.

1

Export Your Realm Application¶

You can configure the read preference for a linked cluster by importing an application directory that includes a cluster configuration file with your desired settings. If you’re configuring read preference for an existing Realm app, the most straightforward method is to export your application, update the cluster configuration, and then import the updated directory. To export your application, click the Export App button on the Export tab of the Settings page in the MongoDB Realm or run the following command from an authenticated instance of realm-cli:

copy

realm-cli export --app-id=<App ID>

2

Specify a Cluster Read Preference¶

Configure the read preference for a linked cluster in the cluster’s config.json file. Locate this file in the cluster’s configuration directory within the application directory (/services/<MongoDB Service Name>). To specify a read preference, set the value of config.readPreference:

copy

{
   "name": "<MongoDB Service Name>",
   "type": "mongodb-atlas",
   "config": {
      "readPreference": "<Read Preference Mode>"
   }
}

The following read preference modes are available:

Mode	Description
primary	Realm routes all read operations to the current replica set primary node. This is the default read preference mode.
primaryPreferred	Realm routes all read operations to the current replica set primary node if it’s available. If the primary is unavailable, such as during an automatic failover, read requests are routed to a secondary node instead.
secondary	Realm routes all read operations to one of the current replica set secondary nodes.
secondaryPreferred	Realm routes all read operations to one of the replica set’s available secondary nodes. If no secondary is available, read requests are routed to the replica set primary instead.
nearest	Realm routes read operations to the replica set member that has the lowest network latency relative to the client.

3

Specify Read Preference Tags¶

If you specify a read preference other than primary, you can also specify one or more read preference tags. To serve a read request, a replica set member must include all of the specified read preference tags in its node configuration. To specify a read preference tag set for a cluster, ensure that you have specified a readPreference other than primary, and then add one or more tag definition objects to config.readPreferenceTagSets:

copy

{
   "name": "<MongoDB Service Name>",
   "type": "mongodb-atlas",
   "config": {
      "readPreference": "<Read Preference Mode (other than primary)>",
      "readPreferenceTagSets": [
         { <Tag Key>: <Tag Value> },
         ...
      ],
   }
}

Atlas Cluster Tag Sets

Atlas clusters are configured with pre-defined tag sets for each member node depending on the member’s type. For detailed information on which tags are defined nodes in an Atlas cluster, see Atlas Replica Set Tags.

4

Import Your Application Directory¶

Once you have specified a Read Preference and any Read Preference Tags, navigate to the root of the application directory and run the following command from an authenticated instance of realm-cli:

copy

realm-cli import

Once the import completes, MongoDB Realm immediately routes all incoming database read requests for the cluster according to your preference.

Note

For a detailed walkthrough of importing an application directory, see Deploy Changes with Realm CLI

← Enable Wire Protocol Connections Configure Advanced Rules →