Azure Cosmos DB: Java examples for the SQL API

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

  • Links to the tasks in each of the example Java project files.
  • Links to the related API reference content.

Prerequisites

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

You can Try Azure Cosmos DB for free without an Azure subscription, free of charge and commitments. Or, you can use the Azure Cosmos DB Emulator with a URI of https://localhost:8081. For the key to use with the emulator, see Authenticating requests.

You need the following to run this sample application:

  • Java Development Kit 7
  • Microsoft Azure DocumentDB Java SDK

You can optionally use Maven to get the latest Microsoft Azure DocumentDB Java SDK 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.microsoft.azure</groupId>
	<artifactId>azure-documentdb</artifactId>
	<version>LATEST</version>
</dependency>

Running the sample applications

Clone the sample repo:

$ git clone https://github.com/Azure/azure-documentdb-java.git

$ cd azure-documentdb-java

You can run the samples either using Eclipse or from the command line using Maven.

To run from Eclipse:

  • Load the main parent project pom.xml file in Eclipse; it should automatically load documentdb-examples.
  • To run the samples, you need a valid Azure Cosmos DB Endpoint. The endpoints are read from src/test/java/com/microsoft/azure/documentdb/examples/AccountCredentials.java.
  • You can pass your endpoint credentials as VM Arguments in Eclipse JUnit Run Config or you can put your endpoint credentials in AccountCredentials.java.
    -DACCOUNT_HOST="https://REPLACE_THIS.documents.azure.com:443/" -DACCOUNT_KEY="REPLACE_THIS"
    
  • Now you can run the samples as JUnit tests in Eclipse.

To run from the command line:

  • The other way for running samples is to use maven:

  • Run Maven and pass your Azure Cosmos DB Endpoint credentials:

    mvn test -DACCOUNT_HOST="https://REPLACE_THIS_WITH_YOURS.documents.azure.com:443/" -DACCOUNT_KEY="REPLACE_THIS_WITH_YOURS"
    

    Note

    Each sample is self-contained; it sets itself up and cleans up after itself. The samples issue multiple calls to DocumentClient.createCollection. Each time this is done, your subscription is billed for 1 hour of usage for the performance tier of the collection created.

Database examples

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

Task API reference
Create and read a database DocumentClient.createDatabase
DocumentClient.readDatabase
Resource.setId
Create and delete a database DocumentClient.deleteDatabase
Create and query a database DocumentClient.queryDatabases

Collection examples

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

Task API reference
Create a single partition collection DocumentClient.createCollection
Create a custom multi-partition collection DocumentCollection
PartitionKeyDefinition
RequestOptions
Delete a collection DocumentClient.deleteCollection

Document examples

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

Task API reference
Create, read, and delete a document DocumentClient.createDocument
DocumentClient.readDocument
DocumentClient.deleteDocument
Create a document with a programmable document definition Document
Resource.setId

Indexing examples

The CollectionCrudSamples file shows how to perform the following tasks. To learn about indexing in Azure Cosmos DB before running the following samples, see indexing policies, indexing types, and indexing paths conceptual articles.

Task API reference
Create an index and set indexing policy Index
IndexingPolicy

For more information about indexing, see Azure Cosmos DB indexing policies.

Query examples

The DocumentQuerySamples file shows how to perform the following tasks. To learn about the SQL query reference in Azure Cosmos DB before running the following samples, see SQL query examples conceptual article.

Task API reference
Perform a simple cross-partition document query DocumentClient.queryDocuments
FeedOptions.setEnableCrossPartitionQuery
Order by query FeedResponse<T>.getQueryIterator

For more information about writing queries, see SQL query within Azure Cosmos DB.

Offer examples

The OfferCrudSamples file shows how to perform the following tasks:

Task API reference
Create a collection and set throughput DocumentClient.createCollection
RequestOptions.setOfferThroughput
Read a collection to find the associated offer Offer.getContent
DocumentClient.replaceOffer
DocumentClient.readCollection
DocumentClient.queryOffers

Partition key examples

The SinglePartitionCollectionDocumentCrudSample file shows how to perform the following tasks. To learn about partitioning and partition keys in Azure Cosmos DB before running the following samples, see Partitioning conceptual article.

Task API reference
Create a single partition collection DocumentClient.createCollection
Change the throughput offer for a single partition collection DocumentClient.replaceOffer

Stored procedure examples

The StoredProcedureSamples file shows how to perform the following tasks. To learn about Server-side programming in Azure Cosmos DB before running the following samples, see Stored procedures, triggers, and user-defined functions conceptual article.

Task API reference
Create a stored procedure StoredProcedure
DocumentClient.createStoredProcedure
Run a stored procedure with arguments DocumentClient.executeStoredProcedure
Run a stored procedure with an object argument DocumentClient.executeStoredProcedure