Java driver quickstart

This driver supports the vector and non-vector data types.

DataStax recommends the Data API and clients for Serverless (Vector) databases. You can use the Data API to perform CQL operations on your table data in Serverless (Vector) databases.

DataStax recommends drivers only for Serverless (Non-Vector) databases, existing applications that previously used a CQL-based driver, or if you need to use some CQL functions that aren’t supported by the Data API. For more information, see Connection methods comparison.

To determine the option that best suits your use case, see Compare connection methods.

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.

Prerequisites

An active Astra account
An active Serverless (Non-Vector) database
A Secure Connect Bundle (SCB)
An application token
A current Java 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.

Complete the prerequisites.

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 SCB credentials.

In the withCloudSecureConnectBundle() method call, include the path to the SCB 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.