Data API client upgrade guide (TypeScript)

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

Method to list index metadata

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

Method to find available regions

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

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

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.

Breaking changes to create collection

The createCollection() method includes the following breaking changes:

The checkExists 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 namespace parameter alias is removed. Use keyspace instead.
The maxTimeMS and defaultMaxTimeMS parameters are removed. Use timeout and timeoutDefaults instead.

For examples, see Create a collection (TypeScript).

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 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 internals: 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.

New response when listing 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 (TypeScript).

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 TypeScript client no longer accepts 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 bulkWrite client method is removed. Use a loop or other standard practice to execute multiple sequential insert operations. For examples, see Insert documents (TypeScript).
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 (TypeScript).
The checkExists 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).

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:

// 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' });

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 TypeScript 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 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 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.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' });