Tutorial: Build a Java app with the Async Java SDK to manage data stored in a SQL API account

As developer, you might have applications that use NoSQL document data. You can use the SQL API account in Azure Cosmos DB to store and access this document data. This tutorial shows you how to build a Java application with the Async Java SDK to store and manage document data.

This tutorial covers the following tasks:

  • Creating and connecting to an Azure Cosmos account
  • Configuring your solution
  • Creating a collection
  • Creating JSON documents
  • Querying the collection


Make sure you have the following resources:

Create an Azure Cosmos DB account

Create an Azure Cosmos account by using the following steps:

  1. Go to the Azure portal to create an Azure Cosmos DB account. Search for and select Azure Cosmos DB.

    The Azure portal Databases pane

  2. Select Add.

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

    Setting Value Description
    Subscription Subscription name Select the Azure subscription that you want to use for this Azure Cosmos 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 account. Because documents.azure.com is appended to the name that you provide to create your URI, use a unique name.

    The name can only contain lowercase letters, numbers, and the hyphen (-) character. It must be between 3-31 characters in length.
    API The type of account to create Select Core (SQL) to create a document database and query by using SQL syntax.

    The API determines the type of account to create. Azure Cosmos DB provides five APIs: Core (SQL) and MongoDB for document data, Gremlin for graph data, Azure Table, and Cassandra. Currently, you must create a separate account for each API.

    Learn more about the SQL API.
    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.

    The new account page for Azure Cosmos DB

  4. Select Review + create. You can skip the Network and Tags sections.

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

    The Azure portal Notifications pane

  6. Select Go to resource to go to the Azure Cosmos DB account page.

    The Azure Cosmos DB account page

Clone the GitHub repository

Clone the GitHub repository for Get Started with Azure Cosmos DB and Java. For example, from a local directory, run the following to retrieve the sample project locally.

git clone https://github.com/Azure-Samples/azure-cosmos-db-sql-api-async-java-getting-started.git

cd azure-cosmos-db-sql-api-async-java-getting-started
cd azure-cosmosdb-get-started

The directory contains a pom.xml file and a src/main/java/com/microsoft/azure/cosmosdb/sample folder containing Java source code, including Main.java. The project contains code required to perform operations with Azure Cosmos DB, like creating documents and querying data within a collection. The pom.xml file includes a dependency on the Azure Cosmos DB Java SDK on Maven.


Connect to an Azure Cosmos account

Next, head back to the Azure portal to retrieve your endpoint and primary master key. The Azure Cosmos DB endpoint and primary key are necessary for your application to understand where to connect to, and for Azure Cosmos DB to trust your application's connection. The AccountSettings.java file holds the primary key and URI values.

In the Azure portal, go to your Azure Cosmos account, and then click Keys. Copy the URI and the PRIMARY KEY from the portal and paste it into the AccountSettings.java file.

public class AccountSettings 
  // Replace MASTER_KEY and HOST with values from your Azure Cosmos account.
  // <!--[SuppressMessage("Microsoft.Security", "CS002:SecretInNextLine")]-->
  public static String MASTER_KEY = System.getProperty("ACCOUNT_KEY", 
          System.getenv().get("ACCOUNT_KEY")), "<Fill your Azure Cosmos account key>"));

  public static String HOST = System.getProperty("ACCOUNT_HOST",
           System.getenv().get("ACCOUNT_HOST")),"<Fill your Azure Cosmos DB URI>"));

Get keys from portal screenshot

Initialize the client object

Initialize the client object by using the host URI and primary key values defined in the "AccountSettings.java" file.

client = new AsyncDocumentClient.Builder()

Create a database

Create your Azure Cosmos database by using the createDatabaseIfNotExists() method of the DocumentClient class. A database is the logical container of JSON document storage partitioned across collections.

