Data API client upgrade guide (Java)

DataStax recommends using the latest versions of the client to access the newest features, improvements, and bug fixes.

This page describes major changes in specific client versions, including major new features, deprecations, removals, and breaking changes. This page is not a changelog and it does not provide client release notes.

For information about the latest client versions, release notes, installation and upgrade instructions, and other client documentation, see:

Version 2.3

DataStax released version 2.3 in July 2026.

PCU groups

The clients added support for Provisioned Capacity Units (PCUs):

You can specify a PCU group when you create a database.
There is a new method to list PCU groups.
The method to find available regions for database creation returns information about PCU groups.

Previous upgrade guides

The following information is for earlier client releases.

Version 2.2

DataStax released version 2.2 in March 2026.

Version 2.1

DataStax released version 2.1 in September 2025.

Expanded support for maps, sets, and lists in tables

Maps, sets, and lists can now be used in table indexes.
Maps can now use non-string keys.
Maps, sets, and lists can now be used in updates.
The push, each, and pullAll update operators were added.
Maps, sets, and lists in tables can now be filtered.

Lexicographical matching and keyword relevance search

Lexicographical matching is currently in public preview. Development is ongoing, and the features and functionality are subject to change. Astra DB Serverless, and the use of such, is subject to the DataStax Preview Terms.

For collections with lexical enabled and tables with a text index, you can perform lexicographical matching and keyword relevance search. For more information, see Find data with lexicographical matching.

User-defined types in tables

You can now create user-defined types and use them in tables. For more information, see User-defined types (UDTs) (Java).

Method to list index metadata

A method to list index metadata was added. For more information, see List index metadata (Java).

Method to find available regions

A method to list available regions for database creation was added. For more information, see Find available regions (Java)

Pagination improvements for cursors

The clients now provide a way to fetch a specific page of results. This is useful for cases where an external action triggers fetching the next page of results. For example, you might use this feature if you implement an infinite scroll interface or a button to load more results.

For an example, see Iterate over found documents.

Filter embedding providers by status

The method to find embedding providers now accepts a parameter to filter the available models by status. By default, the Data API excludes models that are deprecated or end of life. Additionally, the response includes the status of each returned model.

Filter reranking providers by status

The method to find reranking providers now accepts a parameter to filter the available models by status. By default, the Data API excludes models that are deprecated or end of life. Additionally, the response includes the status of each returned model.

Version 2.0

DataStax released version 2.0 in April 2025 to accompany Data API version 1.0.20.

Support for tables

You can now use the Data API and clients to work with tables in your databases.

Improved support for vector data

You can now use the DataAPIVector class to represent and encode vectors. DataAPIVector is a wrapper around an array of floats.

import com.datastax.astra.client.core.vector.DataAPIVector;

DataAPIVector vector = new DataAPIVector(new float[] {.1f, .2f});

When you send a DataAPIVector object, the vector embeddings are binary-encoded by default. DataStax recommends that you always use a DataAPIVector object instead of a list of floats to improve performance.

For more information, see DataAPIVector and Vector type (Java).

Support for hybrid search

Hybrid search and reranking are currently in public preview. Development is ongoing, and the features and functionality are subject to change. Astra DB Serverless, and the use of such, is subject to the DataStax Preview Terms.

Hybrid search uses a reranker model to combine results from a vector search and a lexical search.

When you create a collection, you can now configure a lexical analyzer and a reranker model.
When you insert documents, you can populate the $lexical field for later use in hybrid search.
A new find and rerank command enables you to find documents in a collection with hybrid search.

Java 17 or later required

The Java client now requires Java 17 or later. DataStax recommends Java 21.

Breaking changes to create collection

The createCollection() method includes the following breaking changes:

The new collectionDefinition parameter replaces the following parameters:
- dimension
- metric
- collectionOptions
The namespace parameter alias is removed. Use keyspace instead.
There is a new createCollectionOptions parameter. This parameter allows arbitrary customization of the returned Collection object, including the timeout options.

For examples, see Create a collection (Java).

Replacement of client timeout settings

Previously supported timeout parameters have been removed. New timeout options let you set global timeouts and timeouts for individual operation.

