跳到主要内容

ALTER TABLE

Introduced or updated: v1.2.956

ALTER TABLE 可用于修改现有表的列、注释、Fuse 引擎选项、外部连接等属性，甚至可以与另一张表互换所有元数据。下列小节按能力进行划分。

列操作​

企业版功能
脱敏策略（MASKING POLICY）是企业版功能。 如需获取许可证，请联系 Databend 支持团队。

通过添加、转换、重命名、更改或删除列来修改表。

语法​

-- 在表末尾添加一列
ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name> 
ADD [ COLUMN ] <column_name> <data_type> [ NOT NULL | NULL ] [ DEFAULT <constant_value> ]

-- 在指定位置添加一列
ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name> 
ADD [ COLUMN ] <column_name> <data_type> [ NOT NULL | NULL ] [ DEFAULT <constant_value> ] [ FIRST | AFTER <column_name> ]

-- 添加一个虚拟计算列
ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name> 
ADD [ COLUMN ] <column_name> <data_type> AS (<expr>) VIRTUAL

-- 将存储计算列转换为常规列
ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name> 
MODIFY [ COLUMN ] <column_name> DROP STORED

-- 重命名列
ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name>
RENAME [ COLUMN ] <column_name> TO <new_column_name>

-- 更改数据类型
ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name> 
MODIFY [ COLUMN ] <column_name> <new_data_type> [ DEFAULT <constant_value> ]
       [ , [ COLUMN ] <column_name> <new_data_type> [ DEFAULT <constant_value> ] ]
       ...

-- 更改注释
ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name>
MODIFY [ COLUMN ] <column_name> [ COMMENT '<comment>' ]
[ , [ COLUMN ] <column_name> [ COMMENT '<comment>' ] ]
...
    
-- 为列设置/取消设置脱敏策略
ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name>
MODIFY [ COLUMN ] <column_name> SET MASKING POLICY <policy_name>
       [ USING ( <column_reference> [ , <column_reference> ... ] ) ]
       [ OPTIONS ( where_use_unmasked_value = <boolean> ) ]

ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name>
MODIFY [ COLUMN ] <column_name> UNSET MASKING POLICY

-- 删除一列
ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name> 
DROP [ COLUMN ] <column_name>
备注
  • 在添加或修改列时，仅接受常量值作为默认值。如果使用非常量表达式，将会报错。
  • 尚不支持使用 ALTER TABLE 添加存储计算列。
  • 当更改表列的数据类型时，存在转换错误的风险。例如，如果尝试将文本（String）列转换为数字（Float）列，可能会引发问题。
  • 当为列设置脱敏策略时，请确保策略中定义的数据类型（请参考 CREATE MASKING POLICY 语法中的 arg_type_to_mask 参数）与列的数据类型相匹配。
  • 如果策略需要额外的列，可结合 USING 子句使用，按照参数顺序列出对应的列；第一个参数始终代表正在脱敏的列。
  • 当声明了 USING (...) 时，必须至少提供被脱敏的列以及策略所需的其他列，并确保 USING 中的第一个标识符与正在修改的列一致。
  • 只有常规表支持绑定脱敏策略；视图、流表以及临时表均无法执行 SET MASKING POLICY。
  • 单个列最多只能附加一个安全策略（无论是列脱敏还是行级策略）。在重新绑定之前，请先移除原有策略。
  • 设置或取消设置脱敏策略需要拥有全局 APPLY MASKING POLICY 权限，或针对目标策略具有 APPLY/OWNERSHIP 权限，否则 ALTER TABLE 会被拒绝。
  • 添加或移除 Row Access Policy 需要拥有目标表的 ALTER 权限，并拥有全局 APPLY ROW ACCESS POLICY 权限或针对目标策略具有 APPLY/OWNERSHIP 权限。描述或删除策略需要相同的策略权限。
警告

如果列已绑定脱敏策略，修改列定义或删除该列前必须先执行 ALTER TABLE ... MODIFY COLUMN <col> UNSET MASKING POLICY，否则操作会因安全策略仍然生效而失败。

脱敏策略 WHERE 选项​

