Azure Cosmos DB for NoSQL: Spring Datan Azure Cosmos DB v3 examples

APPLIES TO: NoSQL

Important

These release notes are for version 3 of Spring Datan Azure Cosmos DB. You can find release notes for version 2 here.

Spring Datan Azure Cosmos DB supports only the API for NoSQL.

See these articles for information about Spring Data on other Azure Cosmos DB APIs:

Important

If you don't have an Azure subscription, create an Azure free account before you begin.

You can try Azure Cosmos DB for free, without an Azure subscription, and with no commitment required. Alternatively, you can create an Azure Cosmos DB free tier account, with the first 1000 RU/s and 25 GB of storage for free. You can also use the Azure Cosmos DB emulator with a URI of https://localhost:8081. For the key to use with the emulator, see Authenticating requests.

The latest sample applications that perform CRUD operations and other common operations on Azure Cosmos DB resources are included in the azure-spring-data-cosmos-java-sql-api-samples GitHub repository. This article provides:

  • Links to the tasks in each of the example Spring Datan Azure Cosmos DB project files.
  • Links to the related API reference content.

Prerequisites

You need the following to run this sample application:

  • Java Development Kit 8
  • Spring Datan Azure Cosmos DB v3

You can optionally use Maven to get the latest Spring Datan Azure Cosmos DB v3 binaries for use in your project. Maven automatically adds any necessary dependencies. Otherwise, you can directly download the dependencies listed in the pom.xml file and add them to your build path.

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

Running the sample applications

Clone the sample repo:

$ git clone https://github.com/Azure-Samples/azure-spring-data-cosmos-java-sql-api-samples

$ cd azure-spring-data-cosmos-java-sql-api-samples

You can run the samples using either an IDE (Eclipse, IntelliJ, or VSCODE) or from the command line using Maven.

In application.properties these environment variables must be set

cosmos.uri=${ACCOUNT_HOST}
cosmos.key=${ACCOUNT_KEY}
cosmos.secondaryKey=${SECONDARY_ACCOUNT_KEY}

dynamic.collection.name=spel-property-collection
# Populate query metrics
cosmos.queryMetricsEnabled=true

in order to give the samples read/write access to your account, databases and containers.

Your IDE may provide the ability to execute the Spring Data sample code. Otherwise you may use the following terminal command to execute the sample:

mvn spring-boot:run

Document CRUD examples

The samples file shows how to perform the following tasks. To learn about Azure Cosmos DB documents before running the following samples, see Working with databases, containers, and items conceptual article.

Task API reference
Create a document CosmosRepository.save
Read a document by ID CosmosRepository.derivedQueryMethod
Delete all documents CosmosRepository.deleteAll

Derived query method examples

The samples file shows how to perform the following tasks. To learn about Azure Cosmos DB queries before running the following samples, you may find it helpful to read Baeldung's Derived Query Methods in Spring article.

| Query for documents | CosmosRepository.derivedQueryMethod |

Custom query examples

The samples file shows how to do the following tasks using the SQL query grammar. To learn about the SQL query reference in Azure Cosmos DB before you run the following samples, see SQL query examples for Azure Cosmos DB.

Task API reference
Query for all documents @Query annotation
Query for equality using == @Query annotation
Query for inequality using != and NOT @Query annotation
Query using range operators like >, <, >=, <= @Query annotation
Query using range operators against strings @Query annotation
Query with ORDER BY @Query annotation
Query with DISTINCT @Query annotation
Query with aggregate functions @Query annotation
Work with subdocuments @Query annotation
Query with intra-document Joins @Query annotation
Query with string, math, and array operators @Query annotation

Next steps

Trying to do capacity planning for a migration to Azure Cosmos DB? You can use information about your existing database cluster for capacity planning.