Batch multiple point operations together with the Azure Cosmos DB for NoSQL SDK

The TransactionalBatch class in the JavaScript SDK for Azure Cosmos DB provides functionality to compose and execute batch operations within the same logical partition key. Using this feature, you can perform multiple operations in a single transaction and ensure either all or none of the operations are completed.

In this lab, you’ll use the JavaScript SDK to perform dual-item batch operations where you attempt to create two items as a single logical unit.

Prepare your development environment

If you have not already cloned the lab code repository for Build copilots with Azure Cosmos DB and set up your local environment, view the Setup local lab environment instructions to do so.

Create an Azure Cosmos DB for NoSQL account

If you already created an Azure Cosmos DB for NoSQL account for the Build copilots with Azure Cosmos DB labs on this site, you can use it for this lab and skip ahead to the next section. Otherwise, view the Setup Azure Cosmos DB instructions to create an Azure Cosmos DB for NoSQL account that you will use throughout the lab modules and grant your user identity access to manage data in the account by assigning it to the Cosmos DB Built-in Data Contributor role.

Import the @azure/cosmos library

The @azure/cosmos library is available on npm for easy installation into your JavaScript projects.

  1. In Visual Studio Code, in the Explorer pane, browse to the javascript/04-sdk-batch folder.

  2. Open the context menu for the javascript/04-sdk-batch folder and then select Open in Integrated Terminal to open a new terminal instance.

    đź“ť This command will open the terminal with the starting directory already set to the javascript/04-sdk-batch folder.

  3. Initialize a new Node.js project:

     npm init -y

  4. Install the @azure/cosmos package using the following command:

     npm install @azure/cosmos

  5. Install the @azure/identity library, which allows us to use Azure authentication to connect to the Azure Cosmos DB workspace, using the following command:

     npm install @azure/identity

Use the @azure/cosmos library

Once the Azure Cosmos DB library from the Azure SDK for JavaScript has been imported, you can immediately use its classes to connect to an Azure Cosmos DB for NoSQL account. The CosmosClient class is the core class used to make the initial connection to an Azure Cosmos DB for NoSQL account.

  1. In Visual Studio Code, in the Explorer pane, browse to the javascript/04-sdk-batch folder.

  2. Open the empty JavaScript file named script.js.

  3. Add the following require statements to import the @azure/cosmos and @azure/identity libraries:

     const { CosmosClient, BulkOperationType } = require("@azure/cosmos");
 const { DefaultAzureCredential  } = require("@azure/identity");
 process.env.NODE_TLS_REJECT_UNAUTHORIZED = 0

  4. Add variables named endpoint and credential and set the endpoint value to the endpoint of the Azure Cosmos DB account you created earlier. The credential variable should be set to a new instance of the DefaultAzureCredential class:

     const endpoint = "<cosmos-endpoint>";
 const credential = new DefaultAzureCredential();

    📝 For example, if your endpoint is: https://dp420.documents.azure.com:443/, the statement would be: const endpoint = “https://dp420.documents.azure.com:443/”;.

  5. Add a new variable named client and initialize it as a new instance of the CosmosClient class using the endpoint and credential variables:

     const client = new CosmosClient({ endpoint, aadCredentials: credential });

  6. Add the following code to create a database and container if they do not already exist:

     async function main() {
     // Create database
     const { database } = await client.databases.createIfNotExists({ id: "cosmicworks" });
        
     // Create container
     const { container } = await database.containers.createIfNotExists({
         id: "products",
         partitionKey: { paths: ["/categoryId"] },
         throughput: 400
     });
 }
    
 main().catch((error) => console.error(error));

  7. Your script.js file should now look like this:

     const { CosmosClient, BulkOperationType } = require("@azure/cosmos");
 const { DefaultAzureCredential  } = require("@azure/identity");
 process.env.NODE_TLS_REJECT_UNAUTHORIZED = 0

 const endpoint = "<cosmos-endpoint>";
 const credential = new DefaultAzureCredential();

 const client = new CosmosClient({ endpoint, aadCredentials: credential });

 async function main() {
     // Create database
     const { database } = await client.databases.createIfNotExists({ id: "cosmicworks" });
        
     // Create container
     const { container } = await database.containers.createIfNotExists({
         id: "products",
         partitionKey: { paths: ["/categoryId"] },
         throughput: 400
     });
 }
    
 main().catch((error) => console.error(error));

  8. Save the script.js file.

  9. Before running the script, you must log into Azure using the az login command. At the terminal window, run:

     az login

  10. Run the script to create the database and container:

     node script.js

  11. Switch to your web browser window.

  12. Within the Azure Cosmos DB account resource, navigate to the Data Explorer pane.

  13. In the Data Explorer, expand the cosmicworks database node, then observe the new products container node within the NOSQL API navigation tree.

