Edit

Azure Cosmos DB for NoSQL Java SDK (legacy): Release notes and resources

  • Article

APPLIES TO: NoSQL

This article covers the Azure Cosmos DB Sync Java SDK v2 for the API for NoSQL. This API only supports synchronous operations.

Important

This is not the latest Java SDK for Azure Cosmos DB! We strongly recommend 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.

Warning

On February 29, 2024 the Azure Cosmos DB Sync Java SDK v2.x will be retired. Azure Cosmos DB will cease to provide further maintenance and support for this SDK after retirement. Please follow the instructions here to migrate to Azure Cosmos DB Java SDK v4.

Links
SDK Download Maven
API documentation Java API reference documentation
Contribute to SDK GitHub
Get started Get started with the Java SDK
Web app tutorial Web application development with Azure Cosmos DB
Minimum supported runtime Java Development Kit (JDK) 7+

Release notes

Here's the release notes for each version of the SDK.

2.6.5

  • Removed test dependency com.google.guava/guava due to security vulnerabilities
  • Upgraded dependency com.fasterxml.jackson.core/jackson-databind to 2.14.0
  • Upgraded dependency commons-codec/commons-codec to 1.15
  • Upgraded dependency org.json/json to 20180130

2.6.4

  • Fixed the retry policy for read timeouts

2.6.3

  • Fixed a retry policy when GoneException is wrapped in IllegalStateException - - this change is necessary to make sure Gateway cache is refreshed on 410 so the Spark connector (for Spark 2.4) can use a custom retry policy to allow queries to succeed during partition splits

2.6.2

  • Added a new retry policy to retry on Read Timeouts
  • Upgraded dependency com.fasterxml.jackson.core/jackson-databind to 2.9.10.8
  • Upgraded dependency org.apache.httpcomponents/httpclient to 4.5.13

2.6.1

  • Fixed a bug in handling a query through service interop.

2.6.0

  • Added support for querying change feed from point in time.

2.5.1

  • Fixes primary partition cache issue on documentCollection query.

2.5.0

  • Added support for 449 retry custom configuration.

2.4.7

  • Fixes connection pool timeout issue.
  • Fixes auth token refresh on internal retries.

2.4.6

  • Updated correct client side replica policy tag on databaseAccount and made databaseAccount configuration reads from cache.

2.4.5

  • If the user provides pkRangeId, this version avoids retry on invalid partition key range error

2.4.4

  • Optimized partition key range cache refreshes.
  • Fixes the scenario where the SDK doesn't entertain partition split hint from server and results in incorrect client side routing caches refresh.

2.4.2

  • Optimized collection cache refreshes.

2.4.1

  • Added support to retrieve inner exception message from request diagnostic string.

2.4.0

  • Introduced version API on PartitionKeyDefinition.

2.3.0

  • Added separate timeout support for direct mode.

2.2.3

  • Consuming null error message from service and producing document client exception.

2.2.2

  • Socket connection improvement, adding SoKeepAlive default true.

2.2.0

  • Added request diagnostics string support.

2.1.3

  • Fixed bug in PartitionKey for Hash V2.

2.1.2

  • Added support for composite indexes.
  • Fixed bug in global endpoint manager to force refresh.
  • Fixed bug for upsert operations with preconditions in direct mode.

2.1.1

  • Fixed bug in gateway address cache.

2.1.0

  • Multi-region writes support added for direct mode.
  • Added support for handling IOExceptions thrown as ServiceUnavailable exceptions, from a proxy.
  • Fixed a bug in endpoint discovery retry policy.
  • Fixed a bug to ensure null pointer exceptions aren't thrown in BaseDatabaseAccountConfigurationProvider.
  • Fixed a bug to ensure QueryIterator doesn't return nulls.
  • Fixed a bug to ensure large PartitionKey is allowed.

2.0.0

  • Multi-region writes support added for gateway mode.

1.16.4

  • Fixed a bug in Read partition Key ranges for a query.

1.16.3

  • Fixed a bug in setting continuation token header size in DirectHttps mode.

1.16.2

  • Added streaming failover support.
  • Added support for custom metadata.
  • Improved session handling logic.
  • Fixed a bug in partition key range cache.
  • Fixed an NullPointerException (NPE) bug in direct mode.

1.16.1

  • Added support for Unique Index.
  • Added support for limiting continuation token size in feed-options.
  • Fixed a bug in Json Serialization (timestamp).
  • Fixed a bug in Json Serialization (enum).
  • Dependency on com.fasterxml.jackson.core:jackson-databind upgraded to 2.9.5.