The Java client supports several ways to specify the timeouts for various API operations. You can set default timeouts for an object (such as Collection or Database), and you can set individual timeouts for a single method call.

Prior to version 2.0, some operations offered a timeout option. However, this option was not universally available, and you couldn’t set fixed defaults.

Within each operation’s Options, you can use the timeout object to set timeouts as long millis or a Duration object. For example:

// Define timeout using long millis
CollectionFindOneOptions options1 = new CollectionFindOneOptions()
  .timeout(5000L);
collect.findOne(myFilter, options2);

// Define timeout using a Duration object
CollectionFindOneOptions options2 = new CollectionFindOneOptions()
  .timeout(Duration.ofSeconds(5));

For more fine-grained control, the Java client offers different timeouts that apply to different kinds of operations. Depending on the method called, the client enforces the relevant timeouts for that method, as defined in the timeout portion of the object’s APIOptions. For example:

TimeoutOptions fullFledgesTimeouts = new TimeoutOptions()
  .generalMethodTimeoutMillis(50000)
  .requestTimeoutMillis(2000);
CollectionFindOneOptions options3 = new CollectionFindOneOptions()
  .timeoutOptions(fullFledgesTimeouts);
collect.insertMany( ..., options3)

You can find more information in the parameter list for each method.

New response when listing collection metadata

Previously, the listCollections() method of a Database object returned Stream<CollectionInfo>. Now, the method returns List<CollectionDescriptor>.

For more information about this method, see List collection metadata (Java).

Updated import paths and class names

The import paths for many classes have changed. Additionally, many classes have new names to distinguish the collection and table versions.

For example, instead of com.datastax.astra.client.model.FindOneOptions, there is now com.datastax.astra.client.collections.commands.options.CollectionFindOneOptions and import com.datastax.astra.client.tables.commands.options.TableFindOneOptions.

For more information, see the examples for the collection methods that you use, or see the see the client reference.

No `distinct` method on cursors

Cursors, such as the cursor returned from finding documents, no longer support a distinct method. To find the distinct values, use the method to find distinct values, or iterate over the cursor to collect the distinct values.

Removals

Version 2.0 of the Data API clients removes the following features that were previously deprecated:

The term namespace is replaced by keyspace as of Version 1.5.
The vector and vectorize fields are no longer accepted as alternatives for $vector and $vectorize.

Use a loop or other standard practice to execute multiple sequential insert operations. For examples, see Insert documents (Java).

For examples, see Delete documents (Java).

This option only existed on the client-side. Now, if you attempt to create a collection with the same name as an existing collection, the client surfaces the resulting Data API error only if the existing collection has different settings than the requested new collection.

Version 1.5

DataStax released version 1.5 and Data API version 1.0.16 on September 20, 2024.

Deprecation of `namespace`

Version 1.5 of the Data API clients deprecates namespace in favor of keyspace. In this version, you can use either keyspace or namespace, but you must use one consistently. This change also applies to the Data API itself (HTTP).

This change aligns the Data API and clients with the DevOps API, which already uses keyspace for both namespaces and keyspaces. It also better reflects the underlying Astra DB functionality, in which namespace is effectively an alternative label for keyspace.

Client version 2.0 removed support for namespace. After upgrading to version 2.0 or later, the clients accept only keyspace.

After you upgrade to version 1.5 or later, change your code to use keyspace instead of namespace. For example:

import java.time.Duration;// Before 1.5
Database db = client.getDatabase(String apiEndpoint, String namespace);

// 1.5 and later
Database db = client.getDatabase(String apiEndpoint, String keyspace);

// Second argument can be a DatabaseOptions to specialize even more the database object
DatabaseOptions dbOptions = new DatabaseOptions(token, options)
 .keyspace(keyspace)
 .token("anotherToken")
 .timeout(Duration.ofSeconds(10));
Database db = client.getDatabase(String apiEndpoint ,dbOptions);

Astra DB Serverless documentation and client references use keyspace in place of namespace, with the following exceptions:

Some preexisting integration guides and tutorials that rely on a subcomponent, such as a sample app, that is unrelated to the Data API and has a namespace object, class, variable, or otherwise.
Third-party documentation over which DataStax has no influence.