Cassandra Query Language (CQL) v3.4.3

構文

bc(syntax)..
::= SELECT ( JSON )?
FROM
( WHERE )?
( GROUP BY )?
( ORDER BY )?
( PER PARTITION LIMIT )?
( LIMIT )?
( ALLOW FILTERING )?

::= DISTINCT?

::= (AS )? ( `,' (AS )? )*
| `*'

::=
|
| WRITETIME (' `)'
| MAXWRITETIME `(' `)'
| COUNT `(' `' `)'
| TTL `(' `)'
| CAST `(' AS `)'
| `(' ( (,' ))?? `)'
| `.'
| `[' `]'
| `[' ? .. ? `]'

::= ( AND )*

::=
| (' (,' )* )'
| IN `(' ( (,' )* )? `)'
| `(' (,' )* `)' IN `(' ( (,' )* )? `)'
| TOKEN `(' ( `,' )* `)'

::= =' | `<' | `>' | `⇐' | `>=' | CONTAINS | CONTAINS KEY
::= (,' )*
::= ( ,' )*
::= ( ASC | DESC )?
::= `(' (,' )* `)'
p.
サンプル

bc(sample)..
SELECT name, occupation FROM users WHERE userid IN (199, 200, 207);

SELECT JSON name, occupation FROM users WHERE userid = 199;

SELECT name AS user_name, occupation AS user_occupation FROM users;

SELECT time, value
FROM events
WHERE event_type = `myEvent'
AND time > `2011-02-03'
AND time ⇐ `2012-01-01'

SELECT COUNT (*) FROM users;

SELECT COUNT (*) AS user_count FROM users;

SELECTステートメントは、テーブル内の1つまたは複数の行について1つまたは複数の列を読み取ります。クエリに対応する列のコレクションを含む行のresult-setを返します。JSONキーワードを使用した場合、各行の結果には、`json''という名前の単一の列のみが含まれます。詳細については、`SELECT JSON`のセクションを参照してください。

構文

bc(syntax)..
::= CREATE ROLE ( IF NOT EXISTS )? ( WITH ( AND )* )?

::= PASSWORD =
| LOGIN =
| SUPERUSER =
| OPTIONS =
p.

サンプル

bc(sample).
CREATE ROLE new_role;
CREATE ROLE alice WITH PASSWORD = `password_a' AND LOGIN = true;
CREATE ROLE bob WITH PASSWORD = `password_b' AND LOGIN = true AND SUPERUSER = true;
CREATE ROLE carlos WITH OPTIONS = \{ `custom_option1' : `option1_value', `custom_option2' : 99 };

デフォルトでは、ロールはLOGIN権限またはSUPERUSERステータスを持ちません。

データベースリソースに対する権限は、ロールに付与されます。リソースの種類には、キースペース、テーブル、関数、ロール自体が含まれます。ロールは、階層的な権限構造を作成するために他のロールに付与できます。これらの階層では、権限とSUPERUSERステータスは継承されますが、LOGIN権限は継承されません。

ロールにLOGIN権限がある場合、クライアントは接続時にそのロールとして識別できます。その接続の間、クライアントはそのロールに付与されたすべてのロールと権限を取得します。

クライアントがSUPERUSERでない限り、データベースロールリソースに対するCREATE権限を持つクライアントのみがCREATE ROLEリクエストを発行できます（以下の関連セクションを参照してください）。Cassandraでのロール管理はプラグ可能であり、カスタム実装ではリストされたオプションのサブセットのみがサポートされる場合があります。

ロール名に英数字以外の文字が含まれる場合は、引用符で囲む必要があります。

構文

bc(syntax)..
::= ALTER ROLE (IF EXISTS)? ( WITH ( AND )* )?

::= PASSWORD =
| LOGIN =
| SUPERUSER =
| OPTIONS =
p.

サンプル

bc(sample).
ALTER ROLE bob WITH PASSWORD = `PASSWORD_B' AND SUPERUSER = false;

ロールが存在しない場合、IF EXISTSが使用されている場合を除き、ステートメントはエラーを返します。この場合、操作は何も実行しません。

ALTER ROLEステートメントの実行に関する条件

構文

bc(syntax)..
::= DROP ROLE ( IF EXISTS )?
p.

サンプル

bc(sample).
DROP ROLE alice;
DROP ROLE IF EXISTS bob;

DROP ROLEには、クライアントが問題のロールに対するDROP 権限を持っている必要があります。さらに、クライアントは、ログイン時に識別されたロールをDROPすることはできません。最後に、SUPERUSERステータスを持つクライアントのみが、別のSUPERUSERロールをDROPできます。
存在しないロールを削除しようとすると、IF EXISTSオプションを使用しない限り、無効なクエリ条件になります。オプションが使用され、ロールが存在しない場合、ステートメントは何も実行しません。

構文

bc(syntax).
::= GRANT TO

サンプル

bc(sample).
GRANT report_writer TO alice;

このステートメントは、report_writerロールをaliceに付与します。report_writerに付与された権限は、aliceも取得します。
ロールは有向非巡回グラフとしてモデル化されているため、循環的な付与は許可されていません。次の例はエラー条件になります。

bc(sample).
GRANT role_a TO role_b;
GRANT role_b TO role_a;

bc(sample).
GRANT role_a TO role_b;
GRANT role_b TO role_c;
GRANT role_c TO role_a;

構文

bc(syntax).
::= REVOKE FROM

サンプル

bc(sample).
REVOKE report_writer FROM alice;

このステートメントは、aliceからreport_writerロールを取り消します。aliceがreport_writerロールを介して取得した権限も取り消されます。

Cassandra 2.2でロールが導入される前は、認証と承認はUSERの概念に基づいていました。下位互換性のために、レガシー構文は保持されており、USER中心のステートメントはROLEベースの同等のステートメントの同義語になっています。

構文

bc(syntax)..
::= CREATE USER ( IF NOT EXISTS )? ( WITH PASSWORD )? ()?

::= SUPERUSER
| NOSUPERUSER
p.

サンプル

bc(sample).
CREATE USER alice WITH PASSWORD `password_a' SUPERUSER;
CREATE USER bob WITH PASSWORD `password_b' NOSUPERUSER;

CREATE USERは、LOGINオプションがtrueであるCREATE ROLEと同等です。したがって、次のステートメントのペアは同等です。

bc(sample)..
CREATE USER alice WITH PASSWORD `password_a' SUPERUSER;
CREATE ROLE alice WITH PASSWORD = `password_a' AND LOGIN = true AND SUPERUSER = true;

CREATE USER IF NOT EXISTS alice WITH PASSWORD `password_a' SUPERUSER;
CREATE ROLE IF NOT EXISTS alice WITH PASSWORD = `password_a' AND LOGIN = true AND SUPERUSER = true;

CREATE USER alice WITH PASSWORD `password_a' NOSUPERUSER;
CREATE ROLE alice WITH PASSWORD = `password_a' AND LOGIN = true AND SUPERUSER = false;

CREATE USER alice WITH PASSWORD `password_a' NOSUPERUSER;
CREATE ROLE alice WITH PASSWORD = `password_a' AND LOGIN = true;

CREATE USER alice WITH PASSWORD `password_a';
CREATE ROLE alice WITH PASSWORD = `password_a' AND LOGIN = true;
p.

構文

bc(syntax)..
::= ALTER USER (IF EXISTS)? ( WITH PASSWORD )? ( )?

::= SUPERUSER
| NOSUPERUSER
p.

bc(sample).
ALTER USER alice WITH PASSWORD `PASSWORD_A';
ALTER USER bob SUPERUSER;

ユーザーが存在しない場合、IF EXISTSが使用されている場合を除き、ステートメントはエラーを返します。この場合、操作は何も実行しません。

構文

bc(syntax)..
::= DROP USER ( IF EXISTS )?
p.

サンプル

bc(sample).
DROP USER alice;
DROP USER IF EXISTS bob;

構文

bc(syntax).
::= LIST USERS;

サンプル

bc(sample).
LIST USERS;

このステートメントは以下と同等ですが

bc(sample).
LIST ROLES;

ただし、LOGIN権限を持つロールのみが出力に含まれます。

構文

bc(syntax)..
::= ADD IDENTITY ( IF NOT EXISTS )? TO ROLE ?

サンプル

bc(sample).
ADD IDENTITY 'id1' TO ROLE 'role1';

ロールを追加する権限を持つユーザーのみがIDを追加できます。

ロール名とID名に英数字以外の文字が含まれる場合は、引用符で囲む必要があります。

構文

bc(syntax)..
::= DROP IDENTITY ( IF EXISTS )?
p.

サンプル

bc(sample).
DROP IDENTITY 'testIdentity';
DROP IDENTITY IF EXISTS 'testIdentity';

ロールを削除する権限を持つユーザーのみがIDを削除できます。

IF EXISTSオプションを使用しない限り、存在しないIDを削除しようとすると、無効なクエリ条件になります。オプションが使用され、IDが存在しない場合、ステートメントは何も行いません。

リソースに対する権限はロールに付与されます。Cassandraにはいくつかの異なるタイプのリソースがあり、各タイプは階層的にモデル化されています。

権限は、これらの階層の任意のレベルで付与でき、下位に流れます。したがって、チェーンの上位にあるリソースに対する権限を付与すると、自動的に下位にあるすべてのリソースに同じ権限が付与されます。たとえば、KEYSPACE で SELECT を付与すると、その KEYSPACE 内のすべての TABLES で自動的に付与されます。同様に、ALL FUNCTIONS に対する権限を付与すると、どのキースペースにスコープされているかに関係なく、定義されたすべての関数に付与されます。特定のキースペースにスコープされたすべての関数に権限を付与することも可能です。

権限の変更は、既存のクライアントセッションに表示されます。つまり、権限の変更後に接続を再確立する必要はありません。

利用可能な権限の完全なセットは次のとおりです。

すべての権限がすべてのタイプのリソースに適用できるわけではありません。たとえば、EXECUTE は関数または mbeans のコンテキストでのみ関連します。テーブルを表すリソースに EXECUTE を付与するのは無意味です。適用できないリソースに対して GRANT 権限を付与しようとすると、エラー応答が発生します。以下に、どの権限をどのタイプのリソースに付与できるか、およびその権限によって有効になるステートメントを示します。

構文

bc(syntax)..
::= GRANT ( ALL ( PERMISSIONS )? | ( PERMISSION )? ) ON TO

::= CREATE | ALTER | DROP | SELECT | MODIFY | AUTHORIZE | DESCRIBE | UNMASK | SELECT_MASKED EXECUTE

::= ALL KEYSPACES
| KEYSPACE
| ( TABLE )?
| ALL ROLES
| ROLE
| ALL FUNCTIONS ( IN KEYSPACE )?
| FUNCTION
| ALL MBEANS
| ( MBEAN | MBEANS )
p.

サンプル

bc(sample).
GRANT SELECT ON ALL KEYSPACES TO data_reader;

これにより、data_readerロールを持つすべてのユーザーに、すべてのキースペースにわたって任意のテーブルでSELECTステートメントを実行する権限が付与されます。

bc(sample).
GRANT MODIFY ON KEYSPACE keyspace1 TO data_writer;

これにより、data_writerロールを持つすべてのユーザーに、keyspace1キースペース内のすべてのテーブルでUPDATE、INSERT、UPDATE、DELETE、およびTRUNCATEクエリを実行する権限が付与されます。

bc(sample).
GRANT DROP ON keyspace1.table1 TO schema_owner;

これにより、schema_ownerロールを持つすべてのユーザーに、keyspace1.table1 を DROP する権限が付与されます。

bc(sample).
GRANT EXECUTE ON FUNCTION keyspace1.user_function( int ) TO report_writer;

これにより、report_writerロールを持つすべてのユーザーに、関数 keyspace1.user_function( int )を使用する SELECT、INSERT、およびUPDATE クエリを実行する権限が付与されます。

bc(sample).
GRANT DESCRIBE ON ALL ROLES TO role_admin;

これにより、role_adminロールを持つすべてのユーザーに、LIST ROLESステートメントを使用してシステム内のすべてのロールを表示する権限が付与されます。

構文

bc(syntax)..
::= REVOKE ( ALL ( PERMISSIONS )? | ( PERMISSION )? ) ON FROM

::= CREATE | ALTER | DROP | SELECT | MODIFY | AUTHORIZE | DESCRIBE | UNMASK | SELECT_MASKED EXECUTE

::= ALL KEYSPACES
| KEYSPACE
| ( TABLE )?
| ALL ROLES
| ROLE
| ALL FUNCTIONS ( IN KEYSPACE )?
| FUNCTION
| ALL MBEANS
| ( MBEAN | MBEANS )
p.

サンプル

bc(sample)..
REVOKE SELECT ON ALL KEYSPACES FROM data_reader;
REVOKE MODIFY ON KEYSPACE keyspace1 FROM data_writer;
REVOKE DROP ON keyspace1.table1 FROM schema_owner;
REVOKE EXECUTE ON FUNCTION keyspace1.user_function( int ) FROM report_writer;
REVOKE DESCRIBE ON ALL ROLES FROM role_admin;
p.

timestamp型の値は、標準ベース時間である「エポック」：1970年1月1日00:00:00 GMTからのミリ秒数を表す64ビット符号付き整数としてエンコードされます。

タイムスタンプは、上記で定義したエポックからのミリ秒数を表す単純な長整数としてCQLに入力できます。

また、次のいずれかのISO 8601形式の文字列リテラルとして入力することもできます。それぞれ、2011年2月3日午前4時5分00秒（GMT）を表します。

上記の+0000は、RFC 822の4桁のタイムゾーン指定です。+0000はGMTを表します。米国太平洋標準時は-0800です。必要に応じてタイムゾーンを省略できます。日付は、コーディネートするCassandraノードが構成されているタイムゾーンで解釈されます。

ただし、タイムゾーン構成が予想どおりであることに依存することには、明確な困難が伴うため、可能な場合は常にタイムスタンプにタイムゾーンを指定することをお勧めします。

日付のみが重要な場合は、時刻を省略することもできます。

その場合、時刻は、指定されたまたはデフォルトのタイムゾーンで00:00:00にデフォルト設定されます。

date型の値は、範囲の中央（2^31）に「エポック」を持つ日数を表す32ビット符号なし整数としてエンコードされます。エポックは1970年1月1日です。

日付は、上記で定義した符号なし整数としてCQLに入力できます。

また、次の形式の文字列リテラルとして入力することもできます。

time型の値は、真夜中からのナノ秒数を表す64ビット符号付き整数としてエンコードされます。

時間は、真夜中からのナノ秒数を表す単純な長整数としてCQLに入力できます。

また、次のいずれかの形式の文字列リテラルとして入力することもできます。

counter型は、カウンター列を定義するために使用されます。カウンター列は、値が64ビット符号付き整数であり、インクリメントとデクリメントの2つの操作がサポートされている列です（構文についてはUPDATEを参照）。カウンターの値は設定できないことに注意してください。カウンターは、最初にインクリメント/デクリメントされるまで存在せず、最初のインクリメント/デクリメントは、前の値が0であるかのように行われます。カウンター列の削除はサポートされていますが、いくつかの制限があります（詳細については、Cassandra Wikiを参照してください）。

カウンター型の使用には、次の制限があります。

ベクターは、特定のデータ型の非null値の固定サイズのシーケンスです。リストと同じリテラルを使用します。

ベクターの定義、挿入、更新は以下のようにおこないます。

ベクターの個々の値を変更することはできず、ベクターの個々の要素を選択することもできないことに注意してください。

cast関数は、あるネイティブデータ型を別のデータ型に変換するために使用できます。

次の表は、cast関数でサポートされている変換を示しています。Cassandraは、データ型をそれ自身のデータ型に変換するキャストを黙って無視します。

変換は、Javaのセマンティクスに厳密に依存します。たとえば、double値の1は、テキスト値の「1.0」に変換されます。

bc(sample).
SELECT avg(cast(count as double)) FROM myTable

token関数を使用すると、指定されたパーティションキーのトークンを計算できます。トークン関数の正確な署名は、関係するテーブルとクラスターで使用されるパーティショナーによって異なります。

tokenの引数の型は、パーティションキー列の型によって異なります。戻り値の型は、使用中のパーティショナーによって異なります。

たとえば、デフォルトのMurmur3Partitionerを使用しているクラスターで、テーブルが以下のように定義されている場合

bc(sample).
CREATE TABLE users (
userid text PRIMARY KEY,
username text,
…
)

次に、token関数はtext型の単一の引数を取り（その場合、パーティションキーはuseridです（クラスタリング列がないため、パーティションキーは主キーと同じです））、戻り値の型はbigintになります。

uuid関数はパラメータを取らず、INSERTまたはSETステートメントでの使用に適したランダムなタイプ4のuuidを生成します。

timeuuid、timestamp、またはdateを別のネイティブ型に変換するために、いくつかの関数が提供されています。

ネイティブ型をバイナリデータ（blob）に変換するために、いくつかの関数が提供されています。CQL3でサポートされているすべての<native-type>typeについて（明らかな理由でblobは例外です）、関数type_as_blobはtype型の引数を取り、それをblobとして返します。逆に、関数blob_as_typeは64ビットのblob引数を取り、それをbigint値に変換します。たとえば、bigint_as_blob(3)は0x0000000000000003であり、blob_as_bigint(0x0000000000000003)は3です。

count関数を使用すると、クエリによって返された行をカウントできます。例

bc(sample).
SELECT COUNT (*) FROM plays;
SELECT COUNT (1) FROM plays;

また、指定された列のnull以外の値をカウントするためにも使用できます。例

bc(sample).
SELECT COUNT (scores) FROM plays;

max関数とmin関数を使用すると、指定された列に対してクエリによって返される最大値と最小値を計算できます。

bc(sample).
SELECT MIN (players), MAX (players) FROM plays WHERE game = `quake';

sum関数を使用すると、指定された列に対してクエリによって返されたすべての値を合計できます。

bc(sample).
SELECT SUM (players) FROM plays;

avg関数を使用すると、指定された列に対してクエリによって返されたすべての値の平均を計算できます。

bc(sample).
SELECT AVG (players) FROM plays;

SELECTステートメントでは、新しいJSONキーワードを使用して、各行を単一のJSONエンコードされたマップとして返すことができます。SELECTステートメントの残りの動作は同じです。

結果マップのキーは、通常の結果セットの列名と同じです。たとえば、SELECT JSON a, ttl(b) FROM …​’'のようなステートメントは、キーが"a"と"ttl(b)"のマップになります。ただし、これには1つの注目すべき例外があります。INSERT JSONの動作との対称性のため、大文字を含む大文字と小文字を区別する列名は二重引用符で囲まれます。たとえば、SELECT JSON myColumn FROM …​’'は、マップキー"\"myColumn\""になります（エスケープされた引用符に注意してください）。

マップ値は、結果セットの値のJSONエンコードされた表現（下記を参照）になります。

INSERTステートメントでは、新しいJSONキーワードを使用して、JSONエンコードされたマップを単一行として挿入できます。JSONマップの形式は、一般に、同じテーブルに対するSELECT JSONステートメントによって返される形式と一致する必要があります。特に、大文字と小文字を区別する列名は二重引用符で囲む必要があります。たとえば、myKey''とvalue''という名前の2つの列を持つテーブルに挿入するには、次のようにします。

bc(sample).
INSERT INTO mytable JSON `\{\''myKey\'': 0, ``value'': 0}'

JSONマップから省略された列は、すべてNULL値にデフォルト設定されます（これにより、墓標が作成されます）。

可能な場合、Cassandraはデータ型をネイティブのJSON表現で表現および受け入れます。Cassandraは、すべての単一フィールド型に対して、CQLリテラル形式に一致する文字列表現も受け入れます。たとえば、float、int、UUID、および日付は、CQLリテラル文字列で表現できます。ただし、コレクション、タプル、ユーザー定義型などの複合型は、ネイティブのJSONコレクション（マップとリスト）またはコレクションのJSONエンコードされた文字列表現で表現する必要があります。

次の表は、CassandraがINSERT JSON値（およびfrom_json()引数）で受け入れるエンコーディングと、CassandraがSELECT JSONステートメント（およびfrom_json()）のデータを返すときに使用する形式について説明しています。

from_json()関数は、INSERT JSONと同様に使用できますが、単一の列値に対して使用できます。INSERTステートメントのVALUES句内、またはUPDATE、DELETE、またはSELECTステートメントの列値のいずれかとしてのみ使用できます。たとえば、SELECTステートメントの選択句では使用できません。

to_json()関数は、SELECT JSONと同様に使用できますが、単一の列値に対して使用できます。SELECTステートメントの選択句でのみ使用できます。