Definitions

Conventions

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

  • BNF variant notation. In particular, we’ll use square brakets ([ item ]) for optional items, * and + for repeated items (where + imply at least one).
  • identifiers 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>).
  • 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.
  • fixed-width font.

    Identifiers and keywords

    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_]*. 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. SELECT is the same than 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 uppercase for keywords and lowercase for other identifiers. quoted identifier 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 ill-advised), while select would raise a parsing error. Also, unlike 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. More formally, we have:
    1. identifier::= unquoted_identifier | quoted_identifierunquoted_identifier::= re('[a-zA-Z][link:[a-zA-Z0-9]]*')quoted_identifier::= '"' (any character where " can appear if doubled)+ '"'

    Constants

    constants:
    1. constant::= string | integer | float | boolean | uuid | blob | NULLstring::= ''' (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 | INFINITYboolean::= TRUE | FALSEuuid::= 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 single-quote can be included by repeating it, e.g. 'It''s raining today'. Those are not to be confused with quoted identifiers 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 $$).
  • NaN and Infinity constants.
  • UUID constants.
  • 0x.
  • NULL constant denotes the absence of value. Data types section.

    Terms

    term, which denotes the kind of values that CQL support. Terms are defined by:
    1. term::= constant | literal | function_call | arithmetic_operation | type_hint | bind_markerliteral::= collection_literal | vector_literal | udt_literal | tuple_literalfunction_call::= identifier '(' [ term (',' term)* ] ')'arithmetic_operation::= '-' term | term ('+' | '-' | '*' | '/' | '%') termtype_hint::= '(' cql_type ')' termbind_marker::= '?' | ':' identifier
    A term is thus one of:
  • constant
  • collection, a vector, a user-defined type or a tuple
  • function call, either a native function or a user-defined function
  • arithmetic operation between terms
  • A type hint
  • 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

    --) or double slash (//). / and / (but nesting is not supported).
    1. -- This is a comment// This is a comment too/* This is   a multi-line comment */

    Statements

    CQL consists of statements that can be divided in 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.
  • secondary-indexes statements.
  • materialized-views statements.
  • cql-roles statements.
  • cql-permissions statements.
  • User-Defined Functions (UDFs) statements.
  • udts statements.
  • cql-triggers statements. All the statements are listed below and are described in the rest of this documentation (see links above):
    1. cql_statement::= statement [ ';' ]statement:=: ddl_statement :        | dml_statement        | secondary_index_statement        | materialized_view_statement        | role_or_permission_statement        | udf_statement        | udt_statement        | trigger_statementddl_statement::= use_statement        | create_keyspace_statement        | alter_keyspace_statement        | drop_keyspace_statement        | create_table_statement        | alter_table_statement        | drop_table_statement        | truncate_statementdml_statement::= select_statement        | insert_statement        | update_statement        | delete_statement        | batch_statementsecondary_index_statement::= create_index_statement        | drop_index_statementmaterialized_view_statement::= create_materialized_view_statement        | drop_materialized_view_statementrole_or_permission_statement::= create_role_statement        | alter_role_statement        | drop_role_statement        | grant_role_statement        | revoke_role_statement        | list_roles_statement        | grant_permission_statement        | revoke_permission_statement        | list_permissions_statement        | create_user_statement        | alter_user_statement        | drop_user_statement        | list_users_statementudf_statement::= create_function_statement        | drop_function_statement        | create_aggregate_statement        | drop_aggregate_statementudt_statement::= create_type_statement        | alter_type_statement        | drop_type_statementtrigger_statement::= create_trigger_statement        | drop_trigger_statement

    Prepared Statements

    prepared statements. Prepared statements are an optimization that allows to parse a query only once but execute it multiple times with different concrete values. bind_marker) will need to be prepared. After which the statement can be executed by provided concrete values for each of its marker. 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.