cursor.readPref()
On this page
Definition
cursor.readPref(mode, tagSet, hedgeOptions)
Important
mongosh Method
This is a
mongosh
method. This is not the documentation forNode.js
or other programming language specific driver methods.In most cases,
mongosh
methods work the same way as the legacymongo
shell methods. However, some legacy methods are unavailable inmongosh
.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 |
---|---|---|
string | One of the following read preference modes: | |
array of documents | Optional. A tag set used to target reads to
members with the specified tag(s). For details, see Read Preference Tag Set Lists. | |
document | Optional. A document that specifies whether to enable the use of hedged reads.
The Hedged reads are available for sharded clusters. To use hedged reads,
the Read preference |
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.
Specify Hedged Read
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 sharded clusters 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 )