Interact with Azure Cosmos DB NoSQL API

Use this guide when a JavaScript or TypeScript service needs to read and write documents, issue queries, perform bulk operations, or manage data-plane resources through the documented client SDK. It focuses on application data operations. Account provisioning and other control-plane tasks belong to a separate management SDK and should not be confused with calls that manipulate documents inside an existing account.

Install the document database client package alongside the identity package when using directory-based credentials. The examples construct a client from an endpoint and a default credential chain, which is the recommended authentication approach in the source. This keeps long-lived account keys out of application code. Key and connection-string alternatives are available for environments that require them; treat those values as secrets, load them from the approved runtime secret store, and never commit or log them.

The client exposes a hierarchy of account client, database, container, items, and scripts or conflict resources. A database and container can be created if absent using the corresponding create-if-not-exists methods. Container setup includes a partition-key path, which is a foundational data-model decision: item operations commonly need the item identifier together with its partition key. Choose paths based on access patterns and distribution requirements before loading production data.

The guide demonstrates creating typed documents, reading a document by identifier and partition value, updating it by reading and replacing the current resource, and using upsert when insert-or-replace semantics are intended. A replace workflow should account for the possibility that the item was not found between the read and write, and concurrent updates may require an explicit concurrency strategy. Delete operations should be scoped to the intended item and partition.

Queries can be issued through the container's item query interface, with parameters used for values rather than unsafe string interpolation. For large workloads, use bulk operations and inspect every returned status so partial failures are not mistaken for complete success. Use bounded batches and understand retry behavior before increasing throughput.

A simple partition key uses one document path. Hierarchical keys use PartitionKeyDefinitionVersion.V2 with PartitionKeyKind.MultiHash; the example paths are /tenantId, /userId, and /sessionId. With this key, operations must provide the matching array of partition values. Ensure the values in each document align with the configured paths; mismatches can make point reads or writes fail or route unexpectedly. Partition strategy affects query fan-out and operational cost, so evaluate it against expected reads, writes, and tenant boundaries.

Separate data-plane code from infrastructure provisioning. Use least-privilege identity permissions, validate input before writes, and handle absent resources and service errors explicitly. Avoid logging full documents if they may contain personal or confidential data. For bulk work, capture per-operation outcomes and make retries idempotent where possible. Confirm the installed SDK version and its current method signatures rather than assuming examples remain unchanged.

For TypeScript or JavaScript application access, test representative queries and partition behavior against a non-production account before affecting live data. Database design review, backup planning, access-control policy, and migration planning remain separate responsibilities.