Announcing JavaScript SDK v4 for Azure Cosmos DB 

Sajeetharan Sinnathurai

We are excited to announce the public preview of JavaScript SDK for Azure Cosmos DB version 4. The Azure Cosmos DB JavaScript SDK helps developers build Azure Cosmos DB applications with the NoSQL API and perform various operations more efficiently. The preview of version 4 is now available for download or to provide feedback on GitHub. The SDK targets Node v16 and above and has many new features including Hierarchical partition keys, Client-side request diagnostics, Index metrics , new implementation for Change Feed, Priority-based throttling, etc. The SDK is fully open-sourced, written in TypeScript, supports JavaScript promises and the async/await programming model, and aligns with JS guidelines.

The JavaScript SDK Change Log page has links to all our JavaScript SDK v4 documentation and samples and is the best starting point for anything you want to learn about the SDK. In this blog post, I’ll highlight the most exciting offerings in this new release.

Exploring the Latest Enhancements in the JavaScript SDK

Client-Side Request Diagnostics:

Introducing the Client-Side Request Diagnostics Feature in @azure/cosmos JavaScript SDK v4!. we are introducing the Client-Side Request Diagnostics feature to provide enhanced insights into your client operations, such as Item.read() and Containes.create(), queryIterator.fetchAll(), Item.batch(). A CosmosDiagnostics object is added to response of all client operations, which contains –

• ClientSideRequestStatistics Type: This type contains aggregated diagnostic details, including metadata lookups, retries, endpoints contacted, and request and response statistics like payload size and duration. (collected at diagnostic level info or higher, enabled by default)
• DiagnosticNode: Is a tree-like structure that captures detailed diagnostic information. This feature is disabled by default and is intended for debugging non-production environments only. (collected at diagnostic level debug or higher)
• ClientConfig: Captures essential information related to your client’s configuration settings during client initialization. (collected at diagnostic level debug or higher)

`CosmosDbDiagnosticLevel` Controls the level of detail captured, possible values are silent, debug, and debug-unsafe, with silent being the default value.

If CosmosDbDiagnosticLevel is higher than debug and Azure log level is higher than verbose the diagnostic will be logged.

Here are samples for diagnostic features –

1. Point lookup operators
2. Batch operations
3. Query operations

 Hierarchical Partitioning :

JavaScript SDK v4 adds support for Hierarchical Partitions. Please refer this document to understand the hierarchical partition feature.

Here are samples for Hierarchical Partitioning

 Change Feed new Implementation:

The JavaScript v4 SDK now supports the changefeed pull model for Azure Cosmos DB. Users can now consume change feed at their own pace, choosing to fetch change feed for an entire container, specific feed range, or a partition key. Additionally, they can initiate from various starting points, such as continuation tokens, the feed’s beginning, the current time, or a specified start time.

Following are the samples for trying out the change feed using JS SDK v4:

1. Changefeed for the entire container
2. Changefeed for a feed range
3. Changefeed for a partition key

Priority level request option:

Support to set priority in request options as Low and High. This ensures that low-priority requests are throttled before the high-priority requests when throughput limits are reached. More details can be found here.

Priority level can be set while performing any operation on the documents by passing it as a request option.

Example:

const response = await container.item(document.id).read<TestItem>({ priorityLevel: PriorityLevel.Low });

Index Metrics:

This update enhances Azure Cosmos DB query functionality with the ability to retrieve and display index metrics for the query execution, providing valuable insights for improving performance. Learn more about Index Metrics.

const { resources: resultsIndexMetrics, indexMetrics } = await container.items
.query(querySpec, { populateIndexMetrics: true })
.fetchAll();
console.log("IndexMetrics: ", indexMetrics);
console.log("Query results: ", resultsIndexMetrics);

Upgrade to JavaScript SDK v4

Thinking of upgrading to JavaScript SDK v4? Here’s a quick summary of the versions we’ve released so far and the relevant Change Log.

With v4, Definition of PartitionKey has been made stricter now, but it is practically backward compatible with previous definition of Partition Key. PartitionKeyDefinition has been removed from definition of PartitionKey and is now a independent type now.

We recommend upgrading to JavaScript SDK v4 for the best performance, the newest features, and continued long-term support. Look and give it your best shot!

Get started Azure Cosmos DB JavaScript SDK

It’s alright if you’re completely new to the JavaScript SDK – follow these three steps to get started fast:

1. Install the latest Nodejs version so you can use the SDK.
2. Work through the Quickstart Guide for Javascript SDK v4 which gets you access to the Javascript SDK v4 npm package and walks you through basic Azure Cosmos DB requests.
3. Read the JavaScript SDK best practices  to optimize the SDK for your application.

.Then visit the JavaScript SDK v4 Release Notes page for the rest of our documentation and sample code.

Happy coding!

About Azure Cosmos DB

Azure Cosmos DB is a fully managed and serverless distributed database for modern app development, with SLA-backed speed and availability, automatic and instant scalability, and support for open-source PostgreSQL, MongoDB and Apache Cassandra. Try Azure Cosmos DB for free here. To stay in the loop on Azure Cosmos DB updates, follow us on Twitter, YouTube, and LinkedIn.

To quickly build your first database, watch our Get Started videos on YouTube and explore ways to dev/test free.

Sajeetharan Sinnathurai Principal Program Manager , Azure CosmosDB

Follow