Java client reference

The DataStax Astra DB Serverless (Vector) documentation site is currently in Public Preview and is provided on an “AS IS” basis, without warranty or indemnity of any kind. For more, see the DataStax Preview Terms.

Astra SDK Vector is the official Java client for Astra DB Serverless (Vector).

Prerequisites

The code samples on this page assume the following:

Install the SDK

Use your preferred dependency management tool to install the SDK.

  • Maven

  • Gradle

Requires Maven 3.9+

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-client</artifactId>
      <version>1.0</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.Client</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>
build.gradle
plugins {
    id 'java'
    id 'application'
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.datastax.astra:astra-db-client:1.0'
}

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

DataStax recommends running the latest Java LTS version with the highest patch version available.

Initialize the client

Import libraries and connect to the database.

src/main/java/com/example/Client.java
package com.example;

import com.dtsx.astra.sdk.AstraDB;
import io.stargate.sdk.json.CollectionClient;
import io.stargate.sdk.json.domain.JsonDocument;
import io.stargate.sdk.json.domain.JsonResult;
import io.stargate.sdk.json.domain.SimilarityMetric;
import io.stargate.sdk.json.domain.CollectionDefinition;

import java.util.List;

public class Client {

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

    // Initialization
    AstraDB db = new AstraDB(astraToken, astraApiEndpoint);

    // ...

Create a collection

Create an empty collection and define the length of the embeddings.

src/main/java/com/example/Client.java
    // ...

    CollectionDefinition colDefinition = CollectionDefinition.builder()
        .name("vector_test")
        .vector(5, SimilarityMetric.cosine)
        .build();
    db.createCollection(colDefinition);
    CollectionClient col = db.collection("vector_test");

    // ...

Load data

Load a few documents with embeddings into the database.

src/main/java/com/example/Client.java
    // ...

    col.insertMany(List.of(
        new JsonDocument()
            .id("1")
            .put("text", "ChatGPT integrated sneakers that talk to you")
            .vector(new float[]{0.1f, 0.15f, 0.3f, 0.12f, 0.05f}),
        new JsonDocument()
            .id("2")
            .put("text", "An AI quilt to help you sleep forever")
            .vector(new float[]{0.45f, 0.09f, 0.01f, 0.2f, 0.11f}),
        new JsonDocument()
            .id("3")
            .put("text", "A deep learning display that controls your mood")
            .vector(new float[]{0.1f, 0.05f, 0.08f, 0.3f, 0.6f})
        ));

    // ...

Get a list of the documents closest to a specific vector.

src/main/java/com/example/Client.java
    // ...

    List<JsonResult> resultsSet =
        col.similaritySearch(new float[]{0.15f, 0.1f, 0.1f, 0.35f, 0.55f},10);
    resultsSet.stream().forEach(System.out::println);
  }
}

Run the code

Run the code you defined above.

Maven
mvn clean compile
mvn exec:java -Dexec.mainClass="com.example.Client"
Gradle
gradle build
gradle run

Support

Was This Helpful?

Give Feedback

How can we improve the documentation?