Docs Menu

Docs Home → Develop Applications → MongoDB Manual

cursor.readPref()

On this page

  • Definition
  • Examples

Definition

cursor.readPref(mode, tagSet, hedgeOptions)

Important

mongosh Method

This is a mongosh method. This is not the documentation for Node.js or other programming language specific driver methods.

In most cases, mongosh methods work the same way as the legacy mongo shell methods. However, some legacy methods are unavailable in mongosh.

For the legacy mongo shell documentation, refer to the documentation for the corresponding MongoDB Server release:

For MongoDB API drivers, refer to the language specific MongoDB driver documentation.

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 Read Preference Tag Sets.

hedgeOptions
document

Optional. A document that specifies whether to enable the use of hedged reads.

{ enabled: <boolean> }

The enabled field defaults to true; i.e. specifying an empty document { } is equivalent to specifying { enabled: true }.

Hedged reads are available starting in MongoDB 4.4 for sharded clusters. 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.

Read preference nearest enables the use of hedged reads on sharded clusters by default; i.e. by default, has { enabled: true }.

New in version 4.4.

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

Examples

Specify Read Preference Mode

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

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

Specify Read Preference Tag Set

To target secondaries with specific tags, include both the mode and the tagSet 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.

Tip

See also:

Configure Replica Set Tag Sets

Specify Hedged Read

Starting in MongoDB 4.4 for sharded clusters, you can enable hedged reads for 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 4.4+ sharded cluster using hedged reads, include both the mode and the hedgeOptions, as in the following examples:

  • Without a tag set

    db.collection.find({ }).readPref(
       "secondary",            // mode
       null,                   // tag set
       { enabled: true }       // hedge options
    )

  • With a tag set

    db.collection.find({ }).readPref(
       "secondary",                      // mode
       [ { "datacenter": "B" },  { } ],  // tag set
       { enabled: true }                 // hedge options
    )
←  cursor.readConcern()cursor.returnKey() →

On this page