private void createDatabaseIfNotExists() throws Exception 
    writeToConsoleAndPromptToContinue("Check if database " + databaseName + " exists.");

    String databaseLink = String.format("/dbs/%s", databaseName);

    Observable<ResourceResponse<Database>> databaseReadObs = client.readDatabase(databaseLink, null);

    Observable<ResourceResponse<Database>> databaseExistenceObs = databaseReadObs
                .doOnNext(x -> {System.out.println("database " + databaseName + " already exists.");}).onErrorResumeNext(e -> {
   // if the database doesn't already exists
   // readDatabase() will result in 404 error
   if (e instanceof DocumentClientException) 
       DocumentClientException de = (DocumentClientException) e;
       // if database 
       if (de.getStatusCode() == 404) {
       // if the database doesn't exist, create it.
       System.out.println("database " + databaseName + " doesn't existed," + " creating it...");
       Database dbDefinition = new Database();
       return client.createDatabase(dbDefinition, null);

    // some unexpected failure in reading database happened.
    // pass the error up.
    System.err.println("Reading database " + databaseName + " failed.");
        return Observable.error(e);     

   // wait for completion

   System.out.println("Checking database " + databaseName + " completed!\n");

Create a collection

You can create a collection by using the createDocumentCollectionIfNotExists() method of the DocumentClient class. A collection is a container of JSON documents and the associated JavaScript application logic.


createCollection creates a new collection with reserved throughput, which has pricing implications. For more details, visit our pricing page.

private void createDocumentCollectionIfNotExists() throws Exception 
    writeToConsoleAndPromptToContinue("Check if collection " + collectionName + " exists.");

    // query for a collection with a given id
    // if it exists nothing else to be done
    // if the collection doesn't exist, create it.

    String databaseLink = String.format("/dbs/%s", databaseName);

    // we know there is only single page of result (empty or with a match)
    client.queryCollections(databaseLink, new SqlQuerySpec("SELECT * FROM r where r.id = @id", 
            new SqlParameterCollection(new SqlParameter("@id", collectionName))), null).single() 
            .flatMap(page -> {
            if (page.getResults().isEmpty()) {
             // if there is no matching collection create the collection.
             DocumentCollection collection = new DocumentCollection();
             System.out.println("Creating collection " + collectionName);

             return client.createCollection(databaseLink, collection, null);
            else {
              // collection already exists, nothing else to be done.
              System.out.println("Collection " + collectionName + "already exists");
              return Observable.empty();

 System.out.println("Checking collection " + collectionName + " completed!\n");

Create JSON documents

Create a document by using the createDocument method of the DocumentClient class. Documents are user-defined (arbitrary) JSON content. We can now insert one or more documents. The "src/main/java/com/microsoft/azure/cosmosdb/sample/Families.java" file defines the family JSON documents.

public static Family getJohnsonFamilyDocument() {
     Family andersenFamily = new Family();
     andersenFamily.setId("Johnson" + System.currentTimeMillis());

      Parent parent1 = new Parent();

      Parent parent2 = new Parent();

      return andersenFamily;

Query Azure Cosmos DB resources

Azure Cosmos DB supports rich queries against JSON documents stored in each collection. The following sample code shows how to query documents in Azure Cosmos DB using SQL syntax with the queryDocuments method.

private void executeSimpleQueryAsyncAndRegisterListenerForResult(CountDownLatch completionLatch) 
    // Set some common query options
    FeedOptions queryOptions = new FeedOptions();

    String collectionLink = String.format("/dbs/%s/colls/%s", databaseName, collectionName);
    Observable<FeedResponse<Document>> queryObservable = client.queryDocuments(collectionLink,
           "SELECT * FROM Family WHERE Family.lastName = 'Andersen'", queryOptions);

    queryObservable.subscribe(queryResultPage -> {
            System.out.println("Got a page of query result with " +
            queryResultPage.getResults().size() + " document(s)"
            + " and request charge of " + queryResultPage.getRequestCharge());
   // terminal error signal
        e -> {

   // terminal completion signal
         () -> {

Run your Java console application

To run the application from the console, go to the project folder and compile using Maven:

mvn package

Running mvn package downloads the latest Azure Cosmos DB library from Maven and produces GetStarted-0.0.1-SNAPSHOT.jar. Then run the app by running:


You've now completed this NoSQL tutorial and have a working Java console application.

Clean up resources

When they're no longer needed, you can delete the resource group, the Azure Cosmos account, and all the related resources. To do so, select the resource group for the virtual machine, select Delete, and then confirm the name of the resource group to delete.

Next steps

In this tutorial, you've learned how to build a Java app with the Async Java SDK to manage SQL API data in Azure Cosmos DB. You can now proceed to the next article: