Read Preference — MongoDB Manual

MongoDB.local SF, Jan 15: See the speaker lineup & ship your AI vision faster. Use WEB50 to save 50%Find out more >

• Docs Home
• Get Started
• Development
• Database Manual
  8.2 (Current)
  • Overview
  • Documents
  • Databases & Collections
  • Client Libraries
  • Connect to Clusters
  • Database Users
  • CRUD Operations
  • Indexes
  • Data Modeling
  • Aggregation Operations
  • Search
  • Vector Search
  • AI Integrations
  • Time Series
  • Change Streams
  • Transactions
  • Data Federation
  • In-Use Encryption
  • Development Checklist
  • Replication
  • Oplog
  • Data Synchronization
  • Replica Set Members
  • High Availability
  • Read & Write Semantics
  • Write Concern
  • Read Preference
  • Use Cases
  • Tag Sets
  • maxStalenessSeconds
  • Hedged Reads
  • Server Selection Algorithm
  • Replication Reference
  • Sharding
  • Performance
  • Reference
  • Support
• Streaming Data
  • Atlas Stream Processing
  • Atlas Triggers
• Release Notes
  • Server Release Notes
  • Atlas Release Notes
  • Search Release Notes
  • Vector Search Release Notes
• Management
• Client Libraries
• Tools
• Atlas Architecture Center

• Docs Home
• Get Started
• Development
• Management
• Client Libraries
• Tools
• Atlas Architecture Center
• Database Manual
  8.2 (Current)
  • Overview
  • Documents
  • Databases & Collections
  • Client Libraries
  • Connect to Clusters
  • Database Users
  • CRUD Operations
  • Indexes
  • Data Modeling
  • Aggregation Operations
  • Search
  • Vector Search
  • AI Integrations
  • Time Series
  • Change Streams
  • Transactions
  • Data Federation
  • In-Use Encryption
  • Development Checklist
  • Replication
  • Oplog
  • Data Synchronization
  • Replica Set Members
  • High Availability
  • Read & Write Semantics
  • Write Concern
  • Read Preference
  • Use Cases
  • Tag Sets
  • maxStalenessSeconds
  • Hedged Reads
  • Server Selection Algorithm
  • Replication Reference
  • Sharding
  • Performance
  • Reference
  • Support
• Streaming Data
  • Atlas Stream Processing
  • Atlas Triggers
• Release Notes
  • Server Release Notes
  • Atlas Release Notes
  • Search Release Notes
  • Vector Search Release Notes

Docs MenuAsk MongoDB AIDocs Home / / Read & Write SemanticsDocs Home / Development / Replication / Read & Write SemanticsDocs Home / Development / Replication / Read & Write SemanticsRead PreferenceCopy page

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

click to enlarge

By default, an application directs its read operations to the primary member in a replica set (that is, 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 the maxStalenessSeconds option.

Read Preference Modes

The following table summarizes the read preference modes:

Read Preference Mode	Description
primary	Default mode. All operations read from the current replica set primary. Distributed 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 but if it is unavailable, operations read from secondary members.
secondary	All operations read from the secondary members of the replica set.
secondaryPreferred	Operations typically read data from secondary members of the replica set. If the replica set has only one single primary member and no other members, operations read data from the primary member.
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: The localThresholdMS connection string option The maxStalenessSeconds read preference option Any specified tag set lists

For detailed description of the read preference modes, see Read Preference Modes.

Tip

• Read Preference Tag Set Lists

• Read Preference maxStalenessSeconds

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.

Warning

Starting in MongoDB version 8.2, long-running secondary reads in a sharded cluster may automatically terminate before orphaned document deletion following a chunk migration.

The terminateSecondaryReadsOnOrphanCleanup parameter controls this behavior. To learn more about handling long-running secondary reads, see Long-Running Secondary Reads in Sharded Clusters.

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

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

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 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 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 the maxStalenessSeconds option to avoid reading from secondaries that the client estimates are overly stale.

secondaryPreferred

Operations typically read data from secondary members of the replica set. If the replica set has only one single primary member and no other members, operations read data from the primary member.

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

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

Tip

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 using the driver's read preference API. See the driver API documentation. You can also set the read preference when connecting to the replica set or sharded cluster. For an example, see connection string.

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

When using mongosh, see cursor.readPref() and Mongo.setReadPref().

Read Preference and Transactions

Distributed transactions that contain read operations must use read preference primary. All operations in a given transaction must route to the same member.

Additional Considerations

Consider the following points when using $merge or $out stages in an aggregation pipeline:

• Starting in MongoDB 5.0, pipelines with a $merge stage can run on replica set secondary nodes if all the nodes in the cluster have the featureCompatibilityVersion set to 5.0 or higher and the read preference allows secondary reads.

  • $merge and $out stages run on secondary nodes, but write operations are sent to the primary node.

  • Not all driver versions support $merge operations sent to the secondary nodes. For details, see the driver documentation.

• In earlier MongoDB versions, pipelines with $out or $merge stages always run on the primary node and read preference isn't considered.

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.

Back

Write Concern

Next

Use Cases

Rate this page

On this page

• Read Preference Modes
• Behavior
• Read Preference Modes
• Configure Read Preference
• Read Preference and Transactions
• Additional Considerations

On this page

• Read Preference Modes
• Behavior
• Read Preference Modes
• Configure Read Preference
• Read Preference and Transactions
• Additional Considerations