1.16.0

  • Improved Connection Pooling for Direct Mode.
  • Improved Prefetch improvement for nonorderby cross partition query.
  • Improved UUID generation.
  • Improved Session consistency logic.
  • Added support for multipolygon.
  • Added support for Partition Key Range Statistics for Collection.
  • Fixed a bug in Multi-region support.

1.15.0

1.14.0

  • Internal changes for Microsoft friends libraries.

1.13.0

  • Fixed an issue in reading single partition key ranges.
  • Fixed an issue in ResourceID parsing that affects database with short names.
  • Fixed an issue cause by partition key encoding.

1.12.0

  • Critical bug fixes to request processing during partition splits.
  • Fixed an issue with the Strong and BoundedStaleness consistency levels.

1.11.0

  • Added support for a new consistency level called ConsistentPrefix.
  • Fixed a bug in reading collection in session mode.

1.10.0

  • Enabled support for partitioned collection with as low as 2,500 RU/sec and scale in increments of 100 RU/sec.
  • Fixes a bug in the native assembly, which can cause NullRef exception in some queries.

1.9.6

  • Fixed a bug in the query engine configuration that might cause exceptions for queries in Gateway mode.
  • Fixed a few bugs in the session container that might cause an "Owner resource not found" exception for requests immediately after collection creation.

1.9.5

  • Added support for aggregation queries (COUNT, MIN, MAX, SUM, and AVG).
  • Added support for change feed.
  • Added support for collection quota information through RequestOptions.setPopulateQuotaInfo.
  • Added support for stored procedure script logging through RequestOptions.setScriptLoggingEnabled.
  • Fixed a bug where query in DirectHttps mode might stop responding when encountering throttle failures.
  • Fixed a bug in session consistency mode.
  • Fixes a bug, which might cause NullReferenceException in HttpContext when request rate is high.
  • Improved performance of DirectHttps mode.

1.9.4

  • Added simple client instance-based proxy support with ConnectionPolicy.setProxy() API.
  • Added DocumentClient.close() API to properly close down a DocumentClient instance.
  • Improved query performance in direct connectivity mode by deriving the query plan from the native assembly instead of the Gateway.
  • Set FAIL_ON_UNKNOWN_PROPERTIES = false so users don't need to define JsonIgnoreProperties in their Plain Old Java Object (POJO).
  • Refactored logging to use SLF4J.
  • Fixed a few other bugs in consistency reader.

1.9.3

  • Fixed a bug in the connection management to prevent connection leaks in direct connectivity mode.
  • Fixed a bug in the TOP query where it might throw NullReference exception.
  • Improved performance by reducing the number of network calls for the internal caches.
  • Added status code, ActivityID, and Request URI in DocumentClientException for better troubleshooting.

1.9.2

  • Fixed an issue in the connection management for stability.

1.9.1

  • Added support for BoundedStaleness consistency level.
  • Added support for direct connectivity for CRUD operations for partitioned collections.
  • Fixed a bug in querying a database with SQL.
  • Fixed a bug in the session cache where session token might be set incorrectly.

1.9.0

  • Added support for cross partition parallel queries.
  • Added support for TOP/ORDER BY queries for partitioned collections.
  • Added support for strong consistency.
  • Added support for name based requests when using direct connectivity.
  • Fixed to make ActivityId stay consistent across all request retries.
  • Fixed a bug related to the session cache when recreating a collection with the same name.
  • Added Polygon and LineString DataTypes while specifying collection indexing policy for geo-fencing spatial queries.
  • Fixed issues with Java Doc for Java 1.8.

1.8.1

  • Fixed a bug in PartitionKeyDefinitionMap to cache single partition collections and not make extra fetch partition key requests.
  • Fixed a bug to not retry when an incorrect partition key value is provided.

1.8.0

  • Added the support for multi-region database accounts.
  • Added support for automatic retry on throttled requests with options to customize the max retry attempts and max retry wait time. For more information, see RetryOptions and ConnectionPolicy.getRetryOptions().
  • Deprecated IPartitionResolver based custom partitioning code. Use partitioned collections for higher storage and throughput.

1.7.1

  • Added retry policy support for rate limiting.

1.7.0

  • Added time to live (TTL) support for documents.

1.6.0

1.5.1

  • Fixed a bug in HashPartitionResolver to generate hash values in little-endian to be consistent with other software development kits (SDKs).

1.5.0

  • Add Hash & Range partition resolvers to assist with sharding applications across multiple partitions.

1.4.0

  • Implement Upsert. New upsertXXX methods added to support Upsert feature.
  • Implement ID Based Routing. No public API changes, all changes internal.

1.3.0

  • Release skipped to bring version number in alignment with other SDKs

