Edit

Spring Data Azure Cosmos DB v2 for API for NoSQL (legacy): Release notes and resources

  • Article

APPLIES TO: NoSQL

Spring Data Azure Cosmos DB version 2 for NoSQL allows developers to use Azure Cosmos DB in Spring applications. Spring Data Azure Cosmos DB exposes the Spring Data interface for manipulating databases and collections, working with documents, and issuing queries. Both Sync and Async (Reactive) APIs are supported in the same Maven artifact.

Warning

This version of Spring Data Azure Cosmos DB SDK depends on a retired version of Azure Cosmos DB Java SDK. This Spring Data Azure Cosmos DB SDK will be announced as retiring in the near future! This is not the latest Azure Spring Data Azure Cosmos DB SDK for Azure Cosmos DB and is outdated. Because of performance issues and instability in Azure Spring Data Azure Cosmos DB SDK V2, we highly recommend to use Azure Spring Data Azure Cosmos DB v3 for your project. To upgrade, follow the instructions in the Migrate to Azure Cosmos DB Java SDK v4 guide to understand the difference in the underlying Java SDK V4.

The Spring Framework is a programming and configuration model that streamlines Java application development. Spring streamlines the "plumbing" of applications by using dependency injection. Many developers like Spring because it makes building and testing applications more straightforward. Spring Boot extends this handling of the plumbing with an eye toward web application and microservices development. Spring Data is a programming model for accessing datastores like Azure Cosmos DB from the context of a Spring or Spring Boot application.

You can use Spring Data Azure Cosmos DB in your applications hosted in Azure Spring Apps.

Important

These release notes are for version 2 of Spring Data Azure Cosmos DB. You can find release notes for version 3 here.

Spring Data Azure Cosmos DB supports only the API for NoSQL.

See the following articles for information about Spring Data on other Azure Cosmos DB APIs:

Want to get going fast?

  1. Install the minimum supported Java runtime, JDK 8, so you can use the SDK.
  2. Create a Spring Data Azure Cosmos DB app by using the starter. It's easy!
  3. Work through the Spring Data Azure Cosmos DB developer's guide, which walks through basic Azure Cosmos DB requests.

You can spin up Spring Boot Starter apps fast by using Spring Initializr!

Resources

Resource Link
SDK download Maven
API documentation Spring Data Azure Cosmos DB reference documentation
Contribute to the SDK Spring Data Azure Cosmos DB repo on GitHub
Spring Boot Starter Azure Cosmos DB Spring Boot Starter client library for Java
Developer's guide Spring Data Azure Cosmos DB developer's guide
Using Starter How to use Spring Boot Starter with the Azure Cosmos DB for NoSQL
GitHub repo for Azure Cosmos DB Spring Boot Starter
Sample with Azure App Service How to use Spring and Azure Cosmos DB with App Service on Linux

Release history

2.3.0 (May 21, 2020)

New features

  • Updates Spring Boot version to 2.3.0.

2.2.5 (May 19, 2020)

New features

  • Updates Azure Cosmos DB version to 3.7.3.

Key bug fixes

  • Contains memory leak fixes and Netty version upgrades from Azure Cosmos DB SDK 3.7.3.

2.2.4 (April 6, 2020)

Key bug fixes

  • Fixes allowTelemetry flag to take into account from CosmosDbConfig.
  • Fixes TTL property on container.

2.2.3 (February 25, 2020)

New features

  • Adds new findAll by partition key API.
  • Updates Azure Cosmos DB version to 3.7.0.

Key bug fixes

  • Fixes collectionName -> containerName.
  • Fixes entityClass and domainClass -> domainType.
  • Fixes "Return entity collection saved by repository instead of input entity."

2.1.10 (February 25, 2020)

Key bug fixes

  • Backports fix for "Return entity collection saved by repository instead of input entity."

2.2.2 (January 15, 2020)

New features

  • Updates Azure Cosmos DB version to 3.6.0.

Key bug fixes

2.2.1 (December 31, 2019)

