- Replication >
- Replication Reference >
- Read Preference Reference
Read Preference Reference¶
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 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:
|
Note
The read preference does not affect the visibility of data; i.e., the read preference does not affect whether clients can see data before they are made durable. For information on read isolation level in MongoDB, see Read Isolation, Consistency, and Recency.
Read preference also does not affect causal consistency. The causal consistency guarantees provided by causally consistent sessions for read
operations with "majority"
read concern and write
operations with "majority"
write concern hold across
all members of the MongoDB deployment.
Read Preference Modes¶
-
primary
¶ All read operations use only the current replica set primary. [3] This is the default read mode. If the primary is unavailable, read operations produce an error or throw an exception.
The
primary
read preference mode is not compatible with read preference modes that use tag sets or maxStalenessSeconds. If you specify tag sets or amaxStalenessSeconds
value withprimary
, the driver will produce an error.Multi-document transactions that contain read operations must use read preference
primary
.All operations in a given transaction must route to the same member.
-
primaryPreferred
¶ In most situations, operations read from the primary member of the set. However, if the primary is unavailable, as is the case during failover situations, operations read from secondary members that satisfy the read preference’s
maxStalenessSeconds
and tag sets.When the
primaryPreferred
read preference includes a maxStalenessSeconds value and there is no primary from which to read, the client estimates how stale each secondary is by comparing the secondary’s last write to that of the secondary with the most recent write. The client then directs the read operation to a secondary whose estimated lag is less than or equal tomaxStalenessSeconds
.When the read preference includes a tag set (i.e. a list of tag specifications) and there is no primary from which to read, the client attempts to find secondary members with matching tags (trying the tag specifications in order until a match is found). If matching secondaries are found, the client selects a random secondary from the nearest group of matching secondaries. If no secondaries have matching tags, the read operation produces an error.
When the read preference includes a
maxStalenessSeconds
value and a tag set, the client filters by staleness first and then by the specified tags.Read operations using the
primaryPreferred
mode may return stale data. Use themaxStalenessSeconds
option to avoid reading from secondaries that the client estimates are overly stale.
-
secondary
¶ Operations read only from the secondary members of the set. If no secondaries are available, then this read operation produces an error or exception.
Most replica sets have at least one secondary, but there are situations where there may be no available secondary. For example, a replica set with a primary, a secondary, and an arbiter may not have any secondaries if a member is in recovering state or unavailable.
When the
secondary
read preference includes a maxStalenessSeconds value, the client estimates how stale each secondary is by comparing the secondary’s last write to that of the primary. The client then directs the read operation to a secondary whose estimated lag is less than or equal tomaxStalenessSeconds
. If there is no primary, the client uses the secondary with the most recent write for the comparison.When the read preference includes a tag set (i.e. a list of tag specifications), the client attempts to find secondary members with matching tags (trying the tag specifications in order until a match is found). If matching secondaries are found, the client selects a random secondary from the nearest group of matching secondaries. If no secondaries have matching tags, the read operation produces an error.
When the read preference includes a
maxStalenessSeconds
value and a tag set, the client filters by staleness first and then by the specified tags.Read operations using the
secondary
mode may return stale data. Use themaxStalenessSeconds
option to avoid reading from secondaries that the client estimates are overly stale.
-
secondaryPreferred
¶ In most situations, operations read from secondary members, but in situations where the set consists of a single primary (and no other members), the read operation will use the replica set’s primary.
When the
secondaryPreferred
read preference includes a maxStalenessSeconds value, the client estimates how stale each secondary is by comparing the secondary’s last write to that of the primary. The client then directs the read operation to a secondary whose estimated lag is less than or equal tomaxStalenessSeconds
. If there is no primary, the client uses the secondary with the most recent write for the comparison. If there are no secondaries with estimated lag less than or equal tomaxStalenessSeconds
, the client directs the read operation to the replica set’s primary.When the read preference includes a tag set (i.e. a list of tag specifications), the client attempts to find secondary members with matching tags (trying the tag specifications in order until a match is found). If matching secondaries are found, the client selects a random secondary from the nearest group of matching secondaries. If no secondaries have matching tags, the client ignores tags and reads from the primary.
When the read preference includes a
maxStalenessSeconds
value and a tag set, the client filters by staleness first and then by the specified tags.Read operations using the
secondaryPreferred
mode may return stale data. Use themaxStalenessSeconds
option to avoid reading from secondaries that the client estimates are overly stale.
-
nearest
¶ The driver reads from a member whose network latency falls within the acceptable latency window. Reads in the
nearest
mode do not consider whether a member is a primary or secondary when routing read operations: primaries and secondaries are treated equivalently. The read preference member selection documentation describes the process in detail.Set this mode to minimize the effect of network latency on read operations without preference for current or stale data.
When the read preference includes a maxStalenessSeconds value, the client estimates how stale each secondary is by comparing the secondary’s last write to that of the primary, if available, or to the secondary with the most recent write if there is no primary. The client will then filter out any secondary whose estimated lag is greater than
maxStalenessSeconds
and randomly direct the read to a remaining member (primary or secondary) whose network latency falls within the acceptable latency window.If you specify a tag set, the client attempts to find a replica set member that matches the specified tag sets and directs reads to an arbitrary member from among the nearest group.
When the read preference includes a
maxStalenessSeconds
value and a tag set, the client filters by staleness first and then by the specified tags. From the remainingmongod
instances, the client then randomly directs the read to an instance that falls within the acceptable latency window. The read preference member selection documentation describes the process in detail.Read operations using the
nearest
mode may return stale data. Use themaxStalenessSeconds
option to avoid reading from secondaries that the client estimates are overly stale.Note
All operations read from a member of the nearest group of the replica set that matches the specified read preference mode. The
nearest
mode differs in that it prefers low latency reads over a member’s primary or secondary status.For
nearest
, the client assembles a list of acceptable hosts based onmaxStalenessSeconds
and tag sets and then narrows that list to the host with the shortest ping time and all other members of the set that are within the “local threshold,” or acceptable latency. See Read Preference for Replica Sets for more information.
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.
When using the mongo
shell, see cursor.readPref()
and Mongo.setReadPref()
. For example:
Use Cases¶
Depending on the requirements of an application, you can configure different applications to use different read preferences, or use different read preferences for different queries in the same application. Consider the following applications for different read preference strategies.
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.
Maximize Consistency¶
To avoid stale reads, use primary
read preference and
"majority"
readConcern
. If the primary is
unavailable, e.g. during elections or when a majority of the replica
set is not accessible, read operations using primary
read
preference produce an error or throw an exception.
In some circumstances, it may be possible for a replica set to
temporarily have two primaries; however, only one primary will be
capable of confirming writes with the "majority"
write
concern.
- A partial network partition may segregate a primary (
P
old) into a partition with a minority of the nodes, while the other side of the partition contains a majority of nodes. The partition with the majority will elect a new primary (P
new), but for a brief period, the old primary (P
old) may still continue to serve reads and writes, as it has not yet detected that it can only see a minority of nodes in the replica set. During this period, if the old primary (P
old) is still visible to clients as a primary, reads from this primary may reflect stale data. - A primary (
P
old) may become unresponsive, which will trigger an election and a new primary (P
new) can be elected, serving reads and writes. If the unresponsive primary (P
old) starts responding again, two primaries will be visible for a brief period. The brief period will end whenP
old steps down. However, during the brief period, clients might read from the old primaryP
old, which can provide stale data.
To increase consistency, you can disable automatic failover; however, disabling automatic failover sacrifices availability.
Maximize Availability¶
To permit read operations when possible, use
primaryPreferred
. When there’s a primary you will get
consistent reads [3], but if there is no primary
you can still query secondaries. However, when
using this read mode, consider the situation described in
secondary vs secondaryPreferred.
Minimize Latency¶
To always read from a low-latency node, use nearest
. The
driver or mongos
will read from the nearest member and
those no more than 15 milliseconds [1]
further away than the nearest member.
nearest
does not guarantee consistency. If the nearest
member to your application server is a secondary with some replication
lag, queries could return stale data. nearest
only
reflects network distance and does not reflect I/O or CPU load.
[1] | This threshold is configurable. See
localPingThresholdMs for mongos or your driver
documentation for the appropriate setting. |
Query From Geographically Distributed Members¶
If the members of a replica set are geographically distributed, you can create replica tags based that reflect the location of the instance and then configure your application to query the members nearby.
For example, if members in “east” and “west” data centers are
tagged {'dc': 'east'}
and
{'dc': 'west'}
, your application servers in the east data center can read
from nearby members with the following read preference:
Although nearest
already favors members with low network latency,
including the tag makes the choice more predictable.
secondary
vs secondaryPreferred
¶
For specific dedicated queries (e.g. ETL, reporting), you may shift the
read load from the primary by using the secondary
read
preference mode. For this use case, the secondary
mode is
preferable to the secondaryPreferred
mode because
secondaryPreferred
risks the following situation: if all
secondaries are unavailable and your replica set has enough arbiters [2] to prevent the primary from stepping down,
then the primary will receive all traffic from the clients. If the
primary is unable to handle this load, the queries will compete with
the writes. For this reason, use read preference secondary
to
distribute these specific dedicated queries instead of
secondaryPreferred
.
[2] | In general, avoid deploying more than one arbiter per replica set. |
Additional Considerations¶
For aggregation pipeline
operations, including the $out
stage forces the aggregation
pipeline to run on the primary.
For mapReduce
operations, only “inline”
mapReduce
operations that do not write data support read
preference. Otherwise, mapReduce
operations must run on
the primary members.
[3] | (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. |