Cassandra Query Language (CQL) for Astra DB

Because Astra DB Serverless is powered by Apache Cassandra®, you can send Cassandra Query Language (CQL) queries to your Astra DB Serverless databases with the CQL shell (cqlsh) or Cassandra drivers.

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.

CQL for Astra DB limitations

To ensure high availability and optimum performance, Astra DB Serverless databases have guardrails on underlying Apache Cassandra® functionality, including commands and functionality available through CQL for Astra DB.

User-defined types aren’t supported

CQL for Astra DB does not support user-defined functions (UDFs) or user-defined aggregate functions (UDAs).

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

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 CQL commands

Operations concerning keyspaces, materialized views, functions, aggregates, and search indexes are generally not supported. As a result, the following CQL commands aren’t supported for Astra DB:

CQL commands not 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

  • ALTER ROLE

  • DROP ROLE

  • LIST ROLES

  • LIST PERMISSIONS

  • 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 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 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 created through the CQL shell or a driver. For more information, see Get started with the Data API and About tables with the Data API.

Drivers

Astra DB is compatible with the following drivers:

Language Driver Version Documentation

C++

cpp-driver

Latest cpp-driver release on GitHub

Connect with the C++ driver

C#

csharp-driver

Latest CassandraCSharpDriver release on NuGet

Connect with the C# driver

Go

gocql-astra (with cassandra-gocql-driver)

Latest gocql release on GitHub

Connect with the Go driver

Java

cassandra-java-driver

Latest cassandra-java-driver release on GitHub

Connect with the Java driver

Node.js

nodejs-driver

Latest nodejs-driver release on GitHub

Connect with the Node.js driver

Python

python-driver

Latest python-driver release on GitHub

Connect with the Python driver

Scala

cassandra-spark-connector

Latest cassandra-spark-connector release on GitHub

Connect to Astra DB Serverless with the Apache Cassandra Spark connector

For more information, see Connect to a database: Drivers.

CQL shell

The Cassandra Query Language Shell (cqlsh) is a utility that you can use to issue CQL commands to your Astra DB Serverless database. You can use the embedded CQL shell in the Astra Portal or the standalone CQL shell.

  • Embedded CQL shell

  • Standalone CQL shell

The Astra Portal provides an embedded CQL shell instance, known as the CQL Console, for each Astra DB Serverless database. You can use the CQL Console to run CQL commands on your databases directly from your browser.

  1. In the Astra Portal navigation menu, click Databases, and then click the name of the database that you want to access.

  2. Click CQL Console to open the CQL Console in a new tab.

  3. Wait for the token@cqlsh> prompt to appear.

    This prompt indicates that the CQL Console is connected to your database, and you can begin issuing CQL commands to your database.

  4. Optional: For multi-region databases, you can 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.

The standalone CQL shell is a separate, lightweight utility that you can use to interact with your database.

You can use the Astra CLI to download and configure the standalone CQL shell, including the Secure Connect Bundle (SCB) and an application token for your database. For more information, see Use cqlsh in the Astra CLI documentation.

  1. Install Python version 2.7.12 or later with TLS support.

  2. Download the SCB for your database.

    For multi-region databases, if you want to access data from a secondary region, you must download the SCB for that specific 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.

  3. Download the CQL shell for your Astra DB Serverless database:

    • DataStax Astra

    • DataStax Astra with support for Vector Type.

  4. Change to the directory where you downloaded the CQL shell package:

    $ cd /DOWNLOAD_DIRECTORY

  5. Extract the files:

    $ tar -xvf cqlsh-astra-DATE-bin.tar.gz

    Replace DATE with the package release date, such as 20210304.

  6. Run the cqlsh script:

    cd /cqlsh-astra
./bin/cqlsh -u CLIENT_ID -p CLIENT_SECRET -b PATH_TO_SCB

    Replace the following:

    • PATH_TO_SCB: The path to your database’s SCB zip file

    • CLIENT_ID and CLIENT_SECRET: Either of the following sets of values from your application token:

      • The clientId value and the secret value

      • The literal string token and the token secret, prefixed by AstraCS:

    Optional: Store credentials in the cqlshrc file

    If you don’t want to pass the credentials on the command line every time, you can configure the location in your cqlshrc file:

    1. In the ~/.cassandra directory, open the cqlshrc file.

    2. In the [authentication] section, add the CLIENT_ID and CLIENT_SECRET values from your application token.

    3. In the [connection] section, add the path to the SCB.

    [authentication]
username = CLIENT_ID # or the literal string token
password = CLIENT_SECRET # or the token secret prefixed by 'AstraCS:'

[connection]
secure_connect_bundle = PATH_TO_SCB

  7. Make sure the command returns output indicating that you connected to your database. For example:

    [cqlsh 6.8.0 | DSE 6.8.0.77 | CQL spec 3.4.5 | DSE protocol v2]
Use HELP for help.
username@cqlsh>

CQL for Astra DB documentation and examples

For general information about CQL, including CQL for Astra DB, see the following:

Use Storage-Attached Indexing (SAI)

Run a vector search with CQL

Use analyzers with CQL for Astra DB

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2025 DataStax | Privacy policy | Terms of use | Manage Privacy Choices

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: +1 (650) 389-6000, info@datastax.com