Server Selection Algorithm

MongoDB drivers use a Server Selection algorithm to choose whichreplica set member to use or, when connected to multiplemongos 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 theread preference and localThresholdMSsettings.

The read preference is re-evaluated for each operation.

Note

Multi-document transactions that containread operations must use read preference primary. Alloperations in a given transaction must route to the same member.

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

Important

The maxStalenessSeconds read preference option is intended forapplications that read from secondaries and want to avoid readingfrom a secondary that has fallen overly far behind in replicatingthe primary’s writes. For example, a secondary might stopreplicating due to a network outage between itself and the primary.In that case, the client should stop reading from the secondaryuntil an administrator resolves the outage and the secondary catchesup.

Read PreferenceSelection Process
primary (Default)- The driver selects the primary.
secondary- The driver assembles a list of eligible secondary members.maxStalenessSeconds and tagsets can furtherrestrict the eligibility of the members.- If the list of eligible members is not empty, the driverdetermines which eligible member is the “closest” (i.e. themember with the lowest average network round-trip-time) andcalculates a latency window by adding the averageround-trip-time of this “closest” server and thelocalThresholdMS. The driver uses this latency window topare down the list of eligible members to those members thatfall within this window.- From this list of eligible members that fall within thelatency window, the driver randomly chooses an eligible member.
nearest- The driver assembles a list of eligible members (primary andsecondaries). maxStalenessSeconds and tag setscan further limit theeligibility of the members.- If the list of eligible members is not empty, the driverdetermines which eligible member is the “closest” (i.e. themember with the lowest average network round-trip-time) andcalculates a latency window by adding the averageround-trip-time of this “closest” server and thelocalThresholdMS [1]. The driver usesthis latency window to pare down the list of eligible membersto those members that fall within this window.- From this list of eligible members that fall within thelatency window, the driver randomly chooses an eligible member.
primaryPreferred- If the primary is available, driver selects the primary.- Otherwise, server selection follows the process for the readpreference secondary.
secondaryPreferred- Following the server selection process for the readpreference secondary, if a list of eligible secondarymembers is non-empty, driver chooses an eligible secondary member.- 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 connectionseed list, the driver determines which mongos is the“closest” (i.e. the member with the lowest average networkround-trip-time) and calculates the latency window by adding theaverage round-trip-time of this “closest” mongos instanceand the localThresholdMS. The driver will load balance randomlyacross the mongos instances that fall within the latencywindow.

Read Preference and Shards

For sharded clusters that have replica set shards, mongosapplies the read preference when reading from the shards. Serverselection is governed by the read preference and replication.localPingThresholdMs settings.

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

Important

The maxStalenessSeconds read preference option is intended forapplications that read from secondaries and want to avoid readingfrom a secondary that has fallen overly far behind in replicatingthe primary’s writes. For example, a secondary might stopreplicating due to a network outage between itself and the primary.In that case, the client should stop reading from the secondaryuntil an administrator resolves the outage and the secondary catchesup.

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

Read PreferenceSelection Process
primary (Default)- The mongos selects the primary.
secondary- The mongos assembles a list of eligible secondary members.maxStalenessSeconds and tagsets can furtherrestrict the eligibility of the members.- If the list of eligible members is not empty, the mongosdetermines which eligible member is the “closest” (i.e. themember with the lowest average network round-trip-time) andcalculates a latency window by adding the averageround-trip-time of this “closest” server and thereplication.localPingThresholdMs (or —localThreshold command line option). The mongos uses this latency window topare down the list of eligible members to those members thatfall within this window.- From this list of eligible members that fall within thelatency window, the mongos randomly chooses an eligible member.
nearest- The mongos assembles a list of eligible members (primary andsecondaries). maxStalenessSeconds and tag setscan further limit theeligibility of the members.- If the list of eligible members is not empty, the mongosdetermines which eligible member is the “closest” (i.e. themember with the lowest average network round-trip-time) andcalculates a latency window by adding the averageround-trip-time of this “closest” server and thereplication.localPingThresholdMs (or —localThreshold command line option) [1]. The mongos usesthis latency window to pare down the list of eligible membersto those members that fall within this window.- From this list of eligible members that fall within thelatency window, the mongos randomly chooses an eligible member.
primaryPreferred- If the primary is available, mongos selects the primary.- Otherwise, server selection follows the process for the readpreference secondary.
secondaryPreferred- Following the server selection process for the readpreference secondary, if a list of eligible secondarymembers is non-empty, mongos chooses an eligible secondary member.- Otherwise, if the list is empty, mongos selects the primary.
[1](1, 2) The default threshold value is 15 milliseconds.