Mongo.setReadPref()

On this page

Definition
Compatibility
Behavior
Examples

Definition

Mongo.setReadPref(mode, tagSet): 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.

[1]	To apply a read preference for a specific query or queries, you can apply `cursor.readPref()` to a cursor before iteration. See `cursor.readPref()` for details.

Parameters

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.

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

Compatibility

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

Behavior

Mongo.setReadPref() has the following behavior.

Interaction with db.runCommand()

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

Examples

Specify Read Preference Mode

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.

Specify Read Preference Tag Set

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

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 the datacenter: "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.