从 v1.2.956 开始，OPTIONS (where_use_unmasked_value = true) 允许在符合条件的 SELECT WHERE 表达式中使用绑定列的原始值。默认值为 false。请使用不带引号的布尔字面量 true 或 false。

此授权属于列绑定，而不是策略定义、角色或会话。它影响读取此绑定的所有用户。选出的值仍然脱敏。其他表达式上下文，包括 JOIN ON、GROUP BY、HAVING 和 ORDER BY，仍然使用脱敏值。

警告

用户可以根据谓词的匹配结果或行数推断原始值。只有可以接受此类信息披露时，才应启用此选项。

修改选项时，请使用与现有绑定相同的策略和 USING 列。如有 USING，将 OPTIONS 放在其后。要更换策略或参数列，请先执行 UNSET MASKING POLICY。

设置为 false、再次执行不带 OPTIONS 的 SET MASKING POLICY，或取消策略绑定，都会清除此选项。通常的表权限和策略权限要求仍然适用。

有关示例、别名和子查询的适用范围，以及混合版本部署的限制，请参阅在 SELECT WHERE 中按原始值过滤。

示例​

示例 1：添加、重命名和删除列​

CREATE TABLE default.users (
  username VARCHAR(50) NOT NULL,
  email VARCHAR(255),
  age INT
);

ALTER TABLE default.users
ADD COLUMN business_email VARCHAR(255) NOT NULL DEFAULT 'example@example.com';

ALTER TABLE default.users
ADD COLUMN id int NOT NULL FIRST;

ALTER TABLE default.users
ADD COLUMN middle_name VARCHAR(50) NULL AFTER username;

ALTER TABLE default.users
RENAME COLUMN age TO new_age;

ALTER TABLE default.users
DROP COLUMN new_age;

示例 2：修改列与脱敏策略​

ALTER TABLE users
MODIFY COLUMN age BIGINT DEFAULT 18,
       COLUMN email VARCHAR(320) DEFAULT '';

ALTER TABLE users
MODIFY COLUMN email SET MASKING POLICY pii_email USING (email, username);

ALTER TABLE users
MODIFY COLUMN email UNSET MASKING POLICY;

Row Access Policy 操作​

企业版功能
ROW ACCESS POLICY是企业版功能。 如需获取许可证，请联系 Databend 支持团队。

为表绑定或解除 Row Access Policy。行访问策略会在查询时以及 DML 目标行匹配时过滤行。

语法​

-- 为表添加行访问策略
ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name>
ADD ROW ACCESS POLICY <policy_name> ON ( <column_name> [ , <column_name> ... ] )

-- 从表上移除指定行访问策略
ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name>
DROP ROW ACCESS POLICY <policy_name>

-- 移除表上的所有行访问策略
ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name>
DROP ALL ROW ACCESS POLICIES
备注
  • Row Access Policy 当前为实验性功能。可通过 SET enable_experimental_row_access_policy = 1 或 SET GLOBAL enable_experimental_row_access_policy = 1 启用。
  • 一张表同一时间最多只能绑定一个 Row Access Policy。
  • ON (...) 中的列会按位置绑定到策略参数。列数量和数据类型必须与策略签名匹配。
  • Row Access Policy 只能绑定到常规表；视图、流表和临时表不支持 ADD ROW ACCESS POLICY。
  • 单个列最多只能附加一个安全策略：脱敏策略或行访问策略二选一。
  • 添加或移除 Row Access Policy 需要拥有目标表的 ALTER 权限，并拥有全局 APPLY ROW ACCESS POLICY 权限或针对目标策略具有 APPLY/OWNERSHIP 权限。描述或删除策略需要相同的策略权限。
警告

修改或删除受保护列前，必须先解除行访问策略。否则该列仍被安全策略引用，语句会执行失败。

示例​

SET enable_experimental_row_access_policy = 1;

CREATE TABLE employees(id INT, name STRING, department STRING);

CREATE ROW ACCESS POLICY rap_engineering
AS (dept STRING)
RETURNS BOOLEAN -> dept = 'Engineering';

ALTER TABLE employees
ADD ROW ACCESS POLICY rap_engineering ON (department);

