Quickstart: Build a Spring Data Azure Cosmos DB v3 app to manage Azure Cosmos DB for NoSQL data

Article
02/28/2023

APPLIES TO: NoSQL

In this quickstart, you create and manage an Azure Cosmos DB for NoSQL account from the Azure portal, and by using a Spring Data Azure Cosmos DB v3 app cloned from GitHub.

First, you create an Azure Cosmos DB for NoSQL account using the Azure portal. Alternately, without a credit card or an Azure subscription, you can set up a free Try Azure Cosmos DB account. You can then create a Spring Boot app using the Spring Data Azure Cosmos DB v3 connector, and then add resources to your Azure Cosmos DB account by using the Spring Boot application.

Azure Cosmos DB is a multi-model database service that lets you quickly create and query document, table, key-value, and graph databases with global distribution and horizontal scale capabilities.

Important

These release notes are for version 3 of Spring Data Azure Cosmos DB. You can find release notes for version 2 at Spring Data Azure Cosmos DB v2 for API for NoSQL (legacy): Release notes and resources.

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

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

Prerequisites

An Azure account with an active subscription.
- No Azure subscription? You can try Azure Cosmos DB free with no credit card required.
Java Development Kit (JDK) 8. Set the JAVA_HOME environment variable to the JDK install folder.
A Maven binary archive. On Ubuntu, run apt-get install maven to install Maven.
Git. On Ubuntu, run sudo apt-get install git to install Git.

Introductory notes

The structure of an Azure Cosmos DB account. Irrespective of API or programming language, an Azure Cosmos DB account contains zero or more databases, a database (DB) contains zero or more containers, and a container contains zero or more items, as shown in the following diagram:

Azure Cosmos DB account entities

For more information about databases, containers, and items, see Azure Cosmos DB resource model. A few important properties are defined at the level of the container, among them provisioned throughput and partition key.

The provisioned throughput is measured in Request Units (RUs) which have a monetary price and are a substantial determining factor in the operating cost of the account. You can select provisioned throughput at per-container granularity or per-database granularity. However, you should prefer container-level throughput specification. For more information, see Introduction to provisioned throughput in Azure Cosmos DB.

As items are inserted into an Azure Cosmos DB container, the database grows horizontally by adding more storage and compute to handle requests. Storage and compute capacity are added in discrete units known as partitions. You must choose one field in your documents to be the partition key, which maps each document to a partition.

The way partitions are managed is that each partition is assigned a roughly equal slice out of the range of partition key values. For this reason, you should choose a partition key that's relatively random or evenly distributed. Otherwise, you get hot partitions and cold partitions, which see substantially more or fewer requests. For information on avoiding this condition, see Partitioning and horizontal scaling in Azure Cosmos DB.

Create a database account

Before you can create a document database, you need to create an API for NoSQL account with Azure Cosmos DB.

From the Azure portal menu or the Home page, select Create a resource.
Search for Azure Cosmos DB. Select Create > Azure Cosmos DB.
On the Create an Azure Cosmos DB account page, select the Create option within the Azure Cosmos DB for NoSQL section.

Azure Cosmos DB provides several APIs:
- NoSQL, for document data
- PostgreSQL
- MongoDB, for document data
- Apache Cassandra
- Table
- Apache Gremlin, for graph data
To learn more about the API for NoSQL, see Welcome to Azure Cosmos DB.

In the Create Azure Cosmos DB Account page, enter the basic settings for the new Azure Cosmos DB account.

Setting	Value	Description
Subscription	Subscription name	Select the Azure subscription that you want to use for this Azure Cosmos DB account.
Resource Group	Resource group name	Select a resource group, or select Create new, then enter a unique name for the new resource group.
Account Name	A unique name	Enter a name to identify your Azure Cosmos DB account. Because documents.azure.com is appended to the name that you provide to create your URI, use a unique name. The name can contain only lowercase letters, numbers, and the hyphen (-) character. It must be 3-44 characters.
Location	The region closest to your users	Select a geographic location to host your Azure Cosmos DB account. Use the location that is closest to your users to give them the fastest access to the data.
Capacity mode	Provisioned throughput or Serverless	Select Provisioned throughput to create an account in provisioned throughput mode. Select Serverless to create an account in serverless mode.
Apply Azure Cosmos DB free tier discount	Apply or Do not apply	With Azure Cosmos DB free tier, you get the first 1000 RU/s and 25 GB of storage for free in an account. Learn more about free tier.
Limit total account throughput	Selected or not	Limit the total amount of throughput that can be provisioned on this account. This limit prevents unexpected charges related to provisioned throughput. You can update or remove this limit after your account is created.

