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.

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

Release notes


  • TCP mode now on by default
  • Query metrics in cross partition now returns all partitions
  • Global Strong now works properly
  • Failover for queries not properly retries for multi-master
  • Dependency bumps for security hotfixes


  • Bugfix for Hash V2 support


  • Bugfix for resource leak on client#close() (github #88).


  • Added continuation token support for cross partition queries.


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


  • Direct mode connectivity is now Generally Available(GA). For a sample that uses direct mode connectivity, see azure-cosmosdb-java GitHub repository.
  • 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.


  • Added support for direct mode connectivity.
  • 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).


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


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


  • Fixed a packaging bug.


  • 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.


  • Added support for Multi-region write.


  • 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.


  • Fixed a bug for non-english locales (GitHub #51).
  • Added helper methods in Conflict Resource.


  • 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.


  • 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).


  • Added back-pressure support in query.
  • Added support for partition key range id in query.
  • Fix 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.
  • Fix to avoid passing session token when reading master resources.
  • Added more examples.
  • Added more benchmarking scenarios.
  • Fixed Java header files for proper java doc generation.


  • GA SDK with end-to-end support for non-blocking IO using the Netty library in gateway mode.

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.

Version Release Date Retirement Date
2.4.3 Mar 5, 2019 ---
2.4.2 Mar 1, 2019 ---
2.4.1 Feb 20, 2019 ---
2.4.0 Feb 8, 2019 ---
2.4.0-beta-1 Feb 4, 2019 ---
2.3.1 Jan 15, 2019 ---
2.3.0 Nov 29, 2018 ---
2.2.2 Nov 8, 2018 ---
2.2.1 Nov 2, 2018 ---
2.2.0 September 22, 2018 ---
2.1.0 September 5, 2018 ---
2.0.1 August 16, 2018 ---
2.0.0 June 20, 2018 ---
1.0.2 May 18, 2018 ---
1.0.1 April 20, 2018 ---
1.0.0 February 27, 2018 ---


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.