Description

The documentation for "nearest" read preference is incorrect, specifically on this line:

Operations read from the member of the replica set with the least network latency, irrespective of whether that member is a primary or secondary.

This is misleading because it makes it seems like "nearest" will always select the server with the lowest network latency but this is not the case. "Nearest" actually selects a server (primary or secondary) in the localThresholdMS latency window at random. So it's even possible that "nearest" will select the server with the highest network latency.

The driver server selection spec explains this behavior and the unfortunate naming pretty clearly:

The term 'nearest' is unfortunate, as it implies a choice based on geographic locality or absolute lowest latency, neither of which are true.

Instead, and unlike the other read preference modes, 'nearest' does not favor either primaries or secondaries; instead all servers are candidates and are filtered by tag_sets and maxStalenessSeconds.

To always select the server with the lowest RTT, users should use mode 'nearest' without tag_sets or maxStalenessSeconds and set localThresholdMS to zero.

To distribute reads across all members evenly regardless of RTT, users should use mode 'nearest' without tag_sets or maxStalenessSeconds and set localThresholdMS very high so that all servers fall within the latency window.

In both cases, tag_sets and maxStalenessSeconds could be used to further restrict the set of eligible servers, if desired.

Scope of changes

Impact to Other Docs

MVP (Work and Date)

Resources (Scope or Design Docs, Invision, etc.)