Creating a transactional batch

First, let’s create a simple transactional batch that adds two fictional products to the container. This batch will insert a worn saddle and a rusty handlebar into the container with the same “used accessories” category identifier. Both items have the same logical partition key, ensuring a successful batch operation.

  1. Return to Visual Studio Code. If it is not still open, open the script.js code file within the javascript/04-sdk-batch folder.

  2. Define the two product items to be inserted in the transactional batch:

     const saddle = { id: "0120", name: "Worn Saddle", categoryId: "9603ca6c-9e28-4a02-9194-51cdb7fea816" };
 const handlebar = { id: "012A", name: "Rusty Handlebar", categoryId: "9603ca6c-9e28-4a02-9194-51cdb7fea816" };

  3. Create a transactional batch for the same logical partition key and add the items:

     const partitionKey = "9603ca6c-9e28-4a02-9194-51cdb7fea816";
 const batch = container.items.batch(partitionKey)
     .create(saddle)
     .create(handlebar);

  4. Execute the batch and print the status of the operation:

     const response = await batch.execute();
 console.log(`Status: ${response.statusCode}`);

  5. Once you are done, your code file should now include:

     const { CosmosClient, BulkOperationType } = require("@azure/cosmos");
 const { DefaultAzureCredential  } = require("@azure/identity");
 process.env.NODE_TLS_REJECT_UNAUTHORIZED = 0

 const endpoint = "<cosmos-endpoint>";
 const credential = new DefaultAzureCredential();

 const client = new CosmosClient({ endpoint, aadCredentials: credential });

 async function main() {
     // Create database
     const { database } = await client.databases.createIfNotExists({ id: "cosmicworks" });
            
     // Create container
     const { container } = await database.containers.createIfNotExists({
         id: "products",
         partitionKey: { paths: ["/categoryId"] },
         throughput: 400
     });
    
     const saddle = { id: "0120", name: "Worn Saddle", categoryId: "9603ca6c-9e28-4a02-9194-51cdb7fea816" };
     const handlebar = { id: "012A", name: "Rusty Handlebar", categoryId: "9603ca6c-9e28-4a02-9194-51cdb7fea816" };
    
     const partitionKey = "9603ca6c-9e28-4a02-9194-51cdb7fea816";
     const batch = [
         { operationType: BulkOperationType.Create, resourceBody: saddle },
         { operationType: BulkOperationType.Create, resourceBody: handlebar },
     ];
    
     try {
         const response = await container.items.batch(batch, partitionKey);
    
         response.result.forEach((operationResult, index) => {
             const { statusCode, requestCharge, resourceBody } = operationResult;
             console.log(`Operation ${index + 1}: Status code: ${statusCode}, Request charge: ${requestCharge}, Resource: ${JSON.stringify(resourceBody)}`);
         });
     } catch (error) {
         if (error.code === 400) {
             console.error("Bad Request: Check the structure of the batch.");
         } else if (error.code === 409) {
             console.error("Conflict: One of the items already exists.");
         } else if (error.code === 429) {
             console.error("Too Many Requests: Throttling limit reached.");
         } else {
             console.error(`Batch operation failed. Error code: ${error.code}, message: ${error.message}`);
         }
     }
 }
    
 main().catch((error) => console.error(error));

  6. Save and run the script again:

     node script.js

  7. The output should indicate a successful status code for each operation.

Creating an errant transactional batch

