Connect with the Java client

You can connect to your Serverless (Vector) databases with the astra-db-java client.

For a guided experience to get started with the Java client, see the Quickstart.

Prerequisites

An active Astra account
An active Serverless (Vector) database

Install the Java client

Install the Java client with Maven or Gradle.

Maven
Gradle

Install Java 11 or later and Maven 3.9 or later.

Create a pom.xml file in the root of your project, and then replace VERSION with the latest version of astra-db-java .

pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.example</groupId>
  <artifactId>test-java-client</artifactId>
  <version>1.0-SNAPSHOT</version>

  <!-- The Java client -->
  <dependencies>
    <dependency>
      <groupId>com.datastax.astra</groupId>
      <artifactId>astra-db-java</artifactId>
      <version>VERSION</version>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>exec-maven-plugin</artifactId>
        <version>3.0.0</version>
        <configuration>
          <executable>java</executable>
          <mainClass>com.example.Quickstart</mainClass>
        </configuration>
        <executions>
          <execution>
            <goals>
              <goal>java</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <configuration>
          <source>11</source>
          <target>11</target>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

Install Gradle and Java 11 or later.

Create a build.gradle file in the root of your project:

build.gradle

plugins {
    id 'java'
    id 'application'
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.datastax.astra:astra-db-java:1.+'
}

application {
    mainClassName = 'com.example.Quickstart'
}

When a new client version is released, upgrade your client to get the latest features, improvements, and bug fixes. For information about major changes in specific client versions, see Compare Data API client versions.

To upgrade your Java client, modify the astra-db-java version in your project’s build.gradle or pom.xml.

Set environment variables

The Data API requires an application token and your database’s API endpoint for most operations. Store these values in environment variables to simplify reuse in your scripts:

Generate an application token with the Database Administrator role, and then get your database’s API endpoint in the form of https://DATABASE_ID-REGION.apps.astra.datastax.com. For more information, see Generate an application token for a database.

Set environment variables for your token and API endpoint:

Linux or macOS
Windows

export ASTRA_DB_API_ENDPOINT=API_ENDPOINT
export ASTRA_DB_APPLICATION_TOKEN=TOKEN

set ASTRA_DB_API_ENDPOINT=API_ENDPOINT

set ASTRA_DB_APPLICATION_TOKEN=TOKEN

Connect to a Serverless (Vector) database

When you use a Data API client, your main entry point is the DataAPIClient object. Then, you get a database object to connect to a database. These operations are the basis of your client scripts. For more information, see Instantiate a client object and Connect to a database.

import com.datastax.astra.client.Collection;
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.Database;
import com.datastax.astra.client.model.Document;
import com.datastax.astra.client.model.FindIterable;
import com.datastax.astra.client.model.SimilarityMetric;

public class Quickstart {

  public static void main(String[] args) {
    // Loading Arguments
    String astraToken = System.getenv("ASTRA_DB_APPLICATION_TOKEN");
    String astraApiEndpoint = System.getenv("ASTRA_DB_API_ENDPOINT");

    // Initialize the client
    DataAPIClient client = new DataAPIClient(astraToken);
    System.out.println("Connected to AstraDB");

    Database db = client.getDatabase(astraApiEndpoint);
    System.out.println("Connected to Database.");
  }
}

Next steps

After you connect to a database, you can extend your script to work with the collections and documents in it. You can also use the Java client to manage databases and keyspaces.

For more information about Astra DB APIs, see Intro to Astra DB APIs and Get started with the Data API.

Connect with the Java client

Prerequisites

Install the Java client

Upgrade the Java client

Set environment variables

Connect to a Serverless (Vector) database

Next steps

Was this helpful?

Give Feedback