Data API client upgrade guide

DataStax recommends using the latest versions of the clients 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 the links in the following table:

Language	Client	Dependency	Documentation
Python	astrapy	Python 3.8 or later	Get started with the Data API
TypeScript	astra-db-ts	Node.js 18 or later	Get started with the Data API
Java	astra-db-java	Java 17 or later (21 recommended)	Get started with the Data API

Language

Client

Version

Dependency

Documentation

Python

astrapy

Python 3.8 or later

Get started with the Data API

TypeScript

astra-db-ts

Node.js 18 or later

Get started with the Data API

Java

astra-db-java

Java 17 or later (21 recommended)

Get started with the Data API

Version 2.0

DataStax released clients version 2.0 in March 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 Serverless (Vector) databases.

Improved support for vector data

Python
TypeScript
Java

You can now use the astrapy.data_types.DataAPIVector class to represent and encode vectors. DataAPIVector is a wrapper around a list of floats.

from astrapy.data_types import DataAPIVector

vector = DataAPIVector([.08, .68, .30])

For collections and documents, regardless of whether you use a DataAPIVector object or a list of floats, the vector embeddings are binary-encoded by default, which improves performance. To change the default encoding, see Serdes Options and Custom Data Types.

For tables and rows, the vector embeddings are only binary-encoded if you use a DataAPIVector object. DataStax recommends that you always use a DataAPIVector object instead of a list of floats to improve performance.

When you read the value of a vector field or column, the client always returns a DataAPIVector object, unless you change the default ser/des behavior.

For more information, see DataAPIVector and Data types for tables: Vector type.

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

import { DataAPIVector } from '@datastax/astra-db-ts';

const vector = new DataAPIVector([0.4, -0.6, 0.2]);

When you read the value of a vector field or column, the client always returns a DataAPIVector object, unless you change the default ser/des behavior.

For more information, see Data types for tables: Vector type.

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 Data types for tables: Vector type.

Support for hybrid search

Hybrid search, lexical 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 (Java only)

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

Breaking change to create collection (Python and Java only)

Python
Java

The create_collection() method includes the following breaking changes:

The new definition parameter replaces the following parameters:
- dimension
- metric
- service
- indexing
- default_id_type
The namespace parameter alias is removed. Use keyspace instead.
The check_exists parameter is removed. 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.
The max_time_ms parameter is removed.
The additional_options parameter is removed.
The new collection_admin_timeout_ms parameter replaces the collection_max_time_ms parameter.
There is a new document_type parameter. This parameter specifies the type hint for documents in the collection.
There is a new spawn_api_options parameter. This parameter allows arbitrary customization of the returned Collection object, including the timeout options.

For examples, see Create a 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.

Stricter handling of timestamps and datetimes (Python only)

The Data API Python client now has stricter handling of the standard-library datetime.datetime objects for writing to databases. Primarily, naive datetimes are rejected by default because they can’t inherently be mapped to a timestamp.

For more information, see Python client usage: DataAPITimestamp and datetimes.

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.

Python
TypeScript
Java

The Python 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.

For a quick migration from the deprecated max_time_ms parameter, replace max_time_ms with timeout_ms. When multiple parameters are available, timeout_ms is an alias to the broadest timeout setting. For example:

# Before 2.0
my_collection.insert_many(..., max_time_ms=40000)

# 2.0 and later
my_collection.insert_many(..., timeout_ms=40000)

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

from astrapy.api_options import APIOptions, TimeoutOptions

my_slow_collection = database.get_collection(
    "reports",
    spawn_api_options=APIOptions(
        timeout_options=TimeoutOptions(
            request_timeout_ms=20000,
            general_method_timeout_ms=40000,
        ),
    ),
)
my_slow_collection.insert_many(...)

You can also specify timeouts for individual method calls by passing the appropriate timeout parameters to the method. Depending on the operation type, one or more timeout parameters can be available. For example:

my_collection.insert_one(..., request_timeout_ms=12000)

my_collection.insert_many(
    ...,
    general_method_timeout_ms=40000,
    request_timeout_ms=12000,
)

my_database_admin.create_keyspace(..., keyspace_admin_timeout_ms=30000)

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

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

For a quick migration from the deprecated maxTimeMs parameter, replace maxTimeMs with timeout. For example:

// Before 2.0
await collection.insertMany(..., { maxTimeMS: 40000 });

// 2.0 and later
await collection.insertMany(..., { timeout: 40000 });

For more fine-grained control, the TypeScript 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. For more information, see TypeScript client usage: TimeoutDescriptor. For example:

const mySlowCollection = db.collection("reports", {
  timeoutDefaults: {
    requestTimeoutMs: 20000,
    generalMethodTimeoutMs: 40000,
  },
});

await collection.insertOne(..., {
  timeout: { requestTimeoutMs: 12000 },
});

await collection.insertMany(..., {
  timeout: {
    generalMethodTimeoutMs: 40000,
    requestTimeoutMs: 12000,
  },
});

await db.createKeyspace(..., { keyspaceAdminTimeoutMs: 30000 });

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

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

Python
TypeScript
Java

Previously, the list_collections() method of a Database object returned a cursor to iterate over, CommandCursor[CollectionDescriptor]. Now, the method returns a list of objects, list[CollectionDescriptor].

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

Previously, the listCollections() method of a Db object returned a promise that resolved to a list of FullCollectionInfo objects when the nameOnly option for the method was false. Now, the method returns a promise that resolves to a list of CollectionDescriptor objects.

For more information about this method, see List 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.

Updated import paths and class names (Java only)

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.

Expanded support of identifiers

