Access data with Azure Cosmos DB
Clone or download
Incarnation-p-lee Excluse android json from spring-boot-starter-test, #267. (#284)
Excluse android json from spring-boot-starter-test, fix #267.
Latest commit 37e07e9 Oct 31, 2018

Travis CI codecov Maven Central MIT License

Spring Data for Azure Cosmos DB

Azure Cosmos DB is a globally-distributed database service that allows developers to work with data using a variety of standard APIs, such as SQL, MongoDB, Cassandra, Graph, and Table.

Spring Data Azure Cosmos DB provides initial Spring Data support for Azure Cosmos DB using the SQL API, based on Spring Data framework. Currently it only supports SQL API, the other APIs are in the plan.


Sample Code

Please refer to sample project here.

Spring data version support

This repository supports both Spring Data 1.x and 2.x. Please see this document about more details and corresponding branch mapping.

Feature List

  • Spring Data CRUDRepository basic CRUD functionality
    • save
    • findAll
    • findOne by Id
    • deleteAll
    • delete by Id
    • delete entity
  • Spring Data @Id annotation. There're 2 ways to map a field in domain class to id field of Azure Cosmos DB document.
    • annotate a field in domain class with @Id, this field will be mapped to document id in Cosmos DB.
    • set name of this field to id, this field will be mapped to document id in Azure Cosmos DB.
  • Custom collection Name. By default, collection name will be class name of user domain class. To customize it, add annotation @Document(collection="myCustomCollectionName") to domain class, that's all.
  • Custom IndexingPolicy By default, IndexingPolicy will be set by azure service. To customize it add annotation @DocumentIndexingPolicy to domain class. This annotation has 4 attributes to customize, see following:
   boolean automatic;     // Indicate if indexing policy use automatic or not
   IndexingMode mode;     // Indexing policy mode, option Consistent|Lazy|None.
   String[] includePaths; // Included paths for indexing
   String[] excludePaths; // Excluded paths for indexing
  • Supports Azure Cosmos DB partition. To specify a field of domain class to be partition key field, just annotate it with @PartitionKey. When you do CRUD operation, pls specify your partition value. For more sample on partition CRUD, pls refer to test here
  • Supports Spring Data custom query find operation, e.g., findByAFieldAndBField
  • Supports Spring Data pagable and sort.
  • Supports spring-boot-starter-data-rest.
  • Supports List and nested type in domain class.
  • Configurable ObjectMapper bean with unique name cosmosdbObjectMapper, only configure customized ObjectMapper if you really need to. e.g.,
   @Bean(name = "cosmosdbObjectMapper")
   public ObjectMapper objectMapper() {
      return new ObjectMapper(); // Do configuration to the ObjectMapper if required

Quick Start

Add the dependency

spring-data-cosmosdb is published on Maven Central Repository.
If you are using Maven, add the following dependency.


Setup Configuration

Setup configuration class.

public class AppConfiguration extends AbstractDocumentDbConfiguration {

    private String uri;

    private String key;

    private String dbName;

    public DocumentDBConfig getConfig() {
        return DocumentDBConfig.builder(uri, key, dbName).build();

By default, @EnableDocumentDbRepositories will scan the current package for any interfaces that extend one of Spring Data's repository interfaces. Using it to annotate your Configuration class to scan a different root package by type if your project layout has multiple projects and it's not finding your repositories.

public class AppConfiguration extends AbstractDocumentDbConfiguration {
    // configuration code

Define an entity

Define a simple entity as Document in Azure Cosmos DB.

@Document(collection = "mycollection")
public class User {
    private String id;
    private String firstName;
    private String lastName;
    ... // setters and getters
    public User() {
        // If you do not want to create a default constructor, 
        // use annotation @JsonCreator and @JsonProperty in the full args constructor
    public User(String id, String firstName, String lastName) { = id;
        this.firstName = firstName;
        this.lastName = lastName;

    public String toString() {
        return String.format("User: %s %s, %s", firstName, lastName);

id field will be used as document id in Azure Cosmos DB. If you want use another field like emailAddress as document id, just annotate that field with @Id annotation.

Annotation @Document(collection="mycollection") is used to specify collection name in Azure Cosmos DB. Annotation @PartitionKey on lastName field is used to specify this field be partition key in Azure Cosmos DB.

@Document(collection = "mycollection")
public class User {
    private String emailAddress;


Create repositories

Extends DocumentDbRepository interface, which provides Spring Data repository support.

import DocumentDbRepository;
import org.springframework.stereotype.Repository;

public interface UserRepository extends DocumentDbRepository<User, String> {
    List<User> findByFirstName(String firstName); 

findByFirstName method is custom query method, it will find documents per FirstName.

Create an Application class

Here create an application class with all the components

public class SampleApplication implements CommandLineRunner {

    private UserRepository repository;

    public static void main(String[] args) {, args);

    public void run(String... var1) throws Exception {

        final User testUser = new User("testId", "testFirstName", "testLastName");


        // to find by Id, please specify partition key value if collection is partitioned
        final User result = repository.findOne(testUser.getId(), testUser.getLastName);
        // if emailAddress is mapped to id, then 
        // final User result = respository.findOne(testUser.getEmailAddress(), testUser.getLastName());

Autowired UserRepository interface, then can do save, delete and find operations. Spring Data Azure Cosmos DB uses the DocumentTemplate to execute the queries behind find, save methods. You can use the template yourself for more complex queries.

Filing Issues

If you encounter any bug, please 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.

How To Contribute

Contribution is welcome. Please follow this instruction to contribute code.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact with any additional questions or comments.