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 Open Source 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, 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
  • Edit this page

On this page

  • Definitions
    • Conventions
    • Identifiers and keywords
    • Constants
    • Terms
    • Comments
    • Statements
    • Prepared Statements
ScyllaDB Open Source
  • 5.2
    • master
    • 6.2
    • 6.1
    • 6.0
    • 5.4
    • 5.2
    • 5.1
  • Getting Started
    • Install ScyllaDB
      • ScyllaDB Web Installer for Linux
      • ScyllaDB Unified Installer (relocatable executable)
      • Air-gapped Server Installation
      • What is in each RPM
      • ScyllaDB Housekeeping and how to disable it
      • ScyllaDB Developer Mode
      • ScyllaDB Configuration Reference
    • Configure ScyllaDB
    • ScyllaDB Requirements
      • System Requirements
      • OS Support by Linux Distributions and Version
      • ScyllaDB in a Shared Environment
    • Migrate to ScyllaDB
      • Migration Process from Cassandra to Scylla
      • Scylla and Apache Cassandra Compatibility
      • Migration Tools Overview
    • Integration Solutions
      • Integrate Scylla with Spark
      • Integrate Scylla with KairosDB
      • Integrate Scylla with Presto
      • Integrate Scylla with Elasticsearch
      • Integrate Scylla with Kubernetes
      • Integrate Scylla with the JanusGraph Graph Data System
      • Integrate Scylla with DataDog
      • Integrate Scylla with Kafka
      • Integrate Scylla with IOTA Chronicle
      • Integrate Scylla with Spring
      • Shard-Aware Kafka Connector for Scylla
      • Install Scylla with Ansible
      • Integrate Scylla with Databricks
    • Tutorials
  • ScyllaDB for Administrators
    • Administration Guide
    • Procedures
      • Cluster Management
      • Backup & Restore
      • Change Configuration
      • Maintenance
      • Best Practices
      • Benchmarking Scylla
      • Migrate from Cassandra to Scylla
      • Disable Housekeeping
    • Security
      • ScyllaDB Security Checklist
      • Enable Authentication
      • Enable and Disable Authentication Without Downtime
      • Generate a cqlshrc File
      • Reset Authenticator Password
      • Enable Authorization
      • Grant Authorization CQL Reference
      • 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
      • Encryption at Rest
      • LDAP Authentication
      • LDAP Authorization (Role Management)
    • Admin Tools
      • Nodetool Reference
      • CQLSh
      • REST
      • Tracing
      • Scylla SStable
      • Scylla Types
      • SSTableLoader
      • cassandra-stress
      • SSTabledump
      • SSTable2json
      • Scylla Logs
      • Seastar Perftune
      • Virtual Tables
    • ScyllaDB Monitoring Stack
    • ScyllaDB Operator
    • ScyllaDB Manager
    • Upgrade Procedures
      • ScyllaDB Open Source Upgrade
      • ScyllaDB Open Source to ScyllaDB Enterprise Upgrade
      • ScyllaDB Image
      • ScyllaDB Enterprise
    • System Configuration
      • System Configuration Guide
      • scylla.yaml
      • ScyllaDB Snitches
    • Benchmarking ScyllaDB
  • ScyllaDB for Developers
    • Learn To Use ScyllaDB
      • Scylla University
      • Course catalog
      • Scylla Essentials
      • Basic Data Modeling
      • Advanced Data Modeling
      • MMS - Learn by Example
      • Care-Pet an IoT Use Case and Example
    • Scylla Alternator
    • Scylla Features
      • Scylla Open Source Features
      • Scylla Enterprise Features
    • Scylla Drivers
      • Scylla CQL Drivers
      • Scylla DynamoDB Drivers
    • Workload Attributes
  • CQL Reference
    • CQLSh: the CQL shell
    • Appendices
    • Compaction
    • Consistency Levels
    • Consistency Level Calculator
    • Data Definition
    • Data Manipulation
    • Data Types
    • Definitions
    • Global Secondary Indexes
    • Additional Information
    • Expiring Data with Time to Live (TTL)
    • Additional Information
    • Functions
    • JSON Support
    • Materialized Views
    • Non-Reserved CQL Keywords
    • Reserved CQL Keywords
    • ScyllaDB CQL Extensions
  • ScyllaDB Architecture
    • ScyllaDB Ring Architecture
    • ScyllaDB Fault Tolerance
    • Consistency Level Console Demo
    • ScyllaDB Anti-Entropy
      • Scylla Hinted Handoff
      • Scylla Read Repair
      • Scylla Repair
    • SSTable
      • ScyllaDB SSTable - 2.x
      • ScyllaDB SSTable - 3.x
    • Compaction Strategies
    • Raft Consensus Algorithm in ScyllaDB
  • Troubleshooting ScyllaDB
    • Errors and Support
      • Report a Scylla problem
      • Error Messages
      • Change Log Level
    • ScyllaDB Startup
      • Ownership Problems
      • Scylla will not Start
      • Scylla Python Script broken
    • Upgrade
      • Inaccessible configuration files after ScyllaDB upgrade
    • Cluster and Node
      • Failed Decommission Problem
      • Cluster Timeouts
      • Node Joined With No Data
      • SocketTimeoutException
      • NullPointerException
    • Data Modeling
      • Scylla Large Partitions Table
      • Scylla Large Rows and Cells Table
      • Large Partitions Hunting
    • 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
      • Reverse queries fail
    • ScyllaDB Monitor and Manager
      • Manager and Monitoring integration
      • Manager lists healthy nodes as down
  • Knowledge Base
    • Upgrading from experimental CDC
    • Compaction
    • 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 Scylla and supporting services as a custom user:group
    • Decoding Stack Traces
    • Snapshots and Disk Utilization
    • DPDK mode
    • Debug your database with Flame Graphs
    • How to Change gc_grace_seconds for a Table
    • Gossip in Scylla
    • Increase Permission Cache to Avoid Non-paged Queries
    • How does Scylla LWT Differ from Apache Cassandra ?
    • Map CPUs to Scylla Shards
    • Scylla Memory Usage
    • NTP Configuration for Scylla
    • Updating the Mode in perftune.yaml After a ScyllaDB Upgrade
    • POSIX networking for Scylla
    • Scylla consistency quiz for administrators
    • Recreate RAID devices
    • How to Safely Increase the Replication Factor
    • Scylla and Spark integration
    • Increase Scylla resource limits over systemd
    • Scylla Seed Nodes
    • How to Set up a Swap Space
    • Scylla Snapshots
    • Scylla 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
    • Scylla Nodes are Unresponsive
    • Update a Primary Key
    • Using the perf utility with Scylla
    • Configure Scylla Networking with Multiple NIC/IP Combinations
  • ScyllaDB FAQ
  • Contribute to ScyllaDB
  • Glossary
  • Alternator: DynamoDB API in Scylla
    • Getting Started With ScyllaDB Alternator
    • ScyllaDB Alternator for DynamoDB users
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 08 May 2025.
Powered by Sphinx 7.4.7 & ScyllaDB Theme 1.8.6