cursor.readPref()

On this page本页内容

Definition定义

cursor.readPref(mode, tagSet, hedgeOptions)

mongo Shell Method

This page documents the mongo shell method, and does not refer to the MongoDB Node.js driver (or any other driver) method. 本页记录了mongo shell方法，未提及MongoDB Node.js驱动程序（或任何其他驱动程序）方法。For corresponding MongoDB driver API, refer to your specific MongoDB driver documentation instead.有关相应的MongoDB驱动程序API，请参阅特定的MongoDB驱动程序文档。

Append readPref() to a cursor to control how the client routes the query to members of the replica set.将readPref()附加到游标，以控制客户端如何将查询路由到副本集的成员。

Note

You must apply readPref() to the cursor before retrieving any documents from the database.在从数据库检索任何文档之前，必须对游标应用readPref()。

Parameters参数

Parameter参数Type类型Description描述
mode string

One of the following read preference modes: primary, primaryPreferred, secondary, secondaryPreferred, or nearest以下读取首选项模式之一：primary、primaryPreferred、secondary、secondaryPreferred或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.如果使用primary，则tagSet不可用。

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 }.启用字段默认为true；例如，指定空文档{}等同于指定{enabled:true}。

Hedged reads are available starting in MongoDB 4.4 for sharded clusters. 从MongoDB 4.4开始，分片集群可以使用模糊读取。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.要使用模糊读取，mongos必须启用对模糊读取的支持（默认），非主读取首选项必须启用模糊读取。

Read preference nearest enables the use of hedged reads on sharded clusters by default; i.e. by default, has {enabled: true }.默认情况下，阅读首选项nearest允许在分片集群上使用模糊读取；默认情况下，具有{enabled: true }。

New in version 4.4.版本4.4中的新功能。

cursor.setReadPref() does not support the Read Preference maxStalenessSeconds option for read preference.不支持读取首选项的读取首选项maxStalenessSeconds。

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.在二级选择过程中，MongoDB尝试首先使用datacenter: "B"标记查找二级成员。

  • If found, MongoDB limits the eligible secondaries to those with the datacenter: "B" tag and ignores the remaining tags.如果找到，MongoDB会将符合条件的二级数据库限制为带有datacenter: "B"标记的二级数据库，并忽略其余的标记。
  • If none are found, then, MongoDB tries to find secondary members with the "region": "West" tag.如果没有找到，那么MongoDB会尝试找到带有"region": "West"标记的次要成员。
    • If found, MongoDB limits the eligible secondaries to those with the "region": "West" tag.如果找到，MongoDB将合格的二级供应商限制为带有"region": "West"标签的供应商。
    • If none are found, MongoDB uses any eligible secondaries.如果没有找到，MongoDB将使用任何符合条件的二级数据库。

See Order of Tag Matching for details.详见标签匹配顺序。

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. 从针对分片集群的MongoDB 4.4开始，您可以为非主要读取首选项启用模糊读取。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.要使用模糊读取，mongos必须启用对模糊读取的支持（默认），非主读取首选项必须启用模糊读取。

To target secondaries on 4.4+ sharded cluster using hedged reads, include both the mode and the hedgeOptions, as in the following examples:要使用对冲读取以4.4+分片集群上的二级数据为目标，请包括模式和对冲选项，如以下示例所示：

  • 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
)