On this page

• Read Preference Modes
• Tag Set
• Configure Read Preference
• Use Cases
• Read Preferences for Database Commands

Note

The read preference does not affect the visibility of data; i.e, clients can see the results of writes before they are made durable:

• Regardless of write concern, other clients using "local" or "available" readConcern can see the result of a write operation before the write operation is acknowledged to the issuing client.
• Clients using "local" or "available" readConcern can read data which may be subsequently rolled back.

For more 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. [6] 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 a maxStalenessSeconds value with primary, the driver will produce an error.

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 to maxStalenessSeconds.

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 the maxStalenessSeconds 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 to maxStalenessSeconds. 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. [2]

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 the maxStalenessSeconds 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 to maxStalenessSeconds. 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 to maxStalenessSeconds, 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 the maxStalenessSeconds 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 remaining mongod 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 the maxStalenessSeconds 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 on maxStalenessSeconds 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.

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

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.

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

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:

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

Then, the following tags sets can direct read operations to the aforementioned secondary (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.

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

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