You can have up to one free tier Azure Cosmos DB account per Azure subscription and must opt in when creating the account. If you don't see the option to apply the free tier discount, another account in the subscription has already been enabled with free tier.

Note

The following options are not available if you select Serverless as the Capacity mode:

Apply Free Tier Discount
Limit total account throughput

In the Global Distribution tab, configure the following details. You can leave the default values for this quickstart:

Setting	Value	Description
Geo-Redundancy	Disable	Enable or disable global distribution on your account by pairing your region with a pair region. You can add more regions to your account later.
Multi-region Writes	Disable	Multi-region writes capability allows you to take advantage of the provisioned throughput for your databases and containers across the globe.
Availability Zones	Disable	Availability Zones help you further improve availability and resiliency of your application.

Note

The following options are not available if you select Serverless as the Capacity mode in the previous Basics page:

Geo-redundancy
Multi-region Writes

Optionally, you can configure more details in the following tabs:
- Networking. Configure access from a virtual network.
- Backup Policy. Configure either periodic or continuous backup policy.
- Encryption. Use either service-managed key or a customer-managed key.
- Tags. Tags are name/value pairs that enable you to categorize resources and view consolidated billing by applying the same tag to multiple resources and resource groups.
Select Review + create.
Review the account settings, and then select Create. It takes a few minutes to create the account. Wait for the portal page to display Your deployment is complete.
Select Go to resource to go to the Azure Cosmos DB account page.

Add a container

You can now use the Data Explorer tool in the Azure portal to create a database and container.

Select Data Explorer > New Container.

The Add Container area is displayed on the far right, you may need to scroll right to see it.

In the Add container page, enter the settings for the new container.

Setting	Suggested value	Description
Database ID	ToDoList	Enter Tasks as the name for the new database. Database names must contain from 1 through 255 characters, and they cannot contain `/, \\, #, ?`, or a trailing space. Check the Share throughput across containers option, it allows you to share the throughput provisioned on the database across all the containers within the database. This option also helps with cost savings.
Database throughput	You can provision Autoscale or Manual throughput. Manual throughput allows you to scale RU/s yourself whereas autoscale throughput allows the system to scale RU/s based on usage. Select Manual for this example. Leave the throughput at 400 request units per second (RU/s). If you want to reduce latency, you can scale up the throughput later by estimating the required RU/s with the capacity calculator. Note: This setting is not available when creating a new container in a serverless account.
Container ID	Items	Enter Items as the name for your new container. Container IDs have the same character requirements as database names.
Partition key	/category	The sample described in this article uses /category as the partition key.

Don't add Unique keys or turn on Analytical store for this example. Unique keys let you add a layer of data integrity to the database by ensuring the uniqueness of one or more values per partition key. For more information, see Unique keys in Azure Cosmos DB. Analytical store is used to enable large-scale analytics against operational data without any impact to your transactional workloads.

Select OK. The Data Explorer displays the new database and container.

Add sample data

You can now add data to your new container using Data Explorer.

From the Data Explorer, expand the Tasks database, expand the Items container. Select Items, and then select New Item.

Now add a document to the container with the following structure.

{
    "id": "1",
    "category": "personal",
    "name": "groceries",
    "description": "Pick up apples and strawberries.",
    "isComplete": false
}

Once you've added the json to the Documents tab, select Save.
Create and save one more document where you insert a unique value for the id property, and change the other properties as you see fit. Your new documents can have any structure you want as Azure Cosmos DB doesn't impose any schema on your data.

Query your data

You can use queries in Data Explorer to retrieve and filter your data.

At the top of the Items tab in Data Explorer, review the default query SELECT * FROM c. This query retrieves and displays all documents from the container ordered by ID.
To change the query, select Edit Filter, replace the default query with ORDER BY c._ts DESC, and then select Apply Filter.

The modified query displays the documents in descending order based on their timestamp, so now your second document is listed first.

If you're familiar with SQL syntax, you can enter any supported SQL queries in the query predicate box. You can also use Data Explorer to create stored procedures, user defined functions, and triggers for server-side business logic.

Data Explorer provides easy access in the Azure portal to all of the built-in programmatic data access features available in the APIs. You can also use the Azure portal to scale throughput, get keys and connection strings, and review metrics and SLAs for your Azure Cosmos DB account.

Clone the sample application

