DDL文法的說明和樣本 - Lindorm

本節介紹DDL文法的說明和樣本。

概述

Lindorm CQL將資料存放區在表中，其模式定義了表中所述資料的布局，並且這些表被分組在鍵空間中。Keyspace定義了許多選項，這些選項適用於它包含的所有Table，其中最主要的是Keyspace使用的複製策略，這裡Lindorm CQL並不支援Keyspace的複製策略定義，以及副本數的定義，都是預設定義的值。Lindorm CQL支援使用CQL語言操作Lindorm高效能二級索引以及Lindorm全文索引Search Index，滿足使用者對於索引的使用需求。

Keyspace和Table的文法定義

Lindorm CQL Keyspace文法定義：

keyspace_name ::=  name
name          ::=  unquoted_name | quoted_name
unquoted_name ::=  re('[a-zA-Z_0-9]{1, 48}')
quoted_name   ::=  '"' unquoted_name '"'

Lindorm CQL Table文法定義：

table_name    ::=  [ keyspace_name '.' ] name
name          ::=  unquoted_name | quoted_name
unquoted_name ::=  re('[a-zA-Z_0-9]{1, 48}')
quoted_name   ::=  '"' unquoted_name '"'

說明

Keyspace名和Table名都由字母、數字、字元組成，不可為空。
Keyspace名和Table名不超過48個字元。該限制主要是為了避免檔案名稱（可能包括Keyspace名和Table名）超過某些檔案的限制系統。
預設情況下，Keyspace名和Table名不區分大小寫，比如myTable和mytable是一樣的。但使用雙引號可強制進行區分，例如“myTable”和"mytable"是不一樣的。
表是Keyspace的一部分，並且表名可以由Keyspace名進行強制限定，比如：鍵空間KS和鍵空間GC都具有表Table，但他們的表名分別為ks.table和gc.table。

索引

Lindorm CQL同時支援二級索引和基於搜尋引擎的Search Index。

二級索引
Lindorm CQL支援在表上建立二級索引，從而允許查詢表時使用這些索引。二級索引由以下名稱定義：
```
index_name ::=  re('[a-zA-Z_0-9]+')
```
Search Index
Search Index支援的功能如下：
- 多維查詢。給定多個列的隨機組合，快速返回查詢結果。
- 排序。提供Order By能力，返回結果按照任意指定列進行排序。
- 模糊比對。
如果您想要通過Lindorm CQL使用Search Index，需要先在Lindorm上開通全文檢索索引以及LTS服務，請參見搜尋索引介紹。

CREATE KEYSPACE

建立Keyspace。

文法

CREATE KEYSPACE [ IF NOT EXISTS ] keyspace_name WITH options

說明

Keyspace在Lindorm中類似於Namespace的概念，由於底層設計限制，所以Lindorm CQL暫時不支援設定副本複製策略以及副本數，都是使用預設參數。

參數

參數名稱

樣本值

描述

keyspace_name

testks

索引值空間名稱。

options

replication

目前取值固定為replication和durable_writes。

replication：Map類型。表示副本的預設資料，底層預設2副本儲存。
durable_writes：Boolean類型。表示資料是否持久化寫入。預設值為True。

樣本

CREATE KEYSPACE testks WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1}

說明

Lindorm CQL Keyspace相容層暫時不支援設定replication和durable_writes屬性，您可以看到預設的2副本或者預設值為True的durable_writes屬性，後續會開放對應功能設定。

ALTER KEYSPACE

修改Keyspace的選項。

文法

ALTER KEYSPACE keyspace_name WITH options

說明

ALTER KEYSPACE語句中的options和CREATE KEYSPACE語句中的options是一樣的，但是由於Keyspace層級的options都是預設的，所以無需修改。

參數

ALTER KEYSPACE語句中的options和CREATE KEYSPACE語句中的options是一樣的，請參見參數說明。

樣本

ALTER KEYSPACE testks WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1}

USE

使用某個Keyspace。Lindorm CQL中的許多個物件都綁定到一個鍵空間（表、使用者定義的類型、函數等）。

文法

USE keyspace_name

參數

參數名稱	樣本值	描述
keyspace_name	testks	索引值空間名稱。

樣本

