Cassandra Query Language (CQL) for Astra DB
Because Astra DB is powered by Apache Cassandra®, you can send Cassandra Query Language (CQL) statements to your Astra DB Serverless databases with the CQL shell (cqlsh), Cassandra drivers, or the Data API.
To use CQL for Astra DB, you need an active Astra DB Serverless database with a keyspace. Familiarity with CQL is helpful but not required.
For more information about CQL for Astra DB, including command examples and specifications, see the CQL for Astra DB reference.
Limitations on CQL for Astra DB
To ensure high availability and optimum performance, Astra DB Serverless databases have guardrails on underlying Cassandra functionality, including commands and functionality available through CQL for Astra DB.
Keyspace, table, and column names are case sensitive
If you create a table in the Astra Portal, the table name, keyspace name, and column names become case-sensitive. Make sure your CQL commands use case sensitivity for these values. For more information, see How do I fix a "table does not exist" error in CQL.
Unsupported values are ignored
If you pass a CQL statement with unsupported data definition language (DDL) properties, the statement is executed without the unsupported values. Astra DB ignores the unsupported values and throws a warning.
For example, the following command creates a table with the given schema, and it attempts to pass an additional nodesync property:
CREATE TABLE IF NOT EXISTS library.books
(
id UUID PRIMARY KEY,
lastname text,
firstname text)
WITH nodesync={'enabled': 'true'};If you execute this statement against an Astra DB database, the table is created but the nodesync property is ignored.
The response includes a warning with the ignored unsupported values:
Warnings :
Ignoring provided values [nodesync] as they are not supported for Table
Properties(ignored values are: [additional_write_policy,
bloom_filter_fp_chance, caching, cdc, compaction, compression,
crc_check_chance, dse_edge_label_property, dse_vertex_label_property,
gc_grace_seconds, id, max_index_interval, memtable,
memtable_flush_period_in_ms, min_index_interval, nodesync, read_repair,
speculative_retry])Limited support for user-defined objects
CQL for Astra DB supports user-defined type (UDTs). It doesn’t support user-defined functions (UDFs) or user-defined aggregate functions (UDAs).
Unsupported CQL commands
CQL for Astra DB doesn’t support operations on the following:
-
Access control
-
DSE Search indexes
-
Keyspaces (except
DESCRIBE KEYSPACE) -
Materialized views (MVs)
-
Triggers
-
UDAs
-
UDFs
List of CQL commands that aren’t supported for Astra DB
-
CREATE KEYSPACE -
ALTER KEYSPACE -
DROP KEYSPACE -
CREATE MATERIALIZED VIEW -
ALTER MATERIALIZED VIEW -
DROP MATERIALIZED VIEW -
CREATE AGGREGATE -
DESCRIBE AGGREGATE -
DROP AGGREGATE -
CREATE FUNCTION -
DESCRIBE FUNCTION -
DROP FUNCTION -
CREATE TRIGGER -
DROP TRIGGER -
CREATE ROLE -
GRANT ROLE -
ALTER ROLE -
REVOKE ROLE -
DROP ROLE -
LIST ROLES -
GRANT PERMISSION -
LIST PERMISSIONS -
REVOKE PERMISSION -
RESTRICT -
RESTRICT ROWS -
UNRESTRICT -
UNRESTRICT ROWS -
CREATE SEARCH INDEX -
COMMIT SEARCH INDEX -
REBUILD SEARCH INDEX -
RELOAD SEARCH INDEX -
ALTER SEARCH INDEX SCHEMA -
ALTER SEARCH INDEX CONFIG -
DROP SEARCH INDEX CONFIG
For information about keyspaces and access control in Astra, see Manage keyspaces and Manage roles and permissions.
For a list of supported CQL commands, see the CQL for Astra DB quick reference.
Execute CQL statements
To run CQL statements against your Astra DB Serverless databases, you can use the CQL shell, a Cassandra driver, or the Data API.
Data API and clients
You can use the Data API and clients to manage tables in Serverless (vector) databases, including tables you previously created with cqlsh or a driver.
For more information, see Get started with the Data API and About tables with the Data API.
Drivers
Astra DB Serverless is compatible with the following Cassandra drivers:
| Language | Driver | Version | Documentation |
|---|---|---|---|
C++ |
|||
C# |
|||
Go |
|||
Java |
|||
Node.js |
|||
Python |
|||
Scala |
Connect to Astra DB Serverless with the Apache Cassandra Spark Connector |
For more information, see Connect to a database: Drivers.
CQL shell (cqlsh)
The CQL shell (cqlsh) is a utility that you can use to issue CQL and cqlsh commands to your Astra DB Serverless databases.
You can use the CQL console in the Astra Portal, or you can install the CQL shell utility with the Astra CLI.
-
CQL console (embedded CQL shell)
-
Standalone CQL shell
In the Astra Portal, each Astra DB Serverless database has access to the CQL console, which is an embedded CQL shell instance.
You can use the CQL console to run CQL and cqlsh commands on your databases directly from your browser without installing any additional software.
-
In the Astra Portal, click the name of the database that you want to access.
-
Click CQL console to open the embedded CQL shell in a new tab.
-
Wait for the
token@cqlsh>prompt to appear.This prompt indicates that CQL shell is connected to your database, and you can start sending CQL and
cqlshcommands to your database. -
Optional: For multi-region databases, use the region menu to access data from a secondary region. However, due to Astra DB’s eventual consistency model, changes to data in any region are eventually replicated to the database’s other regions. Typically, you change regions only if the primary region is geographically distant from your machine.
The standalone CQL shell is a lightweight, command-line utility that you can use to send CQL and cqlsh commands to your Astra DB Serverless databases.
Use the Astra CLI to download, install, and use the standalone CQL shell utility:
CQL for Astra DB documentation and examples
For more information about CQL, see the following:
