cursor.readPref()
On this page
Definition
cursor.readPref(mode, tagSet)Important
mongosh Method
This page documents a
mongoshmethod. This is not the documentation for a language-specific driver, such as Node.js.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. |
readPref() 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
Note
This command is supported in all MongoDB Atlas clusters. For information on Atlas support for all commands, see Unsupported Commands.
MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB
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.