- Replication >
- Replica Set Read and Write Semantics >
- Read Preference
Read Preference¶
On this page
Read preference describes how MongoDB clients route read operations to the members of a replica set.
By default, an application directs its read operations to the primary member in a replica set (i.e. read preference mode “primary”). But, clients can specify a read preference to send read operations to secondaries.
Read preference consists of the read preference mode, and optionally, a tag set and maxStalenessSeconds.
Important
Exercise care when specifying read preferences: Modes other than
primary
may return stale data because with
asynchronous replication, data in
the 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 acknowledged or 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-primary
read preference modes:
Running systems operations that do not affect the front-end application.
Providing local reads for geographically distributed applications.
If you have application servers in multiple data centers, you may consider having a geographically distributed replica set and using a non primary or
nearest
read preference. This allows the client to read from the lowest-latency members, rather than always reading from the primary.Maintaining availability during a failover.
Use
primaryPreferred
if you want an application to read from the primary under normal circumstances, but to allow 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
and
secondaryPreferred
to provide extra capacity for
reads, because:
All members of a replica have roughly equivalent write traffic; as a result, secondaries will service reads at roughly the same rate as the primary.
Replication is asynchronous and there is some amount of delay between a successful write operation and its replication to secondaries. 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 ensure monotonic reads.
Distributing read operations to secondaries can compromise availability if any members of the set become unavailable because the remaining members of the set will need to be able to handle all application requests.
Sharding increases read and write capacity by distributing read and write operations across a group of machines, and is often a better strategy for adding capacity.
See Server Selection Algorithm for more information about the internal application of read preferences.
Read Preference Modes¶
Important
All read preference modes except primary
may return
stale data because secondaries replicate
operations from the primary with some delay.
[1] Ensure that your application can tolerate
stale data if you choose to use a non-primary
mode.
Read Preference Mode | Description |
---|---|
primary |
Default mode. All operations read from the current replica set primary. Multi-document transactions that contain
read operations must use read preference All operations in a given transaction must route to the same member. |
primaryPreferred |
In most situations, operations read from the primary but if it is unavailable, operations read from secondary members. |
secondary |
All operations read from the secondary members of the replica set. |
secondaryPreferred |
In most situations, operations read from secondary members but if no secondary members are available, operations read from the primary. |
nearest |
Operations read from a random eligible replica set member, irrespective of whether that member is a primary or secondary, based on a specified latency threshold. The operation considers the following when calculating latency:
|
Tag Set¶
If a replica set member or members are associated with
tags
, you can specify a tag set (array of tag
specification documents) in the read preference to target those members.
To configure a member with
tags, set members[n].tags
to a document that contains the tag
name and value pairs. The value of the tags must be a string.
Then, you can include a tag set in the read preference to target tagged members. A tag set is an array of tag specification documents, where each tag specification document contains one or more tag/value pairs.
To find replica set members, MongoDB tries each document in succession until a match is found. See Order of Tag Matching for details.
For example, if a secondary member has the following
members[n].tags
:
Then, the following tags sets can direct read operations to the aforementioned secondary (or other members with the same tags):
Order of Tag Matching¶
If the tag set lists multiple documents, MongoDB tries each document in succession until a match is found. Once a match is found, that tag specification document is used to find all eligible matching members, and the remaining tag specification documents are ignored. If no members match any of the tag specification documents, the read operation 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 tag
set to read from any eligible member.
For example, consider the following tag set with three tag specification documents:
First, MongoDB tries to find members tagged with both "region":
"South"
and "datacenter": "A"
.
If a member is found, the remaining tag specification documents are not considered. Instead, MongoDB uses this tag specification document to find all eligible members.
Else, MongoDB tries to find members with the tags specified in the second document
If a member is found tagged, the remaining tag specification document is not considered. Instead, MongoDB uses this tag specification 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 selecting
a secondary member of a set for a read operation. However, the
nearest
read mode, when combined with a tag set, selects
the matching member with the lowest network latency. This member may be a
primary or secondary.
Mode | Notes |
---|---|
primaryPreferred |
Specified tag set only applies if selecting eligible secondaries. |
secondary |
Specified tag set always applies. |
secondaryPreferred |
Specified tag set only applies if selecting eligible secondaries. |
nearest |
Specified tag set applies whether selecting either primary or eligible secondaries. |
For information on the interaction between the modes and tag sets, refer to the specific read preference mode documentation.
For information on configuring tag sets, see the Configure Replica Set Tag Sets tutorial.
Configure Read Preference¶
When using a MongoDB driver, you can specify the read preference when connecting to the replica set or sharded cluster. For example, see connection string. You can also specify the read preference at a more granular level. For details, see your driver’s api documentation.
For a given read preference, the MongoDB drivers use the same member selection logic.
When using the mongo
shell, see cursor.readPref()
and Mongo.setReadPref()
. For example:
Read Preference and Transactions¶
Multi-document transactions that contain
read operations must use read preference primary
.
All operations 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 network
congestion, low disk throughput, long-running operations, etc. The read
preference maxStalenessSeconds
option lets you specify a maximum
replication lag, or “staleness”, for reads from secondaries. When a secondary’s estimated staleness exceeds
maxStalenessSeconds
, the client stops using it for read operations.
Important
The maxStalenessSeconds
read preference option is intended for
applications that read from secondaries and want to avoid reading
from a secondary that has fallen overly far behind in replicating
the primary’s writes. For example, a secondary might stop
replicating due to a network outage between itself and the primary.
In that case, the client should stop reading from the secondary
until an administrator resolves the outage and the secondary catches
up.
To use maxStalenessSeconds
, all of the
MongoDB instances in your deployment must be using MongoDB 3.4 or
later. If any instances are on an earlier version of MongoDB, the
driver or mongos
will raise an error.
You can specify maxStalenessSeconds
with the following read
preference modes:
Max staleness is not compatible with mode primary
and only
applies when selecting a
secondary member of a set for a read operation.
When selecting a server for a read operation with maxStalenessSeconds
, clients
estimate how stale each secondary is by comparing the secondary’s last
write to that of the primary. The client will then direct the read
operation to a secondary whose estimated lag is less than or equal to
maxStalenessSeconds
.
If there is no primary, the client uses the secondary with the most recent write for the comparison.
By default, there is no maximum staleness and clients will not consider a secondary’s lag when choosing where to direct a read operation.
You must specify a maxStalenessSeconds
value of 90 seconds or
longer: specifying a smaller maxStalenessSeconds
value will raise
an error. Clients estimate secondaries’ staleness by periodically
checking the latest write date of each replica set member. Since these
checks are infrequent, the staleness estimate is coarse. Thus, clients
cannot enforce a maxStalenessSeconds
value of less than 90 seconds.
[1] | (1, 2) In some circumstances, two nodes in a replica set
may transiently believe that they are the primary, but at most, one
of them will be able to complete writes with { w:
"majority" } write concern. The node that can complete
{ w: "majority" } writes is the current
primary, and the other node is a former primary that has not yet
recognized its demotion, typically due to a network partition.
When this occurs, clients that connect to the former primary may
observe stale data despite having requested read preference
primary , and new writes to the former primary will
eventually roll back. |