This is an upcoming (i.e. in progress) version of the manual.

Read Preference

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

Read operations to a replica set. Default read preference routes the read to the primary. Read preference of ``nearest`` routes the read to the nearest member.

By default, an application directs its read operations to the primary member in a replica set.


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]


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


The following are common use cases for using non-primary read preference modes:

  • Running systems operations that do not affect the front-end application.


    Read preferences aren’t relevant to direct connections to a single mongod instance. However, in order to perform read operations on a direct connection to a secondary member of a replica set, you must set a read preference, such as secondary.

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


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


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

Default mode. All operations read from the current replica set primary.

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 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 member of the replica set with the least network latency, irrespective of the member’s type.

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

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.


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.


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.

Tag Sets

Tag sets allow you to target read operations to specific members of a replica set.

Custom read preferences and write concerns evaluate tag sets in different ways. Read preferences consider the value of a tag when selecting a member to read from. Write concerns ignore the value of a tag when selecting a member, except to consider whether or not the value is unique.

You can specify tag sets with the following 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.

All interfaces use the same member selection logic to choose the member to which to direct read operations, basing the choice on read preference mode and tag sets.

For information on configuring tag sets, see the Configure Replica Set Tag Sets tutorial.

For more information on how read preference modes interact with tag sets, see the documentation for each read preference mode.

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