> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# cursor.readPref() (mongosh method)

## Definition

**Important: mongosh Method**

This page documents a [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh) method. 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.](https://www.mongodb.com/docs/drivers/)

Append [`readPref()`](https://www.mongodb.com/docs/manual/reference/method/cursor.readpref.md#mongodb-method-cursor.readPref) to a cursor to control how the client routes the query to members of the replica set.

**Note:**

You must apply [`readPref()`](https://www.mongodb.com/docs/manual/reference/method/cursor.readpref.md#mongodb-method-cursor.readPref) to the cursor before retrieving any documents from the database.

### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| [mode](https://www.mongodb.com/docs/manual/reference/method/cursor.readpref.md#std-label-cursor-readpref-mode) | string | One of the following [read preference](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-read-preference) modes: [`primary`](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary), [`primaryPreferred`](https://www.mongodb.com/docs/manual/core/read-preference.md#mongodb-readmode-primaryPreferred), [`secondary`](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-secondary), [`secondaryPreferred`](https://www.mongodb.com/docs/manual/core/read-preference.md#mongodb-readmode-secondaryPreferred), or [`nearest`](https://www.mongodb.com/docs/manual/core/read-preference.md#mongodb-readmode-nearest) |
| [tagSet](https://www.mongodb.com/docs/manual/reference/method/cursor.readpref.md#std-label-cursor-readpref-tagset) | array of documents | Optional. A [tag set](https://www.mongodb.com/docs/manual/core/read-preference-tags.md#std-label-replica-set-read-preference-tag-sets) used to target reads to members with the specified tag(s). `tagSet` is not available if using [`primary`.](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary) For details, see [Read Preference Tag Set Lists.](https://www.mongodb.com/docs/manual/core/read-preference-tags.md#std-label-replica-set-read-preference-tag-sets) |

[`readPref()`](https://www.mongodb.com/docs/manual/reference/method/cursor.readpref.md#mongodb-method-cursor.readPref) does not support the [Read Preference `maxStalenessSeconds`](https://www.mongodb.com/docs/manual/core/read-preference-staleness.md#std-label-replica-set-read-preference-max-staleness) option for read preference.

## Compatibility

This method is available in deployments hosted in the following environments:

- [MongoDB Atlas](https://www.mongodb.com/docs/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.](https://www.mongodb.com/docs/atlas/unsupported-commands/)

- [MongoDB Enterprise](https://www.mongodb.com/docs/manual/administration/install-enterprise.md#std-label-install-mdb-enterprise): The subscription-based, self-managed version of MongoDB

- [MongoDB Community](https://www.mongodb.com/docs/manual/administration/install-community.md#std-label-install-mdb-community-edition): 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](https://www.mongodb.com/docs/manual/reference/method/cursor.readpref.md#std-label-cursor-readpref-mode) to target the read to a secondary member.

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

### Specify Read Preference Tag Set

To target secondaries with specific tags, include both the [mode](https://www.mongodb.com/docs/manual/reference/method/cursor.readpref.md#std-label-cursor-readpref-mode) and the [tagSet](https://www.mongodb.com/docs/manual/reference/method/cursor.readpref.md#std-label-cursor-readpref-tagset) array:

```javascript
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](https://www.mongodb.com/docs/manual/core/read-preference-tags.md#std-label-read-pref-order-matching) for details.

**See also:**

[Configure Replica Set Tag Sets](https://www.mongodb.com/docs/manual/tutorial/configure-replica-set-tag-sets.md)