Azure Cosmos DB dev guide
Azure Spring Data for Azure Cosmos DB provides Spring Data support for Azure Cosmos DB for NoSQL. Azure Cosmos DB is a globally distributed database service that allows developers to work with data using various standard APIs, such as SQL, MongoDB, Cassandra, Graph, and Table.
This guide will walk you through the concepts of Azure Spring Data Azure Cosmos DB SDK, supported features, troubleshooting, and known issues. For more information on below concepts and code samples, see the Spring Data for Azure Cosmos DB SDK readme.
Version support policy
Spring Boot version support
This project supports multiple Spring Boot versions. For more information, see Spring Boot Support Policy. 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. For more information, see Spring Boot Version Support.
Spring Data version support
This project supports different spring-data-commons versions. For more information, see Spring Data Version Support.
Which version of Azure Spring Data Azure Cosmos DB to use
Azure Spring Data Azure Cosmos DB library supports multiple versions of Spring Boot / Spring Cloud. For more information on which version of Azure Spring Data Azure Cosmos DB to use with Spring Boot / Spring Cloud version, see Which Version of Azure Spring Data for Azure Cosmos DB should I use?.
Include the package
If you're using Maven, add the following dependency.
- Java Development Kit (JDK), version 8 or higher.
- An active Azure account. If you don't have one, you can sign up for a free account. Alternatively, you can use the Azure Cosmos DB Emulator for development and testing. As emulator https certificate is self-signed, you need to import its certificate to java trusted cert store, explained here
- (Optional) SLF4J is a logging facade.
- (Optional) SLF4J binding is used to associate a specific logging framework with SLF4J.
- (Optional) Maven
SLF4J is only needed if you plan to use logging, also download an SLF4J binding, which will link the SLF4J API with the logging implementation of your choice. For more information, see the SLF4J user manual.
Set up and customize the configuration class
In order to set up the configuration class, you need to extend
AbstractCosmosConfiguration. For more information, see Setup Configuration Class.
You can customize underlying
CosmosAsyncClient used by Azure Spring Data Azure Cosmos DB SDK by providing
GatewayConnectionConfig or both and provide them to
CosmosClientBuilder. For complete sample, visit customizing configuration section.
You can define a simple entity as item in Azure Cosmos DB. You can define entities by adding the
@Container annotation and specifying properties related to the container. For more information, see Define an entity.
Container annotation supports specifying the container name, request units (RUs), time to live, creating containers with autoscale throughput, nested partition key support, and other container properties.
Azure Spring Data Azure Cosmos DB supports
ReactiveCrudRepository (async APIs) and
CrudRepository (sync APIs), which provide the following basic CRUD functionality:
- findOne by ID
- delete by ID
- delete entity
You can extend
CosmosRepository (for sync API support) or
ReactiveCosmosRepository (for async API support) to set up Spring Data repositories for your application. For more information, see Create repositories.
Azure Spring Data Azure Cosmos DB supports specifying annotated queries in the repositories using
@Query. For more information, see QueryAnnotation : Using annotated queries in repositories.
Spring Data Annotations
Spring Data @Id annotation
There are multiple ways to map a field in domain class to
id. For more information, see the spring data ID annotation code section.
ID auto generation
Azure Spring Data Azure Cosmos DB supports auto generation of IDs using the @GeneratedValue annotation. For more information, see the ID auto generation section.
SpEL expression and custom container name
By default, the container name will be the class name of the user domain class. To customize, add the
@Container(containerName="myCustomContainerName") annotation to the domain class. For more information, see the SpEL expression and custom container name section.
IndexingPolicy will be set by Azure service. To customize, add the annotation
@CosmosIndexingPolicy to the domain class. For more information, see the indexing policy section.
Unique key policy
Azure Spring Data Azure Cosmos DB supports setting
UniqueKeyPolicy on the container by adding the annotation
@CosmosUniqueKeyPolicy to the domain class. For more information, see the unique key policy section.
Azure Cosmos DB Partition
Azure-spring-data-cosmos supports Azure Cosmos DB partitions.
To specify a field of the domain class to be a partition key field, just annotate it with
When you perform CRUD operation, specify your partition value.
For more information, see the test here section.
Azure-spring-data-cosmos supports Optimistic Locking for specific containers, which means upserts/deletes by item will fail with an exception in case the item is modified by another process in the meantime. For more information, see the optimistic locking section.
Spring Data custom query, pageable and sorting
Azure-spring-data-cosmos supports Spring Data custom queries, for example, a find operation such as
findByAFieldAndBField. It also supports Spring Data Pageable, Slice and Sort. For more information, see the query, pageable and sorting section.
Using Azure Cosmos DB Java SDK through Spring Data Cosmos
Azure-spring-data-cosmos supports using
Azure Cosmos DB Java SDK. Users can get
CosmosAsyncClient bean through
ApplicationContext and execute any operations supported by Azure Cosmos DB Java SDK. For more information, see the using Azure Cosmos Client through Spring Data Cosmos section.
Spring Data REST
Azure-spring-data-cosmos supports Spring Data REST. For more information, see the Azure Spring Data Azure Cosmos DB REST API section.
Azure-spring-data-cosmos supports auditing fields on database entities using standard spring-data annotations. For more information, see the Spring Data Azure Cosmos DB auditing section.
Azure-spring-data-cosmos supports multi-database configuration, including "multiple database accounts" and "single account, with multiple databases". For a complete code snippet, see the multi database configuration section.
If you encounter any bug, file an issue here.
To suggest a new feature or changes that could be made, file an issue the same way you would for a bug.
Enable Client Logging
Azure-spring-data-cosmos uses SLF4j as the logging facade that supports logging into popular logging frameworks such as log4j and logback. For more information, see the enable client logging section.
For a complete sample project, see the sample project.
For a complete sample project, see the Multi-database sample project.
Single account with Multi-database
For a complete sample project, see the Single account with Multi-database sample project.
- Read more about Azure spring data Azure Cosmos DB.
- Read more about Azure Cosmos DB Service
- See the Azure Spring Data Azure Cosmos DB Samples
- See the Spring MVC with Azure Cosmos DB Sample
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (for example, label, comment). Simply follow the instructions provided by the bot. You'll only need to do this once across all repos using our CLA.