Database Manual / CRUD Operations

Retryable Writes可重试写入

Retryable writes allow MongoDB drivers to automatically retry certain write operations a single time if they encounter network errors, or if they cannot find a healthy primary in the replica set or sharded cluster.可重试写入允许MongoDB驱动程序在遇到网络错误或在副本集或分片集群中找不到健康的primary时自动重试某些写入操作。

Prerequisites先决条件

Retryable writes have the following requirements:可重试写入有以下要求：

Supported Deployment Topologies支持的部署拓扑
Retryable writes require a replica set or sharded cluster, and do not support standalone instances.可重试写入需要副本集或分片群集，不支持单机版实例。
Supported Storage Engine支持的存储引擎
Retryable writes require a storage engine supporting document-level locking, such as the WiredTiger or in-memory storage engines.可重试写入需要支持文档级锁定的存储引擎，如WiredTiger或内存中存储引擎。
3.6+ MongoDB Drivers3.6+MongoDB驱动程序

Clients require MongoDB drivers updated for MongoDB 3.6 or greater:客户端需要为MongoDB 3.6或更高版本更新MongoDB驱动程序：

Java 3.6+

Python 3.6+

C 1.9+

Go 1.8+

C# 2.5+

Node 3.0+

Ruby 2.5+

Rust 2.1+

Swift 1.2+

Perl 2.0+

PHPC 1.4+

Scala 2.2+

C++ 3.6.6+

MongoDB Version版本
The MongoDB version of every node in the cluster must be 3.6 or greater, and the featureCompatibilityVersion of each node in the cluster must be 3.6 or greater. 集群中每个节点的MongoDB版本必须为3.6或更高，集群中每个结点的featureCompatibilityVersion必须为3.6以上。See setFeatureCompatibilityVersion for more information on the featureCompatibilityVersion flag.有关featureCompatibilityVersion标志的更多信息，请参阅setFeatureCompatibilityVersion。
Write Acknowledgment写入确认
Write operations issued with a Write Concern of 0 are not retryable.发出的写入关注为0的写入操作不可重试。

Retryable Writes and Multi-Document Transactions可重试写入和多文档事务

The transaction commit and abort operations are retryable write operations. 事务提交和中止操作是可重试的写入操作。If the commit operation or the abort operation encounters an error, MongoDB drivers retry the operation a single time regardless of whether retryWrites is set to false.如果提交操作或中止操作遇到错误，MongoDB驱动程序将重试该操作一次，而不管retryWrites是否设置为false。

The write operations inside the transaction are not individually retryable, regardless of value of retryWrites.无论retryWrites的值如何，事务中的写入操作都不能单独重试。

For more information on transactions, see Transactions.有关事务的更多信息，请参阅事务。

Enabling Retryable Writes启用可重试写入

MongoDB Drivers驱动程序
Drivers compatible with MongoDB 4.2 and higher enable Retryable Writes by default. Earlier drivers require the retryWrites=true option. 默认情况下，与MongoDB 4.2及更高版本兼容的驱动程序启用可重试写入。早期的驱动程序需要retryWrites=true选项。The retryWrites=true option can be omitted in applications that use drivers compatible with MongoDB 4.2 and higher.在使用与MongoDB 4.2及更高版本兼容的驱动程序的应用程序中，可以省略retryWrites=true选项。
To disable retryable writes, applications that use drivers compatible with MongoDB 4.2 and higher must include retryWrites=false in the connection string.要禁用可重试写入，使用与MongoDB 4.2及更高版本兼容的驱动程序的应用程序必须在连接字符串中包含retryWrites=false。
mongosh

Retryable writes are enabled by default in mongosh. To disable retryable writes, use the --retryWrites=false command line option:mongosh中默认启用可重试写入。要禁用可重试写入，请使用--retryWrites=false命令行选项：

mongosh --retryWrites=false

Retryable Write Operations可重试的写入操作

The following write operations are retryable when issued with acknowledged write concern; e.g., Write Concern cannot be {w: 0}.当发出确认的写入关注时，可以重试以下写入操作；例如，写关注不能为{w: 0}。

Note

The write operations inside the transactions are not individually retryable.事务中的写入操作不能单独重试。

Methods方法Descriptions描述
db.collection.insertOne()
db.collection.insertMany()		Insert operations插入操作
db.collection.updateOne()
db.collection.replaceOne()		Single-document update operations单文档更新操作
db.collection.deleteOne()
db.collection.remove() where justOne is true		Single document delete operations单文档删除操作
db.collection.findAndModify()
db.collection.findOneAndDelete()
db.collection.findOneAndReplace()
db.collection.findOneAndUpdate()		findAndModify operations. All findAndModify operations are single document operations.findAndModify操作。所有findAndModify操作都是单文档操作。

