Migrate to the Data API from CQL

You can use the Data API to manage CQL tables in Serverless (Vector) databases.

To help you migrate your application code to the Data API from a CQL-based approach, such as a Apache Cassandra® driver, this page summarizes the differences between the Data API and CQL.

The Data API doesn’t accept raw CQL statements

Cassandra drivers and other CQL-focused interfaces often require you to pass CQL statements in your application code.

In contrast, the Data API doesn’t accept raw CQL statements. Instead, your application sends Data API commands that are expressed in JSON format or invoked through a client library. These commands are then converted to CQL statements on the server side.

If your application code currently passes raw CQL statements, you must convert these statements to Data API commands as part of your migration to the Data API.

For a mapping of CQL commands to Data API commands, see Supported CQL commands in the Data API.

Unsupported CQL functionality in the Data API

The Data API supports a subset of CQL functionality that covers common use cases for managing CQL tables. However, it doesn’t support all CQL commands, arguments, objects, or types:

All limitations on CQL for Astra DB also apply to the Data API.
BATCH isn’t supported.
IF (LWTs) aren’t supported.
Aggregates aren’t supported, including built-in aggregates, such as COUNT, and user-defined aggregates.
Certain types, formats, and modifiers described in CQL types in the Data API.

Some unsupported types and modifiers are partially supported if they are present in existing CQL tables. For more information, see Support for existing tables with unsupported types.

If you cannot modify your data and code to avoid or accommodate unsupported functionality, then you cannot use the Data API.

Supported CQL commands in the Data API

The following table maps CQL commands to their corresponding Data API commands. To learn how to run these commands with the Data API, follow the links in the Data API command column.

CQL command Data API command

CQL command	Data API command
`ALTER TABLE`	Alter a table
`CREATE INDEX`	Create an index and Create a vector index
`CREATE KEYSPACE`	Create a keyspace
`CREATE TABLE`	Create a table
`DELETE COLUMN FROM`	Update a row
`DELETE FROM`	Delete a row and Delete rows
`DESCRIBE INDEX` (from `cqlsh`)	List index metadata and List index names
`DESCRIBE KEYSPACE` (from `cqlsh`)	List keyspaces
`DESCRIBE TABLE` (from `cqlsh`)	List table metadata and List table names
`DROP INDEX`	Drop an index
`DROP KEYSPACE`	Drop a keyspace
`DROP TABLE`	Drop a table
`INSERT`	Insert a row and Insert rows
`SELECT`	Find a row, Find rows, and Find distinct values
`TRUNCATE`	Delete rows
`UPDATE`	Update a row
`USE`	The Data API doesn’t provide an explicit command for this. Instead, the target table is specified in the Data API request path for HTTP requests, or by options passed to the Data API clients.

ALTER TABLE

Alter a table

CREATE INDEX

Create an index and Create a vector index

CREATE KEYSPACE

Create a keyspace

CREATE TABLE

Create a table

DELETE COLUMN FROM

Update a row

DELETE FROM

Delete a row and Delete rows

DESCRIBE INDEX (from cqlsh)

List index metadata and List index names

DESCRIBE KEYSPACE (from cqlsh)

List keyspaces

DESCRIBE TABLE (from cqlsh)

List table metadata and List table names

DROP INDEX

Drop an index

DROP KEYSPACE

Drop a keyspace

DROP TABLE

Drop a table

INSERT

Insert a row and Insert rows

SELECT

Find a row, Find rows, and Find distinct values

TRUNCATE

Delete rows

UPDATE

Update a row

USE

The Data API doesn’t provide an explicit command for this. Instead, the target table is specified in the Data API request path for HTTP requests, or by options passed to the Data API clients.

CQL types in the Data API

For supported types, see Data types in tables.

Unsupported types, formats, and modifiers include:

User-defined types (UDTs)
Time To Live (TTL)
Column timestamps
Frozen
Static
Tuple

The following types have limited support:

If you are working with an existing CQL table that contains unsupported types, see the following information about how the Data API handles unsupported types.

Responses containing unsupported types

Unsupported types are flagged in Data API responses that contain table definitions, such as listTables. For example, the following partial response indicates that a tuple column is unsupported. The response includes the original CQL definition and the actions that are unavailable through the Data API. In this case, you cannot create tuple columns, read or write from existing tuple columns, or use the column in a search filter clause.

"column_name": {
  "type": "UNSUPPORTED",
  "apiSupport": {
    "createTable": false,
    "insert": false,
    "read": false,
    "filter": false,
    "cqlDefinition": "frozen<tuple<text, text, int>>"
  }
}

Support for existing tables with unsupported types

You can use the Data API to manage existing CQL tables. The following restrictions apply when working with unsupported CQL types in existing tables:

TTL is read-only. However, reading data that has a TTL on it can have unexpected results, such as reads returning different data when the TTL expires.
You can read, write, and filter existing static columns, but DataStax does not recommend modifying static columns with the Data API.

Using the Data API to update an existing static column can have unexpected results. If you require static columns, DataStax recommends using CQL instead of the Data API.
Frozen scalar columns are read-only. Frozen map, list, and set columns are not accessible through the Data API.
You cannot create timeuuid columns, but you can use the Data API to manage values in timeuuid columns. For more information, see UUID types.
You cannot create varchar columns, but you can use the Data API to manage values in varchar columns. For more information, see Other scalar types.

For information about other CQL limitations in the Data API, see Unsupported CQL functionality in the Data API.