Azure Cosmos DB dev guide

Article
08/28/2024

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

Get started

Include the package

If you're using Maven, add the following dependency.

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

Prerequisites

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 DirectConnectionConfig or GatewayConnectionConfig or both and provide them to CosmosClientBuilder. For complete sample, visit customizing configuration section.

Entity setup

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.

Repository setup

Azure Spring Data Azure Cosmos DB supports ReactiveCrudRepository (async APIs) and CrudRepository (sync APIs), which provide the following basic CRUD functionality:

save
findAll
findOne by ID
deleteAll
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.

Custom IndexingPolicy

By default, 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 @PartitionKey.

When you perform CRUD operation, specify your partition value.

For more information, see the test here section.

Optimistic Locking

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 CosmosClient or 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.

Auditing

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.

Multi-database configuration

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.

Troubleshooting

General

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.

Examples

For a complete sample project, see the sample project.

Multi-database accounts

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.

Next steps

Contributing

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.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any other questions or comments.

Impressions

Share via