ALTER TABLE

修改表的列和属性。

添加新列、删除现有列、重命名列和修改表属性。该命令不返回任何结果。

ALTER COLUMNFAMILY 已弃用。

另请参见： CREATE TABLE、DROP TABLE、CREATE CUSTOM INDEX（用于存储附加索引 (SAI)）、CREATE INDEX（用于二级索引 (2i)）

语法

BNF 定义

alter_table_statement::= ALTER TABLE [ IF EXISTS ] table_name alter_table_instruction
alter_table_instruction::= ADD [ IF NOT EXISTS ] column_definition ( ',' column_definition)*
	| DROP [ IF EXISTS ] column_name ( ',' column_name )*
	| RENAME [ IF EXISTS ] column_name to column_name (AND column_name to column_name)*
	| ALTER [ IF EXISTS ] column_name ( column_mask | DROP MASKED )
	| WITH options
column_definition::= column_name cql_type [ column_mask]
column_mask::= MASKED WITH ( DEFAULT | function_name '(' term ( ',' term )* ')' )

ALTER TABLE [<keyspace_name>.]<table_name>
  [ ADD ( <column_definition> | <column_definition_list> ) [ , ... ] ]
  [ DROP <column_name> [ , ... ] ]
  [ [ RENAME <column_name> TO <column_name> ] ]
  [ WITH <table_properties> [ , ... ] ];

语法图例

图例
语法约定	描述
大写	文字关键字。
小写	非文字。
`< >`	变量值。用用户定义的值替换。
`[]`	可选。方括号 (`[]`) 包含可选的命令参数。不要输入方括号。
`( )`	组。圆括号 ( `( )` ) 标识要从中选择的组。不要输入圆括号。
`\|`	或。竖线 (`\|`) 分隔备选元素。输入其中任何一个元素。不要输入竖线。
`...`	可重复。省略号 ( `...` ) 表示您可以根据需要重复语法元素。
`'<文字字符串>'`	单引号 (`'`) 必须包围 CQL 语句中的文字字符串。使用单引号保留大写。
`{ <键> : <值> }`	映射集合。大括号 (`{ }`) 包含映射集合或键值对。冒号分隔键和值。
`<数据类型2`	集合、列表、映射或元组。尖括号 ( `< >` ) 包含集合、列表、映射或元组中的数据类型。用逗号分隔数据类型。
`<cql_语句>;`	结束 CQL 语句。分号 (`;`) 终止所有 CQL 语句。
`[--]`	用两个连字符 ( `--` ) 分隔命令行选项和命令参数。此语法在参数可能被误认为命令行选项时很有用。
`' <<schema\> ... </schema\>> '`	仅搜索 CQL：单引号 (`'`) 包含整个 XML 模式声明。
`@<xml_实体>='<xml_实体类型>'`	仅搜索 CQL：标识要覆盖模式和 solrConfig 文件中 XML 元素的实体和文字值。

必需参数

table_name: 要更改的表的名称。
column_name: 要更改、删除或添加的列的名称。

column_definition

在表名后用圆括号括起来，使用逗号分隔的列表定义多个列。所有表都必须至少有一个主键列。每个列都使用以下语法定义：column_name cql_type_definition [STATIC | PRIMARY KEY] [, ...]

限制

表必须至少有一个 PRIMARY KEY。
当 PRIMARY KEY 位于列定义的末尾时，该列是表的唯一主键，并定义为分区键[分区键]。
静态列不能是主键。
主键可以包含冻结集合。

column_name

为表中的每列使用唯一的名称。要保留大小写或使用特殊字符，请将名称用双引号括起来。

cql_type_definition

定义列中允许的数据类型。请参阅 CQL 数据类型或用户定义类型。

STATIC

可选，该列具有单个值。

PRIMARY KEY

当 PRIMARY KEY 为一列时，将 PRIMARY KEY 附加到列定义的末尾。这只是创建表所需的模式信息。当只有一个主键时，它是分区键；数据按此列中的唯一值进行划分和存储：column_name cql_type_definition PRIMARY KEY。

或者，您可以像声明复合主键一样声明仅包含一列的主键。

可选参数

keyspace_name

包含要更改的表的键空间的名称。如果未指定名称，则使用当前键空间。

ADD ( <column_definition> | <column_definition_list> )

添加一个或多个列并设置列数据类型。指定列名，后跟数据类型。列值会自动设置为 null。要添加多个列，请使用放在圆括号内的逗号分隔的列列表。

