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 | Version | Dependency | Documentation |
---|---|---|---|---|
Python |
Python 3.8 or later |
|||
TypeScript |
Node.js 18 or later |
|||
Java |
Java 17 or later (21 recommended) |
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]);
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 Custom Ser/Des.
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 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. Usekeyspace
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 thecollection_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 returnedCollection
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. Usekeyspace
instead. -
There is a new
createCollectionOptions
parameter. This parameter allows arbitrary customization of the returnedCollection
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,
},
});
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:
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 bykeyspace
as of Version 1.5. -
The Python and TypeScript clients no longer accept
id
andregion
when connecting to a database as of Version 1.5. -
The
vector
andvectorize
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 thedeleteMany
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
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 |
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 This deprecation does not apply to the following:
|
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"