CREATE TABLE
定义新表的列。
Apache Cassandra 支持在选定的键空间中创建新表。使用IF NOT EXISTS
来抑制如果表已存在则出现的错误消息;不会创建任何表。一个静态列可以在一个分区的多行中存储相同的数据,然后使用单个SELECT
语句检索该数据。
表支持单个计数器列。
另请参阅:ALTER TABLE,DROP TABLE,CREATE CUSTOM INDEX(用于存储附加索引 (SAI)),CREATE INDEX(用于辅助索引 (2i))
语法
BNF 定义
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 ] [ column_mask ] [ PRIMARY KEY]
column_mask::= MASKED WITH ( DEFAULT | function_name '(' term ( ',' term )* ')' )
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 ] | options
clustering_order::= column_name (ASC | DESC) ( ',' column_name (ASC | DESC) )*
CREATE TABLE [ IF NOT EXISTS ] [<keyspace_name>.]<table_name> ( <column_definition> [ , ... ] | PRIMARY KEY (column_list) ) [ WITH [ <table_options> ] [ [ AND ] CLUSTERING ORDER BY [ <clustering_column_name> (ASC | DESC) ] ] [ [ AND ] ID = '<table_hash_tag>' ] ] ;
语法约定 | 描述 |
---|---|
大写 |
文字关键字。 |
小写 |
非文字。 |
|
变量值。用用户定义的值替换。 |
|
可选。方括号 ( |
|
组。圆括号 ( |
|
或。竖线 ( |
|
可重复。省略号 ( |
|
单引号 ( |
|
映射集合。大括号 ( |
集合、列表、映射或元组。尖括号 ( |
|
|
结束 CQL 语句。分号 ( |
|
用两个连字符 ( |
|
仅搜索 CQL:单引号 ( |
|
仅搜索 CQL:标识要覆盖模式和 solrConfig 文件中 XML 元素的实体和文字值。 |
column_definition
column_definition
table_options
调整数据处理,包括 I/O 操作、压缩和压缩。表属性选项使用以下语法
-
单个值:
<option_name> = '<value>'
-
多个值:
<option_name> = { '<subproperty>' : '<value>' [, ...] } [AND ...]
简单的 JSON 格式,用大括号括起来的逗号分隔的键值对列表。
如果未指定任何值,则使用默认值。 |
在 CREATE TABLE(或 ALTER TABLE)CQL 语句中,使用WITH
子句来定义表属性选项。用AND
分隔多个值。
CREATE TABLE [<keyspace_name>.]<table_name>
WITH option_name = '<value>'
AND option_name = {<option_map>};
- bloom_filter_fp_chance = <N>
-
SSTable 布隆过滤器的误报概率。当客户端请求数据时,布隆过滤器会在执行磁盘 I/O 之前检查行是否存在。值范围为 0 到 1.0,其中:
0
是用于启用最大可能布隆过滤器的最小值(使用最多的内存),1.0
是禁用布隆过滤器的最大值。
推荐设置: |
默认值:bloom_filter_fp_chance = '0.01'
- caching = { 'keys' : 'value', 'rows_per_partition' : 'value'}
-
优化缓存内存的使用,无需手动调整。根据大小和访问频率对缓存数据进行加权。协调此设置与 cassandra.yaml 文件中的全局缓存属性。有效值
-
ALL
-- 所有主键或行 -
NONE
-- 没有主键或行 -
<N>
: (每个分区仅限行) — 指定一个整数 默认值:{ 'keys': 'ALL', 'rows_per_partition': 'NONE' }
-
- cdc
-
在表上创建变更数据捕获 (CDC) 日志。
有效值
-
TRUE
- 创建 CDC 日志 -
FALSE
- 不要创建 CDC 日志
-
- comment = 'some text that describes the table'
-
提供有关表的文档。
输入对表旨在满足的查询类型的描述。 |
- default_time_to_live
-
TTL(生存时间)以秒为单位,其中零表示禁用。最大可配置值为
630720000
(20 年)。从 2018 年开始,过期时间戳可能会超过存储引擎支持的最大值;请参阅下面的警告。如果该值大于零,则为整个表启用 TTL,并将过期时间戳添加到每个列。每次更新数据时都会计算新的 TTL 时间戳,并且在所有数据过期后会删除该行。默认值:
0
(禁用)。由于2038 年问题,数据库存储引擎只能对
January 19 2038 03:14:07 UTC
之前的 TTL 时间戳进行编码。TTL 日期溢出策略决定是否拒绝或插入过期时间戳晚于最大日期的请求。 - gc_grace_seconds
-
数据被标记为墓碑(删除标记)后,在它有资格进行垃圾回收之前经过的秒数。默认值:864000(10 天)。默认值允许数据库在删除之前最大程度地提高一致性。
在单节点集群中,此属性可以安全地设置为零。您还可以为数据未明确删除的表降低此值,例如,仅包含设置了TTL 的数据的表,或设置了
default_time_to_live
的表。但是,如果您降低了gc_grace_seconds
的值,请考虑它与以下操作的交互-
提示重放:当节点宕机后恢复,其他节点会重放该节点在不可用期间排队的写操作(称为提示)。数据库不会重放创建后超过 gc_grace_seconds 的提示。在cassandra.yaml 文件中的max_hint_window 设置用于设置收集不可用节点提示的时间限制(默认值为 3 小时)。
-
批处理重放:与提示队列类似,批处理操作存储数据库变动,这些变动会按顺序重放。与提示一样,数据库不会重放创建后超过 gc_grace_seconds 的批处理变动。如果您的应用程序使用批处理操作,请考虑降低 gc_grace_seconds 会增加批处理写操作可能恢复已删除数据的可能性。cassandra.yaml 文件中的 configuration/cass_yaml_file.html#batchlog_replay_throttle[batchlog_replay_throttle] 属性可以对批处理重放过程进行一些控制。但是,最重要的因素是您使用的批处理的大小和范围。
-
- memtable_flush_period_in_ms
-
在与表关联的
memtables
刷新之前经过的毫秒数。当 memtable_flush_period_in_ms=0 时,memtable 将在以下情况下刷新-
达到刷新阈值
-
关闭时
-
在 nodetool flush 时
-
当 commitlogs 满了时 默认值:
0
-
- min_index_interval
-
索引摘要中索引条目之间的最小间隙。较低的 min_index_interval 意味着索引摘要包含来自索引的更多条目,这允许数据库搜索更少的索引条目来执行读取。较大的索引摘要也可能使用更多内存。min_index_interval 的值是索引最密集的采样。
- max_index_interval
-
如果所有索引摘要的总内存使用量达到此值,Apache Cassandra 会将最冷的 SSTables 的索引摘要减少到 max_index_interval 设置的最大值。max_index_interval 是与内存压力相关的最稀疏的采样。
- speculative_retry
-
配置快速读取保护。正常的读取请求只发送到满足一致性级别的足够多的副本节点。在快速读取保护中,即使满足一致性级别,也会向其他副本发送额外的读取请求。speculative_retry 属性指定了这些额外读取请求的触发器。
-
ALWAYS:协调器节点在每次读取该表后向所有其他副本发送额外的读取请求。
-
<X>百分位数:跟踪每个表的典型读取延迟(以毫秒为单位)。协调器节点检索正在读取的表的典型延迟时间,并计算该数字的 X%。如果协调器节点等待响应的时间超过了计算出的数字,则会发送冗余读取请求。
例如,如果 Table_A 的 speculative_retry 属性设置为
80percentile
,并且该表的典型延迟为 60 毫秒,则处理 Table_A 读取的协调器节点将首先发送一个正常的读取请求,并在 48 毫秒内(60 毫秒的 80%)没有收到任何响应的情况下发送冗余读取请求。 -
<N>ms:如果协调器节点在
N
毫秒内没有收到任何响应,则会向所有其他副本发送额外的读取请求。 -
NONE:协调器节点在读取该表后不会发送额外的读取请求。
-
压缩策略 | |||
---|---|---|---|
compression = { compression_map }
通过指定压缩算法class
,然后以简单的 JSON 格式指定子属性来配置compression_map
。
使用 |
compression = {
['class' : '<compression_algorithm_name>',
'chunk_length_in_kb' : '<value>',
'crc_check_chance' : '<value>',]
| 'sstable_compression' : '']
}
- class
-
设置压缩器名称。Apache Cassandra 提供以下内置类
压缩算法 Cassandra 类 压缩 解压缩 比率 C* 版本 LZ4Compressor
A+
A+
C+
>=1.2.2
LZ4Compressor
C+
A+
B+
>= 3.6
ZstdCompressor
A-
A-
A+
>= 4.0
SnappyCompressor
A-
A
C
>= 1.0
DeflateCompressor
C
C
A
>= 1.0
仅使用与 Apache Cassandra 捆绑在一起的压缩实现。
选择合适的压缩器取决于您对节省空间而不是读取性能的要求。LZ4 的解压缩速度最快,其次是 Snappy,然后是 Deflate。压缩效率与解压缩速度成反比。Deflate 或 Snappy 的额外压缩不足以弥补通用工作负载的性能下降,但对于存档数据,它们可能值得考虑。
默认值:
LZ4Compressor
。 - chunk_length_in_kb
-
块的大小(以 KB 为单位)。在磁盘上,SSTables 按块压缩,以允许随机读取。大于默认值的值可能会提高压缩率,但会增加读取发生时从磁盘读取数据的最小大小。默认值是压缩表的良好折衷方案。调整压缩大小以考虑读/写访问模式(通常一次请求多少数据)以及表中行的平均大小。
默认值:
64
。 - crc_check_chance
-
启用压缩后,每个压缩块都包含该块的校验和,用于检测磁盘位腐烂并避免腐败传播到其他副本。此选项定义在读取期间检查这些校验和的概率。默认情况下,它们始终被检查。设置为 0 表示禁用校验和检查,设置为 0.5 表示每隔一次读取检查一次。
默认值:
1.0
。 - sstable_compression
-
禁用压缩。指定一个空值。
compaction = {compaction_map}
定义写入后清理数据的策略。
语法使用简单的 JSON 格式
compaction = {
'class' : '<compaction_strategy_name>',
'<property_name>' : <value> [, ...] }
其中<compaction_strategy_name>是SizeTieredCompactionStrategy、TimeWindowCompactionStrategy或LeveledCompactionStrategy。
仅使用与 Apache Cassandra 捆绑在一起的压缩实现。有关更多详细信息,请参阅压缩。 |
通用属性
以下属性适用于所有压缩策略。
compaction = {
'class' : 'compaction_strategy_name',
'enabled' : (true | false),
'log_all' : (true | false),
'only_purge_repaired_tombstone' : (true | false),
'tombstone_threshold' : <ratio>,
'tombstone_compaction_interval' : <sec>,
'unchecked_tombstone_compaction' : (true | false),
'min_threshold' : <num_sstables>,
'max_threshold' : <num_sstables> }
- enabled
-
启用后台压缩。
-
true
运行次要压缩。 -
false
禁用次要压缩。
使用
nodetool enableautocompaction
开始运行压缩。 -
-
默认值:
true
- log_all
-
为整个集群激活高级日志记录。
默认值:
false
- only_purge_repaired_tombstone
-
启用此属性可以防止在
gc_grace_seconds
内未运行修复时数据恢复。如果修复之间的时间很长,数据库会保留所有墓碑。-
true
- 仅允许在已修复的 SSTables 上清除墓碑。 -
false
- 即使表未修复,也会在压缩期间清除 SSTables 上的墓碑。
默认值:
false
-
- tombstone_threshold
-
可回收墓碑与所有包含的列的比率。如果比率超过此限制,压缩将仅在该表上开始以清除墓碑。
默认值:
0.2
- tombstone_compaction_interval
-
SSTable 创建后压缩可以运行的秒数。当 SSTable 超过
tombstone_threshold
时,它有资格进行压缩。由于在进行单个 SSTable 压缩时可能无法删除墓碑,并且由于压缩是根据估计的墓碑比率触发的,因此此设置使两次单个 SSTable 压缩之间的最小间隔可调,以防止 SSTable 不断重新压缩。默认值:
86400
(1 天) - unchecked_tombstone_compaction
-
设置为
true
允许墓碑压缩在不预先检查哪些表有资格进行操作的情况下运行。即使没有此预先检查,Apache Cassandra 也会检查 SSTable 以确保删除墓碑是安全的。默认值:
false
- min_threshold
-
触发次要压缩的 SSTables 的最小数量。
限制:在
LeveledCompactionStrategy
中未使用。默认值:
4
- max_threshold
-
触发次要压缩之前的 SSTables 的最大数量。
限制:在
LeveledCompactionStrategy
中未使用。默认值:
32
SizeTieredCompactionStrategy
压缩类SizeTieredCompactionStrategy
(STCS) 在表满足min_threshold
时触发次要压缩。次要压缩不涉及键空间中的所有表。请参阅SizeTieredCompactionStrategy (STCS)。
默认压缩策略。 |
以下属性仅适用于 SizeTieredCompactionStrategy
compaction = {
'class' : 'SizeTieredCompactionStrategy',
'bucket_high' : <factor>,
'bucket_low' : <factor>,
'min_sstable_size' : <int> }
- bucket_high
-
大小分层压缩合并大小大致相同的 SSTables 集。数据库将每个 SSTable 的大小与节点上该表所有 SSTable 大小的平均值进行比较。它合并大小在 [average-size * bucket_low] 和 [average-size * bucket_high] 之间的 SSTables。
默认值:
1.5
- bucket_low
-
大小分层压缩合并大小大致相同的 SSTables 集。数据库将每个 SSTable 的大小与节点上该表所有 SSTable 大小的平均值进行比较。它合并大小在 [average-size * bucket_low] 和 [average-size * bucket_high] 之间的 SSTables。
默认值:
0.5
- min_sstable_size
-
STCS 将 SSTables 分组到桶中。分组过程将大小差异小于 50% 的 SSTables 分组在一起。对于小型 SSTables,此分组过程过于细粒度。如果您的 SSTables 很小,请使用此选项定义一个大小阈值(以 MB 为单位),低于该阈值的所有 SSTables 都属于一个唯一的桶。
默认值:
50
(MB)
不再支持SizeTieredCompactionStrategy (STCS) 的 |
TimeWindowCompactionStrategy
压缩类TimeWindowCompactionStrategy
(TWCS) 使用一系列时间窗口或桶来压缩 SSTables。TWCS 在每个连续的时间段内创建一个新的时间窗口。在活动时间窗口期间,TWCS 使用 STCS 将所有从内存中刷新的 SSTables 压缩成更大的 SSTables。在时间段结束时,所有这些 SSTables 都被压缩成一个单一的 SSTable。然后下一个时间窗口开始,该过程重复。请参阅TimeWindowCompactionStrategy (TWCS)。
STCS 的所有属性也适用于 TWCS。 |
以下属性仅适用于 TimeWindowCompactionStrategy
compaction = {
'class' : 'TimeWindowCompactionStrategy,
'compaction_window_unit' : <days>,
'compaction_window_size' : <int>,
'split_during_flush' : (true | false) }
- compaction_window_unit
-
用于定义桶大小的时间单位。该值基于 Java
TimeUnit
。有关有效值的列表,请参阅位于docs.oracle.com/javase/8/docs/api/java/util/concurrent/TimeUnit.html的 Java APITimeUnit
页面。默认值:
days
- compaction_window_size
-
每个桶的单位。
默认:
1
分层压缩策略
压缩类LeveledCompactionStrategy
(LCS) 创建固定大小、相对较小的 SSTable(默认 160 MB),并将它们分组到不同的层级中。在每个层级内,SSTable 保证不重叠。每个层级(L0、L1、L2 等)的大小都是前一个层级的 10 倍。与较低层级相比,较高层级的磁盘 I/O 更均匀且可预测,因为 SSTable 不断被压缩到越来越大的层级中。在每个层级中,行键都会合并到下一个层级中不重叠的 SSTable 中。参见 分层压缩策略 (LCS).
以下属性仅适用于分层压缩策略
compaction = {
'class' : 'LeveledCompactionStrategy,
'sstable_size_in_mb' : <int> }
- sstable_size_in_mb
-
使用分层压缩策略的 SSTable 的目标大小。虽然 SSTable 大小应该小于或等于 sstable_size_in_mb,但在压缩过程中,压缩可能会生成更大的 SSTable。当给定分区键的数据异常大时,就会发生这种情况。Apache Cassandra 数据库不会将数据拆分为两个 SSTable。
默认:
160
默认值 160 MB 可能效率低下,并对数据库索引和依赖索引的查询产生负面影响。例如,考虑在使用 (SAI) 索引的表中使用 sstable_size_in_mb 的更高值的好处。有关相关信息,请参见 压缩策略.
时间分层压缩策略(已弃用)
请改用 时间窗口压缩策略。 |
将特定时间段内写入的数据存储在同一个 SSTable 中。
- base_time_seconds
-
第一个时间窗口的大小。
默认:
3600
- max_sstable_age_days(已弃用)
-
如果 SSTable 最近的数据早于此属性,则 Apache Cassandra 不会压缩 SSTable。可以设置小数天数。
默认:
1000
- max_window_size_seconds
-
最大窗口大小(以秒为单位)。
默认:
86400
- timestamp_resolution
-
单位,<MICROSECONDS> 或 <MILLISECONDS>,与插入数据的 timestamps 相匹配。
默认:
MICROSECONDS
可选参数
表关键字
- CLUSTERING ORDER BY ( column_name ASC | DESC)
-
对行存储进行排序,以利用列的磁盘排序。指定排序可以提高查询结果的效率。选项包括
ASC
:升序(默认排序)DESC
:降序,反向排序 - ID
-
如果表意外使用 DROP TABLE 删除,请使用此选项 重新创建表 并运行提交日志重放以检索数据。
- index_name
-
索引的名称。用引号括起来以使用特殊字符或保留大小写。如果未指定名称,Apache Cassandra 将索引命名为:
<table_name>_<column_name>_idx
。 - keyspace_name
-
包含要索引的表的 keyspace 的名称。如果未指定名称,则使用当前 keyspace。
使用说明
如果列中已包含数据,则在执行此语句时会对其进行索引。创建索引后,当列中的数据发生更改时,索引会自动更新。
使用 CREATE INDEX
命令进行索引可能会影响性能。在创建索引之前,请了解何时以及 何时不创建索引。
限制:不支持对计数器列进行索引。
示例
创建以 UUID 作为主键的表
创建以 UUID 作为主键的 cyclist_name
表
CREATE TABLE IF NOT EXISTS cycling.cyclist_name (
id UUID PRIMARY KEY,
lastname text,
firstname text
);
创建复合主键
创建 cyclist_category
表并将数据以反向顺序存储
CREATE TABLE IF NOT EXISTS cycling.cyclist_category (
category text,
points int,
id UUID,
lastname text,
PRIMARY KEY (category, points)
)
WITH CLUSTERING ORDER BY (points DESC);
创建复合分区键
创建针对按年份的骑车手排名查询进行优化的表
CREATE TABLE IF NOT EXISTS cycling.rank_by_year_and_name (
race_year int,
race_name text,
cyclist_name text,
rank int,
PRIMARY KEY ((race_year, race_name), rank)
);
创建包含向量列的表
创建包含向量列的表
CREATE TABLE IF NOT EXISTS cycling.comments_vs (
record_id timeuuid,
id uuid,
commenter text,
comment text,
comment_vector VECTOR <FLOAT, 5>,
created_at timestamp,
PRIMARY KEY (id, created_at)
)
WITH CLUSTERING ORDER BY (created_at DESC);
创建包含冻结 UDT 的表
创建包含冻结用户定义类型 (UDT) 的 race_winners
表
CREATE TABLE IF NOT EXISTS cycling.race_winners (
cyclist_name FROZEN<fullname>,
race_name text,
race_position int,
PRIMARY KEY (race_name, race_position)
);
有关创建 UDT 的信息,请参见 创建用户定义类型。如果在用户定义类型创建中仅使用非集合字段,则可以创建未冻结的 UDT。如果表使用未冻结的 UDT 创建,则可以 更新和删除各个字段值。
创建包含 CDC 日志的表
为 cyclist_id
表创建更改数据捕获日志
CREATE TABLE IF NOT EXISTS cycling.cyclist_id (
lastname text,
firstname text,
age int,
id UUID,
PRIMARY KEY ((lastname, firstname), age)
);
必须在 cassandra.yaml 中启用 CDC 日志记录。
在启用 CDC 日志记录之前,请制定移动和使用日志信息的计划。达到磁盘空间限制后,对启用 CDC 的表的写入将被拒绝,直到释放更多空间。有关可用 CDC 设置的信息,请参见 更改数据捕获 (CDC) 空间设置。 |
以降序存储数据
以下示例显示了一个表定义,该定义将得分最高的类别存储在最前面。
CREATE TABLE IF NOT EXISTS cycling.cyclist_category (
category text,
points int,
id UUID,
lastname text,
PRIMARY KEY (category, points)
)
WITH CLUSTERING ORDER BY (points DESC);
从表 ID 恢复以进行提交日志重放
使用原始 ID 重新创建表,以便通过重放提交日志来恢复表数据
CREATE TABLE IF NOT EXISTS cycling.cyclist_emails (
userid text PRIMARY KEY,
id UUID,
emails set<text>
)
WITH ID = '1bb7516e-b140-11e8-96f8-529269fb1459';
要检索表的 ID,请查询 system_schema.tables
的 id
列。例如
SELECT id
FROM system_schema.tables
WHERE keyspace_name = 'cycling'
AND table_name = 'cyclist_emails';
要执行表的恢复,请参见 备份 以获取更多信息。