ALTER TABLE employees
DROP ROW ACCESS POLICY rap_engineering;

表注释​

用于修改表的注释。如果表尚未设置注释，该命令会为表添加指定的注释。

语法​

ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name> 
COMMENT = '<comment>'

示例​

CREATE TABLE t(id INT) COMMENT ='original-comment';
ALTER TABLE t COMMENT = 'new-comment';

CREATE TABLE s(id INT);
ALTER TABLE s COMMENT = 'new-comment';

为 Fuse 表添加分区​

为现有 Fuse 表添加物理分区键。

语法​

ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name>
PARTITION BY ( <expr> [ , <expr> ... ] )

使用说明​

  • 每个分区表达式必须是确定性的，并且只能引用一个源列。
  • 只修改表定义。已有数据不会重新分布，之后写入的数据才会分区。
  • 请对空表执行。对已有数据的表执行后，在重写整张表之前，对已有行执行 UPDATE、DELETE 和 MERGE INTO 都会失败。参见为已有表添加分区键。
  • 重复执行相同的定义不会产生变化；换成不同的定义会失败，需要先执行 DROP PARTITION KEY。
  • 分区键引用的列不能删除，也不能修改数据类型。重命名被引用的列时，分区表达式会同步更新。
  • 当 Catalog、Database 或 Table 不存在时，IF EXISTS 会忽略错误。
  • 该操作仅支持 Fuse Engine 表。

示例​

CREATE TABLE events (
    event_id   BIGINT,
    event_time TIMESTAMP,
    payload    VARIANT
);

-- 已有数据保持原来的物理布局。
ALTER TABLE events
PARTITION BY (DATE_TRUNC(day, event_time));

-- 后续写入使用按天划分的物理分区。
INSERT INTO events VALUES
    (1, '2026-07-08 10:00:00', PARSE_JSON('{"type":"login"}'));

有关分区键选择、哈希分区和查询裁剪示例，请参见 Fuse 表分区。

删除分区键​

删除 Fuse 表的分区键。

语法​

ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name>
DROP PARTITION KEY

使用说明​

  • 只修改元数据，已有数据不会重写。
  • 已有 Block 不再做分区裁剪，之后的写入不再分区。
  • WRITE_DISTRIBUTION_MODE 重置为 'none'。
  • 之后可以用 ALTER TABLE ... PARTITION BY 再次添加分区键。

示例​

ALTER TABLE events DROP PARTITION KEY;

行级 TTL​

从 v1.2.953 开始，MATERIALIZE TTL 会根据表中已存储的 TTL 定义删除过期行。SET TTL 用于替换或添加定义，REMOVE TTL 用于移除定义。修改定义本身不会删除行。这三种操作都需要表的 ALTER 权限。

语法​

ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name>
SET TTL <time_column> [ + INTERVAL <nonnegative_integer> <unit> ]

ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name> REMOVE TTL

ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name> MATERIALIZE TTL

有关支持的列类型、间隔单位和表达式限制，请参阅 CREATE TABLE：行级 TTL。

清理行为​

MATERIALIZE TTL 同步执行删除，并保持 TTL 定义不变。定义 TTL 不会创建定时清理任务，也不会使过期行在普通查询中自动隐藏。

令 cutoff 表示此命令捕获的当前时间。清理使用以下比较规则：

已存储的定义删除行的条件
TTL time_columnCAST(time_column AS TIMESTAMP) <= cutoff
TTL time_column + INTERVAL n unitCAST(time_column AS TIMESTAMP) < cutoff - INTERVAL n unit

保留时长形式使用严格的小于比较。它先从截止时间中减去间隔，再进行比较。不要将其替换为 time_column + interval <= cutoff，因为在日历边界处可能产生不同结果。时间转换和间隔运算遵循 SQL 时区规则。时间值为 NULL 的行不会被删除。

TTL 清理使用已存储的数据，而非查询可见的数据

此命令需要表的 ALTER 权限。它根据原始存储值进行判断，并删除所有过期行，包括被行访问策略隐藏的行。列脱敏不会改变哪些行会过期。因此，脱敏后的 SELECT 不能可靠地预览删除范围。运行清理前，请检查 TTL 定义。