New features

  • Updates Azure Cosmos DB SDK version to 3.5.0.
  • Adds annotation field to enable or disable automatic collection creation.
  • Improves exception handling. Exposes CosmosClientException through CosmosDBAccessException.
  • Exposes requestCharge and activityId through ResponseDiagnostics.

Key bug fixes

  • SDK 3.5.0 update fixes "Exception when Azure Cosmos DB HTTP response header is larger than 8192 bytes," "ConsistencyPolicy.defaultConsistencyLevel() fails on Bounded Staleness and Consistent Prefix."
  • Fixes findById method's behavior. Previously, this method returned empty if the entity wasn't found instead of throwing an exception.
  • Fixes a bug in which sorting wasn't applied on the next page when CosmosPageRequest was used.

2.1.9 (December 26, 2019)

New features

  • Adds annotation field to enable or disable automatic collection creation.

Key bug fixes

  • Fixes findById method's behavior. Previously, this method returned empty if the entity wasn't found instead of throwing an exception.

2.2.0 (October 21, 2019)

New features

  • Complete Reactive Azure Cosmos DB Repository support.
  • Azure Cosmos DB Request Diagnostics String and Query Metrics support.
  • Azure Cosmos DB SDK version update to 3.3.1.
  • Spring Framework version upgrade to 5.2.0.RELEASE.
  • Spring Data Commons version upgrade to 2.2.0.RELEASE.
  • Adds findByIdAndPartitionKey and deleteByIdAndPartitionKey APIs.
  • Removes dependency from azure-documentdb.
  • Rebrands DocumentDB to Azure Cosmos DB.

Key bug fixes

  • Fixes "Sorting throws exception when pageSize is less than total items in repository."

2.1.8 (October 18, 2019)

New features

  • Deprecates DocumentDB APIs.
  • Adds findByIdAndPartitionKey and deleteByIdAndPartitionKey APIs.
  • Adds optimistic locking based on _etag.
  • Enables SpEL expression for document collection name.
  • Adds ObjectMapper improvements.

2.1.7 (October 18, 2019)

New features

  • Adds Azure Cosmos DB SDK version 3 dependency.
  • Adds Reactive Azure Cosmos DB Repository.
  • Updates implementation of DocumentDbTemplate to use Azure Cosmos DB SDK version 3.
  • Adds other configuration changes for Reactive Azure Cosmos DB Repository support.

2.1.2 (March 19, 2019)

Key bug fixes

  • Removes applicationInsights dependency for:
    • Potential risk of dependencies polluting.
    • Java 11 incompatibility.
    • Avoiding potential performance impact to CPU and/or memory.

2.0.7 (March 20, 2019)

Key bug fixes

  • Backport removes applicationInsights dependency for:
    • Potential risk of dependencies polluting.
    • Java 11 incompatibility.
    • Avoiding potential performance impact to CPU and/or memory.

2.1.1 (March 7, 2019)

New features

  • Updates main version to 2.1.1.

2.0.6 (March 7, 2019)

New features

  • Ignore all exceptions from telemetry.

2.1.0 (December 17, 2018)

New features

  • Updates version to 2.1.0 to address problem.

2.0.5 (September 13, 2018)

New features

  • Adds keywords exists and startsWith.
  • Updates Readme.

Key bug fixes

  • Fixes "Can't call self href directly for Entity."
  • Fixes "findAll will fail if collection is not created."

2.0.4 (Prerelease) (August 23, 2018)

New features

  • Renames package from documentdb to cosmosdb.
  • Adds new feature of query method keyword. 16 keywords from API for NoSQL are now supported.
  • Adds new feature of query with paging and sorting.
  • Simplifies the configuration of spring-data-cosmosdb.
  • Adds deleteCollection and deleteAll APIs.

Key bug fixes

  • Bug fix and defect mitigation.

FAQ

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.

Next steps

Learn more about Azure Cosmos DB.

Learn more about the Spring Framework.

Learn more about Spring Boot.

Learn more about Spring Data.