Connect with the Java client
Learn how to connect to a HCD database with the astra-db-java client.
Prerequisites
-
You have installed a cluster.
-
You have created a keyspace.
-
You have installed Java 11+ and Maven 3.9+ (or Gradle).
Install the Java client
Use Maven or Gradle to install the Java client.
-
Maven
-
Gradle
To install the Java client with Maven:
-
Install Java 11+ and Maven 3.9+.
-
Create a
pom.xml
file in the root of your project.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>1.0.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.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>
To install the Java client with Gradle:
-
Install Java 11+ and Gradle.
-
Create a
build.gradle
file in the root of your project.build.gradleplugins { id 'java' id 'application' } repositories { mavenCentral() } dependencies { implementation 'com.datastax.astra:astra-db-java:1.0.0' } application { mainClassName = 'com.example.Quickstart' }
Connect to a vector-enabled Hyper-Converged Database (HCD) database
Create a file named Quickstart.java
in the ./src/main/java/com/example/
directory of your project.
import com.datastax.astra.client.Collection;
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.Database;
import com.datastax.astra.client.admin.DataAPIDatabaseAdmin;
import com.datastax.astra.client.model.CollectionOptions;
import com.datastax.astra.client.model.CommandOptions;
import com.datastax.astra.client.model.Document;
import com.datastax.astra.client.model.FindOneOptions;
import com.datastax.astra.client.model.NamespaceOptions;
import com.datastax.astra.client.model.SimilarityMetric;
import com.datastax.astra.internal.auth.UsernamePasswordTokenProvider;
import java.util.Optional;
import static com.datastax.astra.client.DataAPIClients.DEFAULT_ENDPOINT_LOCAL;
import static com.datastax.astra.client.DataAPIOptions.DataAPIDestination.HCD;
import static com.datastax.astra.client.DataAPIOptions.builder;
import static com.datastax.astra.client.model.Filters.eq;
public class QuickStartHCD {
public static void main(String[] args) {
// Database Settings
String cassandraUserName = "cassandra";
String cassandraPassword = "cassandra";
String dataApiUrl = DEFAULT_ENDPOINT_LOCAL; // http://localhost:8181
String databaseEnvironment = "HCD" // DSE, HCD, or ASTRA
String keyspaceName = "ks1";
String collectionName = "lyrics";
// Database settings if you export them as environment variables
// String cassandraUserName = System.getenv("DB_USERNAME");
// String cassandraPassword = System.getenv("DB_PASSWORD");
// String dataApiUrl = System.getenv("DB_API_ENDPOINT");
// OpenAI Embeddings
String openAiProvider = "openai";
String openAiKey = System.getenv("OPENAI_API_KEY"); // Need to export OPENAI_API_KEY
String openAiModel = "text-embedding-3-small";
int openAiEmbeddingDimension = 1536;
// Build a token in the form of Cassandra:base64(username):base64(password)
String token = new UsernamePasswordTokenProvider(cassandraUserName, cassandraPassword).getTokenAsString();
System.out.println("1/7 - Creating Token: " + token);
// Initialize the client
DataAPIClient client = new DataAPIClient(token, builder().withDestination(databaseEnvironment).build());
System.out.println("2/7 - Connected to Data API");
}
}
See also
-
See a complete Java example of how to connect to a database, load data into a collection, and perform a similarity search.
-
Read the Java client reference for more details about available methods.
-
Also see the Java tab for details and examples in each task-based section of the API Reference topics: