Read Preference

Read preference describes how MongoDB clients route read operations tothe members of a replica set.

By default, an application directs its read operations to theprimary member in a replica set (i.e. read preferencemode “primary”). But, clients can specify a read preference to sendread operations to secondaries.

Read preference consists of the read preference mode, and optionally, a tag set andmaxStalenessSeconds.

Important

Exercise care when specifying read preferences: Modes other thanprimary may return stale data because withasynchronous replication, data inthe secondary may not reflect the most recent write operations.[1]

Note

The read preference does not affect the visibility of data;i.e. clients can see the results of writes before they are acknowledgedor have propagated to a majority of replica set members. For details,see Read Isolation, Consistency, and Recency.

Use Cases

Indications

The following are common use cases for using non-primaryread preference modes:

• Running systems operations that do not affect the front-endapplication.

Note

Read preferences aren’t relevant to direct connections toa single mongod instance. However, in order to performread operations on a direct connection to a secondary member of areplica set, you must set a read preference, such assecondary.

• Providing local reads for geographically distributed applications.

If you have application servers in multiple data centers, you mayconsider having a geographically distributed replica set and using a non primary ornearest read preference. This allows the client to readfrom the lowest-latency members, rather than always reading from theprimary.

• Maintaining availability during a failover.

Use primaryPreferred if you want an application toread from the primary under normal circumstances, but toallow stale reads from secondaries when the primary is unavailable. This provides a“read-only mode” for your application during a failover.

Counter-Indications

In general, do not use secondary andsecondaryPreferred to provide extra capacity forreads, because:

• All members of a replica have roughly equivalent write traffic; as aresult, secondaries will service reads at roughly the same rate asthe primary.

• Replication is asynchronous and there is some amount ofdelay between a successful write operation and its replication tosecondaries. Reading from a secondary can return stale data;reading from different secondaries may result in non-monotonic reads.

Changed in version 3.6: Starting in MongoDB 3.6, clients can use Client Sessions and Causal Consistency Guarantees to ensuremonotonic reads.

• Distributing read operations to secondaries can compromise availabilityif any members of the set become unavailable because the remainingmembers of the set will need to be able to handle all applicationrequests.

Sharding increases read and write capacity bydistributing read and write operations across a group of machines,and is often a better strategy for adding capacity.

See Server Selection Algorithm for more informationabout the internal application of read preferences.

Read Preference Modes

Important

All read preference modes except primary may returnstale data because secondaries replicateoperations from the primary with some delay.[1] Ensure that your application can toleratestale data if you choose to use a non-primary mode.

Tag Set

If a replica set member or members are associated withtags, you can specify a tag set (array of tagspecification documents) in the read preference to target those members.

To configure a member withtags, set members[n].tags to a document that contains the tagname and value pairs. The value of the tags must be a string.

{ "<tag1>": "<string1>", "<tag2>": "<string2>",... }

Then, you can include a tag set in the read preference to target taggedmembers. A tag set is an array of tag specification documents, whereeach tag specification document contains one or more tag/value pairs.

[ { "<tag1>": "<string1>", "<tag2>": "<string2>",... }, ... ]

To find replica set members, MongoDB tries each document in successionuntil a match is found. See Order of Tag Matching for details.

For example, if a secondary member has the followingmembers[n].tags:

{ "region": "South", "datacenter": "A" }

Then, the following tags sets can direct read operations to the aforementionedsecondary (or other members with the same tags):

[ { "region": "South", "datacenter": "A" }, { } ]     // Find members with both tag values. If none are found, read from any eligible member.
[ { "region": "South" }, { "datacenter": "A" }, { } ] // Find members with the specified region tag. Only if not found, then find members with the specified datacenter tag. If none are found, read from any eligible member.
[ { "datacenter": "A" }, { "region": "South" }, { } ] // Find members with the specified datacenter tag. Only if not found, then find members with the specified region tag. If none are found, read from any eligible member.
[ { "region": "South" }, { } ]                        // Find members with the specified region tag value. If none are found, read from any eligible member.
[ { "datacenter": "A" }, { } ]                        // Find members with the specified datacenter tag value. If none are found, read from any eligible member.
[ { } ]                                               // Find any eligible member.

Order of Tag Matching

