From a508ac06e9a24272d2f69f7a7546640626c16fc4 Mon Sep 17 00:00:00 2001 From: Bereng Date: Thu, 5 May 2022 09:53:38 +0200 Subject: [PATCH] Update the CQL version for the 4.1 release patch by Berenguer Blasi; reviewed by Benjamin Lerer for CASSANDRA-17570 --- README.asc | 2 +- doc/cql3/CQL.textile | 2572 ----------------- doc/modules/cassandra/pages/cql/changes.adoc | 10 + .../cassandra/pages/new/virtualtables.adoc | 4 +- .../apache/cassandra/cql3/QueryProcessor.java | 2 +- 5 files changed, 14 insertions(+), 2576 deletions(-) delete mode 100644 doc/cql3/CQL.textile diff --git a/README.asc b/README.asc index 3c40bf4970..f484aa277e 100644 --- a/README.asc +++ b/README.asc @@ -39,7 +39,7 @@ be sitting in front of a prompt: ---- Connected to Test Cluster at localhost:9160. -[cqlsh 6.0.0 | Cassandra 4.0.2 | CQL spec 3.4.5 | Native protocol v5] +[cqlsh 6.0.0 | Cassandra 4.1 | CQL spec 3.4.6 | Native protocol v5] Use HELP for help. cqlsh> ---- diff --git a/doc/cql3/CQL.textile b/doc/cql3/CQL.textile deleted file mode 100644 index 8bedf19a78..0000000000 --- a/doc/cql3/CQL.textile +++ /dev/null @@ -1,2572 +0,0 @@ - - -h1. Cassandra Query Language (CQL) v3.4.3 - - - - - -{toc:maxLevel=3} - - - -h2. CQL Syntax - -h3. Preamble - -This document describes the Cassandra Query Language (CQL) version 3. CQL v3 is not backward compatible with CQL v2 and differs from it in numerous ways. Note that this document describes the last version of the languages. However, the "changes":#changes section provides the diff between the different versions of CQL v3. - -CQL v3 offers a model very close to SQL in the sense that data is put in _tables_ containing _rows_ of _columns_. For that reason, when used in this document, these terms (tables, rows and columns) have the same definition than they have in SQL. But please note that as such, they do *not* refer to the concept of rows and columns found in the internal implementation of Cassandra and in the thrift and CQL v2 API. - - -h3. Conventions - -To aid in specifying the CQL syntax, we will use the following conventions in this document: - -* Language rules will be given in a "BNF":http://en.wikipedia.org/wiki/Backus%E2%80%93Naur_Form -like notation: - -bc(syntax). ::= TERMINAL - -* Nonterminal symbols will have @@. -* As additional shortcut notations to BNF, we'll use traditional regular expression's symbols (@?@, @+@ and @*@) to signify that a given symbol is optional and/or can be repeated. We'll also allow parentheses to group symbols and the @[]@ notation to represent any one of @@. -* The grammar is provided for documentation purposes and leave some minor details out. For instance, the last column definition in a @CREATE TABLE@ statement is optional but supported if present even though the provided grammar in this document suggest it is not supported. -* Sample code will be provided in a code block: - -bc(sample). SELECT sample_usage FROM cql; - -* References to keywords or pieces of CQL code in running text will be shown in a @fixed-width font@. - -h3(#identifiers). Identifiers and keywords - -p. 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_]@@*@. - -p. 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":#appendixA. - -p. Identifiers and (unquoted) keywords are case insensitive. Thus @SELECT@ is the same than @select@ or @sElEcT@, and @myId@ is the same than @myid@ or @MYID@ for instance. 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. - -p. There is a second kind of identifiers called _quoted identifiers_ defined by enclosing an arbitrary sequence of characters in double-quotes(@"@). Quoted identifiers are never keywords. Thus @"select"@ is not a reserved keyword and can be used to refer to a column, while @select@ would raise a parse error. Also, contrarily 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 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. - -p. *Warning*: _quoted identifiers_ allows to declare columns with arbitrary names, and those can sometime clash with specific names used by the server. For instance, when using 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)"@). - -h3(#constants). Constants - -CQL defines the following kind of _constants_: strings, integers, floats, booleans, uuids and blobs: -* A string constant is an arbitrary sequence of characters characters enclosed by single-quote(@'@). One can include a single-quote in a string by repeating it, e.g. @'It''s raining today'@. Those are not to be confused with quoted identifiers that use double-quotes. -* An integer constant is defined by @'-'?[0-9]+@. -* A float constant is defined by @'-'?[0-9]+('.'[0-9]*)?([eE][+-]?[0-9+])?@. On top of that, @NaN@ and @Infinity@ are also float constants. -* A boolean constant is either @true@ or @false@ up to case-insensitivity (i.e. @True@ is a valid boolean constant). -* A "UUID":http://en.wikipedia.org/wiki/Universally_unique_identifier constant is defined by @hex{8}-hex{4}-hex{4}-hex{4}-hex{12}@ where @hex@ is an hexadecimal character, e.g. @[0-9a-fA-F]@ and @{4}@ is the number of such characters. -* A blob constant is an hexadecimal number defined by @0[xX](hex)+@ where @hex@ is an hexadecimal character, e.g. @[0-9a-fA-F]@. - -For how these constants are typed, see the "data types section":#types. - -h3. 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). - -bc(sample). --- This is a comment -// This is a comment too -/* This is - a multi-line comment */ - -h3(#statements). Statements - -CQL consists of statements. As in SQL, these statements can be divided in 3 categories: -* Data definition statements, that allow to set and change the way data is stored. -* Data manipulation statements, that allow to change data -* Queries, to look up data - -All statements end with a semicolon (@;@) but that semicolon can be omitted when dealing with a single statement. The supported statements are described in the following sections. When describing the grammar of said statements, we will reuse the non-terminal symbols defined below: - -bc(syntax).. - ::= any quoted or unquoted identifier, excluding reserved keywords - ::= ( '.')? - - ::= a string constant - ::= an integer constant - ::= a float constant - ::= | - ::= a uuid constant - ::= a boolean constant - ::= a blob constant - - ::= - | - | - | - | - ::= '?' - | ':' - ::= - | - | - | '(' ( (',' )*)? ')' - | CAST '(' AS ')' - - ::= - | - | - ::= '{' ( ':' ( ',' ':' )* )? '}' - ::= '{' ( ( ',' )* )? '}' - ::= '[' ( ( ',' )* )? ']' - - ::= - - ::= (AND )* - ::= '=' ( | | ) -p. -Please note that not every possible productions of the grammar above will be valid in practice. Most notably, @@ and nested @@ are currently not allowed inside @@. - -p. A @@ can be either anonymous (a question mark (@?@)) or named (an identifier preceded by @:@). Both declare a bind variables for "prepared statements":#preparedStatement. The only difference between an anymous and a named variable is that a named one will be easier to refer to (how exactly depends on the client driver used). - -p. The @@ production is use by statement that create and alter keyspaces and tables. Each @@ is either a _simple_ one, in which case it just has a value, or a _map_ one, in which case it's value is a map grouping sub-options. The following will refer to one or the other as the _kind_ (_simple_ or _map_) of the property. - -p. A @@ will be used to identify a table. This is an identifier representing the table name that can be preceded by a keyspace name. The keyspace name, if provided, allow to identify a table in another keyspace than the currently active one (the currently active keyspace is set through the USE statement). - -p. For supported @@, see the section on "functions":#functions. - -p. Strings can be either enclosed with single quotes or two dollar characters. The second syntax has been introduced to allow strings that contain single quotes. Typical candidates for such strings are source code fragments for user-defined functions. - -__Sample:__ - -bc(sample).. - 'some string value' - - $$double-dollar string can contain single ' quotes$$ -p. - -h3(#preparedStatement). Prepared Statement - -CQL supports _prepared statements_. Prepared statement is an optimization that allows to parse a query only once but execute it multiple times with different concrete values. - -In a statement, each time a column value is expected (in the data manipulation and query statements), a @@ (see above) can be used instead. A statement with bind variables must then be _prepared_. Once it has been prepared, it can executed by providing concrete values for the bind variables. The exact procedure to prepare a statement and execute a prepared statement depends on the CQL driver used and is beyond the scope of this document. - -In addition to providing column values, bind markers may be used to provide values for @LIMIT@, @TIMESTAMP@, and @TTL@ clauses. If anonymous bind markers are used, the names for the query parameters will be @[limit]@, @[timestamp]@, and @[ttl]@, respectively. - - -h2(#dataDefinition). Data Definition - -h3(#createKeyspaceStmt). CREATE KEYSPACE - -__Syntax:__ - -bc(syntax).. - ::= CREATE KEYSPACE (IF NOT EXISTS)? WITH -p. -__Sample:__ - -bc(sample).. -CREATE KEYSPACE Excelsior - WITH replication = {'class': 'SimpleStrategy', 'replication_factor' : 3}; - -CREATE KEYSPACE Excalibur - WITH replication = {'class': 'NetworkTopologyStrategy', 'DC1' : 1, 'DC2' : 3} - AND durable_writes = false; -p. -The @CREATE KEYSPACE@ statement creates a new top-level _keyspace_. A keyspace is a namespace that defines a replication strategy and some options for a set of tables. Valid keyspaces names are identifiers composed exclusively of alphanumerical characters and whose length is lesser or equal to 32. Note that as identifiers, keyspace names are case insensitive: use a quoted identifier for case sensitive keyspace names. - -The supported @@ for @CREATE KEYSPACE@ are: - -|_. name |_. kind |_. mandatory |_. default |_. description| -|@replication@ | _map_ | yes | | The replication strategy and options to use for the keyspace. | -|@durable_writes@ | _simple_ | no | true | Whether to use the commit log for updates on this keyspace (disable this option at your own risk!). | - -The @replication@ @@ is mandatory. It must at least contains the @'class'@ sub-option which defines the replication strategy class to use. The rest of the sub-options depends on that replication strategy class. By default, Cassandra support the following @'class'@: -* @'SimpleStrategy'@: A simple strategy that defines a simple replication factor for the whole cluster. The only sub-options supported is @'replication_factor'@ to define that replication factor and is mandatory. -* @'NetworkTopologyStrategy'@: A replication strategy that allows to set the replication factor independently for each data-center. The rest of the sub-options are key-value pairs where each time the key is the name of a datacenter and the value the replication factor for that data-center. - -Attempting to create an already existing keyspace will return an error unless the @IF NOT EXISTS@ option is used. If it is used, the statement will be a no-op if the keyspace already exists. - -h3(#useStmt). USE - -__Syntax:__ - -bc(syntax). ::= USE - -__Sample:__ - -bc(sample). USE myApp; - -The @USE@ statement takes an existing keyspace name as argument and set it as the per-connection current working keyspace. All subsequent keyspace-specific actions will be performed in the context of the selected keyspace, unless "otherwise specified":#statements, until another USE statement is issued or the connection terminates. - -h3(#alterKeyspaceStmt). ALTER KEYSPACE - -__Syntax:__ - -bc(syntax).. - ::= ALTER KEYSPACE WITH -p. -__Sample:__ - -bc(sample).. -ALTER KEYSPACE Excelsior - WITH replication = {'class': 'SimpleStrategy', 'replication_factor' : 4}; - -p. -The @ALTER KEYSPACE@ statement alters the properties of an existing keyspace. The supported @@ are the same as for the "@CREATE KEYSPACE@":#createKeyspaceStmt statement. - - -h3(#dropKeyspaceStmt). DROP KEYSPACE - -__Syntax:__ - -bc(syntax). ::= DROP KEYSPACE ( IF EXISTS )? - -__Sample:__ - -bc(sample). DROP KEYSPACE myApp; - -A @DROP KEYSPACE@ statement results in the immediate, irreversible removal of an existing keyspace, including all column families in it, and all data contained in those column families. - -If the keyspace does not exists, the statement will return an error, unless @IF EXISTS@ is used in which case the operation is a no-op. - - -h3(#createTableStmt). CREATE TABLE - -__Syntax:__ - -bc(syntax).. - ::= CREATE ( TABLE | COLUMNFAMILY ) ( IF NOT EXISTS )? - '(' ( ',' )* ')' - ( WITH