Docs4dev
Docs
mongodb / v3.6 / reference / core-read-preference-mechanics.html

Server Selection Algorithm

On this page

MongoDB drivers use a Server Selection algorithm to choose which replica set member to use or, when connected to multiple mongos instances, which mongos instance to use.

Server selection occurs once per operation.

Read Preference for Replica Sets

Server selection occurs once per operation and is governed by the read preference and localThresholdMS settings.

The read preference is re-evaluated for each operation.

New in version 3.4: MongoDB 3.4 adds the maxStalenessSeconds read preference option maxStalenessSeconds specifies the maximum replication lag, or “staleness”, that a secondary can suffer and still be eligible for read operations.

Important

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.

Read Preference Selection Process
primary (Default)
  1. The driver selects the primary.
secondary
  1. The driver assembles a list of eligible secondary members. maxStalenessSeconds and tag sets can further restrict the eligibility of the members.
  2. If the list of eligible members is not empty, the driver determines which eligible member is the “closest” (i.e. the member with the lowest average network round-trip-time) and calculates a latency window by adding the average round-trip-time of this “closest” server and the localThresholdMS. The driver uses this latency window to pare down the list of eligible members to those members that fall within this window.
  3. From this list of eligible members that fall within the latency window, the driver randomly chooses an eligible member.
nearest
  1. The driver assembles a list of eligible members (primary and secondaries). maxStalenessSeconds and tag sets can further limit the eligibility of the members.
  2. If the list of eligible members is not empty, the driver determines which eligible member is the “closest” (i.e. the member with the lowest average network round-trip-time) and calculates a latency window by adding the average round-trip-time of this “closest” server and the localThresholdMS [1]. The driver uses this latency window to pare down the list of eligible members to those members that fall within this window.
  3. From this list of eligible members that fall within the latency window, the driver randomly chooses an eligible member.
primaryPreferred
  1. If the primary is available, driver selects the primary.
  2. Otherwise, server selection follows the process for the read preference secondary.
secondaryPreferred
  1. Following the server selection process for the read preference secondary, if a list of eligible secondary members is non-empty, driver chooses an eligible secondary member.
  2. Otherwise, if the list is empty, driver selects the primary.

Read Preference for Sharded Clusters

Load Balancing

If there is more than one mongos instance in the connection seed list, the driver determines which mongos is the “closest” (i.e. the member with the lowest average network round-trip-time) and calculates the latency window by adding the average round-trip-time of this “closest” mongos instance and the localThresholdMS. The driver will load balance randomly across the mongos instances that fall within the latency window.

Read Preference and Shards

For sharded clusters that have replica set shards, mongos applies the read preference when reading from the shards. Server selection is governed by the read preference and replication.localPingThresholdMs settings.

New in version 3.4: MongoDB 3.4 adds the maxStalenessSeconds read preference option maxStalenessSeconds specifies the maximum replication lag, or “staleness”, that a secondary can suffer and still be eligible for read operations.

Important

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.

Changed in version 3.0: The read preference is re-evaluated for each operation.

Read Preference Selection Process
primary (Default)
  1. The mongos selects the primary.
secondary
  1. The mongos assembles a list of eligible secondary members. maxStalenessSeconds and tag sets can further restrict the eligibility of the members.
  2. If the list of eligible members is not empty, the mongos determines which eligible member is the “closest” (i.e. the member with the lowest average network round-trip-time) and calculates a latency window by adding the average round-trip-time of this “closest” server and the replication.localPingThresholdMs (or --localThreshold command line option). The mongos uses this latency window to pare down the list of eligible members to those members that fall within this window.
  3. From this list of eligible members that fall within the latency window, the mongos randomly chooses an eligible member.
nearest
  1. The mongos assembles a list of eligible members (primary and secondaries). maxStalenessSeconds and tag sets can further limit the eligibility of the members.
  2. If the list of eligible members is not empty, the mongos determines which eligible member is the “closest” (i.e. the member with the lowest average network round-trip-time) and calculates a latency window by adding the average round-trip-time of this “closest” server and the replication.localPingThresholdMs (or --localThreshold command line option) [1]. The mongos uses this latency window to pare down the list of eligible members to those members that fall within this window.
  3. From this list of eligible members that fall within the latency window, the mongos randomly chooses an eligible member.
primaryPreferred
  1. If the primary is available, mongos selects the primary.
  2. Otherwise, server selection follows the process for the read preference secondary.
secondaryPreferred
  1. Following the server selection process for the read preference secondary, if a list of eligible secondary members is non-empty, mongos chooses an eligible secondary member.
  2. Otherwise, if the list is empty, mongos selects the primary.
[1] (1, 2) The default threshold value is 15 milliseconds.