Read Preference
Parent: MongoDB Connection String URI · Published reference · snapshot 2026-10-23 · skill mongodb-cohort-6f6a12e41dfc
↓ Facts as markdownall context files
Source-anchored research for Read Preference. Run status: COMPLETED.
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
How it works
- MongoDB connection strings accept `readPreference` to choose a connection's read-routing mode; when the option is omitted, the default mode is `primary`. Drivers also expose read preference through their configuration APIs. (high confidence) [source]
- MongoDB defines five read preference modes: `primary`, `primaryPreferred`, `secondary`, `secondaryPreferred`, and `nearest`. `primaryPreferred` uses the primary when available and otherwise a secondary; `secondary` requires an eligible secondary and errors when none is available; `secondaryPreferred` falls back to the primary when no secondary is eligible. (high confidence) [source]
- `primary` reads only from the primary; `primaryPreferred` uses the primary when available and otherwise eligible secondaries; `secondary` reads only from secondaries and errors if none are available; `secondaryPreferred` normally uses secondaries but can fall back to the primary. `nearest` allows either role, subject to latency and other eligibility filters. (high confidence) (verified as of 2026-10-14) [source]
- A non-primary read preference may return stale data because secondaries replicate asynchronously. Read preference chooses eligible members; it does not itself provide freshness or change causal-consistency guarantees. (high confidence) [source]
Measurements and reference values
- The capacity effect of secondary reads depends on workload. In a three-node benchmark published January 14, 2026, Percona reported almost no improvement from `secondaryPreferred` for a 54%-read/46%-write workload, but reported roughly three times the capacity for a 100%-read workload. MongoDB's manual cautions against treating `secondary` or `secondaryPreferred` as a general read-capacity strategy. (medium confidence) (verified as of 2026-01-14) [source]
- Secondary reads do not guarantee greater throughput. MongoDB's use-case guide cautions against using `secondary` or `secondaryPreferred` generally to add read capacity; in Percona's reported 54% read/46% write workload, enabling `secondaryPreferred` produced almost no max-throughput gain, while its all-read workload showed a benefit. These results are workload-specific. (medium confidence) (verified as of 2026-10-22) [source]
Problems, failure modes and limitations
- Every mode except `primary` may return stale data because secondaries apply primary writes asynchronously. `maxStalenessSeconds` filters secondaries using a client estimate of replication lag; the driver specification describes it as an approximate way to limit stale reads, not a consistency guarantee. (high confidence) [source]
Comparisons and alternatives
- `nearest` does not guarantee that every read goes to the single lowest-latency or least-loaded member: MongoDB selects a random eligible member within a latency window, and the mode reflects network latency rather than CPU or I/O load. A 2015 SoCC study measured daily changes in nearest-K replica ordering across EC2 regions, showing that network paths can change over time; that historical result does not establish current driver behavior. (medium confidence) (verified as of 2026-10-14) [source]
Facts and statements
- For `nearest`, primary and secondary members can both be candidates. The client applies tag and staleness filters, limits candidates to the latency window controlled by `localThresholdMS`, and randomly selects among the remaining members. The mode therefore does not promise the single lowest-RTT member, and it does not account for server CPU or I/O load. (high confidence) [source]
- `secondaryPreferred` does not promise equal use of every secondary. Drivers filter secondaries by tags, estimated staleness, and latency before randomly choosing from eligible members; uneven replication lag or network latency can leave a smaller or different eligible pool. (medium confidence) [source]
- A 2015 SoCC study reported that the then-current MongoDB Java driver's cumulative moving average buffer was never cleared, so its latency estimate could retain old RTT measurements and affect replica selection. This is historical evidence about the driver version studied, not a claim about current releases. (low confidence) [source]
- The URI option `readPreference` sets the connection's read-routing mode. The documented values are `primary` (default), `primaryPreferred`, `secondary`, `secondaryPreferred`, and `nearest`; `readPreferenceTags` and `maxStalenessSeconds` can further restrict eligible members. (high confidence) (verified as of 2026-10-14) [source]
Children
- No children recorded.