title | description | author | ms.author | ms.topic | ms.date | ms.custom |
---|---|---|---|---|---|---|
Azure Cosmos DB dev guide |
This guide describes the features, issues, workarounds, and diagnostic steps to be aware of when you use the Spring Data Azure Cosmos DB SDK. |
KarlErickson |
hangwan |
conceptual |
01/18/2023 |
devx-track-java, spring-cloud-azure, devx-track-extended-java |
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.
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.
This project supports different spring-data-commons versions. For more information, see Spring Data Version Support.
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?.
If you're using Maven, add the following dependency.
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-spring-data-cosmos</artifactId>
<version>LATEST</version>
</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.
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.
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:
- 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 @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.
Azure Spring Data Azure Cosmos DB supports auto generation of IDs using the @GeneratedValue annotation. For more information, see the ID auto generation section.
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.
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.
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-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.
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.
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.
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.
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.
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.
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.
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.