If the tag set lists multiple documents, MongoDB tries each document insuccession until a match is found. Once a match is found, that tagspecification document is used to find all eligible matching members,and the remaining tag specification documents are ignored. If nomembers match any of the tag specification documents, the readoperation returns with an error.

Tip

To avoid an error if no members match any of the tag specifications,you can add an empty document { } as the last element of the tagset to read from any eligible member.

For example, consider the following tag set with three tagspecification documents:

[ { "region": "South", "datacenter": "A" },  { "rack": "rack-1" }, { } ]

First, MongoDB tries to find members tagged with both "region":"South" and "datacenter": "A".

{ "region": "South", "datacenter": "A" }

• If a member is found, the remaining tag specification documents arenot considered. Instead, MongoDB uses this tag specification documentto find all eligible members.

• Else, MongoDB tries to find members with the tags specified in thesecond document

{ "rack": "rack-1" }

• If a member is found tagged, the remaining tag specificationdocument is not considered. Instead, MongoDB uses this tagspecification document to find all eligible members.

• Else, the third document is considered.

{ }

The empty document matches any eligible member.

Tag Set and Read Preference Modes

Tags are not compatible with mode primary, and in general,only apply when selectinga secondary member of a set for a read operation. However, thenearest read mode, when combined with a tag set, selectsthe matching member with the lowest network latency. This member may be aprimary or secondary.

For information on the interaction between the modes and tag sets, refer to thespecific read preference mode documentation.

For information on configuring tag sets, see theConfigure Replica Set Tag Sets tutorial.

Configure Read Preference

When using a MongoDB driver, you can specify the read preference whenconnecting to the replica set or sharded cluster. For example, see connectionstring. You can also specify the readpreference at a more granular level. For details, see your driver’sapi documentation.

For a given read preference, the MongoDB drivers use the samemember selection logic.

When using the mongo shell, see cursor.readPref()and Mongo.setReadPref(). For example:

db.collection.find({}).readPref( "secondary",  [ { "region": "South" } ] )

Read Preference and Transactions

Multi-document transactions that containread operations must use read preference primary. Alloperations in a given transaction must route to the same member.

maxStalenessSeconds

New in version 3.4.

Replica set members can lag behind the primary due to networkcongestion, low disk throughput, long-running operations, etc. The readpreference maxStalenessSeconds option lets you specify a maximumreplication lag, or “staleness”, for reads from secondaries. When a secondary’s estimated staleness exceedsmaxStalenessSeconds, the client stops using it for read operations.

Important

The maxStalenessSeconds read preference option is intended forapplications that read from secondaries and want to avoid readingfrom a secondary that has fallen overly far behind in replicatingthe primary’s writes. For example, a secondary might stopreplicating due to a network outage between itself and the primary.In that case, the client should stop reading from the secondaryuntil an administrator resolves the outage and the secondary catchesup.

To use maxStalenessSeconds, all of theMongoDB instances in your deployment must be using MongoDB 3.4 orlater. If any instances are on an earlier version of MongoDB, thedriver or mongos will raise an error.

Note

Starting in version 4.2, MongoDB introduces a flow control mechanism to control the rate at whichthe primary applies its writes with the goal of keeping majoritycommitted lag under aspecified maximum value.

You can specify maxStalenessSeconds with the following readpreference modes:

• primaryPreferred
• secondary
• secondaryPreferred
• nearest

Max staleness is not compatible with mode primary and onlyapplies when selecting asecondary member of a set for a read operation.

When selecting a server for a read operation with maxStalenessSeconds, clientsestimate how stale each secondary is by comparing the secondary’s lastwrite to that of the primary. The client will then direct the readoperation to a secondary whose estimated lag is less than or equal tomaxStalenessSeconds.

If there is no primary, the client uses the secondary with the mostrecent write for the comparison.

By default, there is no maximum staleness and clients will not consider asecondary’s lag when choosing where to direct a read operation.

You must specify a maxStalenessSeconds value of 90 seconds orlonger: specifying a smaller maxStalenessSeconds value will raisean error. Clients estimate secondaries’ staleness by periodicallychecking the latest write date of each replica set member. Since thesechecks are infrequent, the staleness estimate is coarse. Thus, clientscannot enforce a maxStalenessSeconds value of less than 90 seconds.