db.collection.bulkWrite() with the following write operations:具有以下写入操作：

Bulk write operations that only consist of the single-document write operations. A retryable bulk operation can include any combination of the specified write operations but cannot include any multi-document write operations, such as updateMany.仅由单个文档写入操作组成的批量写入操作。可重试的批量操作可以包括指定写入操作的任何组合，但不能包括任何多文档写入操作，如updateMany。

Bulk operations for:Bulk操作：

Bulk write operations that only consist of the single-document write operations. 仅由单个文档写入操作组成的批量写入操作。A retryable bulk operation can include any combination of the specified write operations but cannot include any multi-document write operations, such as update which specifies true for the multi option.可重试的批量操作可以包括指定写入操作的任何组合，但不能包括任何多文档写入操作，例如为multi选项指定true的更新。

Behavior行为

Persistent Network Errors持续的网络错误

MongoDB retryable writes make only one retry attempt. This helps address transient network errors and replica set elections, but not persistent network errors.MongoDB可重试写入只进行一次重试尝试。这有助于解决瞬态网络错误和副本集选举，但不能解决持久性网络错误。

Failover Period故障转移期

If the driver cannot find a healthy primary in the destination replica set or sharded cluster shard, the drivers wait serverSelectionTimeoutMS milliseconds to determine the new primary before retrying. 如果驱动程序在目标副本集或分片集群分片中找不到健康的primary，则驱动程序将等待serverSelectionTimeoutMS毫秒以确定新的主服务器然后重试。Retryable writes do not address instances where the failover period exceeds serverSelectionTimeoutMS.可重试写入不会解决故障转移期超过serverSelectionTimeoutMS的实例。

Warning

If the client application becomes temporarily unresponsive for more than the localLogicalSessionTimeoutMinutes after issuing a write operation, there is a chance that when the client applications starts responding (without a restart), the write operation may be retried and applied again.如果客户端应用程序在发出写入操作后暂时无响应的时间超过localLogicalSessionTimeoutMinutes，则当客户端应用程序开始响应时（无需重新启动），可能会重试并再次应用写入操作。

Diagnostics诊断

The serverStatus command, and its mongosh shell helper db.serverStatus() includes statistics on retryable writes in the transactions section.serverStatus命令及其mongosh shell助手db.serverStatus()在事务部分包含可重试写入的统计信息。

Retryable Writes Against local Database对local数据库进行可重试写入

The official MongoDB drivers enable retryable writes by default. Applications which write to the local database will encounter write errors unless retryable writes are explicitly disabled.默认情况下，MongoDB官方驱动程序允许可重试写入。除非明确禁用可重试写入，否则写入local数据库的应用程序将遇到写入错误。

To disable retryable writes, specify retryWrites=false in the connection string for the MongoDB cluster.要禁用可重试写入，请在MongoDB集群的连接字符串中指定retryWrites=false。

Error Handling错误处理

Starting in MongoDB 6.1, if both the first and second attempt of a retryable write fail without a single write being performed, MongoDB returns an error with the NoWritesPerformed label.从MongoDB 6.1开始，如果可重试写入的第一次和第二次尝试都失败而没有执行一次写入，MongoDB将返回一个带有NoWritesPerformed标签的错误。

The NoWritesPerformed label differentiates the results of batch operations like insertMany(). In an insertMany operation, one of the following outcomes can occur:NoWritesPerformed标签区分像insertMany()这样的批处理操作的结果。在insertMany操作中，可能会出现以下结果之一：

Outcome结果MongoDB OutputMongoDB输出
No documents are inserted.未插入任何文档。Error returned with NoWritesPerformed label.返回带有NoWritesPerformed标签的错误。
Partial work done. (At least one document is inserted, but not all.)已完成部分工作。（至少插入一个文档，但不是全部。）Error returned without NoWritesPerformed label.返回错误，没有NoWritesPerformed标签。
All documents are inserted.所有文档均已插入。Success returned.成功回来了。

Applications can use the NoWritesPerformed label to definitively determine that no documents were inserted. 应用程序可以使用NoWritesPerformed标签来确定没有插入文档。This error reporting lets the application maintain an accurate state of the database when handling retryable writes.此错误报告使应用程序在处理可重试的写入时能够保持数据库的准确状态。

In previous versions of MongoDB, an error is returned when both the first and second attempts of a retryable write fail. However, there is no distinction made to indicate that no writes were performed.在MongoDB的早期版本中，当可重试写入的第一次和第二次尝试都失败时，会返回错误。然而，没有区别表明没有进行写入。