Interact with Azure Cosmos DB NoSQL API

This skill covers @azure/cosmos (current version 4.9.0, requiring Node.js 20+), the TypeScript/JavaScript data-plane SDK for Azure Cosmos DB's NoSQL API - CRUD on documents, queries, and bulk operations - explicitly distinguished from the separate @azure/arm-cosmosdb management-plane SDK used to create accounts, databases, and containers via ARM. It authenticates a CosmosClient either via AAD with DefaultAzureCredential (recommended) or key-based (endpoint+key or a connection string), and documents the resource hierarchy (CosmosClient → Database → Container → Items/Scripts/Conflicts). Core operations cover creating a database and container, then full CRUD on typed documents (create, read, replace, upsert, delete), plus JSON-Patch-style partial updates (patch with replace/add/remove operations). Queries are shown as simple inline SQL, parameterized SqlQuerySpec (recommended, to prevent injection and improve plan caching), paginated with maxItemCount and a continuationToken, and explicitly cross-partition (enableCrossPartitionQuery: true). Bulk operations (executeBulkOperations) batch Create/Upsert/Read/Replace/Delete/Patch operations in one call, checking each result's status code individually. Partition keys cover both a simple single-path case and a hierarchical (MultiHash) partition key spanning multiple paths (e.g. /tenantId, /userId, /sessionId), which requires operations to pass an array of partition key values instead of a single value. Error handling catches ErrorResponse and switches on status code (404 not found, 409 conflict, 412 precondition/ETag mismatch, 429 rate limited with retryAfterInMs), and optimistic concurrency is demonstrated by reading a document's ETag, then replacing it with accessCondition: { type: "IfMatch", condition: etag } so a concurrent modification surfaces as a 412 rather than silently overwriting. A worked ProductService class shows a service-layer pattern wrapping getById/create/findByCategory around the container, translating a 404 into a null return rather than a thrown error.

Use this skill when building a TypeScript or JavaScript application that reads or writes documents in Azure Cosmos DB's NoSQL API - CRUD, partial updates, bulk writes, or partition-scoped queries. It is not for provisioning Cosmos DB infrastructure (accounts, databases, containers via ARM) - that's the separate @azure/arm-cosmosdb management SDK - and it is specific to the NoSQL API, not Cosmos DB's MongoDB/Cassandra/Gremlin/Table API surfaces.

Input is a Cosmos endpoint and AAD or key credentials, database/container names, a partition key definition, and typed document objects or SQL query specs. Output is created/read/replaced/patched/deleted documents, paginated query result sets with continuation tokens, and per-operation bulk-execution status codes.

Built on @azure/cosmos (data plane) and @azure/identity for AAD authentication, with @azure/arm-cosmosdb as the companion management-plane SDK for provisioning.

npm install @azure/cosmos @azure/identity

TypeScript/JavaScript developers building applications on Azure Cosmos DB's NoSQL API who need CRUD, bulk writes, hierarchical partitioning, and safe concurrent updates via ETags, with type-safe access through the SDK's exported types (Database, Container, FeedOptions, and related response types).