Transactions and Operations

On this page

Operations Supported in Multi-Document Transactions

CRUD Operations
Count Operation
Distinct Operation
DDL Operations
Informational Operations
Restricted Operations

For transactions:

You can specify read/write (CRUD) operations on existing collections. For a list of CRUD operations, see CRUD Operations.
Starting in MongoDB 4.4, 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. (Starting in MongoDB 4.2)
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, or local databases.
You cannot write to system.* collections.
You cannot return the supported operation's query plan (i.e. explain).

For cursors created outside of a transaction, you cannot call getMore inside the transaction.
For cursors created in a transaction, you cannot call getMore outside the transaction.

Starting in MongoDB 4.2, you cannot specify killCursors as the first operation in a transaction.

Operations that affect the database catalog, such as creating or dropping a collection or an index, are not allowed in multi-document transactions. For example, a multi-document transaction cannot include an insert operation that would result in the creation of a new collection. See Restricted Operations.

Operations Supported in Multi-Document Transactions

CRUD Operations

The following read/write operations are allowed in transactions:

Method	Command	Note
`db.collection.aggregate()`	`aggregate`	Excluding the following stages: `$collStats` `$currentOp` `$indexStats` `$listLocalSessions` `$listSessions` `$merge` `$out` `$planCacheStats`
`db.collection.countDocuments()`		Excluding the following query operator expressions: `$where` `$near` `$nearSphere` The method uses the `$match` aggregation stage for the query and `$group` aggregation stage with a `$sum` expression to perform the count.
`db.collection.distinct()`	`distinct`	Available on unsharded collections. For sharded collections, use the aggregation pipeline with the `$group` stage. See Distinct Operation.
`db.collection.find()`	`find`
`db.collection.deleteMany()` `db.collection.deleteOne()` `db.collection.remove()`	`delete`
`db.collection.findOneAndDelete()` `db.collection.findOneAndReplace()` `db.collection.findOneAndUpdate()`	`findAndModify`	Starting in MongoDB 4.4, if the update or replace operation is run with `upsert: true` on a non-existing collection, the collection is implicitly created. In MongoDB 4.2 and earlier, if `upsert: true`, the operation must be run on an existing collection. Tip See also: DDL Operations
`db.collection.insertMany()` `db.collection.insertOne()`	`insert`	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. Tip See also: DDL Operations
`db.collection.updateOne()` `db.collection.updateMany()` `db.collection.replaceOne()`	`update`	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. Tip See also: DDL Operations
`db.collection.bulkWrite()` Various Bulk Operation Methods		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. Tip See also: DDL Operations

Note

Updates to Shard Key Values

Starting in MongoDB 4.2, 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 compatible with the 4.0 features 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 4.0 drivers have deprecated the count() API.

Starting in MongoDB 4.0.3, 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.

DDL Operations

Starting in MongoDB 4.4 with feature compatibility version (fcv) "4.4", you can create collections and indexes inside a multi-document transaction if the transaction is not a cross-shard write transaction.

Explicit DDL Operations

Command	Method	Notes
`create`	`db.createCollection()`	See also the Implicit DDL Operations.
`createIndexes`	`db.collection.createIndex()` `db.collection.createIndexes()`	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 DDL 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: true` `db.collection.findOneAndReplace()` with `upsert: true` `db.collection.findOneAndUpdate()` with `upsert: true`	`findAndModify` with `upsert: true`
`db.collection.insertMany()` `db.collection.insertOne()`	`insert`
`db.collection.updateOne()` with `upsert: true` `db.collection.updateMany()` with `upsert: true` `db.collection.replaceOne()` with `upsert: true`	`update` with `upsert: true`
`db.collection.bulkWrite()` with insert or `upsert:true` operations Various 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:

Operations that affect the database catalog, such as creating or dropping a collection or an index when using MongoDB 4.2 or lower. Starting in MongoDB 4.4, you can create collections and indexes in transactions unless the transaction is a cross-shard write transaction. For details, see Create Collections and Indexes In a Transaction.
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.

Note

Operations Supported in Multi-Document Transactions

CRUD Operations

Tip

See also:

Tip

See also:

Tip

See also:

Tip

See also:

Note

Updates to Shard Key Values

Count Operation

Distinct Operation

DDL Operations

Explicit DDL Operations

Note

Implicit DDL Operations

Informational Operations

Restricted Operations

Tip

See also: