Docs Menu

Docs HomeMongoDB Manual

Transactions and Operations

On this page

  • Operations Supported in Multi-Document Transactions
  • CRUD Operations
  • Count Operation
  • Distinct Operation
  • Administration 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.

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.

The following read/write operations are allowed in transactions:

Method
Command
Note
db.collection.aggregate()

Excluding the following query operator expressions:

The method uses the $match aggregation stage for the query and $group aggregation stage with a $sum expression to perform the count.

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 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:

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

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.

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.

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.

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.

Command
Method
Notes
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.

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
findAndModify with upsert: true
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 commands, such as hello, buildInfo, connectionStatus (and their helper methods) are allowed in transactions; however, they cannot be the first operation in the transaction.

Changed in version 4.4.

The following operations are not allowed in transactions:

←  Production Considerations (Sharded Clusters)Indexes →
Share Feedback