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.

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

java --version

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

mvn -version

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.

• Clone the repository

git clone [email protected]: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

• 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.

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.

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.

Add the following dependency to your pom.xml file:

<dependency>
  <groupId>com.datastax.astra</groupId>
  <artifactId>astra-db-java</artifactId>
  <version>1.1.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.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);
 }
}

• Start the 2 containers with the following command:

docker-compose up -d

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

docker-compose ps

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"
  }
}'

public class QuickStartLocal {

    public static void main(String[] args) {

        // Create a token
        String token = new TokenProviderStargateV2("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");

        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("vector_test", 5, COSINE);
        System.out.println("Created a Collection");
    }
}

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.