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

Article
12/06/2024

APPLIES TO: NoSQL

The Spring Data Azure Cosmos DB version 3 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 an older version of Spring Boot and 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 V3, we highly recommend to use Azure Spring Data Azure Cosmos DB v5 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 and framework 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.

Version support policy

Spring Boot version support

This project supports multiple Spring Boot Versions. Visit spring boot support policy for more information. Maven users can inherit from the spring-boot-starter-parent project to obtain a dependency management section to let Spring manage the versions for dependencies. Visit spring boot version support for more information.

Spring Data version support

This project supports different spring-data-commons versions. Visit spring data version support for more information.

Which version of Azure Spring Data Azure Cosmos DB should I use

Azure Spring Data Azure Cosmos DB library supports multiple versions of Spring Boot / Spring Cloud. Refer to Azure Spring Data Azure Cosmos DB version mapping for detailed information on which version of Azure Spring Data Azure Cosmos DB to use with Spring Boot / Spring Cloud version.

Important

These release notes are for version 3 of Spring Data Azure Cosmos DB.

Azure Spring Data Azure Cosmos DB SDK has dependency on the Spring Data framework, and supports only the API for NoSQL.

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

Get started fast

Get up and running with Spring Data Azure Cosmos DB by following our Spring Boot Starter guide. The Spring Boot Starter approach is the recommended way to get started using the Spring Data Azure Cosmos DB connector.

Alternatively, you can add the Spring Data Azure Cosmos DB dependency to your pom.xml file as shown below:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-spring-data-cosmos</artifactId>
    <version>latest-version</version>
</dependency>

Helpful content

Content	Link
Release notes	Release notes for Spring Data Azure Cosmos DB SDK v3
SDK Documentation	Azure Spring Data Azure Cosmos DB SDK v3 documentation
SDK download	Maven
API documentation	Java API reference documentation
Contribute to SDK	Azure SDK for Java Central Repo on GitHub
Get started	Quickstart: Build a Spring Data Azure Cosmos DB app to manage Azure Cosmos DB for NoSQL data GitHub repo with quickstart code
Basic code samples	Azure Cosmos DB: Spring Data Azure Cosmos DB examples for the API for NoSQL GitHub repo with sample code
Performance tips	Performance tips for Java SDK v4 (applicable to Spring Data)
Troubleshooting	Troubleshoot Java SDK v4 (applicable to Spring Data)
Azure Cosmos DB workshops and labs	Azure Cosmos DB workshops home page

Release history

Release history is maintained in the azure-sdk-for-java repo, for detailed list of releases, see the changelog file.

Recommended version

It's strongly recommended to upgrade to Azure Spring Data Azure Cosmos DB v5 and use the minimum recommended version and above.

Additional notes

Spring Data Azure Cosmos DB supports Java JDK 8, Java JDK 11. Version 3.8.0 and above support Java JDK 17 as well.

FAQ

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.

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.