{"id":6701,"date":"2023-09-13T08:57:50","date_gmt":"2023-09-13T15:57:50","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/cosmosdb\/?p=6701"},"modified":"2023-09-18T22:20:21","modified_gmt":"2023-09-19T05:20:21","slug":"announcing-javascript-sdk-v4","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cosmosdb\/announcing-javascript-sdk-v4\/","title":{"rendered":"Announcing JavaScript SDK v4 for Azure Cosmos DB\u00a0"},"content":{"rendered":"<p>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 <a href=\"https:\/\/github.com\/Azure\/azure-sdk-for-js\/blob\/main\/sdk\/cosmosdb\/cosmos\/CHANGELOG.md#400-unreleased\">download<\/a> or to provide feedback on <a href=\"https:\/\/github.com\/Azure\/azure-sdk-for-js\/issues\">GitHub<\/a>. The SDK targets Node v16 and above and has many new features including <a href=\"https:\/\/learn.microsoft.com\/azure\/cosmos-db\/hierarchical-partition-keys\">Hierarchical partition keys<\/a>, <a href=\"https:\/\/github.com\/Azure\/azure-sdk-for-js\/blob\/main\/sdk\/cosmosdb\/cosmos\/samples-dev\/Diagnostics.ts\">Client-side request diagnostics<\/a>, <a href=\"https:\/\/learn.microsoft.com\/azure\/cosmos-db\/nosql\/index-metrics\">Index metrics <\/a>, <a href=\"https:\/\/learn.microsoft.com\/azure\/cosmos-db\/change-feed\">new implementation for Change Feed<\/a>, <a href=\"https:\/\/devblogs.microsoft.com\/cosmosdb\/introducing-priority-based-execution-in-azure-cosmos-db-preview\/\">Priority-based throttling<\/a>, etc. The SDK is fully open-sourced, written in TypeScript, supports JavaScript promises and the async\/await programming model, and aligns with <a href=\"https:\/\/azure.github.io\/azure-sdk\/typescript_introduction.html\">JS guidelines<\/a>.<\/p>\n<p>The JavaScript <a href=\"https:\/\/github.com\/Azure\/azure-sdk-for-js\/blob\/main\/sdk\/cosmosdb\/cosmos\/CHANGELOG.md#400-2023-09-12\">SDK Change Log<\/a> page has links to all our <a href=\"https:\/\/learn.microsoft.com\/azure\/cosmos-db\/nosql\/quickstart-nodejs?tabs=azure-portal%2Cpasswordless%2Cwindows%2Csign-in-azure-cli\">JavaScript SDK v4 documentation and samples<\/a> and is the best starting point for anything you want to learn about the SDK. In this blog post, I\u2019ll highlight the most exciting offerings in this new release.<\/p>\n<h4>Exploring the Latest Enhancements in the JavaScript SDK<\/h4>\n<h4>Client-Side Request Diagnostics:<\/h4>\n<p>Introducing the Client-Side Request Diagnostics Feature in <a href=\"https:\/\/www.npmjs.com\/package\/@azure\/cosmos\">@azure\/cosmos<\/a> 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 &#8211;<\/p>\n<ul>\n<li>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)<\/li>\n<li>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)<\/li>\n<li>ClientConfig: Captures essential information related to your client&#8217;s configuration settings during client initialization. (collected at diagnostic level debug or higher)<\/li>\n<\/ul>\n<p>`CosmosDbDiagnosticLevel` Controls the level of detail captured, possible values are silent, debug, and debug-unsafe, with silent being the default value.<\/p>\n<p>If CosmosDbDiagnosticLevel is higher than debug and Azure log level is higher than verbose the diagnostic will be logged.<\/p>\n<p>Here are samples for diagnostic features &#8211;<\/p>\n<ol>\n<li data-leveltext=\"%1.\" data-font=\"Calibri\" data-listid=\"3\" aria-setsize=\"-1\" data-aria-posinset=\"1\" data-aria-level=\"1\"><a href=\"https:\/\/github.com\/Azure\/azure-sdk-for-js\/blob\/f1845f549589c6c3620a83e17a81e784267285c9\/sdk\/cosmosdb\/cosmos\/samples\/v3\/typescript\/src\/Diagnostics.ts#L39C2-L39C2\">Point lookup operators<\/a><\/li>\n<li data-leveltext=\"%1.\" data-font=\"Calibri\" data-listid=\"3\" aria-setsize=\"-1\" data-aria-posinset=\"1\" data-aria-level=\"1\"><a href=\"https:\/\/github.com\/Azure\/azure-sdk-for-js\/blob\/f1845f549589c6c3620a83e17a81e784267285c9\/sdk\/cosmosdb\/cosmos\/samples\/v3\/typescript\/src\/Diagnostics.ts#L80\">Batch operations<\/a><\/li>\n<li data-leveltext=\"%1.\" data-font=\"Calibri\" data-listid=\"3\" aria-setsize=\"-1\" data-aria-posinset=\"1\" data-aria-level=\"1\"><a href=\"https:\/\/github.com\/Azure\/azure-sdk-for-js\/blob\/f1845f549589c6c3620a83e17a81e784267285c9\/sdk\/cosmosdb\/cosmos\/samples\/v3\/typescript\/src\/Diagnostics.ts#L74\">Query operations<\/a><\/li>\n<\/ol>\n<h5>\u00a0Hierarchical Partitioning :<\/h5>\n<p>JavaScript SDK v4 adds support for Hierarchical Partitions. Please refer this <a href=\"https:\/\/learn.microsoft.com\/azure\/cosmos-db\/hierarchical-partition-keys?tabs=net-v3%2Cbicep\">document<\/a> to understand the hierarchical partition feature.<\/p>\n<p>Here are <a href=\"https:\/\/github.com\/Azure\/azure-sdk-for-js\/blob\/main\/sdk\/cosmosdb\/cosmos\/samples\/v3\/typescript\/src\/HierarchicalPartitioning.ts\">samples for Hierarchical Partitioning<\/a><\/p>\n<h5>\u00a0Change Feed new Implementation:<\/h5>\n<p>The JavaScript v4 SDK now supports the <a href=\"https:\/\/learn.microsoft.com\/azure\/cosmos-db\/nosql\/change-feed-pull-model?tabs=javascript\">changefeed pull model for Azure Cosmos DB<\/a>. 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&#8217;s beginning, the current time, or a specified start time.<\/p>\n<p>Following are the samples for trying out the change feed using JS SDK v4:<\/p>\n<ol>\n<li data-leveltext=\"%1.\" data-font=\"Calibri\" data-listid=\"6\" aria-setsize=\"-1\" data-aria-posinset=\"1\" data-aria-level=\"1\"><a href=\"https:\/\/github.com\/Azure\/azure-sdk-for-js\/blob\/main\/sdk\/cosmosdb\/cosmos\/samples\/v3\/typescript\/src\/ChangeFeedIterator\/ChangeFeedIteratorEntireContainer.ts\">Changefeed for the entire container<\/a><\/li>\n<li data-leveltext=\"%1.\" data-font=\"Calibri\" data-listid=\"6\" aria-setsize=\"-1\" data-aria-posinset=\"1\" data-aria-level=\"1\"><a href=\"https:\/\/github.com\/Azure\/azure-sdk-for-js\/blob\/main\/sdk\/cosmosdb\/cosmos\/samples\/v3\/typescript\/src\/ChangeFeedIterator\/ChangeFeedIteratorEpkRange.ts\">Changefeed for a feed range<\/a><\/li>\n<li data-leveltext=\"%1.\" data-font=\"Calibri\" data-listid=\"6\" aria-setsize=\"-1\" data-aria-posinset=\"1\" data-aria-level=\"1\"><a href=\"https:\/\/github.com\/Azure\/azure-sdk-for-js\/blob\/main\/sdk\/cosmosdb\/cosmos\/samples\/v3\/typescript\/src\/ChangeFeedIterator\/ChangeFeedPartitionKey.ts\">Changefeed for a partition key<\/a><\/li>\n<\/ol>\n<h5>Priority level request option:<\/h5>\n<p>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 <a href=\"https:\/\/devblogs.microsoft.com\/cosmosdb\/introducing-priority-based-execution-in-azure-cosmos-db-preview\/\">here.<\/a><\/p>\n<p>Priority level can be set while performing any operation on the documents by passing it as a request option.<\/p>\n<p>Example:<\/p>\n<pre>const response = await container.item(document.id).read&lt;TestItem&gt;({ priorityLevel: PriorityLevel.Low });<\/pre>\n<h5>Index Metrics:<\/h5>\n<p>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 <a href=\"https:\/\/learn.microsoft.com\/en-us\/azure\/cosmos-db\/nosql\/index-metrics?tabs=javascript\">Index Metrics<\/a>.<\/p>\n<pre>const { resources: resultsIndexMetrics, indexMetrics } = await container.items\r\n.query(querySpec, { populateIndexMetrics: true })\r\n.fetchAll();\r\nconsole.log(\"IndexMetrics: \", indexMetrics);\r\nconsole.log(\"Query results: \", resultsIndexMetrics);<\/pre>\n<h4>Upgrade to JavaScript SDK v4<\/h4>\n<p>Thinking of upgrading to JavaScript SDK v4? Here\u2019s a quick summary of the versions we\u2019ve released so far and the relevant Change Log.<\/p>\n<table data-tablestyle=\"MsoTableGrid\" data-tablelook=\"1696\" aria-rowcount=\"5\">\n<tbody>\n<tr aria-rowindex=\"1\">\n<td data-celllook=\"0\">Javascript SDK<\/td>\n<td data-celllook=\"0\">Release Date<\/td>\n<td data-celllook=\"0\">Package Name<\/td>\n<td data-celllook=\"0\">Release notes<\/td>\n<\/tr>\n<tr aria-rowindex=\"2\">\n<td data-celllook=\"0\">v1<\/td>\n<td data-celllook=\"0\">08\/05\/2015<\/td>\n<td data-celllook=\"0\">documentdb<\/td>\n<td data-celllook=\"0\"><a href=\"https:\/\/github.com\/Azure\/azure-cosmosdb-node\/blob\/master\/changelog.md\">azure-cosmosdb-node\/changelog.md at master \u00b7 Azure\/azure-cosmosdb-node (github.com)\u00a0<\/a><\/td>\n<\/tr>\n<tr aria-rowindex=\"3\">\n<td data-celllook=\"0\">v2<\/td>\n<td data-celllook=\"0\">08\/08\/2018<\/td>\n<td data-celllook=\"0\">azure\/cosmos<\/td>\n<td data-celllook=\"0\"><a href=\"https:\/\/github.com\/Azure\/azure-cosmos-js\/blob\/master\/changelog.md\">azure-cosmos-js\/changelog.md at master \u00b7 Azure\/azure-cosmos-js (github.com)<\/a><\/td>\n<\/tr>\n<tr aria-rowindex=\"4\">\n<td data-celllook=\"0\">v3<\/td>\n<td data-celllook=\"0\">20\/08\/2019<\/td>\n<td data-celllook=\"0\">azure\/cosmos<\/td>\n<td data-celllook=\"0\"><a href=\"https:\/\/github.com\/Azure\/azure-cosmos-js\/blob\/master\/changelog.md#300\">azure-cosmos-js\/changelog.md at master \u00b7 Azure\/azure-cosmos-js (github.com)<\/a><\/td>\n<\/tr>\n<tr aria-rowindex=\"5\">\n<td data-celllook=\"0\">v4<\/td>\n<td data-celllook=\"0\">13\/09\/2023<\/td>\n<td data-celllook=\"0\">azure\/cosmos<\/td>\n<td data-celllook=\"0\"><a href=\"https:\/\/github.com\/Azure\/azure-sdk-for-js\/blob\/main\/sdk\/cosmosdb\/cosmos\/CHANGELOG.md\">azure-sdk-for-js\/sdk\/cosmosdb\/cosmos\/CHANGELOG.md at main \u00b7 Azure\/azure-sdk-for-js (github.com)<\/a><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>&nbsp;<\/p>\n<p><span dir=\"ltr\">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.<\/span><\/p>\n<p>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!<\/p>\n<h4>Get started Azure Cosmos DB JavaScript SDK<\/h4>\n<p>It\u2019s alright if you\u2019re completely new to the JavaScript SDK \u2013 follow these three steps to get started fast:<\/p>\n<ol>\n<li data-leveltext=\"%1.\" data-font=\"Calibri\" data-listid=\"4\" aria-setsize=\"-1\" data-aria-posinset=\"1\" data-aria-level=\"1\">Install the latest <a href=\"https:\/\/nodejs.org\/en\/download\">Nodejs<\/a> version so you can use the <a href=\"https:\/\/www.npmjs.com\/package\/@azure\/cosmos\">SDK<\/a>.<\/li>\n<li data-leveltext=\"%1.\" data-font=\"Calibri\" data-listid=\"4\" aria-setsize=\"-1\" data-aria-posinset=\"1\" data-aria-level=\"1\">Work through the <a href=\"https:\/\/learn.microsoft.com\/azure\/cosmos-db\/nosql\/tutorial-nodejs-web-app\">Quickstart Guide for Javascript SDK v4<\/a> which gets you access to the <a href=\"https:\/\/www.npmjs.com\/package\/@azure\/cosmos\">Javascript SDK v4 npm package<\/a> and walks you through basic Azure Cosmos DB requests.<\/li>\n<li data-leveltext=\"%1.\" data-font=\"Calibri\" data-listid=\"4\" aria-setsize=\"-1\" data-aria-posinset=\"1\" data-aria-level=\"1\">Read the JavaScript SDK <a href=\"https:\/\/learn.microsoft.com\/azure\/cosmos-db\/nosql\/best-practices-javascript\">best practices<\/a> \u00a0to optimize the SDK for your application.<\/li>\n<\/ol>\n<p>.Then visit the <a href=\"https:\/\/github.com\/Azure\/azure-sdk-for-js\/blob\/main\/sdk\/cosmosdb\/cosmos\/CHANGELOG.md#400-2023-09-12\">JavaScript SDK v4 Release Notes<\/a> page for the rest of our <a href=\"https:\/\/learn.microsoft.com\/azure\/cosmos-db\/nosql\/quickstart-nodejs?tabs=azure-portal%2Cpasswordless%2Cwindows%2Csign-in-azure-cli\">documentation and sample code<\/a>.<\/p>\n<p>Happy coding!<\/p>\n<h4>About Azure Cosmos DB<\/h4>\n<p>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. <a href=\"https:\/\/cosmos.azure.com\/try\/\">Try Azure Cosmos DB for free here<\/a>. To stay in the loop on Azure Cosmos DB updates, follow us on <a href=\"https:\/\/twitter.com\/AzureCosmosDB\">Twitter<\/a>, <a href=\"https:\/\/www.youtube.com\/AzureCosmosDB\">YouTube<\/a>, and <a href=\"https:\/\/www.linkedin.com\/company\/azure-cosmos-db\/\">LinkedIn<\/a>.<\/p>\n<p>To quickly build your first database, watch our <a href=\"https:\/\/youtube.com\/playlist?list=PLmamF3YkHLoLLGUtSoxmUkORcWaTyHlXp\">Get Started videos<\/a> on YouTube and explore ways to <a href=\"https:\/\/docs.microsoft.com\/azure\/cosmos-db\/optimize-dev-test\">dev\/test free.<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"<p>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 [&hellip;]<\/p>\n","protected":false},"author":80443,"featured_media":6710,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[12,14,1884],"tags":[1859],"class_list":["post-6701","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-announcements","category-core-sql-api","category-javascript-sdk","tag-javascript"],"acf":[],"blog_post_summary":"<p>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 [&hellip;]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts\/6701","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/users\/80443"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/comments?post=6701"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts\/6701\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/media\/6710"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/media?parent=6701"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/categories?post=6701"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/tags?post=6701"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}