MongoDB Search searchNodePreference routing and result consistency
Parent: MongoDB Atlas Search · Published reference · snapshot 2026-10-29
↓ Facts as markdownall context files
Source-anchored research for MongoDB Search searchNodePreference routing and result consistency. 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.
Definitions
- SERVER-124090, updated October 23, 2026, is an unresolved improvement with no fix version. It specifies x-mongodb-searchnodepreference as xxHash64(searchNodePreference.key), alongside command and shard headers, and requests equivalent metadata for legacy aggregate, planShardedSearch, and search-cursor getMore paths. This describes engineering requirements for fallback routing, not proof that a particular released version implements them. (low confidence) (verified as of 2026-10-23) [source]
Structure and components
- Affinity improves potential result consistency without guaranteeing permanent consistency. MongoDB explicitly lists changes in the dataset, index structure, cluster topology, and preferred-node availability as causes of remaining inconsistencies. Treating the key as a frozen result snapshot would exceed the documented guarantee. (high confidence) [source]
How it works
- A practical consequence of the documented affinity contract is to reuse the same preference key for a sequence of related requests when repeatability matters. Changing the key removes that sequence's stated same-value routing condition; keeping it still does not freeze the underlying results. This is application guidance inferred from the contract. (medium confidence) [source]
Problems, failure modes and limitations
- Percona's October 1, 2026 $vectorSearch reference includes searchNodePreference: {key: <preference-string>} in its syntax, but its field table does not explain affinity semantics. It corroborates the parameter shape in a separate implementation context, not Atlas availability, failure behavior, or consistency guarantees. (low confidence) (verified as of 2026-10-01) [source]
Comparisons and alternatives
- Routing affinity does not remove the usual result-fetching stage: mongot returns matching document IDs and metadata, and mongod normally looks up the documents. The separate returnStoredSource option controls returning stored fields instead of the backend document lookup. (high confidence) [source]
Facts and statements
- The $search stage accepts the optional object searchNodePreference: {key: <arbitrary string>}. Keeping the key value unchanged preferentially routes repeated queries to the same search node and overrides default search-node routing. (high confidence) [source]
- With separate mongod and mongot nodes, read preference first selects mongod. By default mongod sends the search through its local load balancer across mongot processes; searchNodePreference changes search-node routing at this second step. These are distinct routing controls. (high confidence) [source]
- The related $vectorSearch syntax also includes searchNodePreference with a key string in both MongoDB and Percona documentation. Percona documents its own product syntax; this does not independently establish Atlas routing or result-consistency behavior. (medium confidence) [source]
Children
- No children recorded.