Read Preference

On this page

Overview

When To Specify Read Preference
Procedure

Atlas Device Sync, Atlas Edge Server, Data API, and HTTPS Endpoints are deprecated. Refer to the deprecation page for details.

Overview

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

You cannot set the read preference on a Federated data source.

By default, App Services 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

Navigate to the Cluster Configuration Screen

You can configure the read preference for a linked cluster from the cluster's configuration screen in the App Services UI. To get to the configuration screen, click Linked Data Sources beneath Manage in the left-hand navigation. In the list of data sources, select the cluster on which you want to configure read preference.

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	App Services routes all read operations to the current replica set primary node. This is the default read preference mode.
primaryPreferred	App Services 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	App Services routes all read operations to one of the current replica set secondary nodes.
secondaryPreferred	App Services 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	App Services routes read operations to the replica set member that has the lowest network latency relative to the client.

Specify Read Preference Tags

Note

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.

Save the Cluster Configuration

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

Pull the Latest Version of Your App

To define the read preference for a linked cluster with the App Services CLI, you need a local copy of your application's configuration files.

To pull a local copy of the latest version of your app, run the following:

appservices pull --remote="<Your App ID>"

Tip

You can also download a copy of your application's configuration files from the Deploy > Export App screen in the App Services UI.

Specify a Cluster Read Preference

To configure the read preference for a linked cluster, open the cluster's config.json file and set the value of config.readPreference:

/data_sources/<Service Name>/config.json

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

The following read preference modes are available:

Mode	Description
primary	App Services routes all read operations to the current replica set primary node. This is the default read preference mode.
primaryPreferred	App Services 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	App Services routes all read operations to one of the current replica set secondary nodes.
secondaryPreferred	App Services 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	App Services routes read operations to the replica set member that has the lowest network latency relative to the client.

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:

/data_sources/<Service Name>/config.json

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

Note

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.

Deploy the Updated Data Source Configuration

Once you've set the read preference for the cluster, you can push the updated config to your remote app. App Services CLI immediately deploys the update on push.

appservices push --remote="<Your App ID>"

Back

Query Atlas from Client Apps

Wire Protocol