Azure Cosmos DB Async Java SDK for SQL API: Release notes and resources


The SQL API Async Java SDK differs from the SQL API Java SDK by providing asynchronous operations with support of the Netty library. The pre-existing SQL API Java SDK does not support asynchronous operations.


This is not the latest Java SDK for Azure Cosmos DB! Consider using Azure Cosmos DB Java SDK v4 for your project. To upgrade, follow the instructions in the Migrate to Azure Cosmos DB Java SDK v4 guide and the Reactor vs RxJava guide.


On August 31, 2024 the Azure Cosmos DB Async Java SDK v2.x will be retired; the SDK and all applications using the SDK will continue to function; Azure Cosmos DB will simply cease to provide further maintenance and support for this SDK. We recommend following the instructions above to migrate to Azure Cosmos DB Java SDK v4.

SDK Download Maven
API documentation Java API reference documentation
Contribute to SDK GitHub
Get started Get started with the Async Java SDK
Code sample GitHub
Performance tips GitHub readme
Minimum supported runtime JDK 8

2.6.13 - 2021-01-20

  • Fixed "request headers is too long" for query plan and CRUD operations on stored procedures.
  • Fixed issue with enabling openssl.

2.6.12 - 2021-01-18

  • Fixed an issue with excessive regional fail-overs when retrieving responses with invalid json from Gateway.