USE testks;

DROP KEYSPACE

刪除Keyspace。

文法

DROP KEYSPACE [ IF EXISTS ] keyspace_name

說明

使用DROP KEYSPACE刪除Keyspace會立即生效並且不可恢複，包括Keyspace中的所有表、UDT和函數以及這些表中包含的所有資料。
如果Keyspace不存在，使用該語句系統會返回錯誤。除非您使用IF EXISTS，系統不返回錯誤，但該操作為無效操作。
只有root使用者具有DROP KEYSPACE的許可權。

參數

參數名稱	樣本值	描述
keyspace_name	testks	索引值空間名稱。

樣本

DROP KEYSPACE testks;

CREATE TABLE

建立TABLE。

文法

CREATE TABLE [ IF NOT EXISTS ] table_name
                  '('
                       column_definition
                       ( ',' column_definition )*
                       [ ',' PRIMARY KEY '(' primary_key ')' ]
                 ')' [ WITH table_options ]
column_definition      ::=  column_name cql_type [ STATIC ] [ PRIMARY KEY]
primary_key            ::=  partition_key [ ',' clustering_columns ]
partition_key          ::=  column_name
                            | '(' column_name ( ',' column_name )* ')'
clustering_columns     ::=  column_name ( ',' column_name )*
table_options          ::=  CLUSTERING ORDER BY '(' clustering_order ')' [ AND options ]
                            | options
clustering_order       ::=  column_name (ASC | DESC) ( ',' column_name (ASC | DESC) )*

說明

Lindorm CQL表具有名稱，由一組行組成。建立TABLE表示將定義一行資料將由哪些列組成，哪些列將組成主鍵（Primary Key）以及該表的可選選項（Table Options）。除非使用IF NOT EXISTS語句，否則建立一個已經存在的表將返回錯誤。

Lindorm CQL表中的每一行都有一組預定義列，這些預定義列在建立表時定義（或後面使用ALTER語句添加）。

column_definition主要由定義的列的名稱和類型組成，它限制了該列接受哪些值。此外，列定義可以具有以下修飾符：

STATIC：表示將列聲明為靜態列（暫不支援）。
PRIMARY KEY：表示該列是表主鍵的唯一組成部分。

在一個表中，一行資料由其PRIMARY KEY唯一標識，因此所有表都必須定義一個PRIMARY KEY（只有一個）。PRIMARY KEY定義由表中定義的一列或多列組成。在文法上，主關鍵字定義為關鍵字PRIMARY KEY，後跟用括弧括起來的列名稱的列表，該列名稱用括弧括起來，但是如果主鍵只有一列，則可以用PRIMARY KEY關鍵字替換該列定義。主鍵中定義的列的順序很重要，將會影響資料的分布和儲存順序。

Lindorm CQL主鍵由兩部分組成：

partition key：它是主鍵（Primary Key）的第一部分。它可以是單個列，或者使用附加的括弧可以是多個列。一個表總是至少有一個分區鍵。
clustering columns：這些是主鍵定義的第一部分之後的列，這些列的順序定義了聚類順序，Lindorm CQL中允許不定義clustering columns。

PRIMARY KEY定義的一些樣本：

PRIMARY KEY（a）：a是分區鍵，沒有聚類列。
PRIMARY KEY（a，b，c）：a是分區鍵，b和c是聚簇列。
PRIMARY KEY（（a，b），c）：a和b組成分區鍵（通常稱為複合分區鍵），c是聚簇列。

在Lindorm CQL中，PRIMARY KEY具有較強的意義，partition key和clustering columns組成PRIMARY KEY，單獨的partition key或clustering columns不具有獨立使用的意義。

在表中，Lindorm CQL定義分區的概念。分區就是一組共用相同分區索引值的行。請注意，如果分區鍵由多個列組成，則行僅屬於同一分區，並且所有分區鍵列的值都相同。給定以下表定義和內容：

CREATE TABLE persioninfo (
    a int,
    b int,
    c int,
    d int,
    PRIMARY KEY ((a, b), c, d)
);

SELECT * FROM persioninfo;
   a | b | c | d
  ---+---+---+---
   0 | 0 | 0 | 0    // row 1
   0 | 0 | 1 | 1    // row 2
   0 | 1 | 2 | 2    // row 3
   0 | 1 | 3 | 3    // row 4
   1 | 1 | 4 | 4    // row 5

Lindorm CQL中，partition key以及clustering columns共同組成PRIMARY KEY，他們的地位是等價的，Lindorm CQL中partition key和cluster column組合在一起共同決定一條資料屬於哪個節點，而不是CQL中由partition key單獨決定一條資料屬於哪個節點，例如上述例子中row1和row2在傳統CQL中可以確定是在一個節點中，但是在Lindorm CQL中並不能保證，這是Lindorm CQL與傳統CQL的較大區別。

樣本

CREATE TABLE tb (name text PRIMARY KEY , age int);   //預設建立以name為主鍵的表。
CREATE TABLE ttltb (name text PRIMARY KEY, age int) WITH default_time_to_live = 1000;  //設定表的ttl時間是1000s。
CREATE TABLE cptb (name text PRIMARY KEY, age int) WITH compression = {'sstable_compression': 'LZ4Compressor'};   //設定壓縮演算法為LZ4壓縮；預設是SNAPPY。
CREATE TABLE hct ( name text PRIMARY KEY , age int  ) WITH extensions = {'COLD_BOUNDARY':'10'};  //設定lindorm的冷熱分離的時間軸是10s。

Lindorm CQL Table暫不支援的定義功能

partition key：確定資料分布式從屬的對應節點，Lindorm CQL不能由單一的partition key確定該行資料從屬的物理節點。

支援的table_Option列表

Lindorm CQL的table_options和Cassandra的table_options有一定差異，Lindorm CQL目前支援如下的選項設定。

選項	類型	描述
default_time_to_live	int	表的預設到期時間（ TTL），以秒為單位。預設值為0。
compression	map	可以設定對應檔案（sstable）的compression演算法，支援LZ4、ZSTD、SNAPPY演算法。具體請參考下文Compression介紹。
extensions	map	支援擴充設定，包括設定是否使用冷儲存、使用冷熱分離、表的一致性層級等屬性。具體請參考下文Extensions介紹。

Compression

Lindorm CQL支援如下幾種可配置的壓縮演算法，各個壓縮演算法的係數暫時使用預設參數進行設定。

LZ4（LZ4Compressor）。建立LZ4壓縮的表如下：

CREATE TABLE persioninfo (
   id int,
   name text,
   address text,
   PRIMARY KEY (id, name)
) with compression = {'class': 'LZ4Compressor'};

ZSTD（ZstdCompressor）。建立ZSTD壓縮的表如下：

CREATE TABLE persioninfo (
   id int,
   name text,
   address text,
   PRIMARY KEY (id, name)
) with compression = {'class': 'ZstdCompressor'};

SNAPPY（SnappyCompressor）。建立SNAPPY壓縮的表如下：

CREATE TABLE persioninfo (
   id int,
   name text,
   address text,
   PRIMARY KEY (id, name)
) with compression = {'class': 'SnappyCompressor'};

說明

compression屬性也可以通過ALTER TABLE文法進行修改設定。

Extensions

對於Lindorm的特有屬性我們通過extensions擴充屬性進行設定，擴充屬性如下：

冷儲存。關鍵字為STORAGE_POLICY，配置值為COLD表示冷儲存，DEFAULT表示使用預設熱儲存。

CREATE TABLE persioninfo (name text PRIMARY KEY, age int) WITH extensions = {'STORAGE_POLICY' : 'COLD'};  //建表指定表為冷儲存。
ALTER TABLE persioninfo WITH extensions = {'STORAGE_POLICY' : 'DEFAULT'};  //修改表屬性為熱儲存。

冷熱分離。關鍵字為COLD_BOUNDARY，在冷熱分離使用過程中，無需把表或列簇的屬性設定為COLD，如果已經把列簇的屬性設定為了COLD，請您將冷儲存的屬性去除，具體請參考容量型雲端儲存。

