ScyllaDB University LIVE, FREE Virtual Training Event | March 21
Register for Free
ScyllaDB Documentation Logo Documentation
  • Server
  • Cloud
  • Tools
    • ScyllaDB Manager
    • ScyllaDB Monitoring Stack
    • ScyllaDB Operator
  • Drivers
    • CQL Drivers
    • DynamoDB Drivers
  • Resources
    • ScyllaDB University
    • Community Forum
    • Tutorials
Download
ScyllaDB Docs ScyllaDB Enterprise CQL Reference Definitions

Caution

You're viewing documentation for a previous version. Switch to the latest stable version.

Definitions¶

Conventions¶

To aid in specifying the CQL syntax, we will use the following conventions in this document:

  • Language rules will be given in an informal BNF variant notation. In particular, we’ll use square brackets ([ item ]) for optional items, * and + for repeated items (where + imply at least one).

  • The grammar will also use the following convention for convenience: non-terminal term will be lowercase (and link to their definition) while terminal keywords will be provided “all caps”. Note, however, that keywords are Identifiers and keywords and are thus case insensitive in practice. We will also define some early construction using regexp, which we’ll indicate with re(<some regular expression>).

  • The grammar is provided for documentation purposes and leaves some minor details out. For instance, the comma on the last column definition in a CREATE TABLE statement is optional but supported if present even though the grammar in this document suggests otherwise. Also, not everything accepted by the grammar is necessarily valid CQL.

  • References to keywords or pieces of CQL code in running text will be shown in a fixed-width font.

Identifiers and keywords¶

The CQL language uses identifiers (or names) to identify tables, columns, and other objects. An identifier is a token matching the regular expression [a-zA-Z][a-zA-Z0-9_]*.

A number of such identifiers, like SELECT or WITH, are keywords. They have a fixed meaning for the language, and most are reserved. The list of those keywords can be found in Appendix A: CQL Keywords.

Identifiers and (unquoted) keywords are case insensitive. Thus SELECT is the same as select or sElEcT, and myId is the same than myid or MYID. A convention often used (in particular by the samples of this documentation) is to use upper case for keywords and lower case for other identifiers.

