Java driver quickstart
|
DataStax recommends using the Java client with DSE 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. |
Because DataStax Enterprise (DSE) is based on Apache Cassandra®, you can use Cassandra drivers to connect to your DSE databases.
To use the Java driver, you need to add the driver dependency to your pom.xml, use the ConnectDatabase class to initialize the driver, and then connect the driver to your DSE database.
Once connected, your scripts can use the driver to run commands against your database.
This quickstart explains how to use the Java driver to connect and send some CQL statements to a database.
Prerequisites
Before you configure the Java driver, do the following:
-
Install a cluster and start a DSE database
-
Create or obtain credentials for a superuser
-
Install Java project dependencies, such as a current Java version and Maven
Add the Java driver dependency
-
In your project’s
pom.xmlfile, add a dependency for the Apache Cassandra Java driver.
-
Latest version
-
Version 4.17 and earlier
<dependency> <groupId>org.apache.cassandra</groupId> <artifactId>java-driver-core</artifactId> <version>VERSION</version> </dependency><dependency> <groupId>com.datastax.oss</groupId> <artifactId>java-driver-core</artifactId> <version>VERSION</version> </dependency>If you choose to install an earlier version, make sure you choose a version that is compatible with DSE. If you need to query vector data, make sure your chosen version also supports vector data. For more information, see Cassandra drivers supported by DataStax.
-
Initialize and connect the Java driver
Import the necessary classes, set up a CqlSession with authentication credentials, and specify a default keyspace:
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 DriverExample {
public static void main(String[] args) {
// Initialize the Java driver
String keyspace = "default_keyspace";
CqlSessionBuilder builder = CqlSession.builder();
builder.withAuthCredentials("user_name","password");
builder.withKeyspace(keyspace);
try (CqlSession session = builder.build()) {
int v_dimension = 5;
// ...
}
}
}Run commands with the Java driver
After you connect to the database, you can use the driver to perform operations on your database.
The following examples create a table with a vector-compatible SAI index, load sample data, and run a similarity search.
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, "ChatGPT 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"));
}
}
}
}