We’re excited to launch version 4 of the Azure Cosmos DB JavaScript SDK! This update delivers major improvements that make it easier and faster to build high-performance apps with the Azure Cosmos DB for NoSQL API. Version 4 is available now and targets Node.js v18 and above, introducing a host of new capabilities, including:

• Improved bulk operation support
• More flexible and scalable query design
• Client-side encryption
• Built-in vector and full-text search support
• Enhanced diagnostic logging …and much more.

Version 4 of the SDK is open source, built entirely in TypeScript, and designed for modern JavaScript development. It offers full support for Promises and the async/await pattern, enabling clean and efficient coding. The SDK also follows official JavaScript SDK design guidelines to ensure consistency and reliability.

For a complete overview of features, documentation, and code samples, visit the JavaScript SDK Change Log. Whether upgrading from an earlier version or starting from scratch, it’s the go-to resource for getting up to speed.

This blog highlights some of the most impactful updates in the release—and how they can help accelerate application development with Azure Cosmos DB.

Latest Enhancements in the JavaScript SDK

Improved Query Control in Azure Cosmos DB JavaScript SDK

The Azure Cosmos DB JavaScript SDK introduces a new query pipeline to give developers finer control over query execution and improve transparency.

What’s Changed?

Previously, each fetchNext call aimed to return up to maxItemCount results, often triggering multiple partition queries behind the scenes. This caused:

• 🚀 Higher RU Consumption: The SDK re-queried partitions to meet result guarantees, leading to increased RU charges and potential throttling.
• ⏱️ Unpredictable Latency: Long-running queries reduced responsiveness and developer control.

🆕Benefits of the New Query Pipeline

• 📌 Partition-Level Query Control Each fetchNext call now queries up to maxDegreeOfParallelism partitions. If no results are available, it returns an empty page with RU usage, without querying all partitions.
• 📊 Granular Resource Tracking Developers can track RUs after each iteration and decide whether to continue or stop querying—giving more control over costs and performance.

⚙️ How to Enable It

Use the enableQueryControl flag in FeedOptions:

const queryOptions: FeedOptions = {  
  maxDegreeOfParallelism: 3,  
  maxItemCount: 10,  
  enableQueryControl: true // Enables the new query pipeline. Default value is false
});  

🔍 How It Works

When enableQueryControl is true, each fetchNext:

Queries a limited number of partitions (up to maxDegreeOfParallelism).

• Returns early with empty results and RU usage if no results are found.
• Does not auto-fulfill maxItemCount by scanning all partitions.

🔄 Backward Compatibility

The flag is disabled by default (enableQueryControl: false), ensuring existing behavior is preserved.

📭 Handling Empty Pages

• Empty pages ≠ query complete.
• Always check the hasMoreResults flag.

1. If true, more results are available.
2. Use this flag instead of assuming based on current page results.

Unlocking Efficient Bulk Workloads with the New executeBulkOperations API in the JavaScript SDK

The new executeBulkOperations API in the Azure Cosmos DB JavaScript SDK introduces major improvements for handling bulk workloads. This release addresses previous limitations and delivers powerful enhancements that streamline performance and efficiency at scale. Here’s what’s new:

• No More 100-Operation Limit The previous restriction of 100 operations per bulk request has been lifted. Applications can now send a much larger number of operations in a single request, improving throughput and reducing client-side batching overhead.
• Operation-Level Retry Mechanism We’ve introduced a smarter retry strategy that applies retries at the individual operation level. Rather than retrying the entire batch when failures occur, each operation is evaluated independently and retried as needed. This results in more resilient and efficient error handling.
• Dynamic Congestion Control The SDK now features intelligent per-partition concurrency control. It automatically adjusts the number of concurrent requests based on real-time feedback—scaling up when operations complete successfully and scaling down when throttling (HTTP 429) responses are detected. This ensures optimal performance while respecting throughput limits.

These enhancements make the JavaScript SDK’s bulk support more scalable, fault-tolerant, and adaptive, perfect for high-volume workloads in modern cloud applications.

Follow the sample here for more details.

Client-side encryption support​

Azure Cosmos DB now supports Always Encrypted for Node.js applications, enabling client-side encryption to protect sensitive data before it ever leaves the application. With the Cosmos DB JavaScript SDK, developers can easily encrypt and decrypt specific properties within documents—while keeping encryption keys entirely under their control.

The integration is simple: define a protected data encryption key and apply encryption policies directly in container operations. Here’s a quick  example!

This feature empowers developers to meet stricter compliance and security requirements, all while maintaining a familiar development experience in Node.js.

New AI Search Capabilities

The Azure Cosmos DB JavaScript SDK now includes powerful AI-driven features. With built-in support for Vector Search, Full-Text Search for advanced text indexing and querying, and Hybrid Search that combines keyword and vector semantics, developers can seamlessly build intelligent, search-enhanced applications. Learn more about Full-Text Search and Hybrid Search.

And Much more!

This release introduces key stable enhancements including Partition Merge support, partial hierarchical partition key handling in Change Feed, index metrics, client-side request diagnostics, and additional features to optimize JavaScript applications with Azure Cosmos DB.

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.

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!

Leave a review

Tell us about your Azure Cosmos DB experience! Leave a review on PeerSpot and we’ll gift you $50. Get started here.

About Azure Cosmos DB

Azure Cosmos DB is a fully managed and serverless NoSQL and vector database for modern app development, including AI applications. With its SLA-backed speed and availability as well as instant dynamic scalability, it is ideal for real-time NoSQL and MongoDB applications that require high performance and distributed computing over massive volumes of NoSQL and vector data.

To stay in the loop on Azure Cosmos DB updates, follow us on X, YouTube, and LinkedIn.

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