Data Definition

USE

USE语句允许您更改当前的keyspace (用于连接当前执行的keyspace)。CQL中的一些对象被绑定到一个keyspace(表，用户定义类型，函数，…)，当这些对象在没有完全限定名的情况下，当前被引用的keyspace是默认使用的键空间(也就是说，没有前缀键空间名称)。USE语句只是接受指定的键空间，并使用该名称作为将来所有操作的参数，直到更改该名称为止。

use_statement: USE keyspace_name

ALTER KEYSPACE

ALTER KEYSPACE语句用于修改一个keyspace的选项

alter_keyspace_statement: ALTER KEYSPACE keyspace_name WITH options
例如：

1. ALTER KEYSPACE Excelsior

WITH replication = { 'class' : 'NetworkTopologyStrategy', 'dc1' : 3, 'dc2' : 0};

2. ALTER KEYSPACE Excelsior

WITH replication = {'class': 'SimpleStrategy', 'replication_factor' : 4};

可支持的选项，与 creating a keyspace 部分相同

DROP KEYSPACE

删除一个keyspace

drop_keyspace_statement: DROP KEYSPACE [ IF EXISTS ] keyspace_name

例如：

DROP KEYSPACE Excelsior;

删除键空间会导致立即删除该键空间，包括其中的所有表、UTD和函数，以及这些表中包含的所有数据。

NOTE: 默认情况下，当删除表或键空间时，会生成快照，以便稍后恢复。因此，磁盘空间保持不变，不会立即回收。参考 这篇文章或这个 FAQ条目。

如果键空间不存在，如果未使用 IF EXISTS ，那么语句将返回错误，在这种情况下，操作是无操作。

CREATE TABLE

使用 CREATE TABLE 创建一个新表

create_table_statement: 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: COMPACT STORAGE [ AND `table_options` ]
                : | CLUSTERING ORDER BY '(' `clustering_order` ')' [ AND `table_options` ]
                : | scylla_encryption_options: '=' '{'[`cipher_algorithm` : <hash>]','[`secret_key_strength` : <len>]','[`key_provider`: <provider>]'}'
                : | caching  '=' ' {'caching_options'}'
                : | `options`

clustering_order: `column_name` (ASC | DESC) ( ',' `column_name` (ASC | DESC) )*

例如：

CREATE TABLE monkeySpecies (
  species text PRIMARY KEY,
  common_name text,
  population varint,
  average_size int
) WITH comment='Important biological records'
AND read_repair_chance = 1.0;

CREATE TABLE timeline (
  userid uuid,
  posted_month int,
  posted_time uuid,
  body text,
  posted_by text,
  PRIMARY KEY (userid, posted_month, posted_time)
) WITH compaction = { 'class' : 'LeveledCompactionStrategy' };

CREATE TABLE loads (
  machine inet,
  cpu int,
  mtime timeuuid,
  load float,
  PRIMARY KEY ((machine, cpu), mtime)
) WITH CLUSTERING ORDER BY (mtime DESC);

CREATE TABLE users_picture (
  userid uuid,
  pictureid uuid,
  body text,
  posted_by text,
  PRIMARY KEY (userid, pictureid, posted_by)
) WITH compression = {'sstable_compression': 'LZ4Compressor'};


CREATE TABLE data_atrest (
  pk text PRIMARY KEY,
  c0 int
) WITH scylla_encryption_options = {
  'cipher_algorithm' : 'AES/ECB/PKCS5Padding',
                        'secret_key_strength' : 128,
                        'key_provider': 'LocalFileSystemKeyProviderFactory',
                        'secret_key_file': '/etc/scylla/data_encryption_keys/secret_key'};

CREATE TABLE caching (
  k int PRIMARY KEY,
  v1 int,
  v2 int,
) WITH caching = {'enabled': 'true'};

CQL表有一个名称，由一组rows组成。创建表相当于定义这些行 ( rows ) 将由哪些列 ( columns ) 组成，这些列 ( columns ) 中的哪些列组成主键 ( primary key ) ，以及表的可选选项 ( options ) 。
尝试创建一个已经存在的表，如果未使用 IF NOT EXISTS，则返回一个错误。反之，不会执行该语句。

Column definitions

CQL表中的每一行都有一组预定义的列，这些列是在创建表时定义的(或者稍后使用alter语句添加)。

column_definition主要由所定义的列的名称和它的类型组成，它严格限制了该列可以接受哪些值。

另外，列定义可以有以下修饰符:

1. STATIC：将列声明为静态列
2. PRIMARY KEY：该列是表的主键的唯一组件。

Static columns

有些列可以在表定义中声明为 STATIC 。属于同一分区(具有相同分区键)的所有行“共享”该静态列。例如:

CREATE TABLE t (
    pk int,
    t int,
    v text,
    s text static,
    PRIMARY KEY (pk, t)
);

INSERT INTO t (pk, t, v, s) VALUES (0, 0, 'val0', 'static0');
INSERT INTO t (pk, t, v, s) VALUES (0, 1, 'val1', 'static1');

SELECT * FROM t;
   pk | t | v      | s
  ----+---+--------+-----------
   0  | 0 | 'val0' | 'static1'
   0  | 1 | 'val1' | 'static1'

可以看到，分区中两行的s值是相同的 ( 均为 static1 ) (该示例中的分区键 partition key 为pk，两行都在同一个分区中)：第二次插入覆盖了s的值。

静态列有以下限制：

1. 具有 COMPACT STORAGE 选项 ( 见下文 ) 的表不能使用它们。
2. 没有集群列的表不能有静态列 ( 在没有集群列的表中，每个分区只有一行，因此每个列本质上是静态的 )。
3. 只有非主键 ( non PRIMARY KEY ) 列可以是静态的。

The Primary key

主键在一个表中，一行的唯一标识是它的 PRIMARY KEY，因此所有表必须定义一个PRIMARY KEY ( 且只能定义一个 )。PRIMARY KEY 的定义，由表中定义的一个或多个列组成。从语法上讲，主键是由关键字 PRIMARY KEY 定义的，后面是括号内以逗号分隔的列名列表。但是，如果主键只有一列，则可以通过 该列名称 + PRIMARY KEY 的方式定义。主键定义中列的顺序很重要。

CQL主键由2部分组成：

1. 分区键 ( partition key ) 部分。它是主键定义的第一个组成部分。它可以是单列，也可以是使用额外括号的多列。一个表总是至少有一个分区键，最小的表定义是：

CREATE TABLE t (k text PRIMARY KEY);

2. 集群列 ( the clustering columns ) 。这些是主键定义后的第一个部分，这些列的顺序定义了聚类顺序 ( clustering order )。

一些主键定义的例子：

• 主键 ( a )：a是分区键 partition key，没有集群列 clustering columns。
• 主键 ( a, b, c )：a是分区键，b和c是集群列。
• 主键 ( ( a, b )，c )：a和b组成分区键 (通常称为复合分区键 composite partition key)，c是集群列。

NOTE：不允许 null 作为 分区键 或 集群键 的列。Null值与空字符串不一样。

The partition key

在表中，CQL定义了分区的概念。一个分区 partition 就是一组行 rows，它们的分区键共享相同的值。请注意，如果分区键由多列组成，那么只有当所有这些分区键列的值相同时，行才属于同一个分区。因此，举个例子，给定下面的表定义和内容：

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

SELECT * FROM t;
   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

第1行和第2行在同一个分区中，第3行和第4行也在同一个分区中 (但与第一行第二行组成的分区不同 )，第5行在另一个分区中。

请注意，一个表总是有一个分区键，如果表没有集群列 ( clustering columns) ，那么该表的每个分区只由一行组成 ( 因为主键唯一地标识行，如果没有集群列，主键等于分区键 ) 。

分区最重要的属性是，属于同一分区的所有行都被保证存储在同一组复制节点上。换句话说，表的分区键定义了哪些行将在集群中一起本地化，因此明智地选择分区键是很重要的，这样需要一起提取的行就在同一个分区中 ( 即，这样一起查询这些行就需要联系最少的节点)。

然而，请注意，上述做法也有不足之处：由于所有共享分区键的行都保证存储在同一组复制节点上，因此将过多数据分组的分区键可能会创建一个热点 ( hotspot ) 。

分区的另一个有用的属性是，在写入数据时，属于单个分区的所有更新都是自动地、隔离地完成的，而跨分区则不是这样。

正确选择一个表的分区键和集群列，可能是Scylla中数据建模最重要的方面之一。它在很大程度上影响着可以执行哪些查询以及查询的效率。

NOTE：
不允许空字符串 ( empty string ) 作为分区键值。在复合分区键 ( 多个分区键列 ) 中，它们中的任何一个或全部都可以是空字符串。空字符串不是Null值。

The clustering columns

