Use Multi-document transactions in Azure Cosmos DB API for MongoDB

APPLIES TO: Azure Cosmos DB API for MongoDB

In this article, you'll create a Mongo shell app that executes a multi-document transaction on a fixed collection in Azure Cosmos DB API for MongoDB with server version 4.0.

What are multi-document transactions?

In Azure Cosmos DB API for MongoDB, operations on a single document are atomic. Multi-document transactions enable applications to execute atomic operations across multiple documents. It offers "all-or-nothing" semantics to the operations. On commit, the changes made inside the transactions are persisted and if the transaction fails, all changes inside the transaction are discarded.

Multi-document transactions follow ACID semantics:

  • Atomicity: All operations treated as one​
  • Consistency: Data committed is valid​
  • Isolation: Isolated from other operations​
  • Durability: Transaction data is persisted when client is told so​


Multi-document transactions are supported within an unsharded collection in API version 4.0. Multi-document transactions are not supported across collections or in sharded collections in 4.0. The timeout for transactions is a fixed 5 seconds.

All drivers that support wire protocol version 4.0 or greater will support Azure Cosmos DB API for MongoDB multi-document transactions.

Run multi-document transactions in MongoDB shell


This example does not work in the MongoSH beta (shell) embedded in MongoDB Compass.

  1. Open a command prompt, go to the directory where Mongo shell version 4.0 and higher is installed:

    cd <path_to_mongo_shell_>
  2. Create a mongo shell script connect_friends.js and add the following content

    // insert data into friends collection
    // start transaction
    var session = db.getMongo().startSession();
    var friendsCollection = session.getDatabase("users").friends;
    // operations in transaction
    try {
        friendsCollection.updateOne({ name: "Tom" }, { $set: { friendOf: "Mike" } } );
        friendsCollection.updateOne({ name: "Mike" }, { $set: { friendOf: "Tom" } } );
    } catch (error) {
        // abort transaction on error
        throw error;
     // commit transaction
  3. Run the following command to execute the multi-document transaction. The host, port, user, and key can be found in the Azure portal.

    mongo "<HOST>:<PORT>" -u "<USER>" -p "KEY" --ssl connect_friends.js

Next steps

Explore what's new in Azure Cosmos DB API for MongoDB 4.0