Transactions

Create Collections and Indexes In a Transaction

You can perform the following operations inside of a distributed transaction as long as the transaction is not a cross-shard write transaction:

• Create collections.

• Create indexes on new empty collections created earlier in the same transaction.

When creating a collection inside a transaction:

• You can implicitly create a collection, such as with:

  • an insert operation against a non-existing collection, or

  • an update/findAndModify operation with upsert: true against a non-existing collection.

• You can explicitly create a collection using the create command or its helper db.createCollection().

When creating an index inside a transaction [1], the index to create must be on either:

• a non-existing collection. The collection is created as part of the operation.

• a new empty collection created earlier in the same transaction.

Count Operation

To perform a count operation within a transaction, use the $count aggregation stage or the $group (with a $sum expression) aggregation stage.

MongoDB drivers provide a collection-level API countDocuments(filter, options) as a helper method that uses the $group with a $sum expression to perform a count. The count() API is deprecated.

mongosh provides the db.collection.countDocuments() helper method that uses the $group with a $sum expression to perform a count.

Distinct Operation

To perform a distinct operation within a transaction:

• For unsharded collections, you can use the db.collection.distinct() method/the distinct command as well as the aggregation pipeline with the $group stage.

• For sharded collections, you cannot use the db.collection.distinct() method or the distinct command.

  To find the distinct values for a sharded collection, use the aggregation pipeline with the $group stage instead. For example:

  • Instead of db.coll.distinct("x"), use

    db.coll.aggregate([
       { $group: { _id: null, distinctValues: { $addToSet: "$x" } } },
       { $project: { _id: 0 } }
    ])

  • Instead of db.coll.distinct("x", { status: "A" }), use:

    db.coll.aggregate([
       { $match: { status: "A" } },
       { $group: { _id: null, distinctValues: { $addToSet: "$x" } } },
       { $project: { _id: 0 } }
    ])

  The pipeline returns a cursor to a document:

  { "distinctValues" : [ 2, 3, 1 ] }

  Iterate the cursor to access the results document.

Informational Operations

Informational commands, such as hello, buildInfo, connectionStatus (and their helper methods) are allowed in transactions; however, they cannot be the first operation in the transaction.

Restricted Operations

The following operations are not allowed in transactions:

• Creating new collections in cross-shard write transactions. For example, if you write to an existing collection in one shard and implicitly create a collection in a different shard, MongoDB cannot perform both operations in the same transaction.

• Explicit creation of collections, e.g. db.createCollection() method, and indexes, e.g. db.collection.createIndexes() and db.collection.createIndex() methods, when using a read concern level other than "local".

• The listCollections and listIndexes commands and their helper methods.

• Other non-CRUD and non-informational operations, such as createUser, getParameter, count, etc. and their helpers.

Transactions and Read Preference

Operations in a transaction use the transaction-level read preference.

Using the drivers, you can set the transaction-level read preference at the transaction start:

• If the transaction-level read preference is unset, the transaction uses the session-level read preference.

• If transaction-level and the session-level read preference are unset, the transaction uses the client-level read preference. By default, the client-level read preference is primary.

Distributed transactions that contain read operations must use read preference primary. All operations in a given transaction must route to the same member.

Transactions and Read Concern

Operations in a transaction use the transaction-level read concern. That is, any read concern set at the collection and database level is ignored inside the transaction.

You can set the transaction-level read concern at the transaction start.

• If the transaction-level read concern is unset, the transaction-level read concern defaults to the session-level read concern.

• If transaction-level and the session-level read concern are unset, the transaction-level read concern defaults to the client-level read concern. By default, client-level read concern is "local" for reads against the primary. See also:

  • Transactions and Read Preference

  • Default MongoDB Read Concerns/Write Concerns

Transactions support the following read concern levels:

Transactions and Write Concern

Transactions use the transaction-level write concern to commit the write operations. Write operations inside transactions must be issued without explicit write concern specification and use the default write concern. At commit time, the writes are then commited using the transaction-level write concern.

You can set the transaction-level write concern at the transaction start:

• If the transaction-level write concern is unset, the transaction-level write concern defaults to the session-level write concern for the commit.

• If the transaction-level write concern and the session-level write concern are unset, the transaction-level write concern defaults to the client-level write concern of:

  • w: "majority" in MongoDB 5.0 and later, with differences for deployments containing arbiters. See Implicit Default Write Concern.

  • w: 1

Transactions support all write concern w values, including:

Production Considerations

For various production considerations with using transactions, see Production Considerations. In addition, for sharded clusters, see also Production Considerations (Sharded Clusters).

Arbiters

Transactions whose write operations span multiple shards will error and abort if any transaction operation reads from or writes to a shard that contains an arbiter.

Shard Configuration Restriction

You cannot run transactions on a sharded cluster that has a shard with writeConcernMajorityJournalDefault set to false (such as a shard with a voting member that uses the in-memory storage engine).

Diagnostics

MongoDB provides various transactions metrics:

Feature Compatibility Version (fCV)

To use transactions, the featureCompatibilityVersion for all members of the deployment must be at least:

To check the fCV for a member, connect to the member and run the following command:

db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )

For more information, see the setFeatureCompatibilityVersion reference page.

Storage Engines

distributed transactions are supported on replica sets and sharded clusters where:

• the primary uses the WiredTiger storage engine, and

• the secondary members use either the WiredTiger storage engine or the in-memory storage engines.

Limit Critical Section Wait Time

Starting in MongoDB 5.2 (and 5.0.4):

• When a query accesses a shard, a chunk migration or DDL operation may hold the critical section for the collection.

• To limit the time a shard waits for a critical section within a transaction, use the metadataRefreshInTransactionMaxWaitBehindCritSecMS parameter.