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.

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. Hyper-Converged Database (HCD), 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).

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.

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).

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 field is no longer accepted as an alternative for $vector.

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).

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);

Hyper-Converged Database (HCD) 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.