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 developers can use to work with data by using various standard APIs, such as SQL, MongoDB, Cassandra, Graph, and Table.

This guide explains the concepts of Azure Spring Data Azure Cosmos DB SDK, supported features, troubleshooting, and known issues. For more information about these 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 get a dependency management section that lets 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 and Spring Cloud. For more information about which version of Azure Spring Data Azure Cosmos DB to use with Spring Boot and Spring Cloud, 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. Because the emulator uses a self-signed HTTPS certificate, you need to import its certificate to the Java trusted certificate store, explained here.
• (Optional) SLF4J is a logging facade.
• (Optional) SLF4J binding is used to associate a specific logging framework with SLF4J.
• (Optional) Maven

You only need SLF4J if you plan to use logging. Also download an SLF4J binding, which links 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

To set up the configuration class, extend AbstractCosmosConfiguration. For more information, see Setup Configuration Class.

You can customize the underlying CosmosAsyncClient used by the Azure Spring Data Azure Cosmos DB SDK by providing DirectConnectionConfig, GatewayConnectionConfig, or both, and giving them to CosmosClientBuilder. For a complete sample, visit the customizing configuration section.

Entity setup

You can define a simple entity as an item in Azure Cosmos DB. Define entities by adding the @Container annotation and specifying properties related to the container. For more information, see Define an entity.

The 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 by using @Query. For more information, see QueryAnnotation : Using annotated queries in repositories.

Spring Data Annotations

Spring Data @Id annotation

You can map a field in a domain class to id in multiple ways. 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 by using the @GeneratedValue annotation. For more information, see the ID auto generation section.

SpEL expression and custom container name

By default, the container name is the class name of the user domain class. To customize the container name, 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, the Azure service sets the IndexingPolicy. To customize the IndexingPolicy, add the @CosmosIndexingPolicy annotation to the domain class. For more information, see the indexing policy section.

Unique key policy

Azure Spring Data Azure Cosmos DB supports setting the UniqueKeyPolicy on the container by adding the @CosmosUniqueKeyPolicy annotation 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 as the partition key field, annotate it with @PartitionKey.

When you perform a 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. This support means upserts and deletes by item fail with an exception if another process modifies the item. For more information, see the optimistic locking section.

Spring Data custom query, pageable and sorting

Azure-spring-data-cosmos supports Spring Data custom queries, such as a find operation like 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 the Azure Cosmos DB Java SDK. You can get a 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 by 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 a bug, file an issue here.

To suggest a new feature or changes, 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 multiple database sample project.

Single account with Multi-database

For a complete sample project, see the single account with multiple databases sample project.

Next steps

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

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.