表的集群列定义了该表分区的集群顺序。对于给定的分区，Scylla内部的所有行都按照该聚类顺序进行物理排序。例如，给定：

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

SELECT * FROM t;
   a | b | c
  ---+---+---
   0 | 0 | 4     // row 1
   0 | 1 | 9     // row 2
   0 | 2 | 2     // row 3
   0 | 3 | 3     // row 4

然后，所有的行 ( 都属于同一个分区 ) 都按照b列的值的顺序 ( 上面显示的顺序 ) 在内部存储。因此，当表的分区键允许您对相同副本集中的行进行分组时，集群列控制这些行如何存储在副本上。这种排序允许在一个分区内检索一定范围的行 ( 例如，在上面的例子中，SELECT * FROM t WHERE a = 0 AND b> 1 AND b <= 3 ) 是非常高效的。

NOTE：
允许空字符串 ( empty string ) 作为集群键值。空字符串不是Null值。

Table options

CQL表有许多可以在创建时设置的选项 ( 对于大多数选项，可以在以后更改 )。这些选项在 WITH 关键字之后指定。
在这些选项中，有两个重要的选项不能在创建后更改，并影响可以对表进行哪些查询： COMPACT STORAGE 选项和 CLUSTERING ORDER 选项。这些，以及表的其他选项将在以下章节中描述。

Compact tables

紧凑表 ( Compact tables ) 是用 COMPACT STORAGE 选项定义的表。这个选项只是为了兼容CQL3之前创建的定义而维护的，不应该用于新表。使用此选项声明表会对表产生限制，这些限制在很大程度上是任意的 ( 并且由于历史原因而存在 ) 。这些限制包括：

• 紧凑表不能使用集合和静态列。
• 如果紧凑表至少有一个集群列，那么它必须在主键列之外恰好有一个列。这意味着你不能添加或删除列，特别是在创建之后。
• 紧凑表所能创建的索引是有限的，并且不能在其上创建物化视图。

Reversing the clustering order

表的聚类顺序由该表的聚类列定义。默认情况下，该排序是基于聚类顺序的自然顺序，但是 CLUSTERING ORDER 允许您更改该聚类顺序，以便对某些 ( 可能是所有 ) 列使用相反的自然顺序。

CLUSTERING ORDER 选项接受以逗号分隔的集群列列表，每个列都有一个ASC ( 升序，例如自然顺序 ) 或 DESC ( 降序，例如相反的自然顺序 )。特别注意，默认值 ( 如果未使用 CLUSTERING ORDER ) 等同于对所有集群列使用ASC修饰符。

请注意，这个选项提示存储引擎改变存储行的顺序，但它有三个可预期的后果：

• 它限制了该表上允许的 ORDER BY 子句。您只能按聚类顺序或相反的聚类顺序对结果排序。这意味着如果一个表有两个聚类列 a 和 b，并且您定义 WITH CLUSTERING ORDER (a DESC, b ASC)，那么在查询中，只能使用聚类顺序 ORDER BY (a DESC, b ASC) 或 反向聚类顺序 ORDER BY (a ASC, b DESC)；不允许使用ORDER BY (a ASC, b ASC) (也不能使用ORDER BY (a DESC, b DESC))。
• 它也会在查询时改变结果的默认顺序 (如果没有使用 ORDER BY)。结果总是以在分区内的集群顺序返回。
• 它对某些查询的性能略有影响，因为反向聚类顺序的查询比正向聚类顺序的查询慢。在实践中，如果使用 列的反向自然顺序 进行查询 ( 这在时间序列中很常见，例如，查询 最新到最旧 的数据 )，声明降序聚类是一种优化。

Other table options

表支持以下选项：

Speculative retry options

默认情况下，Scylla读协调器只查询满足一致性级别所需的尽可能多的副本：一个用于一致性级别 ONE，一个用于QUORUM，等等。speculative_retry 决定协调器何时可以查询额外的副本，这在副本缓慢或无响应时很有用。以下是合法值 ( 不区分大小写 )：

此设置不会影响一致性级别为 ALL 的读取，因为它们已经查询了所有副本。
请注意，频繁地从其他副本读取会损害集群性能。如果有疑问，保留默认的99PERCENTILE 。

Compaction options 压实选项

compaction 选项必须至少定义“class”子选项，该子选项定义要使用的压缩策略类。默认支持的类是 'SizeTieredCompactionStrategy', 'LeveledCompactionStrategy', 'IncrementalCompactionStrategy', 和 'DateTieredCompactionStrategy'。自定义策略可以通过指定完整的类名作为字符串常量来提供。

