Session.startTransaction()

Definition定义

Session.startTransaction(<options>)

New in version 4.0.在版本4.0中新增。

Starts a multi-document transaction associated with the session. 启动与会话关联的多文档事务。At any given time, you can have at most one open transaction for a session.在任何给定时间，一个会话最多只能有一个打开的事务。

Note注意

Availability可用性

• In version 4.0, MongoDB supports multi-document transactions on replica sets.在版本4.0中，MongoDB支持副本集上的多文档事务。
• In version 4.2, MongoDB introduces distributed transactions, which adds support for multi-document transactions on sharded clusters and incorporates the existing support for multi-document transactions on replica sets.在版本4.2中，MongoDB引入了分布式事务，它增加了对分片集群上多文档事务的支持，并整合了对副本集上多文档事务的现有支持。

Important重要

Within a transaction, you can only specify read and write (CRUD) operations on existing collections. 在事务中，只能对现有集合指定读写（CRUD）操作。For example, a multi-document transaction cannot include an insert operation that would result in the creation of a new collection.例如，多文档事务不能包含导致创建新集合的插入操作。

The Session.startTransaction() method can take a document following options:Session.startTransaction()方法可以采用以下选项的文档：

{ readConcern: { level: <level>}, writeConcern: { w: <value>, j: <boolean>, wtimeout: <number> } }

Option选项	Description描述
readConcern	Optional. 可选。A document that specifies the read concern for all operations in the transaction, overriding operation-specific read concern.一种文档，指定事务中所有操作的读取关注点，覆盖特定于操作的读取关心点。 You can specify one of the following read concern levels:您可以指定以下读取关注级别之一： "snapshot" "local" "majority" For "local" and "majority" read concern, MongoDB may sometimes substitute a stronger read concern.对于"local"和"majority"读取关注点，MongoDB有时可能会替代更强的读取关注点。
writeConcern	Optional. 可选。A document that specifies the write concern for the transaction. 指定事务的写入关注点的文档。This write concern applies to the transaction commit and abort operations.这种写问题适用于事务提交和中止操作。 The operations within the transaction use "w: 1", overriding operation-specific write concern.事务中的操作使用"w: 1"，覆盖特定于操作的写关注点。 If you commit using "w: 1" write concern, your transaction can be rolled back during the failover process.如果使用"w: 1"写关注点进行提交，则可以在故障转移过程中回滚事务。 For MongoDB Drivers, transactions use the client-level write concern as the default.对于MongoDB驱动程序，事务使用客户端级别的写关注点作为默认值。

Behavior行为

Example示例

Consider a scenario where as changes are made to an employee's record in the hr database, you want to ensure that the events collection in the reporting database are in sync with the hr changes. 考虑这样一个场景：当对hr数据库中的员工记录进行更改时，您希望确保reporting数据库中的events集合与hr更改同步。That is, you want to ensure that these writes are done as a single transaction, such that either both operations succeed or fail.也就是说，您希望确保这些写操作作为单个事务完成，这样两个操作要么成功，要么失败。

The employees collection in the hr database has the following documents:hr数据库中的employees集合包含以下文档：

{ "_id" : ObjectId("5af0776263426f87dd69319a"), "employee" : 3, "name" : { "title" : "Mr.", "name" : "Iba Ochs" }, "status" : "Active", "department" : "ABC" }
{ "_id" : ObjectId("5af0776263426f87dd693198"), "employee" : 1, "name" : { "title" : "Miss", "name" : "Ann Thrope" }, "status" : "Active", "department" : "ABC" }
{ "_id" : ObjectId("5af0776263426f87dd693199"), "employee" : 2, "name" : { "title" : "Mrs.", "name" : "Eppie Delta" }, "status" : "Active", "department" : "XYZ" }

The events collection in the reporting database has the following documents:reporting数据库中的events集合包含以下文档：

{ "_id" : ObjectId("5af07daa051d92f02462644a"), "employee" : 1, "status" : { "new" : "Active", "old" : null }, "department" : { "new" : "ABC", "old" : null } }
{ "_id" : ObjectId("5af07daa051d92f02462644b"), "employee" : 2, "status" : { "new" : "Active", "old" : null }, "department" : { "new" : "XYZ", "old" : null } }
{ "_id" : ObjectId("5af07daa051d92f02462644c"), "employee" : 3, "status" : { "new" : "Active", "old" : null }, "department" : { "new" : "ABC", "old" : null } }

The following example opens a transaction, updates an employee's status to Inactive in the employees status and inserts a corresponding document to the events collection, and commits the two operations as a single transaction.以下示例打开一个事务，在employees状态中将员工的状态更新为Inactive，并将相应的文档插入events集合，然后将这两个操作作为单个事务提交。

// Runs the txnFunc and retries if TransientTransactionError encountered
function runTransactionWithRetry(txnFunc, session) {
    while (true) {
        try {
            txnFunc(session);  // performs transaction
            break;
        } catch (error) {
            // If transient error, retry the whole transaction
            if ( error.hasOwnProperty("errorLabels") && error.errorLabels.includes("TransientTransactionError")  ) {
                print("TransientTransactionError, retrying transaction ...");
                continue;
            } else {
                throw error;
            }
        }
    }
}
// Retries commit if UnknownTransactionCommitResult encountered
function commitWithRetry(session) {
    while (true) {
        try {
            session.commitTransaction(); // Uses write concern set at transaction start.
            print("Transaction committed.");
            break;
        } catch (error) {
            // Can retry commit
            if (error.hasOwnProperty("errorLabels") && error.errorLabels.includes("UnknownTransactionCommitResult") ) {
                print("UnknownTransactionCommitResult, retrying commit operation ...");
                continue;
            } else {
                print("Error during commit ...");
                throw error;
            }
       }
    }
}
// Updates two collections in a transactions
function updateEmployeeInfo(session) {
    employeesCollection = session.getDatabase("hr").employees;
    eventsCollection = session.getDatabase("reporting").events;
    session.startTransaction( { readConcern: { level: "snapshot" }, writeConcern: { w: "majority" } } );
    try{
        employeesCollection.updateOne( { employee: 3 }, { $set: { status: "Inactive" } } );
        eventsCollection.insertOne( { employee: 3, status: { new: "Inactive", old: "Active" } } );
    } catch (error) {
        print("Caught exception during transaction, aborting.");
        session.abortTransaction();
        throw error;
    }
    commitWithRetry(session);
}
// Start a session.
session = db.getMongo().startSession( { readPreference: { mode: "primary" } } );
try{
   runTransactionWithRetry(updateEmployeeInfo, session);
} catch (error) {
   // Do something with error
} finally {
   session.endSession();
}