Java Api for Azure Cosmos Documents DB (SQL Api)

1
votes

I have started to work with Azure Cosmos DB Sql Api. I have found two different Java APIs which can be used to manage this database:

com.azure::azure-cosmos

After following Quick start demo (available in the Azure portal Quick start section)

enter image description here

I have downloaded demo code, which has dependency on:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-cosmos</artifactId>
    <version>4.0.0-preview.1</version>
</dependency>

This Api is described here: azure-cosmos. In this Api I found couple of useful classes like CosmosClientBuilder, CosmosContainer.

com.microsoft.azure::azure-documentdb

However, after reading documentation from docs.microsoft.azure.com I found that they recommend to use com.microsoft.azure::azure-documentdb:

<dependency>
    <groupId>com.microsoft.azure</groupId>
    <artifactId>azure-documentdb</artifactId>
    <version>LATEST</version>
</dependency>
<dependency>
    <groupId>com.microsoft.azure</groupId>
    <artifactId>azure-cosmosdb</artifactId>
    <version>2.6.5</version>
</dependency>

In this Api I do not see the useful CosmosClientBuilder class, and the way of creating connection to the database is little different.

I wonder which Api is recommended to use? Do they serve different purposes?

2
javaazureazure-cosmosdbazure-cosmosdb-sqlapiazure-java-sdk

2 Answers

1
votes

com.azure::azure-cosmos is the recommended version for new users of Azure Cosmos DB Java SDK for SQL API. As you can tell from the Maven artifact ("4.0.0.preview-1") the latest release is a preview version of v4 - keep an eye out later in March for the General Availability (non-preview) release of Azure Cosmos DB Java SDK v4 for SQL API. It will be under a slightly different Maven artifact name.

1
votes

All of these packages are SDK updates for the same API, namely the Core (SQL) API which is recommend for best perf and support.

Version number is what matters. 3.x.x is latest stable 4.0 is preview and we're pushing people to start using 4.0.

Here is the relation of version number to Maven artifact:

com.azure::azure-cosmos: v4.0.x Async/Sync (public preview)

com.microsoft.azure::azure-cosmos : v3.x.x Async/Sync (stable)

com.microsoft.azure::azure-cosmosdb : v2.x.x Async (stable)

com.microsoft.azure::azure-documentdb : v2.4.7 "Legacy" Sync, deprecated (stable)

If you are confused by the many different Maven artifacts for the same SDK - this happened when Azure Cosmos DB SDK migrated into the mainline Azure SDK repo; we've gone through a process of refining our package names. We expect this to be stable going forward.