cursor.readPref()¶

On this page

Definition
Example

Definition¶

cursor.readPref(mode, tagSet)¶: Append readPref() to a cursor to control how the client routes the query to members of the replica set.

Note

You must apply readPref() to the cursor before retrieving any documents from the database.

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 primary.

For details, see Tag Set.

cursor.setReadPref() does not support the maxStalenessSeconds option for read preference.

Example¶

The following operation uses the read preference mode to target the read to a secondary member.

copy

db.collection.find({ }).readPref( "secondary")

To target secondaries with specific tags, include the tag set array:

copy

db.collection.find({ }).readPref(
   "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.