The TypeScript client now supports v1 and v6 UUIDs, in addition to the previously supported v4 and v7 UUIDs. The client also now provides uuid and oid shorthand methods. For more information, see Document IDs.

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 Python and TypeScript clients no longer accept id and region when connecting to a database as of Version 1.5.
The vector and vectorize fields are no longer accepted as alternatives for $vector and $vectorize.
The bulk_write/bulkWrite client method is removed. Use a loop or other standard practice to execute multiple sequential insert operations. For examples, see Insert documents.
The deleteAll client method is replaced by the deleteMany method’s built-in support for emptying a table or collection. For examples, see Delete documents.
The checkExists/check_exists option is removed from the method to create a collection. 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.

Other additions, removals, and changes

For all changes in this release, see the client release notes:

Previous upgrade guides

Version 1.5

DataStax released clients 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:

Python
TypeScript
Java
curl

# Before 1.5
database = client.get_database("API_ENDPOINT", namespace="NAMESPACE_OR_KEYSPACE_NAME")

# 1.5 and later
database = client.get_database("API_ENDPOINT", keyspace="NAMESPACE_OR_KEYSPACE_NAME")

// Before 1.5
const db = client.db('API_ENDPOINT', { namespace: 'NAMESPACE_OR_KEYSPACE_NAME' });

// 1.5 and later
const db = client.db('API_ENDPOINT', { keyspace: 'NAMESPACE_OR_KEYSPACE_NAME' });

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

The impact to HTTP requests is minimal. HTTP already accepted either a keyspace or namespace name in the URL path, and most commands used a keyspace parameter.

curl -sS -L -X POST "ASTRA_DB_ENDPOINT/api/json/v1/NAMESPACE_OR_KEYSPACE_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{DATA_API_COMMAND_BODY}'

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.

Deprecation of `id` and `region` to specify a database

In version 1.5.1 and later of the Python and TypeScript clients, the API_ENDPOINT is the preferred way to use a DataAPIclient to get a database. The API_ENDPOINT inherently includes the database’s ID and region. As a result, the alternative ID and REGION syntax is deprecated.

Client version 2.0 removed support for this usage of ID and REGION in the Python and TypeScript clients. In version 2.0 and later, those clients accept only API_ENDPOINT when you use a DataAPIclient to get a database.

This deprecation does not apply to the following:

ID and REGION with AstraDBAdmin
The Java client
HTTP

After you upgrade to version 1.5.1 or later, change your astrapy and astra-db-ts code to use API_ENDPOINT instead of ID and REGION.

Python
TypeScript
Java
curl

Change your client.get_database commands to use API_ENDPOINT, instead of ID and REGION.

The following examples show multiple versions of the same command. An actual script would use only one.

# Before 1.5.1, the following are all valid:
database = client.get_database("API_ENDPOINT")
database = client.get_database("ID")
database = client["API_ENDPOINT"]
database = client["ID"]
database = client.get_database("API_ENDPOINT", keyspace="KEYSPACE_NAME")
database = client.get_database("ID", keyspace="KEYSPACE_NAME", region="REGION")

# At 1.5.1 and later, use only 'API_ENDPOINT':
database = client.get_database("API_ENDPOINT")
database = client["API_ENDPOINT"]
database = client.get_database("API_ENDPOINT", keyspace="KEYSPACE_NAME")

Change your client.db commands to use API_ENDPOINT, instead of ID and REGION.

The following examples show multiple versions of the same command. An actual script would use only one.

// Before 1.5.1, the following are all valid:
const db = client.db('API_ENDPOINT');
const db = client.db('ID', 'REGION');
const db = client.db('API_ENDPOINT', { keyspace: 'KEYSPACE_NAME' });
const db = client.db('ID', 'REGION', { keyspace: 'KEYSPACE_NAME' });

// At 1.5.1 and later, use only 'API_ENDPOINT':
const db = client.db('API_ENDPOINT');
const db = client.db('API_ENDPOINT', { keyspace: 'KEYSPACE_NAME' });

This deprecation does not apply to the Java client.

You can continue to use either API_ENDPOINT or ID and REGION:

// Syntax before 1.5
Database db = client.getDatabase(String apiEndpoint);
Database db = client.getDatabase(UUID databaseId, String region);
Database db = client.getDatabase(String apiEndpoint, String keyspace);
Database db = client.getDatabase(UUID databaseId, String region, String keyspace);

// Syntax slightly different after 1.5 (keyspace is now an option)
Database db = client.getDatabase(String apiEndpoint, DatabaseOptions options);
Database db = client.getDatabase(UUID databaseId, DatabaseOptions options);
Database db = client.getDatabase(UUID databaseId, String region, DatabaseOptions options);

This deprecation does not apply to HTTP, which already exclusively uses the API endpoint as the basis of the URL path, such as:

curl -sS -L -X POST "ASTRA_DB_ENDPOINT/api/json/v1/KEYSPACE_NAME"

Data API client upgrade guide

Version 2.0

Support for tables

Improved support for vector data

Support for hybrid search

Java 17 or later required (Java only)

Breaking change to create collection (Python and Java only)

Stricter handling of timestamps and datetimes (Python only)

Replacement of client timeout settings

New response when listing collection metadata

Updated import paths and class names (Java only)

No `distinct` method on cursors

Expanded support of identifiers

Removals

Other additions, removals, and changes

Previous upgrade guides

Version 1.5

Deprecation of `namespace`

Deprecation of `id` and `region` to specify a database

See also

Was this helpful?

Give Feedback

Data API client upgrade guide

Version 1.5

Deprecation of namespace

Deprecation of id and region to specify a database

Was this helpful?

Deprecation of `namespace`

Deprecation of `id` and `region` to specify a database