示例​

CREATE TABLE ttl_events (id INT, expires TIMESTAMP) TTL expires;

INSERT INTO ttl_events VALUES
  (1, '2000-01-01 00:00:00'),
  (2, '2099-01-01 00:00:00'),
  (3, NULL);

ALTER TABLE ttl_events MATERIALIZE TTL;

SELECT id FROM ttl_events ORDER BY id;
-- 2
-- 3

ALTER TABLE ttl_events SET TTL expires + INTERVAL 1 DAY;
SHOW CREATE TABLE ttl_events;

ALTER TABLE ttl_events REMOVE TTL;

示例结果假设命令在 2000-01-01 之后、2099-01-01 之前运行。

限制与表结构变更​

  • 只有持久化 Fuse 表支持 TTL。不支持临时表和瞬态表。
  • MATERIALIZE TTL 要求表已有 TTL 定义。表没有定义时会报错。IF EXISTS 会跳过不存在的表，但不会跳过缺少 TTL 定义的表。
  • MATERIALIZE TTL 不能在显式事务内运行。
  • 表没有 TTL 时，REMOVE TTL 不执行任何操作。它不会恢复已删除的行。
  • TTL 引用的列不能被删除。类型变更必须保持 TTL 有效。重命名列会同步更新已存储定义中的列名。
  • 如果提交重试期间 TTL 定义发生变化，清理会失败并返回 TTL definition changed; retry MATERIALIZE TTL。重试前，请检查新定义。

Fuse 引擎选项​

Introduced or updated: v1.2.955

用于设置或取消设置表的 Fuse 引擎选项。

语法​

ALTER TABLE [ <database_name>. ]<table_name> SET OPTIONS (<options>)
ALTER TABLE [ <database_name>. ]<table_name> UNSET OPTIONS (<options>)

可以取消设置的 Fuse 引擎选项包括：

  • block_per_segment
  • block_size_threshold
  • data_retention_period_in_hours
  • data_retention_num_snapshots_to_keep
  • enable_schema_evolution
  • row_avg_depth_threshold
  • row_per_block
  • row_per_page
  • s3_storage_class

S3_STORAGE_CLASS 仅适用于非临时外部 S3 Fuse 表，支持 standard 和 intelligent_tiering，不区分大小写。SET OPTIONS 只影响后续写入，不更改已有 S3 对象。UNSET OPTIONS 移除表级设置，不会重新继承数据库默认值。操作流程和限制请参阅外部表。

示例​

CREATE TABLE fuse_table (a int);
SET hide_options_in_show_create_table=0;
SHOW CREATE TABLE fuse_table;

ALTER TABLE fuse_table SET OPTIONS (block_per_segment = 500, data_retention_period_in_hours = 240);
SHOW CREATE TABLE fuse_table;
CREATE OR REPLACE TABLE t(c INT);
ALTER TABLE t SET OPTIONS(data_retention_num_snapshots_to_keep = 1);
SET enable_auto_vacuum = 1;
INSERT INTO t VALUES(1);
INSERT INTO t VALUES(2);
INSERT INTO t VALUES(3);

ALTER TABLE fuse_table UNSET OPTIONS (block_per_segment, data_retention_period_in_hours);

外部表连接​

更新外部表的连接设置。执行命令时，仅凭证相关字段（access_key_id、secret_access_key、role_arn）会被应用，bucket、region、root 等其他属性保持不变。

语法​

ALTER TABLE [ <database_name>. ]<table_name> CONNECTION = ( connection_name = '<connection_name>' )
参数说明是否必需
connection_name要用于该外部表的连接名称，必须是系统中已存在的连接。是

该命令适用于凭证轮换或 IAM 角色变更场景。在执行之前，目标连接必须已经创建。

安全最佳实践

  • 无需存储访问密钥，避免泄露风险。
  • 自动轮换凭证，减少人工维护。
  • 具备更细粒度的访问控制能力。

如需在 Databend Cloud 中使用 IAM 角色，请参阅 Authenticate with AWS IAM Role。

示例​

