Transactions and Operations
On this page
For transactions:
You can create collections and indexes in transactions. For details, see Create Collections and Indexes in a Transaction
The collections used in a transaction can be in different databases.
Note
You cannot create 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.
You cannot write to capped collections.
You cannot use read concern
"snapshot"when reading from a capped collection. (Starting in MongoDB 5.0)You cannot read/write to collections in the
config,admin, orlocaldatabases.You cannot write to
system.*collections.You cannot return the supported operation's query plan using
explainor similar commands.
For cursors created outside of a transaction, you cannot call
getMoreinside the transaction.For cursors created in a transaction, you cannot call
getMoreoutside the transaction.
You cannot specify
killCursorsas the first operation in a transaction.
Operations Supported in Multi-Document Transactions
CRUD Operations
The following read/write operations are allowed in transactions:
Method | Command | Note |
|---|---|---|
Excluding the following stages: | ||
Available on unsharded collections. For sharded collections, use the aggregation pipeline with the
$group stage. See Distinct Operation. | ||
Starting in MongoDB 4.4, if the update or replace operation is
run with In MongoDB 4.2 and earlier, if | ||
Starting in MongoDB 4.4, if run on a non-existing collection, the collection is implicitly created. In MongoDB 4.2 and earlier, the operation must be run on an existing collection. | ||
Starting in MongoDB 4.4, if run on a non-existing collection, the collection is implicitly created. In MongoDB 4.2 and earlier, the operation must be run on an existing collection. | ||
Starting in MongoDB 4.4, if run on a non-existing collection, the collection is implicitly created. In MongoDB 4.2 and earlier, the operation must be run on an existing collection. |
Note
Updates to Shard Key Values
You can update a document's shard key value (unless the shard key
field is the immutable _id field) by issuing single-document
update / findAndModify operations either in a transaction or as a
retryable write. For details, see
Change a Document's Shard Key Value.
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/thedistinctcommand as well as the aggregation pipeline with the$groupstage.For sharded collections, you cannot use the
db.collection.distinct()method or thedistinctcommand.To find the distinct values for a sharded collection, use the aggregation pipeline with the
$groupstage instead. For example:Instead of
db.coll.distinct("x"), usedb.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.
Administration Operations
You can create collections and indexes inside a distributed transaction if the transaction is not a cross-shard write transaction.
Explicit Create Operations
Command | Method | Notes |
|---|---|---|
See also the Implicit Create Operations. | ||
The index to create must either be on a non-existing collection,
in which case, the collection is created as part of the
operation, or on a new empty collection created earlier in the
same transaction. |
Note
For explicit creation of a collection or an index inside a
transaction, the transaction read concern level must be
"local".
For more information on creating collections and indexes in a transaction, see Create Collections and Indexes in a Transaction.
Implicit Create Operations
You can also implicitly create a collection through the following write operations against a non-existing collection:
Method Run against Non-Existing Collection | Command Run against Non-Existing Collection |
|---|---|
db.collection.findAndModify() with upsert: truedb.collection.findOneAndReplace() with upsert: truedb.collection.findOneAndUpdate() with upsert: true | findAndModify with upsert: true |
db.collection.updateOne() with upsert: truedb.collection.updateMany() with upsert: truedb.collection.replaceOne() with upsert: true | update with upsert: true |
db.collection.bulkWrite() with insert or upsert:true operationsVarious Bulk Operation Methods with insert or upsert:true operations |
For other CRUD operations allowed in transactions, see CRUD Operations.
For more information on creating collections and indexes in a transaction, see Create Collections and Indexes in a Transaction.
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
Changed in version 4.4.
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()anddb.collection.createIndex()methods, when using a read concern level other than"local".The
listCollectionsandlistIndexescommands and their helper methods.Other non-CRUD and non-informational operations, such as
createUser,getParameter,count, etc. and their helpers.