Perform bulk operations in Azure Cosmos DB for NoSQL using the Azure SDK for JavaScript

06/09/2025
Applies to: NoSQL

In this guide, use the executeBulkOperations feature in the Azure SDK for JavaScript to perform bulk create and update operations in Azure Cosmos DB for NoSQL. This feature adjusts per-partition concurrency, automatically handles retry logic for each individual operation, and performs large quantities (100+) of operations. This feature automatically adjusts concurrency dynamically by increasing when calls succeed without throttling and scaling back when throttling occurs.

Prerequisites

An existing Azure Cosmos DB for NoSQL account
- If you don't have an existing account, create a new account.
Node.js 22.x or later

Initialize your development environment

Start by creating a development environment with an initial project and all developer dependencies. For this project, you're going to install the @azure/cosmos from the Azure SDK for JavaScript as a development dependency.

Open a terminal in an empty folder.
Initialize a new Node.js project.
```
npm init
```

Update your newly generated package.json file with this content.

{
  "main": "app.js",
  "scripts": {
    "start": "node app.js"
  }
}

Install the @azure/cosmos package from Node Package Manager (npm).
```
npm install --save @azure/cosmos
```
Important

The bulk execution feature is available in versions 4.3 or later of the @azure/cosmos library in the Azure SDK for JavaScript. If you're using an older version of the SDK, you must migrate to a newer version to use these features.

Configure your connection and resources

Now, use the installed package to configure your connection to an existing Azure Cosmos DB for NoSQL account.

Import the CosmosClient type and the BulkOperationType and PatchOperationType supporting types.

const { BulkOperationType, PatchOperationType, CosmosClient } = require('@azure/cosmos');

Create a new instance of the CosmosClient class passing in the appropriate credentials for your account.

const client = new CosmosClient({
    endpoint: '<azure-cosmos-db-nosql-account-endpoint>',
    credential
});

Create constants for pointers to your existing database and container resources.

const database = client.database('<database-name>');

const container = database.container('<container-name>');

Create a multi-upsert operation in bulk

Start by performing a bulk operation that upserts two items. Both items are composed in an array of OperationInput items. Upsert and Create operations must include, at a minimum, the unique identifier (id) and partition key fields.

Note

In this example, the partition key is the /category field.

Create two constants for items to upsert into the container.

const yambdaSurfboard = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
    category: 'gear-surf-surfboards',
    name: 'Yamba Surfboard',
    quantity: 12,
    price: 850.0,
    clearance: false
};

const kiamaClassicSurfboard = {
    id: 'bbbbbbbb-1111-2222-3333-cccccccccccc',
    category: 'gear-surf-surfboards',
    name: 'Kiama Classic Surfboard',
    quantity: 25,
    price: 790.0,
    clearance: true
};

Create an array of operations using the Upsert operation for both items. Explicitly specify the partitionKey property and the item itself in the resourceBody property.

const upsertOperations = [
    {
        operationType: BulkOperationType.Upsert,
        partitionKey: 'gear-surf-surfboards',
        resourceBody: yambdaSurfboard
    },
    {
        operationType: BulkOperationType.Upsert,
        partitionKey: 'gear-surf-surfboards',
        resourceBody: kiamaClassicSurfboard
    }
];

Parse the bulk operation response

Run and then review the response from the bulk operation. The response contains metadata about each operation.

Perform the operations in bulk using the executeBulkOperations method of the items property of your container.
```
const response = await container.items.executeBulkOperations(upsertOperations);

console.log(response);
```

Parse the response object. The response contains a status code and response object for successful operations. Failed operations include an error object instead.

npm run start

Note

To minimize the size of the response payload, set contentResponseOnWriteEnabled to false. This flag is specific to bulk and batch features in the SDK.

[
  {
    operationInput: {
      operationType: 'Upsert',
      id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
      partitionKey: 'gear-surf-surfboards',
      resourceBody: { ... }
    },
    response: {
      statusCode: 201,
      eTag: '...',
      activityId: '...',
      requestCharge: 7.23,
      resourceBody: { ... },
      diagnostics: { ... },
      headers: { ... }
    }
  },
  ...
]

Perform more bulk operations

Optionally, you can perform other operations including Read, Delete, and Patch. All the operations used in this section must include the partition key field.

Tip

The Create and Upsert operations require both the id and partition key fields. The remaining operations, Read, Delete, Replace, and Patch only require the partition key field. If the required fields aren't specified, the operation fails.

const variousOperations = [
    {
        operationType: BulkOperationType.Read,
        id: 'bbbbbbbb-1111-2222-3333-cccccccccccc',
        partitionKey: 'gear-surf-surfboards',
    },
    {
        operationType: BulkOperationType.Delete,
        id: 'bbbbbbbb-1111-2222-3333-cccccccccccc',
        partitionKey: 'gear-surf-surfboards',
    },
    {
        operationType: BulkOperationType.Patch,
        id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
        partitionKey: 'gear-surf-surfboards',
        resourceBody: {
            operations: [
                {
                    op: PatchOperationType.add,
                    path: '/onSale',
                    value: true
                }
            ],
        },
    }
]

const response = await container.items.executeBulkOperations(upsertOperations);