Azure Cosmos DB Java SDK Query Samples

Explore various ways to query data in Azure Cosmos DB using the official Java SDK. These samples cover common scenarios and demonstrate best practices for efficient data retrieval.

Basic Queries

1. Point Read (Read by ID)

Efficiently retrieve a single document by its unique ID and partition key.


import com.azure.cosmos.*;
import com.azure.cosmos.models.*;

// Assuming 'client' is an initialized CosmosClient and 'container' is a CosmosContainer

// Define the document ID and partition key
String documentId = "myDocumentId";
String partitionKeyFieldValue = "myPartitionKey";
CosmosItemId id = CosmosItemId.of(documentId);
PartitionKey partitionKey = new PartitionKey(partitionKeyFieldValue);

try {
    CosmosItemResponse response = container.getItem(id, partitionKey, MyDocument.class).read();
    MyDocument document = response.getItem();
    System.out.println("Retrieved document: " + document);
} catch (CosmosException e) {
    System.err.println("Error retrieving document: " + e.getMessage());
}

2. Query with SQL

Execute a SQL query against your Cosmos DB container to filter and project data.


import com.azure.cosmos.*;
import com.azure.cosmos.models.*;
import com.azure.cosmos.util.CosmosPagedIterable;

// Assuming 'container' is a CosmosContainer

String query = "SELECT VALUE r FROM r WHERE r.category = 'Electronics'";

CosmosPagedIterable<MyDocument> feedResponse = container.queryItems(query, new QueryRequestOptions(), MyDocument.class);

for (MyDocument item : feedResponse) {
    System.out.println("Found item: " + item);
}

Advanced Queries

3. Parameterized Queries

Use parameterized queries to prevent SQL injection and improve performance with cached query plans.


import com.azure.cosmos.*;
import com.azure.cosmos.models.*;
import com.azure.cosmos.util.CosmosPagedIterable;
import java.util.Arrays;
import java.util.List;

// Assuming 'container' is a CosmosContainer

String query = "SELECT VALUE r FROM r WHERE r.status = @status and r.age > @minAge";
String statusValue = "Active";
int minAgeValue = 30;

QueryDefinition queryDefinition = new QueryDefinition(query)
    .setParameter("@status", statusValue)
    .setParameter("@minAge", minAgeValue);

QueryRequestOptions options = new QueryRequestOptions();

CosmosPagedIterable<MyDocument> feedResponse = container.queryItems(queryDefinition, options, MyDocument.class);

for (MyDocument item : feedResponse) {
    System.out.println("Found item: " + item);
}

4. Query with Ordering and Top

Sort results and limit the number of items returned using ORDER BY and TOP.


import com.azure.cosmos.*;
import com.azure.cosmos.models.*;
import com.azure.cosmos.util.CosmosPagedIterable;

// Assuming 'container' is a CosmosContainer

String query = "SELECT TOP 5 r.name, r.creationDate FROM r WHERE r.isActive = true ORDER BY r.creationDate DESC";

CosmosPagedIterable<MyDocument> feedResponse = container.queryItems(query, new QueryRequestOptions(), MyDocument.class);

for (MyDocument item : feedResponse) {
    System.out.println("Item: " + item.getName() + ", Created: " + item.getCreationDate());
}

5. Querying Nested Properties

Access and filter data within nested JSON objects.


import com.azure.cosmos.*;
import com.azure.cosmos.models.*;
import com.azure.cosmos.util.CosmosPagedIterable;

// Assuming 'container' is a CosmosContainer
// Assuming MyDocument has a property like 'address' which is an object with 'city'

String query = "SELECT VALUE r FROM r WHERE r.address.city = 'New York'";

CosmosPagedIterable<MyDocument> feedResponse = container.queryItems(query, new QueryRequestOptions(), MyDocument.class);

for (MyDocument item : feedResponse) {
    System.out.println("Found item in New York: " + item);
}

6. Aggregation Queries (COUNT, SUM, AVG)

Perform aggregate operations on your data.


import com.azure.cosmos.*;
import com.azure.cosmos.models.*;
import com.azure.cosmos.util.CosmosPagedIterable;

// Assuming 'container' is a CosmosContainer

// Example: Count items with status 'Pending'
String countQuery = "SELECT COUNT(r) FROM r WHERE r.status = 'Pending'";
CosmosPagedIterable<Integer> countResponse = container.queryItems(countQuery, new QueryRequestOptions(), Integer.class);
Integer pendingCount = countResponse.iterator().next();
System.out.println("Number of pending items: " + pendingCount);

// Example: Sum of 'price' for items in 'Books' category
String sumQuery = "SELECT SUM(r.price) FROM r WHERE r.category = 'Books'";
CosmosPagedIterable<Double> sumResponse = container.queryItems(sumQuery, new QueryRequestOptions(), Double.class);
Double totalBookPrice = sumResponse.iterator().next();
System.out.println("Total price of books: " + totalBookPrice);

Key Concepts and Best Practices

Partition Key: Always include the partition key in your queries for optimal performance and cost efficiency.
Indexing: Understand Cosmos DB's indexing policies. For complex queries, consider custom indexing.
Request Options: Utilize QueryRequestOptions for features like maxItemCount, partitionKey, and enableCrossPartitionQuery.
Pagination: The SDK handles pagination for you with CosmosPagedIterable.
Least Privileges: Grant only necessary permissions to your Cosmos DB client.

For more in-depth information, please refer to the Azure Cosmos DB SQL Query Overview and the Azure Cosmos DB Java SDK Samples repository on GitHub.