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:
-
You have an active Astra account.
-
You have created both a database and a collection.
-
You have created an application token with the Database Administrator role.
-
You have installed Java 11+.
Install the SDK
Use your preferred dependency management tool to install the SDK.
-
Maven
-
Gradle
Requires Maven 3.9+
<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>
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.
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.
// ...
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.
// ...
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})
));
// ...
Perform a similarity search
Get a list of the documents closest to a specific vector.
// ...
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.
mvn clean compile
mvn exec:java -Dexec.mainClass="com.example.Client"
gradle build
gradle run