Skip to content

Latest commit

 

History

History
168 lines (109 loc) · 10.7 KB

create-sql-api-spring-data.md

File metadata and controls

168 lines (109 loc) · 10.7 KB
title description author ms.service ms.subservice ms.devlang ms.topic ms.date ms.author ms.custom
Quickstart - Use Spring Data Azure Cosmos DB v3 to create a document database using Azure Cosmos DB
This quickstart presents a Spring Data Azure Cosmos DB v3 code sample you can use to connect to and query the Azure Cosmos DB SQL API
anfeldma-ms
cosmos-db
cosmosdb-sql
java
quickstart
10/06/2020
anfeldma
seo-java-august2019, seo-java-september2019, devx-track-java

Quickstart: Build a Spring Data Azure Cosmos DB v3 app to manage Azure Cosmos DB SQL API data

[!div class="op_single_selector"]

In this quickstart, you create and manage an Azure Cosmos DB SQL API 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 SQL API account using the Azure portal, then create a Spring Boot app using the Spring Data Azure Cosmos DB v3 connector, and then add resources to your 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 here.

Spring Data Azure Cosmos DB supports only the SQL API.

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

Prerequisites

Introductory notes

The structure of a Cosmos DB account. Irrespective of API or programming language, a 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 diagram below:

:::image type="content" source="./media/databases-containers-items/cosmos-entities.png" alt-text="Azure Cosmos account entities" border="false":::

You may read more about databases, containers and items here. 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. Provisioned throughput can be selected at per-container granularity or per-database granularity, however container-level throughput specification is typically preferred. You may read more about throughput provisioning here.

As items are inserted into a 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, and 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; therefore you are advised to choose a partition key which is relatively random or evenly-distributed. Otherwise, some partitions will see substantially more requests (hot partition) while other partitions see substantially fewer requests (cold partition), and this is to be avoided. You may learn more about partitioning here.

Create a database account

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

[!INCLUDE cosmos-db-create-dbaccount]

Add a container

[!INCLUDE cosmos-db-create-collection]

Add sample data

[!INCLUDE cosmos-db-create-sql-api-add-sample-data]

Query your data

[!INCLUDE cosmos-db-create-sql-api-query-data]

Clone the sample application

Now let's switch to working with code. Let's clone a SQL API app from GitHub, set the connection string, and run it. You'll see how easy it is to work with data programmatically.

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-data-cosmos-java-sql-api-getting-started.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 .

Application configuration file

Here we showcase how Spring Boot and Spring Data enhance user experience - the process of establishing a Cosmos client and connecting to Cosmos resources is now config rather than code. At application startup Spring Boot handles all of this boilerplate using the settings in application.properties:

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

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 will automatically do the following: (1) create an underlying Java SDK CosmosClient instance with the URI and key, and (2) connect to the database and container. You're all set - no more resource management code!

Java source

The Spring Data value-add also comes from its simple, clean, standardized and platform-independent interface for operating on datastores. Building on the Spring Data GitHub sample linked above, below are CRUD and query samples for manipulating Azure Cosmos DB documents with Spring Data Azure Cosmos DB.

  • Item creation and updates by using the save method.

    [!code-java]

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

    [!code-java]

  • Item deletes using deleteAll:

    [!code-java]

  • Derived query based on repository method name. Spring Data implements the UserRepository findByFirstName method as a Java SDK SQL query on the firstName field (this query could not be implemented as a point-read):

    [!code-java]

Run the app

Now go back to the Azure portal to get your connection string information and launch the app with your endpoint information. This enables your app to communicate with your hosted database.

  1. In the git terminal window, cd to the sample code folder.

    cd azure-spring-data-cosmos-java-sql-api-getting-started/azure-spring-data-cosmos-java-getting-started/

  2. In the git terminal window, use the following command to install the required Spring Data Azure Cosmos DB packages.

    mvn clean package

  3. In the git terminal window, use the following command to start the Spring Data Azure Cosmos DB application:

    mvn spring-boot:run

  4. The app loads application.properties and connects the resources in your Azure Cosmos DB account.

  5. The app will perform point CRUD operations described above.

  6. The app will perform a derived query.

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

[!INCLUDE cosmosdb-tutorial-review-slas]

Clean up resources

[!INCLUDE cosmosdb-delete-resource-group]

Next steps

In this quickstart, you've learned how to create an Azure Cosmos DB SQL API account, create a document database and container using the Data Explorer, and run a Spring Data app to do the same thing programmatically. You can now import additional data into your Azure Cosmos DB account.

[!div class="nextstepaction"] Import data into Azure Cosmos DB