Skip to content

Latest commit

 

History

History
209 lines (144 loc) · 8.8 KB

create-sql-api-java.md

File metadata and controls

209 lines (144 loc) · 8.8 KB
title description services author ms.service ms.component ms.custom ms.devlang ms.topic ms.date ms.author
Create an Azure Cosmos DB document database with Java'
Presents a Java code sample you can use to connect to and query the Azure Cosmos DB SQL API
cosmos-db
SnehaGunda
cosmos-db
cosmosdb-sql
quick start connect, mvc, devcenter
java
quickstart
10/24/2018
moderakh

Create and manage resources of an Azure Cosmos DB SQL API account using a Java application

[!div class="op_single_selector"]

This quickstart shows how to create and manage resources of an Azure Cosmos DB SQL API account by using a Java application. First, you create an Azure Cosmos DB SQL API account using the Azure portal, create a Java app using the SQL Java SDK, add resources to your Cosmos DB account by using the Java application. The instructions in this quickstart can be followed on any operating system that is capable of running Java. After completing this quickstart you'll be familiar with creating and modifying Cosmos DB databases, collections in either the UI or programmatically, whichever is your preference.

Prerequisites

[!INCLUDE quickstarts-free-trial-note] [!INCLUDE cosmos-db-emulator-docdb-api]

In addition:

  • Java Development Kit (JDK) 1.8+
    • On Ubuntu, run apt-get install default-jdk to install the JDK.
    • Be sure to set the JAVA_HOME environment variable to point to the folder where the JDK is installed.
  • Download and install a Maven binary archive
    • On Ubuntu, you can run apt-get install maven to install Maven.
  • Git
    • On Ubuntu, you can run sudo apt-get install git to install Git.

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 collection

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

  1. 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-cosmos-db-sql-api-async-java-getting-started

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 .

  • AsyncDocumentClient initialization. The AsyncDocumentClient provides client-side logical representation for the Azure Cosmos DB database service. This client is used to configure and execute requests against the service.

    client = new AsyncDocumentClient.Builder()
         .withServiceEndpoint(YOUR_COSMOS_DB_ENDPOINT)
         .withMasterKeyOrResourceToken(YOUR_COSMOS_DB_MASTER_KEY)
         .withConnectionPolicy(ConnectionPolicy.GetDefault())
         .withConsistencyLevel(ConsistencyLevel.Eventual)
         .build();

  • Database creation.

    Database databaseDefinition = new Database();
databaseDefinition.setId(databaseName);

client.createDatabase(databaseDefinition, null)
        .toCompletable()
        .await();

  • DocumentCollection creation.

    DocumentCollection collectionDefinition = new DocumentCollection();
collectionDefinition.setId(collectionName);

//...

client.createCollection(databaseLink, collectionDefinition, requestOptions)
        .toCompletable()
        .await();

  • Document creation by using the createDocument method.

    // Any Java object within your code
// can be serialized into JSON and written to Azure Cosmos DB
Family andersenFamily = new Family();
andersenFamily.setId("Andersen.1");
andersenFamily.setLastName("Andersen");
// More properties

String collectionLink = String.format("/dbs/%s/colls/%s", databaseName, collectionName);
client.createDocument(collectionLink, family, null, true)
        .toCompletable()
        .await();

  • SQL queries over JSON are performed using the queryDocuments method.

    FeedOptions queryOptions = new FeedOptions();
queryOptions.setPageSize(-1);
queryOptions.setEnableCrossPartitionQuery(true);
queryOptions.setMaxDegreeOfParallelism(-1);

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

System.out.println("Running SQL query...");
while (it.hasNext()) {
    FeedResponse<Document> page = it.next();
    System.out.println(
            String.format("\tRead a page of results with %d items",
                    page.getResults().size()));
    for (Document doc : page.getResults()) {
        System.out.println(String.format("\t doc %s", doc));
    }
}

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-cosmos-db-sql-api-async-java-getting-started/azure-cosmosdb-get-started

  2. In the git terminal window, use the following command to install the required Java packages.

    mvn package

  3. In the git terminal window, use the following command to start the Java application (replace YOUR_COSMOS_DB_HOSTNAME with the quoted URI value from the portal, and replace YOUR_COSMOS_DB_MASTER_KEY with the quoted primary key from portal)

    mvn exec:java -DACCOUNT_HOST=YOUR_COSMOS_DB_HOSTNAME -DACCOUNT_KEY=YOUR_COSMOS_DB_MASTER_KEY

    The terminal window displays a notification that the FamilyDB database was created.

  4. Press a key to create the database, and then another key to create the collection.

    Switch back to Data Explorer in your browser to see that it now contains a FamilyDB database, and FamilyCollection collection.

  5. Switch to the console window and press a key to create the first document, and then another key to create the second document. Then switch back to Data Explorer to view them.

  6. Press a key to run a query and see the output in the console window.

  7. The app doesn't delete the created resources. Switch back to the portal to clean up the resources. from your account so that you don't incur charges.

    Console output

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 account, document database, and collection using the Data Explorer, and run an app to do the same thing programmatically. You can now import additional data into your Azure Cosmos DB collection.

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