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.

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.

Method to list index metadata

A method to list index metadata was added. For more information, see List index metadata (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.

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

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

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

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