Flink SQL ALTER 语句在线演进 Table/View/Function/Catalog/Model

1. ALTER 语句是干嘛的

ALTER 用来修改已经注册到 Catalog 里的对象定义，包括：

ALTER TABLE
ALTER VIEW
ALTER DATABASE
ALTER FUNCTION
ALTER CATALOG
ALTER MODEL

核心价值：让你在不重建对象的情况下，完成 schema 演进、主键/水位线调整、属性参数更新、重命名 等操作。

2. Java 如何执行 ALTER（和 CREATE / DROP 一样）

在 Java 中直接用 TableEnvironment.executeSql() 执行 ALTER，成功返回 OK，失败抛异常。

java 复制代码

EnvironmentSettings settings = EnvironmentSettings.newInstance()...
TableEnvironment tableEnv = TableEnvironment.create(settings);

tableEnv.executeSql("CREATE TABLE Orders (`user` BIGINT, product STRING, amount INT) WITH (...)");

// 1) 在第一列位置新增字段
tableEnv.executeSql("ALTER TABLE Orders ADD `order` INT COMMENT 'order identifier' FIRST");

// 2) 一次性新增多个组件：列、主键、水位线、列位置
tableEnv.executeSql(
  "ALTER TABLE Orders ADD (" +
  "  ts TIMESTAMP(3), " +
  "  category STRING AFTER product, " +
  "  PRIMARY KEY(`order`) NOT ENFORCED, " +
  "  WATERMARK FOR ts AS ts - INTERVAL '1' HOUR" +
  ")"
);

// 3) 修改：类型/NOT NULL/注释/位置/水位线策略
tableEnv.executeSql(
  "ALTER TABLE Orders MODIFY (" +
  "  amount DOUBLE NOT NULL, " +
  "  category STRING COMMENT 'category identifier' AFTER `order`, " +
  "  WATERMARK FOR ts AS ts" +
  ")"
);

// 4) 删除 watermark
tableEnv.executeSql("ALTER TABLE Orders DROP WATERMARK");

// 5) 删除列
tableEnv.executeSql("ALTER TABLE Orders DROP (amount, ts, category)");

// 6) 重命名列/表
tableEnv.executeSql("ALTER TABLE Orders RENAME `order` TO order_id");
tableEnv.executeSql("ALTER TABLE Orders RENAME TO NewOrders");

// 7) 修改 catalog 属性
tableEnv.executeSql("CREATE CATALOG cat2 WITH ('type'='generic_in_memory')");
tableEnv.executeSql("ALTER CATALOG cat2 SET ('default-database'='db')");

3. ALTER TABLE：最重要、最常用的一类

3.1 支持的动作总览（记住这 6 个就够了）

sql 复制代码

ALTER TABLE [IF EXISTS] table_name {
    ADD ...
  | MODIFY ...
  | DROP ...
  | RENAME old_column TO new_column
  | RENAME TO new_table_name
  | SET (...) | RESET (...)
}

你可以把它理解为：

ADD：加东西（列/主键/水位线/分区/桶）
MODIFY：改东西（列定义/位置/主键列/水位线策略/分布）
DROP：删东西（列/主键/水位线/分区/分布）
RENAME：改名（列/表）
SET/RESET：改属性（connector options 等）

4. ADD：给已有表"加能力"

4.1 新增列（默认加到最后，可指定 FIRST / AFTER）

sql 复制代码

ALTER TABLE MyTable ADD category_id STRING COMMENT 'identifier of the category';
ALTER TABLE MyTable ADD new_col STRING FIRST;
ALTER TABLE MyTable ADD new_col STRING AFTER old_col;

4.2 一次性新增：列 + 计算列 + 主键 + Watermark

这是生产最常用的"演进组合拳"：

sql 复制代码

ALTER TABLE MyTable ADD (
  log_ts STRING COMMENT 'log timestamp string' FIRST,
  ts AS TO_TIMESTAMP(log_ts) AFTER log_ts,
  PRIMARY KEY (id) NOT ENFORCED,
  WATERMARK FOR ts AS ts - INTERVAL '3' SECOND
);

4.3 新增分区（以及分区属性）

sql 复制代码

ALTER TABLE MyTable ADD PARTITION (p1=1,p2='a') WITH ('k1'='v1');
ALTER TABLE MyTable ADD
  PARTITION (p1=1,p2='a') WITH ('k1'='v1')
  PARTITION (p1=1,p2='b') WITH ('k2'='v2');

4.4 新增分布/桶（DISTRIBUTION）

sql 复制代码

