Read preference describes how MongoDB clients route read operations to members of a replica set.
By default, an application directs its read operations to the primary member in a replica set. Reading from the primary guarantees that read operations reflect the latest version of a document. However, by distributing some or all reads to secondary members of the replica set, you can improve read throughput or reduce latency for an application that does not require fully up-to-date data.
You must exercise care when specifying read preferences: modes other than primary can and will return stale data because the secondary queries will not include the most recent write operations to the replica set’s primary.
The following are common use cases for using non-primary read preference modes:
Running systems operations that do not affect the front-end application.
Issuing reads to secondaries helps distribute load and prevent operations from affecting the main workload of the primary. This can be a good choice for reporting and analytics workloads, for example.
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 read preference or the nearest. This reduces network latency by having the application server to read from a nearby secondary, rather than a distant primary.
Maintaining availability during a failover.
Use primaryPreferred if you want your application to do consistent reads from the primary under normal circumstances, but to allow stale reads from secondaries in an emergency. This provides a “read-only mode” for your application during a failover.
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.
In general, do not use primary and primaryPreferred to provide extra capacity. 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.
Read Preference Processes for more information about the internal application of read preferences.
New in version 2.2.
All read preference modes except primary may return stale data because secondaries replicate operations from the primary with some delay. Ensure that your application can tolerate stale data if you choose to use a non-primary mode.
MongoDB drivers support five read preference modes.
|Read Preference Mode||Description|
|primary||Default mode. All operations read from the current replica set primary.|
|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 the nearest member of the replica set, irrespective of the member’s type.|
You can specify a read preference mode on connection objects, database objects, collection objects, or per-operation. The syntax for specifying the read preference mode is specific to the driver and to the idioms of the host language.
Read preference modes are also available to clients connecting to a sharded cluster through a mongos. The mongos instance obeys specified read preferences when connecting to the replica set that provides each shard in the cluster.
If read operations account for a large percentage of your application’s traffic, distributing reads to secondary members can improve read throughput. However, in most cases sharding provides better support for larger scale operations, as clusters can distribute read and write operations across a group of machines.
Custom read preferences and write concerns evaluate tags sets in different ways: read preferences consider the value of a tag when selecting a member to read from. while write concerns ignore the value of a tag to 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 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 will select the nearest member that matches the specified tag set, which 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.