Now let's switch to working with code. Let's clone an API for NoSQL app from GitHub, set the connection string, and run it.

Run the following command to clone the sample repository. This command creates a copy of the sample app on your computer.

git clone https://github.com/Azure-Samples/azure-spring-boot-samples.git

Review the code

This step is optional. If you're interested in learning how the database resources are created in the code, you can review the following snippets. Otherwise, you can skip ahead to Run the app.

Passwordless (Recommended)
Password

In this section, the configurations and the code don't have any authentication operations. However, connecting to Azure service requires authentication. To complete the authentication, you need to use Azure Identity. Spring Cloud Azure uses DefaultAzureCredential, which Azure Identity provides to help you get credentials without any code changes.

DefaultAzureCredential supports multiple authentication methods and determines which method to use at runtime. This approach enables your app to use different authentication methods in different environments (local vs. production) without implementing environment-specific code. For more information, see the Default Azure credential section of Authenticate Azure-hosted Java applications.

When developing locally with passwordless authentication, make sure the user account that connects to Cosmos DB is assigned a role with the correct permissions to perform data operations. Currently, Azure Cosmos DB for NoSQL doesn't include built-in roles for data operations, but you can create your own using the Azure CLI or PowerShell.

Roles consist of a collection of permissions or actions that a user is allowed to perform, such as read, write, and delete. You can read more about configuring role-based access control (RBAC) in the Cosmos DB security configuration documentation.

Create the custom role

Create a role using the az role definition create command. Pass in the Cosmos DB account name and resource group, followed by a body of JSON that defines the custom role. The following example creates a role named PasswordlessReadWrite with permissions to read and write items in Cosmos DB containers. The role is also scoped to the account level using /.

az cosmosdb sql role definition create \
    --account-name <cosmosdb-account-name> \
    --resource-group  <resource-group-name> \
    --body '{
    "RoleName": "PasswordlessReadWrite",
    "Type": "CustomRole",
    "AssignableScopes": ["/"],
    "Permissions": [{
        "DataActions": [
            "Microsoft.DocumentDB/databaseAccounts/readMetadata",
            "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*",
            "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*"
        ]
    }]
}'

When the command completes, copy the ID value from the name field and paste it somewhere for later use.
Assign the role you created to the user account or service principal that will connect to Cosmos DB. During local development, this will generally be your own account that's logged into a development tool like Visual Studio or the Azure CLI. Retrieve the details of your account using the az ad user command.
```
az ad user show --id "<your-email-address>"
```
Copy the value of the id property out of the results and paste it somewhere for later use.

Assign the custom role you created to your user account using the az cosmosdb sql role assignment create command and the IDs you copied previously.

az cosmosdb sql role assignment create \
    --account-name <cosmosdb-account-name> \
    --resource-group  <resource-group-name> \
    --scope "/" \
    --principal-id <your-user-id> \
    --role-definition-id <your-custom-role-id>

Authenticate using DefaultAzureCredential

For local development, make sure you're authenticated with the same Azure AD account you assigned the role to. You can authenticate via popular development tools, such as the Azure CLI or Azure PowerShell. The development tools with which you can authenticate vary across languages.

Sign-in to Azure through the Azure CLI using the following command:

az login

You will need to install the Azure CLI to work with DefaultAzureCredential through Visual Studio Code.

On the main menu of Visual Studio Code, navigate to Terminal > New Terminal.

Sign-in to Azure through the Azure CLI using the following command:

az login

Sign-in to Azure using PowerShell via the following command:

Connect-AzAccount

You can authenticate to Cosmos DB for NoSQL using DefaultAzureCredential by adding the azure-identity dependency to your application. DefaultAzureCredential automatically discovers and uses the account you signed in with in the previous step.

Application configuration file

Configure the Azure Database for MySQL credentials in the application.yml configuration file in the cosmos/spring-cloud-azure-starter-data-cosmos/spring-cloud-azure-data-cosmos-sample directory. Replace the values of ${AZURE_COSMOS_ENDPOINT} and ${COSMOS_DATABASE}.

spring:
  cloud:
    azure:
      cosmos:
        endpoint: ${AZURE_COSMOS_ENDPOINT}
        database: ${COSMOS_DATABASE}

After Spring Boot and Spring Data create the Azure Cosmos DB account, database, and container, they connect to the database and container for delete, add, and find operations.

Application configuration file

The following section shows how Spring Boot and Spring Data use configuration instead of code to establish an Azure Cosmos DB client and connect to Azure Cosmos DB resources. At application startup Spring Boot handles all of this boilerplate using the following settings in application.yml:

