Spring Data Azure Cosmos DB v3 for Core (SQL) API: Release notes and resources


The Spring Data Azure Cosmos DB version 3 for Core (SQL) 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.


Spring Data Azure Cosmos DB has a dependency on the Spring Data framework.

azure-spring-data-cosmos versions from 3.0.0 to 3.4.0 support Spring Data versions 2.2 and 2.3.

azure-spring-data-cosmos versions 3.5.0 and above support Spring Data versions 2.4.3 and above.

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 Azure Spring Cloud applications.


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

Spring Data Azure Cosmos DB supports only the SQL API.

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:


Helpful content

Content Link
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 SQL API data
GitHub repo with quickstart code
Basic code samples Azure Cosmos DB: Spring Data Azure Cosmos DB examples for the SQL API
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 Cosmos DB workshops home page


  • The 3.10.0 release - it's strongly recommended to use version 3.10.0 and above.
  • The 3.5.0 release supports Spring Boot 2.4.3 and above.

Release History

3.8.0-beta.1 (Unreleased)

3.7.0 (2021-05-12)

New Features

3.6.0 (2021-04-06)

New Features

  • Updated azure-cosmos to version 4.14.0.

3.5.1 (2021-03-24)

Key Bug Fixes

  • Updated azure-cosmos to hotfix version 4.13.1.

3.5.0 (2021-03-11)


This release supports spring boot 2.4.3 and above.

New Features

  • Updated spring-boot to major version 2.4.3.
  • Updated spring-core to major version 5.3.4.
  • Updated spring-data-commons to major version 2.4.5.
  • Updated azure-cosmos version to 4.13.0.
  • Added support for org.springframework.data.domain.Persistable entity type.
  • Added support to log SQL Queries.
  • Added support for Pageable and Sort for @query annotated queries.

Key Bug Fixes

  • Fixed issue when using automatic id generation with the auditable framework.
  • Fixed query deserialization issue with @query annotated queries.

3.4.0 (2021-02-09)

New Features

  • Updated azure-cosmos version to 4.12.0.

Key Bug Fixes

  • Fixed @EnableAuditing for Java 11 modules.

3.3.0 (2021-01-15)

New Features

  • Support for composite indexes in CosmosIndexPolicy annotation.
  • Support for changes in CosmosIndexPolicy annotation.
  • Updated azure-cosmos version to 4.11.0.

Key Bug Fixes

  • Fixed query generation with sort and limit.

3.2.0 (2020-12-11)

New Features

  • Updated Spring Data Commons version to 2.3.5.RELEASE.
  • Updated Spring Core version to 5.2.10.RELEASE.

Key Bug Fixes

  • Fixed publishing of spring.factories file with released jar.
  • Fixed repository query with repeated parameters.

3.1.0 (2020-10-21)

New Features

  • Added support for ARRAY_CONTAINS CriteriaType.
  • Updated azure-cosmos version to 4.7.1.

Key Bug Fixes

  • Fixed an issue where annotated queries do not pick the annotated container name.

3.0.0 (2020-09-30)

New Features

  • Updated azure-cosmos dependency to 4.6.0

3.0.0-beta.2 (2020-09-17)

New Features

  • Updated artifact id to azure-spring-data-cosmos.
  • Updated azure-cosmos dependency to 4.5.0.
  • Query Annotation support for native queries.
  • Support for Java 11.
  • Added support for Nested Partition Key by exposing partitionKeyPath field in @Container annotation.
  • Added support for limit query type allowing top and first to be used when defining repository APIs.

Key Bug Fixes

  • Fixed nested partition key bug when used with @GeneratedValue annotation.

3.0.0-beta.1 (2020-08-17)

New Features

  • Updated group id to com.azure.
  • Updated artifact id to azure-spring-data-cosmos-core.
  • Updated azure-cosmos SDK dependency to 4.3.2-beta.2.
  • Support for auditing entities - automatic management of createdBy, createdDate, lastModifiedBy and lastModifiedDate annotated fields.
  • @GeneratedValue annotation support for automatic id generation for id fields of String type.
  • Multi-database configuration support for single cosmos account with multiple databases and multiple cosmos accounts with multiple databases.
  • Support for @Version annotation on any string field.
  • Updated sync APIs return types to Iterable types instead of List.
  • Exposed CosmosClientBuilder from Cosmos SDK as spring bean to @Configuration class.
  • Updated CosmosConfig to contain query metrics and response diagnostics processor implementation.
  • Support for returning Optional data type for single result queries.


  • CosmosDbFactory to CosmosFactory.
  • CosmosDBConfig to CosmosConfig.
  • CosmosDBAccessException to CosmosAccessException.
  • Document annotation to Container annotation.
  • DocumentIndexingPolicy annotation to CosmosIndexingPolicy annotation.
  • DocumentQuery to CosmosQuery.
  • application.properties flag populateQueryMetrics to queryMetricsEnabled.

Key Bug Fixes

  • Scheduling diagnostics logging task to Parallel threads to avoid blocking Netty I/O threads.
  • Fixed optimistic locking on delete operation.
  • Fixed issue with escaping queries for IN clause.
  • Fixed issue by allowing long data type for @Id.
  • Fixed issue by allowing boolean, long, int, double as data types for @PartitionKey annotation.
  • Fixed IgnoreCase & AllIgnoreCase keywords for ignore case queries.
  • Removed default request unit value of 4000 when creating containers automatically.

Additional notes

  • Spring Data Azure Cosmos DB supports Java JDK 8 and Java JDK 11.
  • Spring Data 2.3 is currently supported, Spring Data 2.4 is not supported currently.


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.

Next steps

Learn more about Azure Cosmos DB.

Learn more about the Spring Framework.

Learn more about Spring Boot.

Learn more about Spring Data.