所有默认策略都支持许多常见选项，以及特定于所选策略的选项 ( 有关详细信息，请参阅与策略对应的部分：STCS, LCS, ICS 和 TWCS )。不建议使用 DTCS，建议使用TWCS。

Compression options 压缩选项

compression 选项 定义 表中的sstable是否被压缩以及如何压缩。以下子选项是可用的：

例如，要启用压缩功能：

CREATE TABLE id (id int PRIMARY KEY) WITH compression = {'sstable_compression': 'LZ4Compressor'};

例如，要关闭压缩功能：

CREATE TABLE id (id int PRIMARY KEY) WITH compression = {};

CDC options

3.2新版功能：Scylla Open Source
以下选项可与 Change Data Capture 一起使用。

例如：

CREATE TABLE customer_data (
    cust_id uuid,
    cust_first-name text,
    cust_last-name text,
    cust_phone text,
    cust_get-sms text,
    PRIMARY KEY (customer_id)
) WITH cdc = { 'enabled' : 'true', 'preimage' : 'true' };

Caching options 缓存选项

缓存优化表的缓存内存使用。缓存的数据根据大小和访问频率进行权衡。

例如：

CREATE TABLE caching (
                 k int PRIMARY KEY,
                 v1 int,
                 v2 int,
             ) WITH caching = {'enabled': 'true'};

Encryption options 加密选项

加密选项 ( Encryption options ) 在启用或禁用静态加密时使用，从Scylla Enterprise 2019.1.1版本可用。

NOTE：
当 key_provider 为 LocalFileSystemKeyProviderFactory 时，必须使用 secret_key_file: 参数指明密钥所在的位置。见Encryption at Rest

Tombstones GC options

ScyllaDB继承了 Apache Cassandra 的 gc_grace_seconds 选项。该选项允许指定在通过压缩带有删除墓碑标记数据之前的等待时间(以秒为单位)。此选项假定您在指定的时间内运行 repair 。在等待时间内未能运行修复可能会导致已删除数据的恢复。

tombstone_gc 选项允许您阻止数据恢复。配置 repair 模式后，只有在执行 repair 后才会移除 tombstone。与 gc_grace_seconds 不同的是，tombstone_gc 没有时间限制 —— 当修复模式开启时，墓碑垃圾收集会一直等到修复运行。

tombstone_gc 选项可以通过 ALTER TABLE 和 CREATE TABLE 来启用。例如：

CREATE TABLE ks.cf (key blob PRIMARY KEY,  val blob) WITH tombstone_gc = {'mode':'repair'};

ALTER TABLE ks.cf WITH tombstone_gc = {'mode':'repair'} ;

NOTE：
tombstone_gc 选项在 ScyllaDB 5.0 中是作为实验特性添加的，默认情况下是禁用的。需要显式指定修复模式表属性才能启用该功能。

以下模式是可用的：

其他需要考虑的：

• 添加新列 (参见下面的 ALTER TABLE ) 是一个常量时间操作。因此，在创建表时不需要尝试预测未来的使用情况。

Limiting the rate of requests per partition

您可以通过对 CREATE TABLE 或 ALTER TABLE 语句应用ScyllaDB CQL扩展来限制对分区的读速率和写速率。有关详细信息，请参见 每分区速率限制 ( Per-partition rate limit )。

ALTER TABLE

修改已存在的表使用ALTER table语句：

alter_table_statement: ALTER TABLE `table_name` `alter_table_instruction`
alter_table_instruction: ADD `column_name` `cql_type` ( ',' `column_name` `cql_type` )*
                       : | DROP `column_name`
                       : | DROP '(' `column_name` ( ',' `column_name` )* ')'
                       : | ALTER `column_name` TYPE `cql_type`
                       : | WITH `options`
                       : | scylla_encryption_options: '=' '{'[`cipher_algorithm` : <hash>]','[`secret_key_strength` : <len>]','[`key_provider`: <provider>]'}'

例如：

ALTER TABLE addamsFamily ADD gravesite varchar;

ALTER TABLE addamsFamily
       WITH comment = 'A most excellent and useful table'
       AND read_repair_chance = 0.2;