Now, let’s create a transactional batch that will error purposefully. This batch will attempt to insert two items that have different logical partition keys. We will create a flickering strobe light in the “used accessories” category and a new helmet in the “pristine accessories” category. By definition, this should be a bad request and return an error when performing this transaction.

  1. Return to the editor tab for the script.js code file.

  2. Delete the following lines of code:

     const saddle = { id: "0120", name: "Worn Saddle", categoryId: "9603ca6c-9e28-4a02-9194-51cdb7fea816" };
 const handlebar = { id: "012A", name: "Rusty Handlebar", categoryId: "9603ca6c-9e28-4a02-9194-51cdb7fea816" };

 const partitionKey = "9603ca6c-9e28-4a02-9194-51cdb7fea816";
 const batch = [
     { operationType: BulkOperationType.Create, resourceBody: saddle },
     { operationType: BulkOperationType.Create, resourceBody: handlebar },
 ];

  3. Modify the script to create a new flickering strobe light and a new helmet with different partition key values.

     const light = { id: "012B", name: "Flickering Strobe Light", categoryId: "9603ca6c-9e28-4a02-9194-51cdb7fea816" };
 const helmet = { id: "012C", name: "New Helmet", categoryId: "0feee2e4-687a-4d69-b64e-be36afc33e74" };

  4. Create a string variable named partition_key with a value of 9603ca6c-9e28-4a02-9194-51cdb7fea816:

     const partitionKey = "9603ca6c-9e28-4a02-9194-51cdb7fea816";

  5. Create a new batch with the light and helmet items:

     const partitionKey = "9603ca6c-9e28-4a02-9194-51cdb7fea816";
 const batch = [
     { operationType: BulkOperationType.Create, resourceBody: light },
     { operationType: BulkOperationType.Create, resourceBody: helmet },
 ];

  6. Once you are done, your code file should now include:

     const { CosmosClient, BulkOperationType } = require("@azure/cosmos");
 const { DefaultAzureCredential  } = require("@azure/identity");
 process.env.NODE_TLS_REJECT_UNAUTHORIZED = 0

 const endpoint = "<cosmos-endpoint>";
 const credential = new DefaultAzureCredential();

 const client = new CosmosClient({ endpoint, aadCredentials: credential });

 async function main() {
     // Create database
     const { database } = await client.databases.createIfNotExists({ id: "cosmicworks" });
            
     // Create container
     const { container } = await database.containers.createIfNotExists({
         id: "products",
         partitionKey: { paths: ["/categoryId"] },
         throughput: 400
     });
    
     const light = { id: "012B", name: "Flickering Strobe Light", categoryId: "9603ca6c-9e28-4a02-9194-51cdb7fea816" };
     const helmet = { id: "012C", name: "New Helmet", categoryId: "0feee2e4-687a-4d69-b64e-be36afc33e74" };
    
     const partitionKey = "9603ca6c-9e28-4a02-9194-51cdb7fea816";
     const batch = [
         { operationType: BulkOperationType.Create, resourceBody: light },
         { operationType: BulkOperationType.Create, resourceBody: helmet },
     ];
    
     try {
         const response = await container.items.batch(batch, partitionKey);
    
         response.result.forEach((operationResult, index) => {
             const { statusCode, requestCharge, resourceBody } = operationResult;
             console.log(`Operation ${index + 1}: Status code: ${statusCode}, Request charge: ${requestCharge}, Resource: ${JSON.stringify(resourceBody)}`);
         });
     } catch (error) {
         if (error.code === 400) {
             console.error("Bad Request: Check the structure of the batch.");
         } else if (error.code === 409) {
             console.error("Conflict: One of the items already exists.");
         } else if (error.code === 429) {
             console.error("Too Many Requests: Throttling limit reached.");
         } else {
             console.error(`Batch operation failed. Error code: ${error.code}, message: ${error.message}`);
         }
     }
 }
    
 main().catch((error) => console.error(error));

  7. Save and run the script again:

     node script.js

  8. Observe the output from the terminal. The status code on the items should be either 424 for Failed Dependency, or 400 for Bad Request. This occurred because all items within the transaction did not share the same partition key value as the transactional batch.

  9. Close the integrated terminal.

  10. Close Visual Studio Code.