• Stitch >
• MongoDB Atlas >
• Configure MongoDB

Specify Read Preference for a MongoDB Cluster

Overview

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

By default, Stitch 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

• Stitch UI
• Import/Export

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 Stitch 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	All read operations are routed to the current replica set primary node. This is the default read preference mode.
primaryPreferred	All read operations are routed 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	All read operations are routed to one of the current replica set secondary nodes.
secondaryPreferred	All read operations are routed 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	Read operations are routed 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. In order 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

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, Stitch routes all incoming database read requests for the cluster according to your preference.

1

Export Your Stitch 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 Stitch application, 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 Stitch UI or run the following command from an authenticated instance of stitch-cli:

copy

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

2

Specify a Cluster Read Preference

The read preference for a linked cluster is configured in the cluster’s config.json file. This file is located 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	All read operations are routed to the current replica set primary node. This is the default read preference mode.
primaryPreferred	All read operations are routed 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	All read operations are routed to one of the current replica set secondary nodes.
secondaryPreferred	All read operations are routed 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	Read operations are routed 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. In order 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 stitch-cli:

copy

stitch-cli import

Once the import completes, Stitch 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 Stitch CLI

←   Configure Advanced Rules Enable Wire Protocol Connections  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.