ALTER TABLE data_atrest (
    pk text PRIMARY KEY,
    c0 int
) WITH scylla_encryption_options = {
   'cipher_algorithm' : 'AES/ECB/PKCS5Padding',
   'secret_key_strength' : 128,
   'key_provider': 'LocalFileSystemKeyProviderFactory',
   'secret_key_file': '/etc/scylla/data_encryption_keys/secret_key'};

ALTER TABLE customer_data
   WITH cdc = { 'enabled' : 'true', 'preimage' : 'true' };

ALTER TABLE语句可以：

• 向表中添加新列 ( 通过Add指令 )。请注意，表的主键是不能更改的，因此，通过扩展，新添加的列将永远不会成为主键的一部分。另外，请注意紧凑表（compact tables）对列的添加有限制。请注意，在集群包含的数据量上，这将消耗常量时间。
• 从表中删除列。这将删除列及其所有内容，但请注意，虽然列立即不可用，但其内容仅在压缩期间惰性删除。也请注意下面的警告。由于惰性删除，在删除或包含在集群中的数据量中，Alter 操作消耗常量时间。
• 将列的数据类型更改为兼容的类型。
• 更改一些表选项 (通过 WITH 指令)。支持的选项与创建表时相同 ( 除了创建后不能更改的 COMPACT STORAGE 和 CLUSTERING ORDER )。注意，设置任何压缩子选项 compaction 都有擦除之前所有压缩选项 compaction 的效果，所以如果你想保留它们，你需要重新指定所有的子选项。同样的注意事项也适用于压缩 compression 子选项集。( 注意区分compaction 和 compression的区别！)
• 更改或添加上面的任何加密选项。
• 更改或添加上述任何CDC选项。
• 更改或添加每个分区的速率限制。参见限制每个分区的请求速率。

WARNING：
删除列时假定用于该列值的时间戳是以微妙为单位的“真实的”时间戳。使用以微秒为单位的“真实”时间戳是默认设置，也是强烈推荐的，但由于Scylla允许客户端在任何表上提供任何时间戳，因此理论上可以使用另一种约定。请注意，如果您这样做，将无法正常工作。

WARNING：
一旦一个列被删除，就允许重新添加一个与被删除的列同名的列，除非被删除的列的类型是一个(非冻结的)列(由于内部技术限制)。

DROP TABLE

删除表使用 DROP TABLE命令：

drop_table_statement: DROP TABLE [ IF EXISTS ] `table_name`

删除表会立即删除该表，包括它包含的所有数据和任何关联的二级索引。

NOTE：
默认情况下，当删除表或键空间时，会生成快照，以便稍后恢复。因此，磁盘空间保持不变，不会立即回收。请参阅本文或此FAQ条目。

如果未使用 IF EXISTS，且表不存在，则返回一个错误，在这种情况下，该操作是无操作。

NOTE：
删除具有物化视图的表是不允许的，并且会返回一个错误。为此，必须首先显式删除依赖于表的物化视图 ( materialized views )。有关详细信息，请参阅物化视图。

TRUNCATE

一张表可以使用 TRUNCATE 语句进行截断：

truncate_statement: TRUNCATE [ TABLE ] `table_name`

注意，为了与其他DDL语句保持一致，允许使用 TRUNCATE TABLE foo，但是表是当前唯一可以被截断的对象，因此 TABLE 关键字可以省略。
截断表将永久删除表中的所有现有数据，但不会删除表本身。

CAUTION：
不要在被截断的表上运行任何操作。截断操作是一种管理操作，在同一表上并行运行任何其他操作都可能导致截断表的数据处于未定义状态。

本篇笔记翻译自ScallyDB官方文档，详情见 Apache Cassandra Query Language (CQL) Reference

本栏目推荐文章
• UCB Data100：数据科学的原理和技巧：第十一章到第十五章
• UCB Data100：数据科学的原理和技巧：第十六章到第二十章
• UCB Data100：数据科学的原理和技巧：第一章到第五章
• UCB Data100：数据科学的原理和技巧：第六章到第十章
• easyui data-filter 不显示筛选框
• Dynamics 365 Finance Operations Data Event Catalog - Power Platform Convergence
• devmapper: Thin Pool has 162394 free data blocks which is less than minimum required 163840 free data blocks
• Azure Data Factory（十一）Data Flow 的使用解析
• Data Mining notes
• Load text: https://tensorflow.google.cn/tutorials/load_data/text

Definition Datadefinition data definition high-definition ultra-high-definition aaai_ultra-high-definition definition multiple of timestamp current_timestamp definition incorrect class definition duplicate错误 save high-definition screenshots definition optimization definition convex the