CREATE TABLE persioninfo (name text PRIMARY KEY, age int) with extensions = {'COLD_BOUNDARY':'86400'};  //建表指定冷熱分離時間軸為1天（86400秒），超過時間軸資料被寫到冷介質。
ALTER TABLE persioninfo with extensions = {'COLD_BOUNDARY':''};    //取消冷熱分離。
ALTER TABLE persioninfo with extensions = {'COLD_BOUNDARY':'1000'};   //修改時間軸為1000s。

CONSISTENCY_TYPE：對於lindorm多zone情境下，設定表的一致性層級，有eventual、timestamp、basic、strong四種層級。

CREATE TABLE persioninfo (name text PRIMARY KEY, age int) with extensions = {'CONSISTENCY_TYPE':'strong'};  //建表一致性層級為strong。
ALTER TABLE persioninfo with extensions = {'CONSISTENCY_TYPE':'eventual'};  //修改一致性層級為eventual。

Mutability：使用者在使用二級索引、search index之前需要設定Mutability，取值：IMMUTABLE、IMMUTABLE_ROWS（CONSISTENCY_TYPE必須為strong），MUTABLE_LATEST（CONSISTENCY_TYPE必須為strong），MUTABLE_ALL（建表預設的層級，CONSISTENCY_TYPE必須為strong）。
```
CREATE TABLE persioninfo (name text PRIMARY KEY, age int) with extensions = {'MUTABILITY':'IMMUTABLE'};  //建表指定mutability為IMMUTABLE。
ALTER TABLE persioninfo with extensions = {'MUTABILITY':'MUTABLE_LATEST'};   //修改表mutability為MUTABLE_LATEST。
```

暫不支援的table_Option列表

選項	類型	描述
comment	string	表示對錶的描述。預設值為f。
speculative_retry	simple simple	預設值為99PERCENTILE。
cdc	boolean	在表上建立一個更改資料擷取（CDC）日誌。預設值為false。
gc_grace_seconds	int	等待垃圾收集墓碑（刪除標記）之前的時間。預設值為86400。
bloom_filter_fp_chance	float	穩定布隆過濾器誤判的目標機率。所述布隆過濾器的大小將確定所提供的機率，因此降低此值會影響記憶體中和磁碟上布隆過濾器的大小。預設值為0.00075。
compaction	map	預設值為STCS策略。
caching	map	無
memtable_flush_period_in_ms	map	預設值為0。
read_repair	int	預設值為BLOCKING。

ALTER TABLE

修改TABLE。

文法

ALTER TABLE table_name alter_table_instruction
alter_table_instruction ::=  ADD column_name cql_type ( ',' column_name cql_type )*                           
                             | WITH options

說明

ALTER TABLE語句可以進行以下操作：

可以通過ADD指令，將新列添加到表中。由於表的主鍵無法更改，因此新添加的列將永遠不會成為主鍵的一部分。需要注意，緊湊表對列添加有一定的限制。
Lindorm CQL暫時不支援刪除列操作。
可以通過WITH指令，更改表的選項。支援修改的表的選項與建立表時的選項相同，但是無法更改CLUSTERING ORDER。Lindorm CQL支援修改default_time_to_live、compression、extensions選項的設定。

樣本

CREATE TABLE persioninfo (name text PRIMARY KEY, age int);
ALTER TABLE persioninfo ADD address text;

DROP TABLE

刪除TABLE。

文法

DROP TABLE [ IF EXISTS ] table_name

說明

使用DROP TABLE刪除TABLE會立即生效並且不可恢複，包括Table中的所有資料。
如果TABLE不存在，使用該語句系統會返回錯誤。除非您使用IF EXISTS，系統不返回錯誤，但該操作為無效操作。
只有root使用者具有DROP TABLE的許可權。

參數

參數名稱	樣本值	描述
table_name	persioninfo	表名稱。

樣本

DROP TABLE persioninfo;

TRUNCATE

清空表資料。

文法

TRUNCATE [ TABLE ] table_name

說明

使用TRUNCATE會永久刪除表中所有的資料，但不會刪除表本身的表結構狀態。
只有root使用者具有TRUNCATE TABLE的許可權。

參數

參數名稱	樣本值	描述
table_name	persioninfo	表名稱。

樣本

TRUNCATE TABLE persioninfo;

CREATE INDEX

建立二級索引。

文法