CREATE CONNECTION external_table_conn
    STORAGE_TYPE = 's3'
    ACCESS_KEY_ID = '<your-access-key-id>'
    SECRET_ACCESS_KEY = '<your-secret-access-key>';

CREATE CONNECTION external_table_conn_new
    STORAGE_TYPE = 's3'
    ACCESS_KEY_ID = '<your-new-access-key-id>'
    SECRET_ACCESS_KEY = '<your-new-secret-access-key>';

CREATE OR REPLACE TABLE external_table_test (
    id INT,
    name VARCHAR,
    age INT
)
's3://testbucket/13_fuse_external_table/'
CONNECTION=(connection_name = 'external_table_conn');

ALTER TABLE external_table_test CONNECTION=( connection_name = 'external_table_conn_new' );
CREATE CONNECTION s3_access_key_conn
    STORAGE_TYPE = 's3'
    ACCESS_KEY_ID = '<your-access-key-id>'
    SECRET_ACCESS_KEY = '<your-secret-access-key>';

CREATE TABLE sales_data (
    order_id INT,
    product_name VARCHAR,
    quantity INT
)
's3://sales-bucket/data/'
CONNECTION=(connection_name = 's3_access_key_conn');

CREATE CONNECTION s3_role_conn
    STORAGE_TYPE = 's3'
    ROLE_ARN = 'arn:aws:iam::123456789012:role/databend-access';

ALTER TABLE sales_data CONNECTION=( connection_name = 's3_role_conn' );

快照标签操作​

Introduced or updated: v1.2.891

创建或删除引用特定 FUSE 表快照的命名快照标签。快照标签允许您为表的某个时间点状态创建书签，以便稍后通过 AT 子句进行查询。

完整语法和示例请参阅：

备注

快照标签与治理标签不同。快照标签为表快照创建书签用于时间回溯，而治理标签为对象附加键值元数据用于分类。

交换表​

在同一个事务中交换两张表的所有元数据和数据，使双方的列、约束以及数据完全互换。

语法​

ALTER TABLE [ IF EXISTS ] <source_table_name> SWAP WITH <target_table_name>
参数说明
source_table_name要交换的第一张表
target_table_name要交换的第二张表

使用说明​

  • 仅支持 Fuse 引擎表，外部表、系统表等其他类型不支持。
  • 临时表无法与永久表或瞬态表交换。
  • 当前角色必须同时拥有两张表的所有权。
  • 两张表必须位于同一个数据库，无法跨库交换。
  • 操作为原子事务，要么全部成功，要么全部回滚。
  • 操作不会丢失数据，双方的数据与元数据都会被完整保留。

示例​

CREATE OR REPLACE TABLE t1(a1 INT, a2 VARCHAR, a3 DATE);
CREATE OR REPLACE TABLE t2(b1 VARCHAR);

DESC t1;
DESC t2;

ALTER TABLE t1 SWAP WITH t2;

DESC t1;
DESC t2;

Tag 操作​

为表分配或移除治理标签。治理标签是用于分类和数据治理的键值元数据。Tag 必须先通过 CREATE TAG 创建。完整说明请参阅 SET TAG / UNSET TAG。

语法​

ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name>
    SET TAG <tag_name> = '<value>' [, <tag_name> = '<value>' ...]

ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name>
    UNSET TAG <tag_name> [, <tag_name> ...]

示例​

ALTER TABLE default.users SET TAG env = 'prod', owner = 'team_a';
ALTER TABLE default.users UNSET TAG env, owner;
指出文档中的错误或问题，我们将会赠予您专属纪念 T 恤一件！
问题反馈
提 issue
用户 ue**ke@163.com 指出问题【注释与命令不符，拼写错误】，获得 Tshirt 一件
加入我们的社区
GitHub
🌟 9.5K Stars
知乎
bilibili
开源中国
欢迎体验 Databend Cloud

基于 Rust + 对象存储构建的新一代多模态数仓，一个平台即可进行 BI、向量、全文检索及地理空间分析。

支持标准 SQL，自动弹性伸缩，助您快速构建现代化数据平台。

注册即领 ￥200 代金券。

注册体验