1.2.0

  • Supports GeoSpatial Index.
  • Validates ID property for all resources. Ids for resources can't contain ?, /, #, \, characters, or end with a space.
  • Adds new header "index transformation progress" to ResourceResponse.

1.1.0

  • Implements V2 indexing policy

1.0.0

  • GA SDK

Release and 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. We recommend that you always upgrade to the latest SDK version as early as possible.

Warning

After 30 might 2020, Azure Cosmos DB will no longer make bug fixes, add new features, and provide support to versions 1.x of the Azure Cosmos DB Java SDK for API for NoSQL. If you prefer not to upgrade, requests sent from version 1.x of the SDK will continue to be served by the Azure Cosmos DB service.

After 29 February 2016, Azure Cosmos DB will no longer make bug fixes, add new features, and provide support to versions 0.x of the Azure Cosmos DB Java SDK for API for NoSQL. If you prefer not to upgrade, requests sent from version 0.x of the SDK will continue to be served by the Azure Cosmos DB service.

Version Release Date Retirement Date
2.6.1 Dec 17, 2020 Feb 29, 2024
2.6.0 July 16, 2020 Feb 29, 2024
2.5.1 June 03, 2020 Feb 29, 2024
2.5.0 May 12, 2020 Feb 29, 2024
2.4.7 Feb 20, 2020 Feb 29, 2024
2.4.6 Jan 24, 2020 Feb 29, 2024
2.4.5 Nov 10, 2019 Feb 29, 2024
2.4.4 Oct 24, 2019 Feb 29, 2024
2.4.2 Sep 26, 2019 Feb 29, 2024
2.4.1 Jul 18, 2019 Feb 29, 2024
2.4.0 May 04, 2019 Feb 29, 2024
2.3.0 Apr 24, 2019 Feb 29, 2024
2.2.3 Apr 16, 2019 Feb 29, 2024
2.2.2 Apr 05, 2019 Feb 29, 2024
2.2.0 Mar 27, 2019 Feb 29, 2024
2.1.3 Mar 13, 2019 Feb 29, 2024
2.1.2 Mar 09, 2019 Feb 29, 2024
2.1.1 Dec 13, 2018 Feb 29, 2024
2.1.0 Nov 20, 2018 Feb 29, 2024
2.0.0 Sept 21, 2018 Feb 29, 2024
1.16.4 Sept 10, 2018 May 30, 2020
1.16.3 Sept 09, 2018 May 30, 2020
1.16.2 June 29, 2018 May 30, 2020
1.16.1 May 16, 2018 May 30, 2020
1.16.0 March 15, 2018 May 30, 2020
1.15.0 Nov 14, 2017 May 30, 2020
1.14.0 Oct 28, 2017 May 30, 2020
1.13.0 August 25, 2017 May 30, 2020
1.12.0 July 11, 2017 May 30, 2020
1.11.0 May 10, 2017 May 30, 2020
1.10.0 March 11, 2017 May 30, 2020
1.9.6 February 21, 2017 May 30, 2020
1.9.5 January 31, 2017 May 30, 2020
1.9.4 November 24, 2016 May 30, 2020
1.9.3 October 30, 2016 May 30, 2020
1.9.2 October 28, 2016 May 30, 2020
1.9.1 October 26, 2016 May 30, 2020
1.9.0 October 03, 2016 May 30, 2020
1.8.1 June 30, 2016 May 30, 2020
1.8.0 June 14, 2016 May 30, 2020
1.7.1 April 30, 2016 May 30, 2020
1.7.0 April 27, 2016 May 30, 2020
1.6.0 March 29, 2016 May 30, 2020
1.5.1 December 31, 2015 May 30, 2020
1.5.0 December 04, 2015 May 30, 2020
1.4.0 October 05, 2015 May 30, 2020
1.3.0 October 05, 2015 May 30, 2020
1.2.0 August 05, 2015 May 30, 2020
1.1.0 July 09, 2015 May 30, 2020
1.0.1 May 12, 2015 May 30, 2020
1.0.0 April 07, 2015 May 30, 2020
0.9.5-prelease Mar 09, 2015 February 29, 2016
0.9.4-prelease February 17, 2015 February 29, 2016
0.9.3-prelease January 13, 2015 February 29, 2016
0.9.2-prelease December 19, 2014 February 29, 2016
0.9.1-prelease December 19, 2014 February 29, 2016
0.9.0-prelease December 10, 2014 February 29, 2016

Frequently asked Questions

How will I be notified of the retiring SDK?

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

How can I request features be added to an SDK or connector?

New features are not always added to every SDK or connector immediately. If there is a feature not supported that you would like added, please add feedback to our community forum.