Support of Azure Cosmos DB for Java

CAST supports Azure Cosmos DB via its com.castsoftware.nosqljava extension. Details about how this support is provided for Java source code is discussed below.

Supported Client Libraries

Library Version Supported
Azure Cosmos DB Java SDK for SQL API Up to: 4.32.0 ✔️
Azure Cosmos DB Async Java SDK for SQL API Up to: 4.32.0 ✔️
Azure Cosmos DB Java SDK v4 Up to: 4.32.0 ✔️

Supported Operations

Operations Method Supported
Insert - v2
Insert - v4
Update - v2
Update - v4
Select - v2
Select - v4
Delete - v2
Delete - v4

Above mentioned methods are supported for both Synchronous and Asynchronous clients.


Icon Description
Java CosmosDB Database
Java CosmosDB Collection
Java Unknown CosmosDB Database
Java Unknown CosmosDB Collection
Link type Source and destination of link Methods Supported
belongsTo From Java CosmosDB Collection object to Java CosmosDB Database object -
useLink Between the caller Java Method objects and Java CosmosDB Collection object CreateCollection
useInsertLink Between the caller Java Method objects and Java CosmosDB Collection object CreateDocument
useUpdateLink Between the caller Java Method objects and Java CosmosDB Collection object ReplaceDocument
useSelectLink Between the caller Java Method objects and Java CosmosDB Collection object ReadDocument
useDeleteLink Between the caller Java Method objects and Java CosmosDB Collection object DeleteDocument

What results can you expect?

 Some example scenarios are shown below:

Cosmos DB Client Creation

CosmoDB client creation

private static final String HOST = "[YOUR_ENDPOINT_HERE]";
 private static final String MASTER_KEY = "[YOUR_KEY_HERE]";
 private static DocumentClient documentClient = new DocumentClient(HOST, MASTER_KEY,
                 ConnectionPolicy.GetDefault(), ConsistencyLevel.Session);
 public static DocumentClient getDocumentClient() {
     return documentClient;

CosmoDb Async client creation

public AsyncDocumentClient client = new AsyncDocumentClient.Builder()

Insert Data Operation


  public static Family andersenFamily = new Family();

    public void TestCreateDocument() throws DocumentClientException {
        // Insert your Java objects as documents
        System.out.println("Creating doc");


        this.client.createDocument("/dbs/familydb/colls/familycoll", andersenFamily, new RequestOptions(), true);

        System.out.println("Done Creating doc");


  public Single<OutcomingAccountStatus> createStatus(IncomingCreateAccountStatus incoming) {

    Mono<YapeAccountStatus> createYapeAccountStatus =
        defer(() -> {
          YapeAccountStatus yapeAccountStatus = new YapeAccountStatus();

          return cosmosAsyncDatabase.getContainer(CONTAINER_YAPE_ACCOUNT_STATUS)
                  new PartitionKey(yapeAccountStatus.getIdYapeAccount()),
                  new CosmosItemRequestOptions())
              .map(itemResponse -> yapeAccountStatus);

Select Data Operation


public void TestQueryDocuments() {

        System.out.println("Querying db...");
        FeedResponse<Document> queryResults = this.client.queryDocuments("/dbs/familydb/colls/familycoll",
                "SELECT * FROM Family WHERE = 'Andersen.1'", null);

        System.out.println("Running SQL query...");
        for (Document family : queryResults.getQueryIterable()) {
            System.out.println(String.format("\tRead %s", family));


public void TestReadDocument() throws DocumentClientException {
        this.client.readDocument("/dbs/familydb/colls/familycoll/docs/Andersen.1", null);

public void TestReadDocuments() throws DocumentClientException {
        this.client.readDocuments("/dbs/familydb", null);


private Mono<YapeAccountStatus> getLastStatusMono(String idYapeAccount) {
SqlQuerySpec sqsGetLastStatusQuery = SqlBuilder.create()
.query("select top 1 s.status from s where s.idYapeAccount = @idYapeAccount "
+ "and s.status != @statusDeleted order by s.creationDate desc")
new SqlParameter("@idYapeAccount", idYapeAccount),
new SqlParameter("@statusDeleted", AccountStatus.DELETED.getCode()))

CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();
options.setPartitionKey(new PartitionKey(idYapeAccount));

return cosmosAsyncDatabase.getContainer(CONTAINER_YAPE_ACCOUNT_STATUS)
.queryItems(sqsGetLastStatusQuery, options, YapeAccountStatus.class)

Update Operation


public void TestReplaceDocument() throws DocumentClientException {
        // Update a property
        this.client.replaceDocument("/dbs/familydb/colls/familycoll/docs/Andersen.1", andersenFamily, null);


 private Mono<BlockedResources> replaceItem(BlockedResources blockedResources, CosmosItemRequestOptions options) {

    return getBlockedResourcesContainer().replaceItem(blockedResources, blockedResources.getId(),
        new PartitionKey(blockedResources.getResource()), options)
        .doOnSuccess(itemResponse -> blockedResources.set_etag(itemResponse.getETag()))
        .map(itemResponse -> blockedResources);

Delete Operation

public void TestDeleteDocument() throws DocumentClientException {
        this.client.deleteDocument("", null);

Known Limitations

Major limitations

No support for Cassandra API, MongoDB API, Gremlin API, Table API or other APIs built by Microsoft for accessing an Azure Cosmos DB service. See the API reference here :

Minor limitations     

  • Database and collection names are resolved as known objects when a connection string is passed to the client directly:

    • Example: This connection string is passed to client - “/dbs/familydb/colls/familycoll” 
  • Database and collection are marked as Unknown when Database Collection and document objects are passed as an argument in CRUD methods.

  • Runtime Ambiguities are not resolved:

    • Example: Different databases are accessed in if/else cases based on some conditions