<column_name> <cql_type> [ , ]
[ <column_name> <cql_type> [ , ... ]

限制：在创建表后，不支持向主键添加列。

DROP ( <column> | <column_list> )

删除一个或多个列。行中包含的值也会被删除，无法恢复。要删除多个列，请使用放在圆括号内的逗号分隔的列列表。

RENAME <column_name> TO <column_name>

更改主键列的名称，并保留现有值。

限制：不支持物化视图基表或具有二级索引的表。

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 是禁用布隆过滤器的最大值。

推荐设置：0.1。较高的值会导致收益递减。

默认值：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 年问题，数据库存储引擎只能通过2038 年 1 月 19 日 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

配置快速读取保护。正常的读取请求只发送到满足一致性级别的足够多的副本节点。在快速读取保护中，即使满足一致性级别，也会向其他副本发送额外的读取请求。推测重试属性指定了这些额外读取请求的触发器。

ALWAYS：协调器节点在每次读取该表的之后，都会向所有其他副本发送额外的读取请求。
<X>百分位数：跟踪每个表的典型读取延迟（以毫秒为单位）。协调器节点检索正在读取的表的典型延迟时间，并计算该数字的 X%。如果协调器节点等待响应的时间超过了计算出的数字，则会发送冗余读取请求。

例如，如果 Table_A 的 speculative_retry 属性设置为80percentile，并且该表的典型延迟为 60 毫秒，则处理 Table_A 读取的协调器节点将首先发送一个正常的读取请求，如果在 48 毫秒内（即 60 毫秒的 80%）没有收到任何响应，则会发送冗余读取请求。
<N>ms：如果协调器节点在N毫秒内没有收到任何响应，则协调器节点会向所有其他副本发送额外的读取请求。
NONE：协调器节点在读取该表的之后不会发送额外的读取请求。

压缩策略
UCS	LCS	STCS	TWCS

压缩策略

table_properties

您可以修改现有表的属性。某些属性是设置为值的单个选项

<option_name> = <value> [ AND ... ]

例如，speculative_retry = '10ms'。将字符串属性的值用单引号括起来。

其他表属性使用 JSON 映射设置：option_name = { <subproperty_name> : <value> [ , ... ] }

有关更多详细信息，请参阅table_options。

使用说明

限制

只能重命名主键中的聚类列。
无法更改列的数据类型。
对于具有物化视图的表，即使列未在物化视图中使用，也无法从表中删除该列。
无法重命名或删除具有依赖的二级索引的列。
不要添加与现有列同名但数据类型不同的列。这将阻止提交日志重放并破坏包含旧数据的现有 SSTables。

示例

本节使用cyclist_races 表。

添加列

要添加列，请使用 ADD 指令

ALTER TABLE cycling.cyclist_races
ADD manager UUID;

要添加集合类型列

ALTER TABLE cycling.cyclist_races
ADD completed list<text>;

此操作不会验证现有数据。

限制：您不能使用ADD指令添加

与现有列同名的列
如果表没有聚类列，则添加静态列。

删除列

要从表中删除列，请使用 DROP 指令

ALTER TABLE cycling.cyclist_races
DROP manager;

DROP从表定义中删除列。该列在删除后立即无法用于查询。数据库在下次压缩期间删除列数据。

限制

如果您删除了列然后重新添加，Apache Cassandra 不会恢复在删除列之前写入的值。
不要重新添加包含由客户端生成的的时间戳的已删除列；您可以重新添加包含由写入时间工具生成的的时间戳的列。

重命名列

要重命名race_times 表中的列

ALTER TABLE cycling.race_times
RENAME race_date TO date;

限制：以下限制适用于RENAME

您只能重命名聚类列，这些列是主键的一部分。
您不能重命名分区键，因为分区键决定了节点上的数据存储位置。如果需要不同的分区名称，则必须重新创建表并将数据迁移。

使用RENAME时存在许多限制，因为 SSTables 是不可变的。要更改磁盘上数据的状态，必须重写所有内容。
您可以索引重命名的列。
如果已在列上创建索引，则无法重命名该列。
您不能重命名静态列。

修改表属性

要更改现有表的属性，请使用ALTER TABLE和WITH。您可以指定一个

单个属性名称和值。
属性映射以设置名称和值，如下一节关于压缩和压缩中所示。

例如，要使用 WITH 向cyclist_base 表添加注释

ALTER TABLE cycling.cyclist_base
WITH comment = 'basic cyclist information';

将文本属性值用单引号括起来。

修改压缩和压缩

使用属性映射来更改comments 表的压缩或压缩设置

ALTER TABLE cycling.cyclist_base
WITH comment = 'basic cyclist information';

将每个键的名称用单引号括起来。如果值为字符串，则也用引号括起来。

如果您更改了具有现有数据的表的压缩策略，数据库将使用新策略重写所有现有 SSTables。这可能需要数小时，这对生产系统来说可能是一个重大问题。有关最大限度地减少这种中断的策略，请参阅如何在生产集群上更改压缩策略和更改压缩策略的影响。

更改缓存

将comments 表的行缓存中存储的每个分区的行数设置为 10 行

ALTER TABLE cycling.comments
WITH caching = {
  'keys' : 'NONE',
  'rows_per_partition' : 10
};

更改推测重试

将cyclist_base表修改为推测重试的第 95 个百分位数

ALTER TABLE cycling.cyclist_base
WITH speculative_retry = '95percentile';

将cyclist_base表修改为使用 10 毫秒进行推测重试

ALTER TABLE cycling.cyclist_base
WITH speculative_retry = '10ms';

启用和禁用后台压缩

以下示例将enabled属性设置为false以禁用后台压缩

ALTER TABLE cycling.comments
WITH COMPACTION = {
  'class' : 'SizeTieredCompactionStrategy',
  'enabled' : 'false'
};

禁用后台压缩可能会有害：没有它，数据库不会重新获得磁盘空间，并且可能允许僵尸传播。虽然压缩使用 I/O，但在大多数情况下最好将其保持启用状态。

读取扩展压缩日志

将log_all子属性设置为true以收集有关节点上压缩活动的深入信息，这些信息存储在专用日志文件中。

如果您为任何节点上的任何表启用了扩展压缩日志记录，则它将为集群中所有节点上的所有表启用。

启用扩展压缩时，数据库会在 home/logs 中创建一个名为 compaction-%d.log 的文件（其中%d是顺序号）。

压缩日志记录服务会记录有关以下类型的压缩事件的详细信息

type:enable

列出以前已刷新的 SSTables。

{"type":"enable","keyspace":"test","table":"t","time":1470071098866,"strategies":
  [    {"strategyId":"0","type":"LeveledCompactionStrategy","tables":[],"repaired":true,"folders":
      ["/home/carl/oss/cassandra/bin/../data/data"]},
    {"strategyId":"1","type":"LeveledCompactionStrategy","tables":[],"repaired":false,"folders":
      ["/home/carl/oss/cassandra/bin/../data/data"]
    }
 ]
}

type: flush

记录从 memtable 到磁盘上的 SSTable 的刷新事件，包括每个表的压缩策略。

{"type":"flush","keyspace":"test","table":"t","time":1470083335639,"tables":
  [    {"strategyId":"1","table":
      {"generation":1,"version":"mb","size":106846362,"details":
        {"level":0,"min_token":"-9221834874718566760","max_token":"9221396997139245178"}
      }
    }
 ]
}

type: compaction

记录压缩事件。

{"type":"compaction","keyspace":"test","table":"t","time":1470083660267,
 "start":"1470083660188","end":"1470083660267","input":
  [    {"strategyId":"1","table":
      {"generation":1372,"version":"mb","size":1064979,"details":
        {"level":1,"min_token":"7199305267944662291","max_token":"7323434447996777057"}
      }
    }
 ],"output":
  [    {"strategyId":"1","table":
      {"generation":1404,"version":"mb","size":1064306,"details":
        {"level":2,"min_token":"7199305267944662291","max_token":"7323434447996777057"}
      }
    }
 ]
}

type: pending

列出压缩策略的挂起任务数量。

{"type":"pending","keyspace":"test","table":"t",
 "time":1470083447967,"strategyId":"1","pending":200}

查看表定义

使用DESCRIBE或DESC查看表定义。

DESC cycling.comments;

将返回表详细信息，包括列名。

CREATE TABLE cycling.comments (
    id uuid,
    created_at timestamp,
    comment text,
    commenter text,
    record_id timeuuid,
    PRIMARY KEY (id, created_at)
) WITH CLUSTERING ORDER BY (created_at DESC)
    AND bloom_filter_fp_chance = 0.01
    AND caching = {'keys': 'NONE', 'rows_per_partition': '10'}
    AND comment = ''
    AND compaction = {'class': 'org.apache.cassandra.db.compaction.SizeTieredCompactionStrategy', 'enabled': 'true', 'max_threshold': '32', 'min_threshold': '4'}
    AND compression = {'chunk_length_in_kb': '64', 'class': 'org.apache.cassandra.io.compress.DeflateCompressor'}
    AND crc_check_chance = 1.0
    AND default_time_to_live = 0
    AND gc_grace_seconds = 864000
    AND max_index_interval = 2048
    AND memtable_flush_period_in_ms = 0
    AND min_index_interval = 128
    AND speculative_retry = '99PERCENTILE';

Cassandra 文档

版本

ALTER TABLE

语法

必需参数

column_definition

可选参数

table_options

使用说明

示例

添加列

删除列

重命名列

修改表属性

修改压缩和压缩

更改缓存

更改推测重试

启用和禁用后台压缩

读取扩展压缩日志

查看表定义