Docs4dev
Docs
mongodb / v3.6 / reference / reference-method-cursor.readPref.html

cursor.readPref()

On this page

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.

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

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

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.