Azure Cosmos DB Node.js SDK for SQL API: Release notes and resources

Resource Link
Download SDK NPM
API Documentation JavaScript SDK reference documentation
SDK installation instructions Installation instructions
Contribute to SDK GitHub
Samples Node.js code samples
Getting started tutorial Get started with the JavaScript SDK
Web app tutorial Build a Node.js web application using Azure Cosmos DB
Current supported platform Node.js v6.x - required for SDK Version 2.0.0 and above.
Node.js v4.2.0
Node.js v0.12
Node.js v0.10

Release notes


  • Adds interface for node Agent type. Typescript users no longer have to install @types/node as a dependency
  • Preferred locations are now properly honored
  • Improvements to contributing developer documentation
  • Various typo fixes


  • Fixes type definition issue introduced in 2.0.3


  • Remove big-integer dependency
  • Switch to reference directives for AsyncIterable type. Typescript users no longer have to customize their "lib" setting.
  • Typo Fixes


  • Fix readme links


  • Fix retry interface implementation


  • GA of Version 2.0.0 of the JavaScript SDK
  • Added support for multi-region writes.


  • RC1 of Version 2.0.0 of the JavaScript SDK for public preview.
  • New object model, with top-level CosmosClient and methods split across relevant Database, Container, and Item classes.
  • Support for promises.
  • SDK converted to TypeScript.


  • npm documentation fixed.


  • Added support for default retries on connection issues.
  • Added support to read collection change feed.
  • Fixed session consistency bug that intermittently caused "read session not available".
  • Added support for query metrics.
  • Modified http Agent's maximum number of connections.


  • Updated documentation to reference Azure Cosmos DB instead of Azure DocumentDB.
  • Added Support for proxyUrl setting in ConnectionPolicy.


  • Minor fix for case sensitive file systems.


  • Adds support for Session Consistency.
  • This SDK version requires the latest version of Azure Cosmos DB Emulator available for download from


  • Split proofed cross partition queries.
  • Adds supports for resource link with leading and trailing slashes (and corresponding tests).


  • npm documentation fixed.


  • Fixed a bug in executeStoredProcedure where documents involved had special Unicode characters (LS, PS).
  • Fixed a bug in handling documents with Unicode characters in the partition key.
  • Fixed support for creating collections with the name media. GitHub issue #114.
  • Fixed support for permission authorization token. GitHub issue #178.


  • Added support for a new consistency level called ConsistentPrefix.
  • Added support for UriFactory.
  • Fixed a Unicode support bug. GitHub issue #171.


  • Added the support for aggregation queries (COUNT, MIN, MAX, SUM, and AVG).
  • Added the option for controlling degree of parallelism for cross partition queries.
  • Added the option for disabling SSL verification when running against Azure Cosmos DB Emulator.
  • Lowered minimum throughput on partitioned collections from 10,100 RU/s to 2500 RU/s.
  • Fixed the continuation token bug for single partition collection. GitHub issue #107.
  • Fixed the executeStoredProcedure bug in handling 0 as single param. GitHub issue #155.


  • Fixed user-agent header to include the SDK version.
  • Minor code cleanup.


  • Disabling SSL verification when using the SDK to target the emulator(hostname=localhost).
  • Added support for enabling script logging during stored procedure execution.


  • Added support for cross partition parallel queries.
  • Added support for TOP/ORDER BY queries for partitioned collections.


  • Added retry policy support for throttled requests. (Throttled requests receive a request rate too large exception, error code 429.) By default, Azure Cosmos DB retries nine times for each request when error code 429 is encountered, honoring the retryAfter time in the response header. A fixed retry interval time can now be set as part of the RetryOptions property on the ConnectionPolicy object if you want to ignore the retryAfter time returned by server between the retries. Azure Cosmos DB now waits for a maximum of 30 seconds for each request that is being throttled (irrespective of retry count) and returns the response with error code 429. This time can also be overridden in the RetryOptions property on ConnectionPolicy object.
  • Cosmos DB now returns x-ms-throttle-retry-count and x-ms-throttle-retry-wait-time-ms as the response headers in every request to denote the throttle retry count and the cumulative time the request waited between the retries.
  • The RetryOptions class was added, exposing the RetryOptions property on the ConnectionPolicy class that can be used to override some of the default retry options.


  • Added the support for multi-region database accounts.


  • Added the support for Time To Live(TTL) feature for documents.



  • Fixed RangePartitionResolver.resolveForRead bug where it was not returning links due to a bad concat of results.


  • Fixed hashPartitionResolver resolveForRead(): When no partition key supplied was throwing exception, instead of returning a list of all registered links.


  • Fixes issue #100 - Dedicated HTTPS Agent: Avoid modifying the global agent for Azure Cosmos DB purposes. Use a dedicated agent for all of the lib’s requests.


  • Fixes issue #81 - Properly handle dashes in media ids.


  • Fixes issue #95 - EventEmitter listener leak warning.


  • Fixes issue #92 - rename folder Hash to hash for case-sensitive systems.


  • Implement sharding support by adding hash & range partition resolvers.


  • Implement Upsert. New upsertXXX methods on documentClient.


  • Skipped to bring version numbers in alignment with other SDKs.


  • Split Q promises wrapper to new repository.
  • Update to package file for npm registry.


  • Implements ID Based Routing.
  • Fixes Issue #49 - current property conflicts with method current().


  • Added support for GeoSpatial index.
  • Validates id property for all resources. Ids for resources cannot contain ?, /, #, //, characters or end with a space.
  • Adds new header "index transformation progress" to ResourceResponse.


  • Implements V2 indexing policy.


  • Issue #40 - Implemented eslint and grunt configurations in the core and promise SDK.


  • Issue #45 - Promises wrapper does not include header with error.


  • Implemented ability to query for conflicts by adding readConflicts, readConflictAsync, and queryConflicts.
  • Updated API documentation.
  • Issue #41 - client.createDocumentAsync error.


  • GA SDK.

