Flink Table API & SQL 流式处理概念全解析:动态表、状态管理与算子级 State TTL 实战指南
Flink Table API & SQL 流式处理概念全解析:动态表、状态管理与算子级 State TTL 实战指南
Flink 的 Table API 与 SQL 是面向批流一体的统一关系型 API:无论输入是有界的批数据还是无界的流数据,查询都保持一致的语义。本文以 docs/content/docs/dev/table/concepts/overview.md 为核心骨架,深入讲解流式模式下 Table API & SQL 的状态管理机制——包括有状态算子的显式/隐式推导、空闲状态保留时间(Idle State Retention Time)、算子级状态 TTL 的三种配置方式(SET 语句、STATE_TTL Hint、修改 CompiledPlan JSON),以及有状态作业升级与状态演化的约束,并辅以仓库源码作为实现依据。读完本文,你将能独立判断一个流式查询"哪里用了状态、用了多少",并掌握为管道中不同算子设置差异化状态 TTL 的完整实战流程。
批流统一语义下的 Table API & SQL
Table API 和 SQL 是批处理和流处理统一的 API,这意味着 Table API & SQL 查询的语义与其输入是有界批输入还是无界流输入无关。在流式模式下执行的表程序(Table Program)会充分发挥 Flink 作为有状态流处理器的全部能力。
具体而言,流式表程序可以配置 状态后端 以及各类 checkpoint 选项,以应对不同的状态规模与容错需求;也可以对正在运行的 Table API & SQL 管道打 savepoint,并在之后的某个时间点恢复应用状态。
概念上,源表永远不会被完整地保存在状态中。实现者处理的是逻辑表,即动态表,其状态需求取决于所使用的具体操作。
状态管理
状态使用:声明式查询下的"隐形"状态
由于 Table API & SQL 程序的声明式特性,管道中哪里使用了状态、使用了多少状态并不总是显而易见的。由规划器(Planner)决定是否需要状态来计算正确结果,管道会在当前优化器规则集下尽量争取占用尽可能少的状态。
有状态算子(Stateful Operators)
包含有状态操作的查询,例如 Join、聚合 或 去重,需要将中间结果保存在容错的存储中,Flink 的状态抽象正是为此而设计。
例如,两个表的普通 SQL Join 要求算子将两个输入表完整地保存在状态中。为了正确的 SQL 语义,运行时必须假设匹配可能发生在两侧的任意时刻。Flink 提供了优化的 窗口 Join 与 Interval Join,通过利用 watermark 的概念来尽量压缩状态规模。
另一个例子是下面的词频统计(word count)查询:
CREATE TABLE doc (
word STRING
) WITH (
'connector' = '...'
);
CREATE TABLE word_cnt (
word STRING PRIMARY KEY NOT ENFORCED,
cnt BIGINT
) WITH (
'connector' = '...'
);
INSERT INTO word_cnt
SELECT word, COUNT(1) AS cnt
FROM doc
GROUP BY word;
word 字段被用作分组键,连续查询(continuous query)为每一个观察到的 word 向 sink 写入一个计数。由于 word 的值随时间不断演化,且连续查询永远不会结束,框架需要为每一个观察到的 word 值维护一个计数。因此,随着越来越多的 word 值被观察到,查询的总状态大小会持续增长。
上图中,INSERT INTO word_cnt SELECT word, COUNT(1) AS cnt FROM doc GROUP BY word 这一显式查询(EXPLICIT query)被规划器解析为"Source Operator → Stateful Operator(派生自查询)→ Sink Operator"的拓扑,有状态算子下方维护着每个 key(如 'hello'、'meow')对应的键控状态值(如计数 2、1)。
与之相对,仅包含字段投影或过滤的查询(如 SELECT ... FROM ... WHERE)通常是无状态管道。但在某些情况下,有状态操作会通过输入的特征隐式推导出来(例如输入是不含 UPDATE_BEFORE 的 changelog,参见 Table 到 Stream 的转换),或通过用户配置推导出来(参见 table-exec-source-cdc-events-duplicate)。
下图展示了一个查询 upsert-kafka 源 的 SELECT ... FROM 语句:
CREATE TABLE upsert_kakfa (
id INT PRIMARY KEY NOT ENFORCED,
message STRING
) WITH (
'connector' = 'upsert-kafka',
...
);
SELECT * FROM upsert_kakfa;
该表源只提供 INSERT、UPDATE_AFTER 和 DELETE 类型的消息,而下游 sink 需要完整的 changelog(包含 UPDATE_BEFORE)。因此,虽然查询本身不涉及显式的有状态计算,规划器仍然会生成一个名为 "ChangelogNormalize" 的有状态算子来补全 changelog。
该图展示了"Stateful Operator derived from trait of input"(派生自输入特征的有状态算子)的典型形态:upsert-kafka 源依据主键 id 做 HASH 分区,事件流(+I/+U/-U/-D)经过有状态算子补全 UPDATE_BEFORE 后输出完整 changelog 给下游。这一机制的实现位于 StreamExecChangelogNormalize.java,它构建 KeyedProcessOperator 与 OneInputStreamOperator,配合键选择器与 StateMetadata 完成按 key 的状态管理。
每个算子具体需要多少状态、如何限制可能无限增长的状态规模,请参考各算子的独立文档。
空闲状态保留时间(Idle State Retention Time)
Idle State Retention Time 参数 table.exec.state.ttl 定义了:一个 key 的状态在不被更新的情况下保留多久之后被移除。
对于前面的词频统计示例,只要某个 word 的计数在配置的时段内未被更新,该计数就会被移除。
移除某个 key 的状态后,连续查询会完全忘记曾经见过这个 key。如果后续又处理到一条该 key 的记录,它会被当作第一条该 key 的记录来处理。对上面的例子而言,这意味着某个 word 的计数会从 0 重新开始计数。
状态 TTL 的三种配置方式
| 配置方式 | TableAPI/SQL 支持 | 粒度(Granularity) | 优先级(Priority) |
|---|---|---|---|
SET 'table.exec.state.ttl' = '...' |
TableAPI / SQL | 管道级(Pipeline level),所有有状态算子默认使用该值。 | 这是默认的状态 TTL 配置,可被启用 STATE_TTL hint 或修改序列化的 CompiledPlan 中的值所覆盖。 |
SELECT /*+ STATE_TTL(...) */ ... |
SQL | 算子级,目前仅支持 regular join 与 group aggregation。 | Hint 优先于默认的 table.exec.state.ttl。该值会在计划翻译阶段被序列化进 CompiledPlan。详见 State TTL Hint。 |
| 修改 CompiledPlan 的序列化 JSON 内容 | TableAPI / SQL | 算子级,通用支持。每个有状态算子的 TTL 都会显式序列化为 JSON 中的一个条目,修改 JSON 文件即可改变任意有状态算子的 TTL。 | CompiledPlan 中的 TTL 来源于 table.exec.state.ttl 或 STATE_TTL hint。如果作业通过 CompiledPlan 提交,最终 TTL 值由最后被修改的状态元数据决定。 |
配置算子级状态 TTL
⚠️ 高级特性,请谨慎使用。 该特性仅适用于管道中存在多个状态、且需要为每个状态设置不同 TTL(Time-to-Live)的场景。如果管道不涉及有状态计算,无需按此流程操作;如果管道只使用一个状态,只需在管道级设置
table.exec.state.ttl即可。
Table API & SQL 支持在算子级配置细粒度的状态 TTL 以改善状态使用。可配置的粒度定义为每个有状态算子的入边(incoming input edges)数量:
OneInputStreamOperator可以为 1 个状态配置 TTL;TwoInputStreamOperator(如 regular join)有两个输入,可以为左状态和右状态分别配置 TTL;- 更一般地,对于有 K 个输入的
MultipleInputStreamOperator,可以配置 K 个状态 TTL。
典型使用场景:
- 为 regular join 设置不同的 TTL:regular join 生成一个
TwoInputStreamOperator,左状态保存左输入、右状态保存右输入,可以为左右状态分别设置不同的 TTL。 - 为同一管道内不同变换设置不同 TTL:例如某个 ETL 管道先用
ROW_NUMBER做去重,再用GROUP BY做聚合。该表程序会生成两个各自拥有状态的OneInputStreamOperator,此时可以为去重状态和聚合状态分别设置不同的 TTL。
注意:基于窗口的操作(如 Window Join、Window Aggregation、Window Top-N 等)以及 Interval Join 不依赖
table.exec.state.ttl来控制状态保留,它们的状态 TTL 无法在算子级配置。
第一步:生成 Compiled Plan
设置流程从使用 COMPILE PLAN 语句生成一个 JSON 文件开始,该 JSON 文件表示当前表程序的序列化执行计划。
注意:目前
COMPILE PLAN语句不支持SELECT... FROM...查询。
Java 方式
TableEnvironment tableEnv = TableEnvironment.create(EnvironmentSettings.inStreamingMode());
tableEnv.executeSql(
"CREATE TABLE orders (order_id BIGINT, order_line_id BIGINT, buyer_id BIGINT, ...)");
tableEnv.executeSql(
"CREATE TABLE line_orders (order_line_id BIGINT, order_status TINYINT, ...)");
tableEnv.executeSql(
"CREATE TABLE enriched_orders (order_id BIGINT, order_line_id BIGINT, order_status TINYINT, ...)");
// CompilePlan#writeToFile 仅支持本地文件路径;
// 如需写入远程文件系统,请使用 tableEnv.executeSql("COMPILE PLAN 'hdfs://path/to/plan.json' FOR ...")
CompiledPlan compiledPlan =
tableEnv.compilePlanSql(
"INSERT INTO enriched_orders \n"
+ "SELECT a.order_id, a.order_line_id, b.order_status, ... \n"
+ "FROM orders a JOIN line_orders b ON a.order_line_id = b.order_line_id");
compiledPlan.writeToFile("/path/to/plan.json");
Scala 方式
val tableEnv = TableEnvironment.create(EnvironmentSettings.inStreamingMode())
tableEnv.executeSql(
"CREATE TABLE orders (order_id BIGINT, order_line_id BIGINT, buyer_id BIGINT, ...)")
tableEnv.executeSql(
"CREATE TABLE line_orders (order_line_id BIGINT, order_status TINYINT, ...)")
tableEnv.executeSql(
"CREATE TABLE enriched_orders (order_id BIGINT, order_line_id BIGINT, order_status TINYINT, ...)")
val compiledPlan =
tableEnv.compilePlanSql(
"""
|INSERT INTO enriched_orders
|SELECT a.order_id, a.order_line_id, b.order_status, ...
|FROM orders a JOIN line_orders b ON a.order_line_id = b.order_line_id
|""".stripMargin)
// CompilePlan#writeToFile 仅支持本地文件路径;
// 如需写入远程文件系统,请使用 tableEnv.executeSql("COMPILE PLAN 'hdfs://path/to/plan.json' FOR ...")
compiledPlan.writeToFile("/path/to/plan.json")
SQL CLI 方式
Flink SQL> CREATE TABLE orders (order_id BIGINT, order_line_id BIGINT, buyer_id BIGINT, ...);
[INFO] Execute statement succeeded.
Flink SQL> CREATE TABLE line_orders (order_line_id BIGINT, order_status TINYINT, ...);
[INFO] Execute statement succeeded.
Flink SQL> CREATE TABLE enriched_orders (order_id BIGINT, order_line_id BIGINT, order_status TINYINT, ...);
[INFO] Execute statement succeeded.
Flink SQL> COMPILE PLAN 'file:///path/to/plan.json' FOR INSERT INTO enriched_orders
> SELECT a.order_id, a.order_line_id, b.order_status, ...
> FROM orders a JOIN line_orders b ON a.order_line_id = b.order_line_id;
[INFO] Execute statement succeeded.
SQL 语法
COMPILE PLAN [IF NOT EXISTS] <plan_file_path> FOR <insert_statement>|<statement_set>;
statement_set:
EXECUTE STATEMENT SET
BEGIN
insert_statement;
...
insert_statement;
END;
insert_statement:
<insert_from_select>|<insert_from_values>
上述语句会在 /path/to/plan.json 生成一个 JSON 文件。
COMPILE PLAN语句支持将计划写入远程 filesystem scheme,如hdfs://或s3://。请确保目标路径已配置写权限。
从源码看,CompiledPlan.java 定义了这一"不可变、已完全优化、可执行"的实体:它编码了算子、表达式、函数、数据类型与表连接器;compilePlanSql 负责从 SQL 编译计划,writeToFile / asJsonString 负责持久化,loadPlan(PlanReference) 负责从文件或字符串恢复,execute() 负责执行。其中 @Experimental 注解也表明该 API 仍在演进中。
第二步:修改 Compiled Plan
每个使用状态的算子都会显式生成一个名为 "state" 的 JSON 数组,结构如下。理论上,第 k 个输入流的算子会拥有第 k 个状态。
"state": [
{
"index": 0,
"ttl": "0 ms",
"name": "${1st input state name}"
},
{
"index": 1,
"ttl": "0 ms",
"name": "${2nd input state name}"
},
...
]
定位到需要修改的算子,将 TTL 的值改为一个正整数,注意要包含时间单位 "ms"。例如,将某个状态 TTL 设为 1 小时,可以这样修改 JSON:
{
"index": 0,
"ttl": "3600000 ms",
"name": "${1st input state name}"
}
保存文件后,使用 EXECUTE PLAN 语句提交作业。
概念提示:下游有状态算子的 TTL 应大于等于上游有状态算子的 TTL。
第三步:执行 Compiled Plan
EXECUTE PLAN 语句会将指定文件反序列化回当前表程序的执行计划,然后提交作业。通过 EXECUTE PLAN 提交的作业将应用文件中读取的状态 TTL,而不是配置项 table.exec.state.ttl。
Java 方式
TableEnvironment tableEnv = TableEnvironment.create(EnvironmentSettings.inStreamingMode());
tableEnv.executeSql(
"CREATE TABLE orders (order_id BIGINT, order_line_id BIGINT, buyer_id BIGINT, ...)");
tableEnv.executeSql(
"CREATE TABLE line_orders (order_line_id BIGINT, order_status TINYINT, ...)");
tableEnv.executeSql(
"CREATE TABLE enriched_orders (order_id BIGINT, order_line_id BIGINT, order_status TINYINT, ...)");
// PlanReference#fromFile 仅支持本地文件路径;
// 如需从远程文件系统读取,请使用 tableEnv.executeSql("EXECUTE PLAN 'hdfs://path/to/plan.json'").await();
tableEnv.loadPlan(PlanReference.fromFile("/path/to/plan.json")).execute().await();
Scala 方式
val tableEnv = TableEnvironment.create(EnvironmentSettings.inStreamingMode())
tableEnv.executeSql(
"CREATE TABLE orders (order_id BIGINT, order_line_id BIGINT, buyer_id BIGINT, ...)")
tableEnv.executeSql(
"CREATE TABLE line_orders (order_line_id BIGINT, order_status TINYINT, ...)")
tableEnv.executeSql(
"CREATE TABLE enriched_orders (order_id BIGINT, order_line_id BIGINT, order_status TINYINT, ...)")
// PlanReference#fromFile 仅支持本地文件路径;
// 如需从远程文件系统读取,请使用 tableEnv.executeSql("EXECUTE PLAN 'hdfs://path/to/plan.json'").await()
tableEnv.loadPlan(PlanReference.fromFile("/path/to/plan.json")).execute().await()
SQL CLI 方式
Flink SQL> CREATE TABLE orders (order_id BIGINT, order_line_id BIGINT, buyer_id BIGINT, ...);
[INFO] Execute statement succeeded.
Flink SQL> CREATE TABLE line_orders (order_line_id BIGINT, order_status TINYINT, ...);
[INFO] Execute statement succeeded.
Flink SQL> CREATE TABLE enriched_orders (order_id BIGINT, order_line_id BIGINT, order_status TINYINT, ...);
[INFO] Execute statement succeeded.
Flink SQL> EXECUTE PLAN 'file:///path/to/plan.json';
[INFO] Submitting SQL update statement to the cluster...
[INFO] SQL update statement has been successfully submitted to the cluster:
Job ID: 79fbe3fa497e4689165dd81b1d225ea8
SQL 语法
EXECUTE PLAN [IF EXISTS] <plan_file_path>;
该语句会反序列化 JSON 文件并提交一个 insert 语句作业。
完整示例:为 regular join 左右状态设置不同 TTL
下面的表程序计算富化的订单发货信息,它执行一个 regular inner join,并为左侧与右侧状态设置不同的 TTL。
生成 compiled plan
-- 左源表
CREATE TABLE Orders (
`order_id` INT,
`line_order_id` INT
) WITH (
'connector'='...'
);
-- 右源表
CREATE TABLE LineOrders (
`line_order_id` INT,
`ship_mode` STRING
) WITH (
'connector'='...'
);
-- sink 表
CREATE TABLE OrdersShipInfo (
`order_id` INT,
`line_order_id` INT,
`ship_mode` STRING
) WITH (
'connector' = '...'
);
COMPILE PLAN '/path/to/plan.json' FOR
INSERT INTO OrdersShipInfo
SELECT a.order_id, a.line_order_id, b.ship_mode
FROM Orders a JOIN LineOrders b
ON a.line_order_id = b.line_order_id;
生成的 JSON 文件内容(节选关键节点)如下:
{
"flinkVersion" : "1.18",
"nodes" : [ {
"id" : 1,
"type" : "stream-exec-table-source-scan_1",
"scanTableSource" : {
"table" : {
"identifier" : "`default_catalog`.`default_database`.`Orders`",
"resolvedTable" : { ... }
}
},
"outputType" : "ROW<`order_id` INT, `line_order_id` INT>",
"description" : "TableSourceScan(table=[[default_catalog, default_database, Orders]], fields=[order_id, line_order_id])",
"inputProperties" : [ ]
}, {
"id" : 2,
"type" : "stream-exec-exchange_1",
"inputProperties" : [ ... ],
"outputType" : "ROW<`order_id` INT, `line_order_id` INT>",
"description" : "Exchange(distribution=[hash[line_order_id]])"
}, {
"id" : 3,
"type" : "stream-exec-table-source-scan_1",
"scanTableSource" : {
"table" : {
"identifier" : "`default_catalog`.`default_database`.`LineOrders`",
"resolvedTable" : {...}
}
},
"outputType" : "ROW<`line_order_id` INT, `ship_mode` VARCHAR(2147483647)>",
"description" : "TableSourceScan(table=[[default_catalog, default_database, LineOrders]], fields=[line_order_id, ship_mode])",
"inputProperties" : [ ]
}, {
"id" : 4,
"type" : "stream-exec-exchange_1",
"inputProperties" : [ ... ],
"outputType" : "ROW<`line_order_id` INT, `ship_mode` VARCHAR(2147483647)>",
"description" : "Exchange(distribution=[hash[line_order_id]])"
}, {
"id" : 5,
"type" : "stream-exec-join_1",
"joinSpec" : { ... },
"state" : [ {
"index" : 0,
"ttl" : "0 ms",
"name" : "leftState"
}, {
"index" : 1,
"ttl" : "0 ms",
"name" : "rightState"
} ],
"inputProperties" : [ ... ],
"outputType" : "ROW<`order_id` INT, `line_order_id` INT, `line_order_id0` INT, `ship_mode` VARCHAR(2147483647)>",
"description" : "Join(joinType=[InnerJoin], where=[(line_order_id = line_order_id0)], select=[order_id, line_order_id, line_order_id0, ship_mode], leftInputSpec=[NoUniqueKey], rightInputSpec=[NoUniqueKey])"
}, {
"id" : 6,
"type" : "stream-exec-calc_1",
"projection" : [ ... ],
"condition" : null,
"inputProperties" : [ ... ],
"outputType" : "ROW<`order_id` INT, `line_order_id` INT, `ship_mode` VARCHAR(2147483647)>",
"description" : "Calc(select=[order_id, line_order_id, ship_mode])"
}, {
"id" : 7,
"type" : "stream-exec-sink_1",
"configuration" : { ... },
"dynamicTableSink" : {
"table" : {
"identifier" : "`default_catalog`.`default_database`.`OrdersShipInfo`",
"resolvedTable" : { ... }
}
},
"inputChangelogMode" : [ "INSERT" ],
"inputProperties" : [ ... ],
"outputType" : "ROW<`order_id` INT, `line_order_id` INT, `ship_mode` VARCHAR(2147483647)>",
"description" : "Sink(table=[default_catalog.default_database.OrdersShipInfo], fields=[order_id, line_order_id, ship_mode])"
} ],
"edges" : [ ... ]
}
可以清晰地看到:id 为 5 的 stream-exec-join_1 节点带有 "state" 数组,包含 index: 0 的 leftState 与 index: 1 的 rightState。这个结构正是"第 k 个输入流算子拥有第 k 个状态"的直观体现——与 StreamExecJoin.java 中 regular join 生成 TwoInputStreamOperator(左右各一个状态)的实现一致。
修改计划内容并执行计划
join 算子状态对应的 JSON 结构如下:
"state": [
{
"index": 0,
"ttl": "0 ms",
"name": "leftState"
},
{
"index": 1,
"ttl": "0 ms",
"name": "rightState"
}
]
"index" 表示当前状态是算子的第几个输入(从 0 开始计数)。当前左右两侧的 TTL 值都是 "0 ms",表示状态永不过期。现在把左状态改为 "3000 ms"、右状态改为 "9000 ms":
"state": [
{
"index": 0,
"ttl": "3000 ms",
"name": "leftState"
},
{
"index": 1,
"ttl": "9000 ms",
"name": "rightState"
}
]
保存文件的修改后执行计划:
EXECUTE PLAN '/path/to/plan.json'
至此,左输入状态保留 3 秒、右输入状态保留 9 秒的差异化 TTL 配置生效。
有状态升级与状态演化(Stateful Upgrades and Evolution)
以流式模式执行的表程序被设计为 standing queries(常驻查询):它们只定义一次,然后作为静态的端到端管道被持续求值。
对于有状态管道,无论是查询的修改还是 Flink 规划器的变化,都可能导致完全不同的执行计划,这使有状态升级与表程序的状态演化在当前阶段颇具挑战,社区正在努力改进这些不足。
例如,添加一个过滤谓词后,优化器可能会决定重排 join 或改变中间算子的 schema,从而因拓扑变化或算子状态内列布局不同而导致无法从 savepoint 恢复。
查询实现者必须确保变更前后的优化计划是兼容的。可以使用 SQL 中的 EXPLAIN 命令或 Table API 的 table.explain() 来获取计划洞察。
由于新的优化器规则不断加入、算子不断变得更高效更专用,升级到更新的 Flink 版本也可能导致计划不兼容。
⚠️ 当前限制:框架目前无法保证状态可以从 savepoint 映射到新的表算子拓扑。 换句话说:只有当查询和 Flink 版本都保持不变时,savepoint 才受支持。
由于社区拒绝在 patch 版本(例如从 1.13.1 到 1.13.2)中修改优化计划与算子拓扑,因此将 Table API & SQL 管道升级到更新的 bug fix 版本是安全的。但大版本升级(例如从 1.12 到 1.13)不受支持。
针对上述两个短板(修改的查询、修改的 Flink 版本),建议调查更新后的表程序状态是否可以用历史数据再次"预热"(即初始化),然后再切换到实时数据。Flink 社区正在开发 hybrid source 以便尽可能方便地完成这种切换。
下一步阅读
- 动态表(Dynamic Tables):描述动态表的概念。
- 时间属性(Time attributes):解释时间属性以及 Table API & SQL 中如何处理时间属性。
- 版本表(Versioned Tables):描述 Temporal Table 概念。
- 连续查询中的 Join:连续查询中支持的不同 Join 类型。
- 连续查询中的确定性(Determinism):连续查询中的确定性。
- 查询配置(Query configuration):列出 Table API & SQL 特有的配置项。

