Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
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.
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
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.
Now, use the installed package to configure your connection to an existing Azure Cosmos DB for NoSQL account.
Import the
CosmosClient
type and theBulkOperationType
andPatchOperationType
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>');
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 thepartitionKey
property and the item itself in theresourceBody
property.const upsertOperations = [ { operationType: BulkOperationType.Upsert, partitionKey: 'gear-surf-surfboards', resourceBody: yambdaSurfboard }, { operationType: BulkOperationType.Upsert, partitionKey: 'gear-surf-surfboards', resourceBody: kiamaClassicSurfboard } ];
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 theitems
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 anerror
object instead.npm run start
Note
To minimize the size of the response payload, set
contentResponseOnWriteEnabled
tofalse
. 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: { ... } } }, ... ]
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);