There is a second kind of identifier called quoted identifiers, defined by enclosing an arbitrary sequence of characters (non-empty) in double-quotes("). Quoted identifiers are never keywords. Thus "select" is not a reserved keyword and can be used to refer to a column (note that using this is particularly advised), while select would raise a parsing error. Also, contrary to unquoted identifiers and keywords, quoted identifiers are case sensitive ("My Quoted Id" is different from "my quoted id"). A fully lowercase quoted identifier that matches [a-zA-Z][a-zA-Z0-9_]* is, however, equivalent to the unquoted identifier obtained by removing the double-quote (so "myid" is equivalent to myid and to myId but different from "myId"). Inside a quoted identifier, the double-quote character can be repeated to escape it, so "foo "" bar" is a valid identifier.

Note

quoted identifiers allow to declare columns with arbitrary names, and those can sometimes clash with specific names used by the server. For instance, when using a conditional update, the server will respond with a result-set containing a special result named "[applied]". If you’ve declared a column with such a name, this could potentially confuse some tools and should be avoided. In general, unquoted identifiers should be preferred, but if you use quoted identifiers, it is strongly advised to avoid any name enclosed by squared brackets (like "[applied]") and any name that looks like a function call (like "f(x)").

More formally, we have:

identifier: `unquoted_identifier` | `quoted_identifier`
unquoted_identifier: re('[a-zA-Z][a-zA-Z0-9_]*')
quoted_identifier: '"' (any character where " can appear if doubled)+ '"'

Constants¶

CQL defines the following kind of constants:

constant: `string` | `integer` | `float` | `boolean` | `uuid` | `blob` | NULL

string: '\'' (any character where ' can appear if doubled)+ '\''
      : '$$' (any character other than '$$') '$$'

integer: re('-?[0-9]+')

float: re('-?[0-9]+(\.[0-9]*)?([eE][+-]?[0-9+])?') | NAN | INFINITY

boolean: TRUE | FALSE

uuid: `hex`{8}-`hex`{4}-`hex`{4}-`hex`{4}-`hex`{12}

hex: re("[0-9a-fA-F]")

blob: '0' ('x' | 'X') `hex`+

In other words:

  • A string constant is an arbitrary sequence of characters enclosed by single-quote('). A single-quote can be included by repeating it, e.g. 'It''s raining today'. Those are not to be confused with quoted Identifiers and keywords that use double-quotes. Alternatively, a string can be defined by enclosing the arbitrary sequence of characters by two dollar characters, in which case single-quote can be used without escaping ($$It's raining today$$). That latter form is often used when defining user-defined functions to avoid having to escape single-quote characters in function body (as they are more likely to occur than $$).

  • Integer, float, and boolean constant are defined as expected. Note, however, than float allows the special NaN and Infinity constants.

  • CQL supports UUID constants.

  • Blob content types are provided in hexadecimal and prefixed by 0x.

  • The special NULL constant denotes the absence of value.

For how these constants are typed, see the data-types document.

Terms¶

CQL has the notion of a term, which denotes the kind of values that CQL support. Terms are defined by:

term: `constant` | `literal` | `function_call` | `arithmetic_operation` | `type_hint` | `bind_marker`

literal: `collection_literal` | `udt_literal` | `tuple_literal`

function_call: `identifier` '(' [ `term` (',' `term`)* ] ')'

arithmetic_operation: '-' `term` | `term` ('+' | '-' | '*' | '/' | '%') `term`

type_hint: '(' `cql_type` `)` term

bind_marker: '?' | ':' `identifier`

A term is thus one of:

  • A constant.

  • A literal for either a collection (including usage of list_or_vector_literal for a vector), a user-defined type or a tuple (see the linked sections for details).

  • An arithmetic operation between terms.

  • A type hint

  • A bind marker, which denotes a variable to be bound at execution time. See the section on Prepared Statements for details. A bind marker can be either anonymous (?) or named (:some_name). The latter form provides a more convenient way to refer to the variable for binding it and should generally be preferred.

Comments¶

A comment in CQL is a line beginning by either double dashes (--) or double slash (//).

Multi-line comments are also supported through enclosure within /* and */ (but nesting is not supported).

-- This is a comment
// This is a comment too
/* This is
   a multi-line comment */

Statements¶

CQL consists of statements that can be divided into the following categories:

  • Data Definition statements - to define and change how the data is stored (keyspaces and tables).

  • Data Manipulation statements - for selecting, inserting and deleting data.

  • Permissions statements.

  • cql-triggers statements.

All the statements are listed below and are described in the rest of this documentation (see links above):

cql_statement: `statement` [ ';' ]
statement: `ddl_statement`
         : | `dml_statement`
         : | `secondary_index_statement`
         : | `materialized_view_statement`
         : | `role_or_permission_statement`
         : | `udf_statement`
         : | `udt_statement`
         : | `trigger_statement`
ddl_statement: `use_statement`
             : | `create_keyspace_statement`
             : | `alter_keyspace_statement`
             : | `drop_keyspace_statement`
             : | `create_table_statement`
             : | `alter_table_statement`
             : | `drop_table_statement`
             : | `truncate_statement`
 dml_statement: `select_statement`
              : | `insert_statement`
              : | `update_statement`
              : | `delete_statement`
              : | `batch_statement`
 trigger_statement: `create_trigger_statement`
                  : | `drop_trigger_statement`

Prepared Statements¶

CQL supports prepared statements. Prepared statements are an optimization that allows parsing a query only once but executes it multiple times with different concrete values.

Any statement that uses at least one bind marker (see bind_marker) will need to be prepared. After which, the statement can be executed by provided concrete values for each of its markers. The exact details of how a statement is prepared and then executed depends on the CQL driver used, and you should refer to your driver documentation.

© 2016, The Apache Software Foundation.

Apache Cassandra Query Language

Was this page helpful?

PREVIOUS
Data Types
NEXT
Global Secondary Indexes
  • Create an issue

On this page

  • Definitions
    • Conventions
    • Identifiers and keywords
    • Constants
    • Terms
    • Comments
    • Statements
    • Prepared Statements
ScyllaDB Enterprise
  • enterprise
    • 2024.2
    • 2024.1
    • 2023.1
    • 2022.2
  • Getting Started
    • Install ScyllaDB Enterprise
      • ScyllaDB Web Installer for Linux
      • Install ScyllaDB Without root Privileges
      • Install scylla-jmx Package
      • Air-gapped Server Installation
      • ScyllaDB Housekeeping and how to disable it
      • ScyllaDB Developer Mode
      • Launch ScyllaDB on AWS
      • Launch ScyllaDB on GCP
      • Launch ScyllaDB on Azure
    • Configure ScyllaDB
    • ScyllaDB Configuration Reference
    • ScyllaDB Requirements
      • System Requirements
      • OS Support
      • Cloud Instance Recommendations
      • ScyllaDB in a Shared Environment
    • Migrate to ScyllaDB
      • Migration Process from Cassandra to ScyllaDB
      • ScyllaDB and Apache Cassandra Compatibility
      • Migration Tools Overview
    • Integration Solutions
      • Integrate ScyllaDB with Spark
      • Integrate ScyllaDB with KairosDB
      • Integrate ScyllaDB with Presto
      • Integrate ScyllaDB with Elasticsearch
      • Integrate ScyllaDB with Kubernetes
      • Integrate ScyllaDB with the JanusGraph Graph Data System
      • Integrate ScyllaDB with DataDog
      • Integrate ScyllaDB with Kafka
      • Integrate ScyllaDB with IOTA Chronicle
      • Integrate ScyllaDB with Spring
      • Shard-Aware Kafka Connector for ScyllaDB
      • Install ScyllaDB with Ansible
      • Integrate ScyllaDB with Databricks
      • Integrate ScyllaDB with Jaeger Server
      • Integrate ScyllaDB with MindsDB
    • Tutorials
  • ScyllaDB for Administrators
    • Administration Guide
    • Procedures
      • Cluster Management
      • Backup & Restore
      • Change Configuration
      • Maintenance
      • Best Practices
      • Benchmarking ScyllaDB
      • Migrate from Cassandra to ScyllaDB
      • Disable Housekeeping
    • Security
      • ScyllaDB Security Checklist
      • Enable Authentication
      • Enable and Disable Authentication Without Downtime
      • Creating a Custom Superuser
      • Generate a cqlshrc File
      • Reset Authenticator Password
      • Enable Authorization
      • Grant Authorization CQL Reference
      • Certificate-based Authentication
      • Role Based Access Control (RBAC)
      • ScyllaDB Auditing Guide
      • Encryption: Data in Transit Client to Node
      • Encryption: Data in Transit Node to Node
      • Generating a self-signed Certificate Chain Using openssl
      • Configure SaslauthdAuthenticator
      • Encryption at Rest
      • LDAP Authentication
      • LDAP Authorization (Role Management)
      • Software Bill Of Materials (SBOM)
    • Admin Tools
      • Nodetool Reference
      • CQLSh
      • Admin REST API
      • Tracing
      • ScyllaDB SStable
      • ScyllaDB Types
      • SSTableLoader
      • cassandra-stress
      • SSTabledump
      • SSTableMetadata
      • ScyllaDB Logs
      • Seastar Perftune
      • Virtual Tables
      • Reading mutation fragments
      • Maintenance socket
      • Maintenance mode
      • Task manager
    • Version Support Policy
    • ScyllaDB Monitoring Stack
    • ScyllaDB Operator
    • ScyllaDB Manager
    • Upgrade Procedures
      • About Upgrade
      • Upgrade Guides
    • System Configuration
      • System Configuration Guide
      • scylla.yaml
      • ScyllaDB Snitches
    • Benchmarking ScyllaDB
    • ScyllaDB Diagnostic Tools
  • ScyllaDB for Developers
    • Develop with ScyllaDB
    • Tutorials and Example Projects
    • Learn to Use ScyllaDB
    • ScyllaDB Alternator
    • ScyllaDB Drivers
      • ScyllaDB CQL Drivers
      • ScyllaDB DynamoDB Drivers
  • CQL Reference
    • CQLSh: the CQL shell
    • Appendices
    • Compaction
    • Consistency Levels
    • Consistency Level Calculator
    • Data Definition
    • Data Manipulation
      • SELECT
      • INSERT
      • UPDATE
      • DELETE
      • BATCH
    • Data Types
    • Definitions
    • Global Secondary Indexes
    • Expiring Data with Time to Live (TTL)
    • Functions
    • Wasm support for user-defined functions
    • JSON Support
    • Materialized Views
    • Non-Reserved CQL Keywords
    • Reserved CQL Keywords
    • DESCRIBE SCHEMA
    • Service Levels
    • ScyllaDB CQL Extensions
  • Features
    • Lightweight Transactions
    • Global Secondary Indexes
    • Local Secondary Indexes
    • Materialized Views
    • Counters
    • Change Data Capture
      • CDC Overview
      • The CDC Log Table
      • Basic operations in CDC
      • CDC Streams
      • CDC Stream Generations
      • Querying CDC Streams
      • Advanced column types
      • Preimages and postimages
      • Data Consistency in CDC
    • Workload Attributes
    • Workload Prioritization
  • ScyllaDB Architecture
    • Data Distribution with Tablets
    • ScyllaDB Ring Architecture
    • ScyllaDB Fault Tolerance
    • Consistency Level Console Demo
    • ScyllaDB Anti-Entropy
      • ScyllaDB Hinted Handoff
      • ScyllaDB Read Repair
      • ScyllaDB Repair
    • SSTable
      • ScyllaDB SSTable - 2.x
      • ScyllaDB SSTable - 3.x
    • Compaction Strategies
    • Raft Consensus Algorithm in ScyllaDB
    • Zero-token Nodes
  • Troubleshooting ScyllaDB
    • Errors and Support
      • Report a ScyllaDB problem
      • Error Messages
      • Change Log Level
    • ScyllaDB Startup
      • Ownership Problems
      • ScyllaDB will not Start
      • ScyllaDB Python Script broken
    • Upgrade
      • Inaccessible configuration files after ScyllaDB upgrade
    • Cluster and Node
      • Handling Node Failures
      • Failure to Add, Remove, or Replace a Node
      • Failed Decommission Problem
      • Cluster Timeouts
      • Node Joined With No Data
      • NullPointerException
      • Failed Schema Sync
    • Data Modeling
      • ScyllaDB Large Partitions Table
      • ScyllaDB Large Rows and Cells Table
      • Large Partitions Hunting
      • Failure to Update the Schema
    • Data Storage and SSTables
      • Space Utilization Increasing
      • Disk Space is not Reclaimed
      • SSTable Corruption Problem
      • Pointless Compactions
      • Limiting Compaction
    • CQL
      • Time Range Query Fails
      • COPY FROM Fails
      • CQL Connection Table
    • ScyllaDB Monitor and Manager
      • Manager and Monitoring integration
      • Manager lists healthy nodes as down
    • Installation and Removal
      • Removing ScyllaDB on Ubuntu breaks system packages
  • Knowledge Base
    • Upgrading from experimental CDC
    • Compaction
    • Consistency in ScyllaDB
    • Counting all rows in a table is slow
    • CQL Query Does Not Display Entire Result Set
    • When CQLSh query returns partial results with followed by “More”
    • Run ScyllaDB and supporting services as a custom user:group
    • Customizing CPUSET
    • Decoding Stack Traces
    • Snapshots and Disk Utilization
    • DPDK mode
    • Debug your database with Flame Graphs
    • Efficient Tombstone Garbage Collection in ICS
    • How to Change gc_grace_seconds for a Table
    • Gossip in ScyllaDB
    • Increase Permission Cache to Avoid Non-paged Queries
    • How does ScyllaDB LWT Differ from Apache Cassandra ?
    • Map CPUs to ScyllaDB Shards
    • ScyllaDB Memory Usage
    • NTP Configuration for ScyllaDB
    • Updating the Mode in perftune.yaml After a ScyllaDB Upgrade
    • POSIX networking for ScyllaDB
    • ScyllaDB consistency quiz for administrators
    • Recreate RAID devices
    • How to Safely Increase the Replication Factor
    • ScyllaDB and Spark integration
    • Increase ScyllaDB resource limits over systemd
    • ScyllaDB Seed Nodes
    • How to Set up a Swap Space
    • ScyllaDB Snapshots
    • ScyllaDB payload sent duplicated static columns
    • Stopping a local repair
    • System Limits
    • How to flush old tombstones from a table
    • Time to Live (TTL) and Compaction
    • ScyllaDB Nodes are Unresponsive
    • Update a Primary Key
    • Using the perf utility with ScyllaDB
    • Configure ScyllaDB Networking with Multiple NIC/IP Combinations
  • Reference
    • AWS Images
    • Azure Images
    • GCP Images
    • Configuration Parameters
    • Glossary
    • Limits
    • ScyllaDB Enterprise vs. Open Source Matrix
    • API Reference (BETA)
    • Metrics (BETA)
  • ScyllaDB University
  • ScyllaDB FAQ
  • Alternator: DynamoDB API in Scylla
    • Getting Started With ScyllaDB Alternator
    • ScyllaDB Alternator for DynamoDB users
    • Alternator-specific APIs
Docs Tutorials University Contact Us About Us
© 2025, ScyllaDB. All rights reserved. | Terms of Service | Privacy Policy | ScyllaDB, and ScyllaDB Cloud, are registered trademarks of ScyllaDB, Inc.
Last updated on 09 Apr 2025.
Powered by Sphinx 7.4.7 & ScyllaDB Theme 1.8.6