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 not yet available in Maven Central. You can build it locally and install it in your local repository.

1. Local Installation

1.1 Prerequisites

📦 Java Development Kit (JDK) 8

• 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 -DskipTests=true

1.3 Installation

Add the following dependency to your pom.xml file:

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

2. QuickStart

After creating a new java Project and adding the dependency to your pom.xml file, you can start using the library.

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

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.Collection;
import com.datastax.astra.client.Database;
import com.datastax.astra.client.model.Document;
import com.datastax.astra.client.model.FindIterable;
import java.util.List;
import static com.datastax.astra.client.model.Filters.eq;
import static com.datastax.astra.client.model.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. 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.