Release & Retirement Dates

Microsoft provides notification at least 12 months in advance of retiring an SDK in order to smooth the transition to a newer/supported version.

New features and functionality and optimizations are only added to the current SDK, as such it is recommended that you always upgrade to the latest SDK version as early as possible.

Any request to Cosmos DB using a retired SDK is be rejected by the service.

Version Release Date Retirement Date
2.0.0-3 (RC) August 2, 2018 ---
1.14.4 May 03, 2018 ---
1.14.3 May 03, 2018 ---
1.14.2 December 21, 2017 ---
1.14.1 November 10, 2017 ---
1.14.0 November 9, 2017 ---
1.13.0 October 11, 2017 ---
1.12.2 August 10, 2017 ---
1.12.1 August 10, 2017 ---
1.12.0 May 10, 2017 ---
1.11.0 March 16, 2017 ---
1.10.2 January 27, 2017 ---
1.10.1 December 22, 2016 ---
1.10.0 October 03, 2016 ---
1.9.0 July 07, 2016 ---
1.8.0 June 14, 2016 ---
1.7.0 April 26, 2016 ---
1.6.0 March 29, 2016 ---
1.5.6 March 08, 2016 ---
1.5.5 February 02, 2016 ---
1.5.4 February 01, 2016 ---
1.5.2 January 26, 2016 ---
1.5.2 January 22, 2016 ---
1.5.1 January 4, 2016 ---
1.5.0 December 31, 2015 ---
1.4.0 October 06, 2015 ---
1.3.0 October 06, 2015 ---
1.2.2 September 10, 2015 ---
1.2.1 August 15, 2015 ---
1.2.0 August 05, 2015 ---
1.1.0 July 09, 2015 ---
1.0.3 June 04, 2015 ---
1.0.2 May 23, 2015 ---
1.0.1 May 15, 2015 ---
1.0.0 April 08, 2015 ---


1. How will customers be notified of the retiring SDK?

Microsoft will provide 12 month advance notification to the end of support of the retiring SDK in order to facilitate a smooth transition to a supported SDK. Further, customers will be notified through various communication channels – Azure Management Portal, Developer Center, blog post, and direct communication to assigned service administrators.

2. Can customers author applications using a "to-be" retired Azure Cosmos DB SDK during the 12 month period?

Yes, customers will have full access to author, deploy and modify applications using the "to-be" retired Azure Cosmos DB SDK during the 12 month grace period. During the 12 month grace period, customers are advised to migrate to a newer supported version of Azure Cosmos DB SDK as appropriate.

3. Can customers author and modify applications using a retired Azure Cosmos DB SDK after the 12 month notification period?

After the 12 month notification period, the SDK will be retired. Any access to Azure Cosmos DB by an applications using a retired SDK will not be permitted by the Azure Cosmos DB platform. Further, Microsoft will not provide customer support on the retired SDK.

4. What happens to Customer’s running applications that are using unsupported Azure Cosmos DB SDK version?

Any attempts made to connect to the Azure Cosmos DB service with a retired SDK version will be rejected.

5. Will new features and functionality be applied to all non-retired SDKs?

New features and functionality will only be added to new versions. If you are using an old, non-retired, version of the SDK your requests to Azure Cosmos DB will still function as previous but you will not have access to any new capabilities.

6. What should I do if I cannot update my application before a cut-off date?

We recommend that you upgrade to the latest SDK as early as possible. Once an SDK has been tagged for retirement you will have 12 months to update your application. If, for whatever reason, you cannot complete your application update within this timeframe then please contact the Cosmos DB Team and request their assistance before the cutoff date.

See also

To learn more about Cosmos DB, see Microsoft Azure Cosmos DB service page.