Mongo.setReadPref() (original) (raw)

Mongo.setReadPref(mode, tagSet, hedgeOptions)

Call the setReadPref() method on a Mongo connection object to control how the client will route all queries to members of the replica set. [1]

Note

You must call Mongo.setReadPref() on the connection object before retrieving documents using that connection to use that read preference.

Parameter	Type	Description
mode	string	One of the following read preference modes: primary,primaryPreferred, secondary,secondaryPreferred, or nearest
tagSet	array of documents	Optional. A tag set used to target reads to members with the specified tag(s). tagSet is not available if using read preference mode primary.For details, see Read Preference Tag Set Lists.
hedgeOptions	document	IMPORTANT: Starting in MongoDB 8.0, hedged reads are deprecated. Queries that specify the read preferencenearest no longer use hedged reads by default. If you explicitly specify a hedged read, MongoDB performs a hedged read and logs a warning.Optional. A document that specifies whether to enable the use ofhedged reads:{ enabled: }The enabled field defaults to true; i.e. specifying an empty document { } is equivalent to specifying { enabled: true }.Hedged reads are available for sharded clusters. To use hedged reads, the mongos must have enabled support for hedged reads (the default) and the non-primary read preference must enable the use of hedged reads.Read preference nearest enables the use of hedged reads on sharded clusters by default; i.e. by default, has { enabled: true }.

Mongo.setReadPref() does not support theRead Preference maxStalenessSeconds option for read preference.

This method is available in deployments hosted in the following environments:

MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud
MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB

Mongo.setReadPref() has the following behavior.

Starting in mongosh 2.0, db.runCommand() ignores any global read preferences added through the connection string or by using theMongo.setReadPref() method. To specify the desired read preference, use the options argument when calling db.runCommand().

The following operation sets the read preference mode to target the read to a secondary member. This implicitly allows reads from secondaries.


db.getMongo().setReadPref('secondary')

However, if called while connected to the primary using mongosh, the above command does not route queries to a secondary.

To target secondaries with specific tags, include both the mode and the tagSetarray:


db.getMongo().setReadPref(

   "secondary",

   [

      { "datacenter": "B" },    // First, try matching by the datacenter tag

      { "region": "West"},      // If not found, then try matching by the region tag

      { }                       // If not found, then use the empty document to match all eligible members

   ]

)

During the secondary selection process, MongoDB tries to find secondary members with the datacenter: "B" tag first.

If found, MongoDB limits the eligible secondaries to those with thedatacenter: "B" tag and ignores the remaining tags.
If none are found, then, MongoDB tries to find secondary members with the "region": "West" tag.
- If found, MongoDB limits the eligible secondaries to those with the"region": "West" tag.
- If none are found, MongoDB uses any eligible secondaries.

See Order of Tag Matching for details.

Important

Starting in MongoDB 8.0, hedged reads are deprecated. Queries that specify the read preference nearest no longer use hedged reads by default. If you explicitly specify a hedged read, MongoDB performs a hedged read and logs a warning.

For sharded clusters, you can enable hedged readsfor non-primary read preferences. To use hedged reads, the mongos must have enabled support for hedged reads (the default) and the non-primary read preferences must enable the use of hedged reads.

To target secondaries on sharded clusters using hedged reads, include both the mode and thehedgeOptions, as in the following examples:

Without a tag set

db.getMongo().setReadPref(  
   "secondary",            // mode  
   null,                   // tag set  
   { enabled: true }       // hedge options  
)

With a tag set

db.getMongo().setReadPref(  
   "secondary",                      // mode  
   [ { "datacenter": "B" },  { } ],  // tag set  
   { enabled: true }                 // hedge options  
)