Java client usage
This page provides language-specific guidance for using the Data API Java client.
For information about installing and getting started with the Java client, see Get started with the Data API.
Client hierarchy
When you create apps using the Data API clients, you must instantiate a DataAPIClient object.
The DataAPIClient object serves as the entry point to the client hierarchy. It includes the following concepts:
Adjacent to these concepts are the administration classes for database administration. The specific administration classes you use, and how you instantiate them, depends on your client language and database type (Astra DB, HCD, or DSE).
-
-
AstraDbDatabaseAdminorDataAPIDatabaseAdmin
-
You directly instantiate the DataAPIClient object only.
Then, through the DataAPIClient object, you can instantiate and access other classes and concepts.
Where necessary, instructions for instantiating other classes are provided in the command reference relevant to each class.
For instructions for instantiating the DataAPIClient object, see Instantiate a client object.
TimeoutOptions
|
This option requires client version 2.0-preview or later. For more information, see Data API client upgrade guide. |
Use the TimeoutOptions class to specify timeouts when interacting with the Data API through the Java client.
You can set timeouts when initializing a class or when calling a method.
The following examples demonstrate how to set timeoutOptions, but the values given in these examples are the default values:
// Initialization with longs
TimeoutOptions timeoutOptions = new TimeoutOptions()
.generalMethodTimeoutMillis(10000L)
.requestTimeoutMillis(10000L)
.connectTimeoutMillis(10000L)
.databaseAdminTimeoutMillis(10000L)
.collectionAdminTimeoutMillis(10000L)
.tableAdminTimeoutMillis(10000L);
// Using durations to initialize the values
TimeoutOptions timeoutOptions2 = new TimeoutOptions()
.generalMethodTimeout(Duration.ofSeconds(10))
.requestTimeoutMillis(10000L)
.connectTimeout(Duration.ofSeconds(10))
.databaseAdminTimeout(Duration.ofSeconds(10))
.collectionAdminTimeout(Duration.ofSeconds(10))
.tableAdminTimeout(Duration.ofSeconds(10));
// Passing those information at initialization
DataAPIClientOptions clientOptions =
new DataAPIClientOptions().timeoutOptions(timeoutOptions);
DataAPIClient client = new DataAPIClient("TOKEN", clientOptions);
// Per method
TableFindOneOptions opsOptions = new TableFindOneOptions()
.timeoutOptions(timeoutOptions);
// Here the field update will be
// equivalent to generalMethodTimeoutMillis(..)
new TableFindOptions()
.timeout(Duration.ofSeconds(10));DataAPIVector
|
This option requires client version 2.0-preview or later. For more information, see Data API client upgrade guide. |
Use the DataAPIVector class to represent and encode vectors when interacting with the Data API using the Java client.
A DataAPIVector is a wrapper around an array of float numbers, and supports the basic access patterns of the equivalent list:
float[] embeddings = new float[] {.1f, .2f};
DataAPIVector vector = new DataAPIVector(embeddings);The serialization of a DataAPIVector object is binary, which speeds up communication. The client automatically serializes and deserializes DataAPIVector objects when interacting with the Data API.
{ "$binary": "AQAAAAIAAAABAAAA" }The following code example assumes default options for all involved objects:
float[] floatArrayEmbeddings = new float[] {.1f, .2f};
DataAPIVector dataAPIvector = new DataAPIVector(floatArrayEmbeddings);
collection.insertOne(new Document().vector(vector));
Optional<Document> doc = collection.findOne(Filters.eq("_id" ,"1"));
DataAPIVector dataAPIVectorReturned = doc.get().getVector();It is still possible to send an array of floats directly instead of using DataAPIVector.
However, this is not recommended for performance reasons.
float[] floatArrayEmbeddings = new float[] {.1f, .2f};
collection.insertOne(new Document().vector(floatArrayEmbeddings));The serialization of the DataAPIVector is done by Jackson at a global level.
It is enabled by default, but can be disabled at runtime.
Some embeddings with high dimension (1400+) might generate a string that is too long for an indexed property. To disable the binary serialization globally, disable encoding so that DataAPIVector objects will be serialized as an array of floats.
This options cannot be overridden by methods.
// Disable binary encoding
DataAPIClientOptions.getSerdesOptions()
.disableEncodeDataApiVectorsAsBase64();
// Enable binary encoding (default)
DataAPIClientOptions.getSerdesOptions()
.encodeDataApiVectorsAsBase64(true);For more information, see Work with rows: Write vector data.
See also
For command specifications, see the command references, such as Work with collections, and Work with tables.
For major changes between versions, see Data API client upgrade guide.
For the complete client reference, see Java client reference.
