diff --git a/zh_CN/sql-reference/statements/alter.md b/zh_CN/sql-reference/statements/alter.md index 1cfb20e..922aff5 100644 --- a/zh_CN/sql-reference/statements/alter.md +++ b/zh_CN/sql-reference/statements/alter.md @@ -14,26 +14,64 @@ ALTER 语句用于修改已有对象。当前主要包括: ## ALTER TABLE +`ALTER TABLE` 用于修改已有表的结构、表选项或表名,支持在一条语句中组合多个操作,多个操作之间使用逗号分隔。 + +### 语法 + +```sql +ALTER TABLE table_name alter_action [, alter_action ...]; + +alter_action: + ADD COLUMN column_definition +| DROP COLUMN column_name +| MODIFY OPTIONS option_name = option_value [, option_name = option_value ...] +| RENAME new_table_name +``` + ### ADD COLUMN ADD COLUMN子句可用于向表中添加指定类型的新列。 -```SQL +```sql -- 在表 `table_name` 中添加一个新列 `k`, 类型为 INT ALTER TABLE table_name ADD COLUMN k INT; -- 在表 `table_name` 中添加一个新列 `l`,类型为 INT,默认值为 10 ALTER TABLE table_name ADD COLUMN l INT DEFAULT 10; ``` +如需一次新增多个列,需要重复编写 `ADD COLUMN` 子句: +```sql +ALTER TABLE table_name + ADD COLUMN length INT32, + ADD COLUMN city STRING; +``` + +不支持以下在一个子句中添加多列的写法: +```sql +ALTER TABLE table_name ADD COLUMN (length INT32, city STRING); +``` + ### DROP COLUMN DROP COLUMN子句可用于从表中删除列。 -```SQL +```sql -- 从 `table_name` 中删除列 k ALTER TABLE table_name DROP column k; ``` +如需一次删除多个列,需要重复编写 `DROP COLUMN` 子句: +```sql +ALTER TABLE table_name + DROP COLUMN length, + DROP COLUMN city; +``` + +不支持以下在一个子句中删除多列的写法: +```sql +ALTER TABLE table_name DROP COLUMN length, city; +``` + ::: tip 列只有在没有任何索引依赖时才能被删除。如:PRIMARY KEY、UNIQUE等。 ::: @@ -42,20 +80,76 @@ ALTER TABLE table_name DROP column k; 修改 Table Options。 -```SQL +```sql -- Modify options of a table ALTER TABLE table_name MODIFY OPTIONS ttl='10d', memtable_size='64M'; ``` +`MODIFY OPTIONS` 内部也使用逗号分隔多个选项,因此它既可以单独使用,也可以与其他 `ALTER TABLE` 子句组合。 + ### RENAME 修改 Table 的名字。 -```SQL +```sql -- Modify name of a table ALTER TABLE table_name rename new_name; ``` +### 多操作示例 + +以下写法在一个 `ALTER TABLE` 语句中同时执行多个变更: + +```sql +ALTER TABLE sx1 + ADD COLUMN sid INT32, + DROP COLUMN flag, + RENAME sx2; + +ALTER TABLE sx1 + MODIFY OPTIONS ttl = '10d', memtable_size = '32M', + ADD COLUMN sid INT32; + +ALTER TABLE sx1 + ADD COLUMN sid INT32, + ADD COLUMN city STRING, + DROP COLUMN flag, + MODIFY OPTIONS ttl = '10d'; +``` + +### 多操作的优先级 + +当一个 `ALTER TABLE` 语句中包含可能存在冲突的多个变更时,遵照以下的优先级策略: + +- 先执行所有的 `DROP COLUMN` 操作; +- 最后执行所有的 `ADD COLUMN` 操作; + +下面列举了几个可能存在冲突的场景示例,实际可能冲突场景更多,使用时请参考最佳建议和使用限制: + +```sql +-- 原表中包含列 a, b, c + +-- 同时增加同名的列 +ALTER TABLE ADD COLUMN d int32, ADD COLUMN d real; + +-- 同时增加并删除同名的列 +-- 失败,因为先 DROP 时找不到列 d +ALTER TABLE ADD COLUMN d int32, DROP COLUMN d; +-- 成功,因为先 DROP 原列 c 再创建新的列 c +ALTER TABLE ADD COLUMN c int32, DROP COLUMN c; +``` + +::: tip +最佳建议是避免出现冲突,不要依赖优先级策略来解决逻辑顺序问题,这类场景建议拆分成多条 SQL。 +::: + +### 使用限制 + +- 多个操作之间必须显式写出操作关键字,例如 `ADD COLUMN ... , ADD COLUMN ...`。不能省略第二个操作的关键字; +- 不要依赖语句中各个操作的书写顺序来推断底层执行顺序,建议让每个操作彼此独立、避免互相依赖; +- 时序表引擎支持在一条语句中组合 `ADD COLUMN`、`DROP COLUMN`、`MODIFY OPTIONS` 和 `RENAME`; +- 关系引擎当前不支持在单条 `ALTER TABLE` 语句中混合多种不同类型的操作;这类场景建议拆分为多条 SQL。 + ## ALTER PIPELINE 当前流计算相关的 `ALTER` 语句只支持 pipeline 生命周期管理。