Java driver quickstart
|
DataStax recommends using the Java client with Serverless (Vector) databases. Use the Java driver only if you are working with an existing application that previously used a CQL-based driver or if you plan to explicitly use CQL. |
Review the Connection methods comparison page to determine the option that best suits your use case.
This quickstart explains how to use the Java driver to connect to your database, load a set of vector embeddings, and perform a similarity search to find vectors that are close to the one in your query.
-
An active Astra account
-
An active Serverless (Non-Vector) database
-
A secure connect bundle downloaded from the Astra Portal.
-
A current Java driver version
Add dependencies
Add the required Java driver dependency to your Maven pom.xml file.
You need version 4.17.0 or later to support Serverless (Vector) databases.
<dependency>
<groupId>com.datastax.oss</groupId>
<artifactId>java-driver-core</artifactId>
<version>4.17.0</version>
</dependency>Import libraries and connect to the database
Import the necessary Java libraries and establish a connection to the database using the CqlSession builder.
import com.datastax.oss.driver.api.core.CqlSession;
import com.datastax.oss.driver.api.core.cql.ResultSet;
import com.datastax.oss.driver.api.core.cql.Row;
import com.datastax.oss.driver.api.core.CqlSessionBuilder;
import com.datastax.oss.driver.api.core.cql.PreparedStatement;
import com.datastax.oss.driver.api.core.data.CqlVector;
import com.datastax.oss.driver.api.core.type.codec.TypeCodecs;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.List;
public class VectorTest {
public static void main(String[] args) {
// Initialize the Java driver
String keyspace = "default_keyspace";
CqlSessionBuilder builder = CqlSession.builder();
builder.withCloudSecureConnectBundle(Paths.get(System.getenv("ASTRA_DB_SECURE_BUNDLE_PATH")));
builder.withAuthCredentials("token", System.getenv("ASTRA_DB_APPLICATION_TOKEN"));
builder.withKeyspace(keyspace);
try (CqlSession session = builder.build()) {
int v_dimension = 5;
// ...
}
}
}After you connect to the database, you can use the driver to perform operations on your database.
Create a table and vector-compatible Storage Attached Index (SAI)
Define a new table that is compatible with vector data and create an SAI for efficient queries.
// ...
session.execute(String.format(
"CREATE TABLE IF NOT EXISTS vector_test (id INT PRIMARY KEY, " +
"text TEXT, vector VECTOR<FLOAT,%d>);",
v_dimension)
);
session.execute(String.format(
"CREATE CUSTOM INDEX IF NOT EXISTS idx_vector_test ON vector_test " +
"(vector) USING 'StorageAttachedIndex' WITH OPTIONS = {'similarity_function' : 'cosine'};")
);
// ...Load data
Insert a few documents with embeddings into the collection.
// ...
List<Object[]> textBlocks = Arrays.asList(
new Object[]{1, "Chat bot integrated sneakers that talk to you", CqlVector.newInstance(Arrays.asList(0.1f, 0.15f, 0.3f, 0.12f, 0.05f))},
new Object[]{2, "An AI quilt to help you sleep forever", CqlVector.newInstance(Arrays.asList(0.45f, 0.09f, 0.01f, 0.2f, 0.11f))},
new Object[]{3, "A deep learning display that controls your mood", CqlVector.newInstance(Arrays.asList(0.1f, 0.05f, 0.08f, 0.3f, 0.6f))}
);
PreparedStatement ps = session.prepare(String.format(
"INSERT INTO vector_test (id, text, vector) VALUES (?, ?, ?)")
);
for (Object[] block : textBlocks) {
session.execute(ps.bind(block));
}
// ...Perform a similarity search
Insert sample data with text and vector embeddings into the table. Then, find documents that are close to a specific vector embedding.
// ...
String annQuery = String.format(
"SELECT id, text, similarity_cosine(vector, [0.15, 0.1, 0.1, 0.35, 0.55]) as sim " +
"FROM vector_test " +
"ORDER BY vector ANN OF [0.15, 0.1, 0.1, 0.35, 0.55] LIMIT 2"
);
ResultSet rs = session.execute(annQuery);
for (Row row : rs) {
System.out.printf("[%d] \"%s\" (sim: %.4f)\n", row.getInt("id"), row.getString("text"), row.getFloat("sim"));
}
}
}
}
// ...Migrate the Java driver
You can migrate an earlier Java driver to a version that can connect to your Astra DB database.
-
In your pom.xml, update the Java driver version:
<dependency> <groupId>com.datastax.oss</groupId> <artifactId>java-driver-core</artifactId> <version>*VERSION*</version> </dependency> -
In your existing Java driver code, modify the connection code to use the secure connect bundle credentials.
In the
withCloudSecureConnectBundle()method call, include the path to the secure connect bundle for your Astra DB database (secure-connect-DATABASE_NAME.zip).CqlSessionBuilder builder = CqlSession.builder(); builder.withCloudSecureConnectBundle(Paths.get(System.getenv("/*SECURE_CONNECT_BUNDLE_PATH*/secure-connect-*DATABASE_NAME*.zip"))); builder.withAuthCredentials("token", System.getenv("*APPLICATION_TOKEN*")); -
Build your project to test the connection.
