Java Client for Data API

This client library provides a simplified way to interact with Data API for AstraDB or local instances. For detailed documentation, each operation comes with a detailed description and examples.

• astra-db-ts is the equivalent for typescript
• astrapy is the equivalent in python

This library is under development and is available in Maven Central. You can build it locally and install it in your local repository.

📋 Table Of Content

1. Installation
   1. Prerequisites
   2. Packaging
2. QuickStart with Astra DB
   1. Sign up for Astra DB
   2. Create a Database
   3. Get your credentials
   4. Create a new project and add the dependency
3. [QuickStart with Local Instances]()
   1. Start Data Api with DSE
   2. Start Data Api with HCD
   3. Datq Api Information
   4. Using Java client with Local Instance
4. What's Next

1. Installation

1.1 Prerequisites

📦 Java Development Kit (JDK) 11

• Use the reference documentation to install a Java Development Kit
• Validate your installation with

java --version

📦 Apache Maven

• Use the reference documentation to install Apache Maven
• Validate your installation with

mvn -version

📦 Docker (local Installation)

Docker is an open-source project that automates the deployment of software applications inside containers by providing an additional layer of abstraction and automation of OS-level virtualization on Linux.

1.2 Packaging

• Clone the repository

git clone git@github.com:datastax/astra-db-java.git

• Build the project (java 11 and Maven is required)

Note: You should skip the tests if you want to speed up the build, to run the test you need to have a bit of setup:

• An environment variable ASTRA_DB_APPLICATION_TOKEN with your an Organization Administrator Astra token (PROD)
• An environment variable ASTRA_DB_APPLICATION_TOKEN_DEV with your an Organization Administrator Astra token (DEV)
• A running Data API locally with docker (see the docker-compose.yml in the root of the project)

mvn clean install -Dtest.skipped=true

2. QuickStart with Astra DB

2.1. Sign up for Astra DB

• Access https://astra.datastax.com and register with Google or Github account. It is free to use. There is free forever tiers of up to 25$ of consumption every month.

2.2. Create a Database

If you are creating a new account, you will be brought to the DB-creation form directly.

• Get to the databases dashboard (by clicking on Databases in the left-hand navigation bar, expanding it if necessary), and click the [Create Database] button on the right.

• ℹ️ Fields Description

If all fields are filled properly, clicking the "Create Database" button will start the process.

It should take a couple of minutes for your database to become Active.

2.3. Get your credentials

To connect to your database, you need the API Endpoint and a token. The api endpoint is available on the database screen, there is a little icon to copy the URL in your clipboard. (it should look like https://<db-id>-<db-region>.apps.astra.datastax.com).

To get a token click the [Generate Token] button on the right. It will generate a token that you can copy to your clipboard.

2.4 Create a new project and add the dependency

Add the following dependency to your pom.xml file:

<dependency>
  <groupId>com.datastax.astra</groupId>
  <artifactId>astra-db-java</artifactId>
  <version>1.3.0</version>
</dependency>

Here is a sample class that demonstrates how to use the library:

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.collections.documents.Document;
import com.datastax.astra.client.core.paging.FindIterable;

import java.util.List;

import static com.datastax.astra.client.core.query.Filters.eq;
import static com.datastax.astra.client.core.vector.SimilarityMetric.cosine;

public class GettingStarted {
   public static void main(String[] args) {
      // Initializing client with a token
      DataAPIClient client = new DataAPIClient("my_token");

      // Accessing the Database through the HTTP endpoint
      Database db = client.getDatabase("http://db-region.apps.astra.datastax.com");

      // Create collection with vector support
      Collection<Document> col = db.createCollection("demo", 2, cosine);

      // Insert records
      col.insertMany(List.of(
              new Document("doc1").vector(new float[]{.1f, 0.2f}).append("key", "value1"),
              new Document().id("doc2").vector(new float[]{.2f, 0.4f}).append("hello", "world"),
              new Document("doc3").vector(new float[]{.5f, 0.6f}).append("key", "value1"))
      );

      // Search
      FindIterable<Document> docs = col.find(
              eq("key", "value1"), // metadata filter
              new float[]{.5f, .5f},              //vector
              10);                                 // maxRecord

      // Iterate and print your results
      for (Document doc : docs) System.out.println(doc);
   }
}

3. QuickStart with Local Instances

3.1. Start Data Api with DSE

• Start the 2 containers with the following command:

docker-compose up -d

3.2. Start Data Api with HCD

docker-compose -f docker-compose-hcd.yml up -d

• Check the status of the containers with the following command:

docker-compose ps

3.3. Datq Api Information

Output

NAME                          IMAGE                                           COMMAND                
astra-db-java-coordinator-1   stargateio/coordinator-dse-next:v2.1.0-BETA-9   "./starctl"             
astra-db-java-jsonapi-1       stargateio/jsonapi:v1.0.6         

• Here are the information to connect to the local instance:

• The API will have 3 resources

• Sample curl to create a namespace:

curl -X 'POST' \
  'http://localhost:8181/v1' \
  -H 'accept: application/json' \
  -H 'Token: Cassandra:Y2Fzc2FuZHJh:Y2Fzc2FuZHJh' \
  -H 'Content-Type: application/json' \
  -d '{
  "createNamespace": {
    "name": "default_keyspace"
  }
}'

3.4. Using Java client with Local Instance

public class QuickStartLocal {

    public static void main(String[] args) {

        // Create a token
        String token = new UsernamePasswordTokenProvider("cassandra", "cassandra").getToken();
        System.out.println("Token: " + token);

        // Initialize the client
        DataAPIClient client = new DataAPIClient(token, builder().withDestination(CASSANDRA).build());
        System.out.println("Connected to Data API");

       // Create a default keyspace
       ((DataAPIDatabaseAdmin) client
               .getDatabase(dataApiUrl)
               .getDatabaseAdmin()).createNamespace(keyspaceName, NamespaceOptions.simpleStrategy(1));
        System.out.println("Keyspace created ");

        Database db = client.getDatabase("http://localhost:8181", "default_keyspace");
        System.out.println("Connected to Database");

        // Create a collection. The default similarity metric is cosine.
        Collection<Document> collection = db.createCollection("simple", 5, COSINE);
        System.out.println("Created a Collection simple");

       // Create a collection with Vector embeddings OPEN AI
       Collection<Document> collectionLyrics =  db.createCollection("vector", CollectionOptions.builder()
                       .vectorSimilarity(SimilarityMetric.COSINE)
                       .vectorDimension(1536)
                       .vectorize("openai", "text-embedding-3-small")
                       .build(),
               new CommandOptions<>().embeddingAPIKey("sk-....."));
    }
}

4. What's Next

This is an the organization of the different classes of the framework.

• For more information use the JAVADOC documentation

• The examples directory contains more examples on how to use the library.