Apache Cassandra 1.2 Documentation

CQL lexical structure

CQL input consists of statements. Like SQL, statements change data, look up data, store data, or change the way data is stored. Statements end in a semicolon (;).

For example, the following is valid CQL syntax:

SELECT * FROM MyTable;

UPDATE MyTable
  SET SomeColumn = 'SomeValue'
  WHERE columnName = B70DE1D0-9908-4AE3-BE34-5573E5B09F14;

This is a sequence of two CQL statements. This example shows one statement per line, although a statement can usefully be split across lines as well.

Uppercase/lowercase sensitivity

Keyspace, column, and table names created using CQL 3 are case-insensitive unless enclosed in double quotation marks. If you enter names for these objects using any uppercase letters, Cassandra stores the names in lowercase. You can force the case by using double quotation marks. For example:

CREATE TABLE test (
  Foo int PRIMARY KEY,
  "Bar" int
);

The following table shows partial queries that work and do not work to return results from the test table:

Queries that Work Queries that Don't Work
SELECT foo FROM ... SELECT "Foo" FROM ...
SELECT Foo FROM ... SELECT "BAR" FROM ...
SELECT FOO FROM ... SELECT bar FROM ...
SELECT "foo" FROM ...  
SELECT "Bar" FROM ...  

SELECT "foo" FROM ... works because internally, Cassandra stores foo in lowercase. The double-quotation mark character can be used as an escape character for the double quotation mark.

Case sensitivity rules in earlier versions of CQL apply when handling legacy tables.

CQL keywords are case-insensitive. For example, the keywords SELECT and select are equivalent. This document shows keywords in uppercase.

Escaping unreadable characters

Column names that contain characters that CQL cannot parse need to be enclosed in double quotation marks in CQL 3. In CQL 2, single quotation marks were used.

Valid literals

Valid literal consist of these kinds of values:

  • blob: hexidecimal.

  • boolean: true or false, case-insensitive, and in CQL 3, enclosure in single quotation marks is not required prior to release 1.2.2. In 1.2.2 and later, using quotation marks is not allowed.

  • A numeric constant can consist of integers 0-9 and a minus sign prefix. A numeric constant can also be float. A float can be a series of one or more decimal digits, followed by a period, ., and one or more decimal digits. There is no optional + sign. The forms .42 and 42 are unacceptable. You can use leading or trailing zeros before and after decimal points. For example, 0.42 and 42.0. A float constant, expressed in E notation, consists of the characters in this regular expression:

    '-'?[0-9]+('.'[0-9]*)?([eE][+-]?[0-9+])?

    The next section presents an example.

  • identifier: A letter followed by any sequence of letters, digits, or the underscore. Names of tables, columns, and other objects are identifiers. Enclose them in double quotation marks.

  • integer: An optional minus sign, -, followed by one or more digits.

  • string literal: Characters enclosed in single quotation marks. To use a single quotation mark itself in a string literal, escape it using a single quotation mark. For example, use '' to make dog plural: dog''s.

  • uuid: 32 hex digits, 0-9 or a-f, which are case-insensitive, separated by dashes, -, after the 8th, 12th, 16th, and 20th digits. For example: 01234567-0123-0123-0123-0123456789ab

  • timeuuid: Uses the time in 100 nanosecond intervals since 00:00:00.00 UTC (60 bits), a clock sequence number for prevention of duplicates (14 bits), plus the IEEE 801 MAC address (48 bits) to generate a unique identifier. For example: d2177dd0-eaa2-11de-a572-001b779c76e3

  • whitespace: Separates terms and used inside string literals, but otherwise CQL ignores whitespace.

Using exponential notation in CQL 3.0.1

Cassandra 1.2.1 and later supports exponential notation. This example shows exponential notation in the output from a cqlsh 3.0.1 command:

CREATE TABLE test(
  id varchar PRIMARY KEY,
  value_double double,
  value_float float
);

INSERT INTO test (id, value_float, value_double)
  VALUES ('test1', -2.6034345E+38, -2.6034345E+38);

SELECT * FROM test;

 id    | value_double | value_float
-------+--------------+-------------
 test1 |  -2.6034e+38 | -2.6034e+38

CQL Keywords

Here is a list of keywords and whether or not the words are reserved. A reserved keyword cannot be used as an identifier unless you enclose the word in double quotation marks. Non-reserved keywords have a specific meaning in certain context but can be used as an identifier outside this context.

Word Reserved
ADD yes
ALL no
ALLOW yes
ALTER yes
AND yes
APPLY yes
ASC yes
ASCII no
AUTHORIZE yes
BATCH yes
BEGIN yes
BIGINT no
BLOB no
BOOLEAN no
BY yes
CLUSTERING no
COLUMNFAMILY yes
COMPACT no
COUNT no
COUNTER no
CREATE yes
DECIMAL no
DELETE yes
DESC yes
DOUBLE no
DROP yes
FILTERING no
FLOAT no
FROM yes
GRANT yes
IN yes
INDEX yes
INET yes
INSERT yes
INT no
INTO yes
KEY no
KEYSPACE yes
KEYSPACES yes
LIMIT yes
LIST no
MAP no
MODIFY yes
NORECURSIVE yes
NOSUPERUSER no
OF yes
ON yes
ORDER yes
PASSWORD yes
PERMISSION no
PERMISSIONS no
PRIMARY yes
RENAME yes
REVOKE yes
SCHEMA yes
SELECT yes
SET yes
STORAGE no
SUPERUSER no
TABLE yes
TEXT no
TIMESTAMP no
TIMEUUID no
TO yes
TOKEN yes
TRUNCATE yes
TTL no
TYPE no
UNLOGGED yes
UPDATE yes
USE yes
USER no
USERS no
USING yes
UUID no
VALUES no
VARCHAR no
VARINT no
WHERE yes
WITH yes
WRITETIME no