> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# Read Preference

Read preference describes how MongoDB clients route read operations to the members of a [replica set.](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-replica-set)

![Read operations to a replica set showing default and \`\`nearest\`\` read preference routing.](/images/replica-set-read-preference.bakedsvg.svg)

By default, an application directs its read operations to the [primary](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary) member in a [replica set](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-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](https://www.mongodb.com/docs/manual/core/read-preference.md#std-label-read-pref-modes-summary) and optionally, a [tag set list](https://www.mongodb.com/docs/manual/core/read-preference-tags.md#std-label-replica-set-read-preference-tag-sets), and the [maxStalenessSeconds](https://www.mongodb.com/docs/manual/core/read-preference-staleness.md#std-label-replica-set-read-preference-max-staleness) option.

## Read Preference Modes

The following table summarizes the read preference modes:

| Read Preference Mode | Description |
| --- | --- |
| [`primary`](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary) | Default mode. All operations read from the current replica set [primary.](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary) [Transactions](https://www.mongodb.com/docs/manual/core/transactions.md#std-label-transactions) that contain read operations must use read preference [`primary`](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary). All operations in a given transaction must route to the same member. |
| [`primaryPreferred`](https://www.mongodb.com/docs/manual/core/read-preference.md#mongodb-readmode-primaryPreferred) | In most situations, operations read from the [primary](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary) but if it is unavailable, operations read from [secondary](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-secondary) members. |
| [`secondary`](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-secondary) | All operations read from the [secondary](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-secondary) members of the replica set. |
| [`secondaryPreferred`](https://www.mongodb.com/docs/manual/core/read-preference.md#mongodb-readmode-secondaryPreferred) | Operations typically read data from [secondary](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-secondary) members of the replica set. If the replica set has only one single [primary](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary) member and no other members, operations read data from the primary member. |
| [`nearest`](https://www.mongodb.com/docs/manual/core/read-preference.md#mongodb-readmode-nearest) | Operations read from a random eligible [replica set](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-replica-set) member, irrespective of whether that member is a [primary](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary) or [secondary](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-secondary), based on a specified latency threshold. The operation considers the following when calculating latency: The [`localThresholdMS`](https://www.mongodb.com/docs/manual/reference/connection-string-options.md#mongodb-urioption-urioption.localThresholdMS) connection string option; The [maxStalenessSeconds](https://www.mongodb.com/docs/manual/core/read-preference-staleness.md#std-label-replica-set-read-preference-max-staleness) read preference option; Any specified [tag set lists](https://www.mongodb.com/docs/manual/tutorial/configure-replica-set-tag-sets.md) |

For detailed description of the read preference modes, see [Read Preference Modes.](https://www.mongodb.com/docs/manual/core/read-preference.md#std-label-replica-set-read-preference-modes)

**See also:**

- [Read Preference Tag Set Lists](https://www.mongodb.com/docs/manual/core/read-preference-tags.md#std-label-replica-set-read-preference-tag-sets)

- [Read Preference `maxStalenessSeconds`](https://www.mongodb.com/docs/manual/core/read-preference-staleness.md#std-label-replica-set-read-preference-max-staleness)

## Behavior

- All read preference modes except [`primary`](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary) may return stale data because [secondaries](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-secondary) replicate operations from the primary in an asynchronous process.  Ensure that your application can tolerate stale data if you choose to use a non-[`primary`](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary) mode.

- Read preference does not affect the visibility of data. 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.](https://www.mongodb.com/docs/manual/core/read-isolation-consistency-recency.md)

- Read preference does not affect [causal consistency](https://www.mongodb.com/docs/manual/core/read-isolation-consistency-recency.md#std-label-causal-consistency). The [causal consistency guarantees](https://www.mongodb.com/docs/manual/core/read-isolation-consistency-recency.md#std-label-sessions) provided by causally consistent sessions for read operations with [`"majority"`](https://www.mongodb.com/docs/manual/reference/read-concern-majority.md#mongodb-readconcern-readconcern.-majority-) read concern and write      operations with [`"majority"`](https://www.mongodb.com/docs/manual/reference/write-concern.md#mongodb-writeconcern-writeconcern.-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`](https://www.mongodb.com/docs/manual/reference/parameters.md#mongodb-parameter-param.terminateSecondaryReadsOnOrphanCleanup) parameter controls this behavior. To learn more about handling long-running secondary reads, see [Long-Running Secondary Reads in Sharded Clusters.](https://www.mongodb.com/docs/manual/core/long-running-secondary-reads.md#std-label-long-running-secondary-reads)

## Read Preference Modes

All read operations use only the current replica set [primary](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary).  This is the default read mode. If the primary is unavailable, read operations produce an error or throw an exception.

The [`primary`](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary) read preference mode is not compatible with read preference modes that use [tag set lists](https://www.mongodb.com/docs/manual/core/read-preference-tags.md#std-label-replica-set-read-preference-tag-sets) or [maxStalenessSeconds](https://www.mongodb.com/docs/manual/core/read-preference-staleness.md#std-label-replica-set-read-preference-max-staleness). If you specify tag set lists or a `maxStalenessSeconds` value with [`primary`](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary), the driver will produce an error.

[Transactions](https://www.mongodb.com/docs/manual/core/transactions.md#std-label-transactions) that contain read operations must use read preference [`primary`](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary). All operations in a given transaction must route to the same member.

In most situations, operations read from the [primary](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary) member of the set. However, if the primary is unavailable, as is the case during [failover](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-failover) situations, operations read from [secondary](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-secondary) members that satisfy the read preference's `maxStalenessSeconds` and tag set lists.

When the [`primaryPreferred`](https://www.mongodb.com/docs/manual/core/read-preference.md#mongodb-readmode-primaryPreferred) read preference includes a [maxStalenessSeconds value](https://www.mongodb.com/docs/manual/core/read-preference-staleness.md#std-label-replica-set-read-preference-max-staleness) 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)](https://www.mongodb.com/docs/manual/core/read-preference-tags.md#std-label-replica-set-read-preference-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](https://www.mongodb.com/docs/manual/core/read-preference-mechanics.md#std-label-replica-set-read-preference-behavior-nearest) 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`](https://www.mongodb.com/docs/manual/core/read-preference.md#mongodb-readmode-primaryPreferred) mode may return stale data. Use the `maxStalenessSeconds` option to avoid reading from secondaries that the client estimates are overly stale.

In sharded clusters that enable the ingress request rate limiter, shard nodes that are shedding load can return errors labeled `SystemOverloadedError`.

For clusters that have [`overloadAwareServerSelectionEnabled`](https://www.mongodb.com/docs/manual/reference/parameters.md#mongodb-parameter-param.overloadAwareServerSelectionEnabled) set to `true`, when a primary responds with a retryable error labeled with `SystemOverloadedError`, the router may temporarily route reads to eligible secondaries instead of the overloaded server. This applies to any read preference that can select multiple servers. By default, `overloadAwareServerSelectionEnabled` is set to `false`.

Operations read *only* from the [secondary](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-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](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary), a secondary, and an [arbiter](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-arbiter) may not have any secondaries if a member is in recovering state or unavailable.

When the [`secondary`](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-secondary) read preference includes a [maxStalenessSeconds value](https://www.mongodb.com/docs/manual/core/read-preference-staleness.md#std-label-replica-set-read-preference-max-staleness), 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)](https://www.mongodb.com/docs/manual/core/read-preference-tags.md#std-label-replica-set-read-preference-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](https://www.mongodb.com/docs/manual/core/read-preference-mechanics.md#std-label-replica-set-read-preference-behavior-nearest) 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`](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-secondary) mode may return stale data. Use the `maxStalenessSeconds` option to avoid reading from secondaries that the client estimates are overly stale.

Operations typically read data from [secondary](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-secondary) members of the replica set. If the replica set has only one single [primary](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary) member and no other members, operations read data from the primary member.

When the [`secondaryPreferred`](https://www.mongodb.com/docs/manual/core/read-preference.md#mongodb-readmode-secondaryPreferred) read preference includes a [maxStalenessSeconds value](https://www.mongodb.com/docs/manual/core/read-preference-staleness.md#std-label-replica-set-read-preference-max-staleness), 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)](https://www.mongodb.com/docs/manual/core/read-preference-tags.md#std-label-replica-set-read-preference-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](https://www.mongodb.com/docs/manual/core/read-preference-mechanics.md#std-label-replica-set-read-preference-behavior-nearest) 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`](https://www.mongodb.com/docs/manual/core/read-preference.md#mongodb-readmode-secondaryPreferred) mode may return stale data. Use the `maxStalenessSeconds` option to avoid reading from secondaries that the client estimates are overly stale.

The driver reads from a member whose network latency falls within the acceptable latency window. Reads in the [`nearest`](https://www.mongodb.com/docs/manual/core/read-preference.md#mongodb-readmode-nearest) mode do not consider whether a member is a [primary](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary) or [secondary](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-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](https://www.mongodb.com/docs/manual/core/read-preference-staleness.md#std-label-replica-set-read-preference-max-staleness), 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.](https://www.mongodb.com/docs/manual/core/read-preference-mechanics.md#std-label-replica-set-read-preference-behavior-nearest)

If you specify a [tag set list](https://www.mongodb.com/docs/manual/core/read-preference-tags.md#std-label-replica-set-read-preference-tag-sets), 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.](https://www.mongodb.com/docs/manual/core/read-preference-mechanics.md#std-label-replica-set-read-preference-behavior-nearest)

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`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) instances, the client then randomly directs the read to an instance that falls within the acceptable latency window. The read preference [member selection](https://www.mongodb.com/docs/manual/core/read-preference-mechanics.md#std-label-replica-set-read-preference-behavior-nearest) documentation describes the process in detail.

Read operations using the [`nearest`](https://www.mongodb.com/docs/manual/core/read-preference.md#mongodb-readmode-nearest) mode may return stale data. Use the `maxStalenessSeconds` option to avoid reading from secondaries that the client estimates are overly stale.

**See also:**

To learn about use cases for specific read preference settings, see [Read Preference Use Cases.](https://www.mongodb.com/docs/manual/core/read-preference-use-cases.md#std-label-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](https://www.mongodb.com/docs/drivers/). You can also set the read preference when [connecting to the replica set or sharded cluster](https://www.mongodb.com/docs/manual/reference/connection-string-options.md#std-label-connections-read-preference). For an example, see [connection string.](https://www.mongodb.com/docs/manual/reference/connection-string-options.md#std-label-connections-read-preference)

For a given read preference, the MongoDB drivers use the same [member selection logic.](https://www.mongodb.com/docs/manual/core/read-preference-mechanics.md#std-label-replica-set-read-preference-behavior-member-selection)

When using [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh), see [`cursor.readPref()`](https://www.mongodb.com/docs/manual/reference/method/cursor.readPref.md#mongodb-method-cursor.readPref) and [`Mongo.setReadPref()`.](https://www.mongodb.com/docs/manual/reference/method/Mongo.setReadPref.md#mongodb-method-Mongo.setReadPref)

## Read Preference and Transactions

[Transactions](https://www.mongodb.com/docs/manual/core/transactions.md#std-label-transactions) that contain read operations must use read preference [`primary`](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary). All operations in a given transaction must route to the same member.

## Additional Considerations

Consider the following points when using [`$merge`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/merge.md#mongodb-pipeline-pipe.-merge) or [`$out`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/out.md#mongodb-pipeline-pipe.-out) stages in an [aggregation pipeline:](https://www.mongodb.com/docs/manual/core/aggregation-pipeline.md#std-label-aggregation-pipeline)

- Starting in MongoDB 5.0, pipelines with a `$merge` stage can run on replica set [secondary](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-secondary) nodes if all the nodes in the cluster have the [featureCompatibilityVersion](https://www.mongodb.com/docs/manual/reference/command/setFeatureCompatibilityVersion.md#std-label-view-fcv) set to `5.0` or higher and the [read preference](https://www.mongodb.com/docs/manual/core/read-preference.md#std-label-read-preference) allows secondary reads.

  - `$merge` and `$out` stages run on secondary nodes, but write operations are sent to the [primary](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary) node.

  - Not all driver versions support `$merge` operations sent to the secondary nodes. For details, see the [driver](https://www.mongodb.com/docs/drivers/) 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`](https://www.mongodb.com/docs/manual/reference/command/mapReduce.md#mongodb-dbcommand-dbcmd.mapReduce) operations, only "inline" [`mapReduce`](https://www.mongodb.com/docs/manual/reference/command/mapReduce.md#mongodb-dbcommand-dbcmd.mapReduce) operations that do not write data support read preference. Otherwise, [`mapReduce`](https://www.mongodb.com/docs/manual/reference/command/mapReduce.md#mongodb-dbcommand-dbcmd.mapReduce) operations run on the [primary](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary) member.

In [some circumstances](https://www.mongodb.com/docs/manual/core/read-preference-use-cases.md#std-label-edge-cases), 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" }`](https://www.mongodb.com/docs/manual/reference/write-concern.md#mongodb-writeconcern-writeconcern.-majority-) write concern. The node that can complete [`{ w: "majority" }`](https://www.mongodb.com/docs/manual/reference/write-concern.md#mongodb-writeconcern-writeconcern.-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](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-network-partition). When this occurs, clients that connect to the former primary may observe stale data despite having requested read preference [`primary`](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary), and new writes to the former primary will eventually roll back.