- 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 list and Read Preference maxStalenessSeconds.
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 |
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:
|
Behavior¶
- All read preference modes except
primary
may return stale data because secondaries replicate operations from the primary in an asynchronous process. [1] Ensure that your application can tolerate stale data if you choose to use a non-primary
mode. - 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.
- Read preference 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. [1] 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 set lists or maxStalenessSeconds. If you specify tag set lists 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 set lists.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 list (an array of tag sets) and there is no primary from which to read, the client attempts to find secondary members with matching tags (trying the tag sets 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 list, 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 list (an array of tag sets), the client attempts to find secondary members with matching tags (trying the tag sets 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 list, 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 list (an array of tag sets), the client attempts to find secondary members with matching tags (trying the tag sets 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 list, 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 list, the client attempts to find a replica set member that matches the specified tag set lists and directs reads to an arbitrary member from among the nearest group.
When the read preference includes a
maxStalenessSeconds
value and a tag set list, 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.
See also
To learn about use cases for specific read preference settings, see Read Preference Use Cases.
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.
Additional Considerations¶
For aggregation pipeline
operations that include the $out
or $merge
stages, the pipeline runs on the primary member regardless of
read preference setting.
For mapReduce
operations, only “inline”
mapReduce
operations that do not write data support read
preference. Otherwise, mapReduce
operations run on the
primary member.
[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. |