Data API client upgrade guide (Python)

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.

Change to supported Python versions

The Python client no longer supports Python version 3.9. Python versions 3.10 to 3.14 are supported.

Dropped `region_name`

The deprecated region_name alias for name was removed from the AstraDBAdminDatabaseRegionInfo and AstraDBAvailableRegionInfo classes

Renamed methods

Several methods of the fluent interface for CollectionDefinition were renamed:

set_default_id renamed to with_default_id
set_vector_dimension renamed to with_vector_dimension
set_vector_metric renamed to with_vector_metric
set_vector_source_model renamed to with_vector_source_model
set_vector_service renamed to with_vector_service
set_rerank renamed to with_rerank
set_lexical renamed to with_lexical

The set_* methods remain as deprecated aliases and will be removed in a future release.

Previous upgrade guides

The following information is for earlier client releases.

Version 2.2

DataStax released version 2.2 in March 2026.

Change to supported Python versions

The Python client now supports Python version 3.9 to 3.14.

REPL

The Python client introduced an astrapy-repl command for a ready-to-use interactive python shell (REPL). The REPL automatically imports astrapy symbols and generates client and database variables.

For more information, run astrapy-repl -h.

Event observer API

The Python client introduced an API to listen to events. This API complements standard logging and provides an alternative way to monitor events. You can use the API to enable custom logging and monitoring of Data API interactions.

For more information, see the astrapy.event_observers module.

Version 2.1

DataStax released version 2.1 in September 2025.

Method to list index metadata

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

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 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 Vector type (Python).

Breaking changes to create collection

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

Stricter handling of timestamps and datetimes

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

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.

New response when listing collection metadata

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

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 Python client no longer accepts id and region when connecting to a database as of Version 1.5.
The vector field is no longer accepted as an alternative for $vector.
The bulk_write client method is removed. Use a loop or other standard practice to execute multiple sequential insert operations. For examples, see Insert documents (Python).
The delete_all client method is replaced by the deletemany method’s built-in support for emptying a table or collection. For examples, see Delete documents (Python).
The 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.

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:

# 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")

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.

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

In version 1.5.1 and later of the Python client, 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 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 ID and REGION with AstraDBAdmin.

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

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

Data API client upgrade guide (Python)

Version 2.3

Change to supported Python versions

Dropped `region_name`

Renamed methods

Previous upgrade guides

Version 2.2

Change to supported Python versions

REPL

Event observer API

Version 2.1

Method to list index metadata

Version 2.0

Support for tables

Improved support for vector data

Breaking changes to create collection

Stricter handling of timestamps and datetimes

Replacement of client timeout settings

New response when listing collection metadata

No `distinct` method on cursors

Removals

Version 1.5

Deprecation of `namespace`

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

Was this helpful?

Give Feedback