2.6.11 - 2020-09-15

  • Added http request time out cap for avoiding region failover for high latency request.(#360)

2.6.10 - 2020-08-31

  • Fixes region fail over issue for direct tcp calls, direct tcp calls network failure will be retried in other available region but it wont mark the current region unavailable, and subsequent tcp requests will still go to current region.(#351)

2.6.9 - 2020-06-15

  • Fixed duplicate results on order by when resuming from continuation token (#341)

2.6.8 - 2020-05-11

  • Fixes an issue due to which the order by results when resuming from continuation token might contain duplicates/missing documents (#332)

2.6.7 - 2020-04-21

  • Fixed multiple memory leak in direct TCP transport client (#326)

2.6.6 - 2020-03-12

  • Made DocumentClientException thread safe (#323)

2.6.5 - 2020-01-31

  • Fixed an issue where continuation token is not being set properly when trying to resume cross partition queries(#312)
  • Moving deserialization out of netty threads (#315)
  • Fixed dont retry writes on forbidden (#307)

2.6.4 - 2020-01-02

  • Fixed a bug where SDK was retrying on writes on network failure(#301)
  • Add support for specifying default Direct TCP options using System properties (#299)
  • Improved diagnostics in Direct TCP transport client (#287)
  • Bumped netty.version to 4.1.42.Final and netty-tcnative.version to 2.0.26.Final to address a Direct TCP SSL issue (#274)

2.6.3 - 2019-10-23

  • Addressed status code reporting errors that undermined retry policy:
    • RequestRateTooLargeException.getStatusCode now correctly returns TOO_MANY_REQUESTS.
    • ServiceUnavailableException.getStatusCode now correctly returns SERVICE_UNAVAILABLE.
    • DocumentClientExceptionTest in commons and direct-impl now verify that the correct status code is returned for all DocumentClientException subtypes.

2.6.2 - 2019-10-05

  • Fixed query failure when setting MaxItemCount to -1 (#261).
  • Fixed a NPE bug on Partitoin split (#267).
  • Improved logging in Direct mode.

2.6.1 - 2019-09-04

  • Multimaster regional failover fixes for query logic (#245)
  • jackson-databind update (#244)
  • Direct TCP fixes (memory, perf) & metrics interface (#242)

2.6.0 - 2019-08-01

  • Retrieving query info using new query plan retriever (#111)
  • Offset limit query support (#234)

2.5.1 - 2019-07-31

  • Fixing executeStoredProcedureInternal to use client retry policy (#210)

2.4.6 - 2019-07-19

  • memory improvements

2.5.0 - 2019-06-25

  • TCP transport enabled by default
  • TCP transport improvements
  • Lots of testing improvements

2.4.5 - 2019-05-06

  • Added support for Hash v2 (#96)
  • Open source direct connectivity implementation (#94)
  • Added Support for Diagnostics String

2.4.4 - 2019-06-25

  • misc fixes

2.4.3 - 2019-03-05

  • Fixed resource leak issue on closing client

2.4.2 - 2019-03-01

  • Fixed bugs in continuation token support for cross partition queries

2.4.1 - 2019-02-20

  • Fixed some bugs in Direct mode.
  • Improved logging in Direct mode.
  • Improved connection management.

2.4.0 - 2019-02-08

  • Direct GA.
  • Added support for QueryMetrics.
  • Changed the APIs accepting java.util.Collection for which order is important to accept java.util.List instead. Now ConnectionPolicy#getPreferredLocations(), JsonSerialization, and PartitionKey(.) accept List.

2.4.0-beta1 - 2019-02-04

  • Added support for Direct Https.
  • Changed the APIs accepting java.util.Collection for which order is important to accept java.util.List instead. Now ConnectionPolicy#getPreferredLocations(), JsonSerialization, and PartitionKey(.) accept List.
  • Fixed a Session bug for Document query in Gateway mode.
  • Upgraded dependencies (netty 0.4.20 github #79, RxJava 1.3.8).

2.3.1 - 2019-01-15

  • Fix handling very large query responses.
  • Fix resource token handling when instantiating client (github #78).
  • Upgraded vulnerable dependency jackson-databind (github #77).

2.3.0 - 2018-11-29

  • Fixed a resource leak bug.
  • Added support for MultiPolygon
  • Added support for custom headers in RequestOptions.

2.2.2 - 2018-11-26

  • Fixed a packaging bug.

2.2.1 - 2018-11-05

  • Fixed a NPE bug in write retry path.
  • Fixed a NPE bug in endpoint management.
  • Upgraded vulnerable dependencies (github #68).
  • Added support for Netty network logging for troubleshooting.

2.2.0 - 2018-10-04

  • Added support for Multi-region write.

2.1.0 - 2018-09-06

  • Added support for Proxy.
  • Added support for resource token authorization.
  • Fixed a bug in handling large partition keys (github #63).
  • Documentation improved.
  • SDK restructured into more granular modules.

2.0.1 - 2018-08-16

  • Fixed a bug for non-english locales (github #51).
  • Added helper methods for Conflict resource.

2.0.0 - 2018-06-20

  • Replaced org.json dependency by jackson due to performance reasons and licensing (github #29).
  • Removed deprecated OfferV2 class.
  • Added accessor method to Offer class for throughput content.
  • Any method in Document/Resource returning org.json types changed to return a jackson object type.
  • getObject(.) method of classes extending JsonSerializable changed to return a jackson ObjectNode type.
  • getCollection(.) method changed to return Collection of ObjectNode.
  • Removed JsonSerializable subclasses' constructors with org.json.JSONObject arg.
  • JsonSerializable.toJson (SerializationFormattingPolicy.Indented) now uses two spaces for indentation.

1.0.2 - 2018-05-18

  • Added support for Unique Index Policy.
  • Added support for limiting response continuation token size in feed options.
  • Added support for Partition Split in Cross Partition Query.
  • Fixed a bug in Json timestamp serialization (github #32).
  • Fixed a bug in Json enum serialization.
  • Fixed a bug in managing documents of 2MB size (github #33).
  • Dependency com.fasterxml.jackson.core:jackson-databind upgraded to 2.9.5 due to a bug (jackson-databind: github #1599)
  • Dependency on rxjava-extras upgraded to due to a bug (rxjava-extras: github #30).
  • The metadata description in pom file updated to be inline with the rest of documentation.
  • Syntax improvement (github #41), (github #40).

1.0.1 - 2018-04-20

  • Added back-pressure support in query.
  • Added support for partition key range id in query.
  • Changed to allow larger continuation token in request header (bugfix github #24).
  • netty dependency upgraded to 4.1.22.Final to ensure JVM shuts down after main thread finishes.
  • Changed to avoid passing session token when reading master resources.
  • Added more examples.
  • Added more benchmarking scenarios.
  • Fixed java header files for proper javadoc generation.

1.0.0 - 2018-02-26

  • Release 1.0.0 has fully end to end support for non-blocking IO using netty library in Gateway mode.
  • Dependency on azure-documentdb SDK removed.
  • Artifact id changed to azure-cosmosdb from azure-documentdb-rx in 0.9.0-rc2.
  • Java package name changed to from in 0.9.0-rc2.

0.9.0-rc2 - 2018-02-26

  • FeedResponsePage renamed to FeedReponse
  • Some minor modifications to ConnectionPolicy configuration. All time fields and methods in ConnectionPolicy suffixed with "InMillis" to be more precise of the time unit.
  • ConnectionPolicy#setProxy() removed.
  • FeedOptions#pageSize renamed to FeedOptions#maxItemCount
  • Release 1.0.0 deprecates 0.9.x releases.


  • First release of azure-documentdb-rx SDK.
  • CRUD Document API fully non-blocking using netty. Query async API implemented as a wrapper using blocking SDK azure-documentdb.

Release and retirement dates

Microsoft will provide 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. So it's recommended that you always upgrade to the latest SDK version as early as possible.

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


All versions 1.x of the Async Java SDK for SQL API will be retired on August 30, 2020.

Version Release Date Retirement Date
2.6.4 Jan 2, 2020 Aug 31, 2024
2.6.3 Oct 23, 2019 Aug 31, 2024
2.6.2 Oct 5, 2019 Aug 31, 2024
2.6.1 Sept 4, 2019 Aug 31, 2024
2.6.0 Aug 1, 2019 Aug 31, 2024
2.5.1 Jul 31, 2019 Aug 31, 2024
2.4.6 Jul 19, 2019 Aug 31, 2024
2.5.0 Jun 25, 2019 Aug 31, 2024
2.4.5 May 6, 2019 Aug 31, 2024
2.4.3 Mar 5, 2019 Aug 31, 2024
2.4.2 Mar 1, 2019 Aug 31, 2024
2.4.1 Feb 20, 2019 Aug 31, 2024
2.4.0 Feb 8, 2019 Aug 31, 2024
2.4.0-beta-1 Feb 4, 2019 Aug 31, 2024
2.3.1 Jan 15, 2019 Aug 31, 2024
2.3.0 Nov 29, 2018 Aug 31, 2024
2.2.2 Nov 8, 2018 Aug 31, 2024
2.2.1 Nov 2, 2018 Aug 31, 2024
2.2.0 September 22, 2018 Aug 31, 2024
2.1.0 September 5, 2018 Aug 31, 2024
2.0.1 August 16, 2018 Aug 31, 2024
2.0.0 June 20, 2018 Aug 31, 2024
1.0.2 May 18, 2018 August 30, 2020
1.0.1 April 20, 2018 August 30, 2020
1.0.0 February 27, 2018 August 30, 2020


How will I be notified of the retiring SDK?

Azure will provide 12 month's advance notice before the end of support of the retiring SDK to facilitate a smooth transition to a supported SDK. We'll notify you through various communication channels: the Azure portal, Azure updates, and direct communication to assigned service administrators.

Can I author applications by using a to-be-retired Azure Cosmos DB SDK during the 12-month period?

Yes, you'll be able to author, deploy, and modify applications by using the to-be-retired Azure Cosmos DB SDK during the 12-month notice period. We recommend that you migrate to a newer supported version of the Azure Cosmos DB SDK during the 12-month notice period, as appropriate.

After the retirement date, what happens to applications that use the unsupported Azure Cosmos DB SDK?

After the retirement date, Azure Cosmos DB will no longer make bug fixes, add new features, or provide support to the retired SDK versions. If you prefer not to upgrade, requests sent from the retired versions of the SDK will continue to be served by the Azure Cosmos DB service.

Which SDK versions will have the latest features and updates?

New features and updates will be added only to the latest minor version of the latest supported major SDK version. We recommend that you always use the latest version to take advantage of new features, performance improvements, and bug fixes. If you're using an old, non-retired version of the SDK, your requests to Azure Cosmos DB will still function, but you won't have access to any new capabilities.

What should I do if I can't update my application before a cutoff date?

We recommend that you upgrade to the latest SDK as early as possible. After an SDK is tagged for retirement, you'll have 12 months to update your application. If you're not able to update by the retirement date, requests sent from the retired versions of the SDK will continue to be served by Azure Cosmos DB, so your running applications will continue to function. But Azure Cosmos DB will no longer make bug fixes, add new features, or provide support to the retired SDK versions.

If you have a support plan and require technical support, contact us by filing a support ticket.

See also

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