ALTER TABLE MyTable ADD DISTRIBUTION BY HASH(uid) INTO 4 BUCKETS;
ALTER TABLE MyTable ADD DISTRIBUTION BY (uid) INTO 4 BUCKETS;
ALTER TABLE MyTable ADD DISTRIBUTION BY (uid);
ALTER TABLE MyTable ADD DISTRIBUTION INTO 4 BUCKETS;

重要提醒：把某列加入主键，会隐式把该列的可空性改成 NOT NULL（nullability 会变为 false）。

5. MODIFY：改列类型、位置、注释、可空性、主键与水位线

5.1 改字段定义（类型/注释/位置）

sql 复制代码

ALTER TABLE MyTable
MODIFY measurement DOUBLE COMMENT 'unit is bytes per second' AFTER id;

5.2 改 watermark 策略、主键列、计算列

注意：被 MODIFY 的列/组件必须已存在于 schema 中。

sql 复制代码

ALTER TABLE MyTable MODIFY (
  log_ts STRING COMMENT 'log timestamp string' AFTER id,
  ts AS TO_TIMESTAMP(log_ts) AFTER log_ts,
  PRIMARY KEY (id) NOT ENFORCED,
  WATERMARK FOR ts AS ts
);

同样提醒：把某列改成主键列，也会隐式变为 NOT NULL。

6. DROP：删列 / 主键 / watermark / 分区 / 分布

sql 复制代码

ALTER TABLE MyTable DROP measurement;
ALTER TABLE MyTable DROP (col1, col2, col3);

ALTER TABLE MyTable DROP PRIMARY KEY;

ALTER TABLE MyTable DROP PARTITION (`id` = 1);
ALTER TABLE MyTable DROP PARTITION (`id` = 1), PARTITION (`id` = 2);

ALTER TABLE MyTable DROP WATERMARK;

ALTER TABLE MyTable DROP DISTRIBUTION;

7. RENAME：改列名 / 改表名

sql 复制代码

ALTER TABLE MyTable RENAME request_body TO payload;
ALTER TABLE MyTable RENAME TO MyTable2;

8. SET / RESET：修改表属性（常用于 connector 参数）

8.1 SET：覆盖或新增属性

sql 复制代码

ALTER TABLE DataGenSource SET ('rows-per-second' = '10');

8.2 RESET：恢复属性默认值

sql 复制代码

ALTER TABLE DataGenSource RESET ('rows-per-second');

9. ALTER VIEW / DATABASE / FUNCTION / CATALOG / MODEL

9.1 ALTER VIEW：改名 or 改查询定义

sql 复制代码

ALTER VIEW my_view RENAME TO my_view_v2;
ALTER VIEW my_view AS SELECT ...;

9.2 ALTER DATABASE：更新库属性

sql 复制代码

ALTER DATABASE my_db SET ('k1'='v1', 'k2'='v2');

9.3 ALTER FUNCTION：替换 UDF 标识（类路径/全限定名）+ 语言

sql 复制代码

ALTER FUNCTION my_udf AS 'com.xxx.NewUdf' LANGUAGE JAVA;
ALTER TEMPORARY SYSTEM FUNCTION f AS 'com.xxx.F' LANGUAGE JAVA;

带 IF EXISTS 时：函数不存在就忽略，不报错。

9.4 ALTER CATALOG：SET / RESET / COMMENT

sql 复制代码

ALTER CATALOG cat2 SET ('default-database'='db');
ALTER CATALOG cat2 RESET ('default-database');
ALTER CATALOG cat2 COMMENT 'comment for catalog ''cat2''';

9.5 ALTER MODEL：SET / RESET / RENAME

sql 复制代码

ALTER MODEL MyModel SET ('model-version'='2.0', 'batch-size'='32');
ALTER MODEL MyModel RESET ('model-version', 'batch-size');
ALTER MODEL MyModel RENAME TO NewModel;

10. 最佳实践与常见坑（建议放到博客结尾）

复杂变更尽量用"一个 ALTER 多组件"：比如一次性加计算列 + watermark + 主键，避免多次演进导致不一致。
主键列会隐式 NOT NULL：这点会影响下游 sink（尤其是 upsert），提前确认数据里有没有 null。
watermark 修改属于"语义级变更"：会影响窗口计算、延迟、迟到数据处理，建议在灰度环境验证。
SET/RESET 特别适合做运行参数调节：例如 datagen 的速率、某些 connector 的行为开关，脚本化很好用。
尽量加 IF EXISTS（表/函数等支持时）：让运维脚本幂等，避免多环境重复执行失败。