Server Selection Algorithm
Parent: MongoDB Driver Internals · Published reference · snapshot 2026-10-23 · skill mongodb-cohort-67b8def68c5a
↓ Facts as markdownall context files
Source-anchored research for Server Selection Algorithm. 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
- `nearest` does not guarantee geographic proximity or the absolute lowest application latency. It admits eligible servers within the configured RTT window, so a server slower than the lowest-RTT candidate can still be selected when `localThresholdMS` is positive. A 2023 MongoDB community answer and a Database Administrators Stack Exchange answer describe the same latency-window behavior. (medium confidence) [source]
Measurements and reference values
- For each operation, the driver narrows topology-known servers by operation type and topology. Read operations apply read preference and any configured tag-set or max-staleness criteria. After an optional custom server selector, the driver applies a latency window: a suitable server can be selected when its average monitoring RTT is at most the lowest suitable RTT plus `localThresholdMS`. The current documented default is 15 ms. (high confidence) (verified as of 2026-10-22) [source]
- A 2015 GeoPerf study found that the then-current MongoDB Java driver's cumulative moving average RTT estimator did not adapt to periodic path-latency changes in the authors' simulation. The authors reported inferior selection performance to the tested C++ driver in 80% of their cases. This is historical evidence about the versions studied, not a result about current driver releases. (low confidence) [source]
- `localThresholdMS` defines the latency window among suitable servers: from the lowest average RTT through that RTT plus the configured threshold. Any server inside the window may be selected, so a positive threshold can leave slower-than-fastest servers eligible. The spec gives a 15 ms default. (high confidence) (verified as of 2026-10-22) [source]
- `serverSelectionTimeoutMS` sets the maximum time the driver waits for a suitable server; the spec gives a 30,000 ms default and describes retrying after topology checks while no suitable server is available. Mongoose confirms that the Node.js driver applies this setting to initial connection and later operations. (high confidence) (verified as of 2026-10-22) [source]
- A 2015 study of the then-current MongoDB C++ and Java clients described filtering replicas more than 15 ms slower than the closest and choosing randomly among those remaining. It also reported that the tested Java client's latency-averaging buffer never cleared. These are version-specific historical findings, not evidence of current driver behavior. (low confidence) (verified as of 2015-08-27) [source]
Problems, failure modes and limitations
- The Go driver documents `localThresholdMS` and `serverSelectionTimeoutMS` as connection-URI options, with defaults of 15 ms and 30 seconds. The server-selection spec defines the timeout as the maximum time to wait for a suitable server; Mongoose's documentation says the Node.js driver applies it to initial connection and later operations. Lowering it trades faster failure for less time to wait through topology changes such as an election. (high confidence) (verified as of 2026-10-22) [source]
Facts and statements
- As of 2026-10-22, the driver specification says single-threaded clients choose randomly within the latency window, while multithreaded or asynchronous clients choose two random candidates and select the one with the lower `operationCount`, which estimates in-flight work. The Kotlin coroutine guide documents this two-candidate rule. The Ruby, PyMongo, and Rust guides still describe a single random choice; the Ruby issue tracker says Ruby still uses shuffle-and-pick-first and has no `operationCount` tracking. (high confidence) (verified as of 2026-10-22) [source]
- The driver determines suitable servers from deployment topology and operation type. For reads, the active read preference and its eligibility filters constrain candidates; an optional application selector can filter the readable set before latency-window filtering. Writes begin with writable servers. PyMongo documents this order explicitly. (high confidence) [source]
- The accepted server-selection spec prescribes different in-window strategies by concurrency model: single-threaded drivers choose one candidate at random, while multi-threaded or asynchronous drivers sample two candidates and choose the one with lower current `operationCount`. This normative behavior does not promise strict round-robin distribution. (low confidence) (verified as of 2026-10-22) [source]
- PyMongo applies a user-defined `server_selector` after forming read-preference candidates and before applying `localThresholdMS`; the selector must return suitable server descriptions. Returning an empty list leaves no server available for the operation. The driver spec describes this application-provided selector as an optional filter. (high confidence) (verified as of 2026-10-22) [source]
Children
- Server Discovery and Monitoring RTT estimates (frontier)
- Read preference candidate filtering (frontier)
- Connection URI server-selection options (frontier)
- Custom server selectors (frontier)
- Server selection timeout and retry loop (frontier)
Frontier under this node: Connection URI server-selection options, Custom server selectors, Read preference candidate filtering, Server Discovery and Monitoring RTT estimates, Server selection timeout and retry loop