spring:
  cloud:
    azure:
      cosmos:
        key: ${AZURE_COSMOS_KEY}
        endpoint: ${AZURE_COSMOS_ENDPOINT}
        database: ${COSMOS_DATABASE}

Once you create an Azure Cosmos DB account, database, and container, just fill-in-the-blanks in the config file and Spring Boot/Spring Data does the following: (1) creates an underlying Java SDK CosmosClient instance with the URI and key, and (2) connects to the database and container. You're all set - no more resource management code!

Java source

Spring Data provides a simple, clean, standardized, and platform-independent interface for operating on datastores, as shown in the following examples. These CRUD and query examples enable you to manipulate Azure Cosmos DB documents by using Spring Data Azure Cosmos DB. These examples build on the Spring Data GitHub sample linked to earlier in this article.

Item creation and updates by using the save method.

// Save the User class to Azure Cosmos DB database.
final Mono<User> saveUserMono = repository.save(testUser);

Point-reads using the derived query method defined in the repository. The findById performs point-reads for repository. The fields mentioned in the method name cause Spring Data to execute a point-read defined by the id field:

//  Nothing happens until we subscribe to these Monos.
//  findById will not return the user as user is not present.
final Mono<User> findByIdMono = repository.findById(testUser.getId());
final User findByIdUser = findByIdMono.block();
Assert.isNull(findByIdUser, "User must be null");

Item deletes using deleteAll:

repository.deleteAll().block();
LOGGER.info("Deleted all data in container.");

Derived query based on repository method name. Spring Data implements the repository findByFirstName method as a Java SDK SQL query on the firstName field. You can't implement this query as a point-read.
```
final Flux<User> firstNameUserFlux = repository.findByFirstName("testFirstName");
```

Run the app

Now go back to the Azure portal to get your connection string information. Then, use the following steps to launch the app with your endpoint information so your app can communicate with your hosted database.

In the Git terminal window, cd to the sample code folder.

cd azure-spring-boot-samples/cosmos/spring-cloud-azure-starter-data-cosmos/spring-cloud-azure-data-cosmos-sample

In the Git terminal window, use the following command to install the required Spring Data Azure Cosmos DB packages.
```
mvn clean package
```
In the Git terminal window, use the following command to start the Spring Data Azure Cosmos DB application:
```
mvn spring-boot:run
```
The app loads application.yml and connects the resources in your Azure Cosmos DB account.
The app performs point CRUD operations described previously.
The app performs a derived query.
The app doesn't delete your resources. Switch back to the portal to clean up the resources from your account if you want to avoid incurring charges.

Review SLAs in the Azure portal

The Azure portal monitors your Azure Cosmos DB account throughput, storage, availability, latency, and consistency. Charts for metrics associated with an Azure Cosmos DB Service Level Agreement (SLA) show the SLA value compared to actual performance. This suite of metrics makes monitoring your SLAs transparent.

To review metrics and SLAs:

Select Metrics in your Azure Cosmos DB account's navigation menu.
Select a tab such as Latency, and select a timeframe on the right. Compare the Actual and SLA lines on the charts.
Review the metrics on the other tabs.

Clean up resources

When you're done with your app and Azure Cosmos DB account, you can delete the Azure resources you created so you don't incur more charges. To delete the resources:

In the Azure portal Search bar, search for and select Resource groups.
From the list, select the resource group you created for this quickstart.
On the resource group Overview page, select Delete resource group.
In the next window, enter the name of the resource group to delete, and then select Delete.

Next steps

In this quickstart, you learned how to create an Azure Cosmos DB for NoSQL account and create a document database and container using the Data Explorer. You then ran a Spring Data app to do the same thing programmatically. You can now import more data into your Azure Cosmos DB account.

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

If all you know is the number of vCores and servers in your existing database cluster, read about estimating request units using vCores or vCPUs
If you know typical request rates for your current database workload, read about estimating request units using Azure Cosmos DB capacity planner

Quickstart: Build a Spring Data Azure Cosmos DB v3 app to manage Azure Cosmos DB for NoSQL data

Prerequisites

Introductory notes

Create a database account

Add a container

Add sample data

Query your data

Clone the sample application

Review the code

Create the custom role

Authenticate using DefaultAzureCredential

Application configuration file

Application configuration file

Java source

Run the app

Review SLAs in the Azure portal

Clean up resources

Next steps

Feedback

Additional resources

Additional resources