CREATE [ CUSTOM ] INDEX [ IF NOT EXISTS ] [ index_name ]
                                ON table_name '(' index_identifier ')'
                                [ USING string [ WITH OPTIONS = map_literal ] ]
index_identifier       ::=  column_name
                           | '(' column_name ')'

說明

CREATE INDEX語句用於為指定的表中的列自動建立二級索引。您可以在ON關鍵字之前指定索引名。如果該列已經存在資料，則將對其進行非同步索引。建立索引後，您在插入資料時，系統將自動為該列的新資料建立索引。

如果建立一個已經存在的索引系統將返回錯誤。如果使用IF NOT EXISTS選項建立一個已經存在的索引，則操作屬於無效操作。

CREATE INDEX語句只支援對單個列進行索引構建。如果想要對錶下面的多個列構建索引的話，您可以使用CREATE CUSTOM INDEX語句中的USING 'com.alibaba.lindorm.cserver.schema.index.LindormSecondaryIndex'進行構建。

樣本

CREATE INDEX myindex ON persioninfo (c2);
CREATE INDEX ON persioninfo (c2);
CREATE CUSTOM INDEX myindex ON persioninfo (c1,c2) USING 'com.alibaba.lindorm.cserver.schema.index.LindormSecondaryIndex';

DROP INDEX

刪除二級索引。

文法

DROP INDEX [ IF EXISTS ] index_name

說明

使用DROP INDEX語句用於刪除已存在的二級索引。語句的變數是索引名稱index_name，可以選擇指定索引的鍵空間。
如果索引不存在，使用該語句系統會返回錯誤。除非您使用IF EXISTS，系統不返回錯誤，但該操作為無效操作。

樣本

DROP INDEX myindex;

CREATE SEARCH INDEX

建立全文索引。

文法

CREATE SEARCH INDEX [ IF NOT EXISTS ] index_name ON [keyspace_name.]table_name
| [ WITH [ COLUMNS （column1,...,columnn） ]
| [ WITH [ COLUMNS （*） ]

說明

CREATE SEARCH INDEX語句支援在來源資料表的某些列上構建全文索引。
WITH COLUMNS（column）：指定某個或某幾個列構建SEARCH INDEX，各column間以英文逗號（,）分隔。
WITH COLUMNS（*）：使用（*）符號表示對所有列構建全文索引。
建立SEARCH INDEX的表需要對來源資料表的屬性通過Extension進行擴充。如果是Lindorm多Zone情境下，預設需要指定一致性以及MUTABLE屬性，非多Zone情境下不需要進行設定。

樣本

CREATE SEARCH INDEX schidx ON persioninfo WITH COLUMNS (c2, c3);

DROP SEARCH INDEX

刪除全文索引。

文法

DROP SEARCH INDEX [IF EXISTS] ON [keyspace_name.]table_name;

樣本

DROP SEARCH INDEX ON testks.persioninfo;

REBUILD SEARCH INDEX

將索引狀態設定為有效。

文法

REBUILD SEARCH INDEX [ASYNC] [IF EXISTS] ON [keyspace_name.]table_name；

說明

全文索引構建完成以後，索引的狀態是INACTIVE的，需要手動執行REBUILD操作，才能將索引狀態置為有效。執行REBUILD操作還會為存量資料構建SEARCH INDEX，整個過程會比較漫長，可以通過ASYNC參數指定此次構建是非同步作業。

樣本

REBUILD SEARCH INDEX ON persioninfo;
REBUILD SEARCH INDEX ASYNC ON persioninfo;

ALTER SEARCH INDEX

修改全文索引的狀態、手動添加索引列或者刪除索引列。

文法

ALTER SEARCH INDEX SCHEMA [IF EXISTS] ON [keyspace_name.]table_name
  ( ADD FIELD column_name
  | DROP FIELD column_name) ;

說明

使用ALTER SEARCH INDEX修改全文索引的狀態後，需要使用REBUILD 重建索引的狀態。
添加ADD SEARCH INDEX或刪除DROP SEARCH INDEX的索引列需要在來源資料表中存在。

樣本

ALTER SEARCH INDEX SCHEMA ON persioninfo ADD  (c3);
ALTER SEARCH INDEX SCHEMA ON persioninfo DROP  (c2);