Flink SQL 的 JOB 管理语句SHOW / DESCRIBE / STOP（SQL CLI SQL Gateway 实战）

1. JOB 语句能做什么？

官方定位很明确：

Job statements are used for management of Flink jobs.
（JOB 语句用于 Flink 作业管理。）

也就是说，你不需要跑到 Web UI 或 REST API 才能看作业/停作业，在 SQL CLI/Gateway 里也可以“就地管理”。

2. SQL CLI 实战：三连操作（SHOW → DESCRIBE → STOP）

2.1 SHOW JOBS：列出集群作业

FlinkSQL>SHOWJOBS;+----------------------------------+----------+---------+-------------------------+|job id|job name|status|starttime|+----------------------------------+----------+---------+-------------------------+|228d70913eab60dda85c5e7f78b5782c|myjob|RUNNING|2023-02-11T05:03:51.523|+----------------------------------+----------+---------+-------------------------+

输出一般包含：job id / job name / status / start time。

2.2 DESCRIBE JOB：查看某个 job 的信息

FlinkSQL>DESCRIBEJOB'228d70913eab60dda85c5e7f78b5782c';+----------------------------------+----------+---------+-------------------------+|job id|job name|status|starttime|+----------------------------------+----------+---------+-------------------------+|228d70913eab60dda85c5e7f78b5782c|myjob|RUNNING|2023-02-11T05:03:51.523|+----------------------------------+----------+---------+-------------------------+

当你从SHOW JOBS拿到 job_id 后，下一步通常就是DESCRIBE JOB确认目标是不是你要操作的那个。

2.3 STOP JOB：停止作业（带 SAVEPOINT 示例）

先设置 savepoint 目录（也可以由集群配置提供）：

FlinkSQL>SET'execution.checkpointing.savepoint-dir'='file:/tmp/';[INFO]Executestatement succeeded.

然后停止作业并触发 savepoint：

FlinkSQL>STOP JOB'228d70913eab60dda85c5e7f78b5782c'WITHSAVEPOINT;+-----------------------------------------+|savepointpath|+-----------------------------------------+|file:/tmp/savepoint-3addd4-0b224d9311e6|+-----------------------------------------+

执行后会返回savepoint path，这通常就是你后续“从 savepoint 恢复”的关键凭证（路径要保存好）。

3. 语法与关键点（官方语义梳理）

3.1 SHOW JOBS

SHOWJOBS

作用：显示 Flink 集群中的作业。
限制：只在 SQL CLI 或 SQL Gateway 可用。

3.2 DESCRIBE / DESC JOB

{DESCRIBE|DESC} JOB'<job_id>'

作用：显示指定 job_id 的作业信息。
限制：只在 SQL CLI 或 SQL Gateway 可用。

3.3 STOP JOB：停止作业（可选 SAVEPOINT、可选 DRAIN）

STOP JOB'<job_id>'[WITHSAVEPOINT][WITHDRAIN]

WITH SAVEPOINT：停止前做一次 Savepoint

• 含义：在停止作业前执行一次 savepoint

• savepoint 目录配置来源：

  • 可在集群配置里设置execution.checkpointing.savepoint-dir
  • 也可通过SET 语句设置（并且SET 的优先级更高）

也就是：你在 SQL CLI 里SET了 savepoint-dir，就会覆盖集群默认值。

WITH DRAIN：在最后一次 checkpoint barrier 前把 watermark 提到最大

官方解释是：

Increase the watermark to the maximum value before the last checkpoint barrier. Use it when you want to terminate the job permanently.

直白理解（不展开超出原文的机制细节）：

• WITH DRAIN是一种“更倾向永久终止”的停止方式
• 它会在停止前把 watermark 推到最大值（在最后一次 checkpoint barrier 之前）

注意：STOP JOB同样只在 SQL CLI 或 SQL Gateway 可用。

4. 最佳实践：生产里怎么用更稳

4.1 停作业前先确认目标：SHOW → DESCRIBE

不要直接 copy job_id 就 stop，建议固定流程：

1）SHOW JOBS;
2）DESCRIBE JOB '<job_id>';（确认名称、状态、启动时间等）

这样能显著减少“停错作业”的概率。

4.2 需要可恢复，优先用 WITH SAVEPOINT

很多生产场景停作业的真实诉求是：可恢复、可迁移、可升级。
这时优先：

SET'execution.checkpointing.savepoint-dir'='file:/tmp/';STOP JOB'<job_id>'WITHSAVEPOINT;

并保存返回的savepoint path。

4.3 临时变更 savepoint-dir：用 SET 覆盖集群默认

如果你只是临时想把 savepoint 输出到某个位置，不想改集群配置，直接在会话里：

SET'execution.checkpointing.savepoint-dir'='file:/tmp/';

官方明确：SET 的优先级更高。

5. 常见坑点提醒

• 限制坑：SHOW JOBS / DESCRIBE JOB / STOP JOB只在SQL CLI / SQL Gateway可用，不要在普通 TableEnvironment 的 Java 程序里指望它们能跑通。
• 路径坑：开启WITH SAVEPOINT时，别忘了 savepoint-dir 的来源与优先级（SET > cluster config）。
• 语义坑：WITH DRAIN是用于“永久终止”的场景（官方这么建议），不要把它当成普通 stop 的默认选项随手用。

6. 总结

Flink SQL 的 JOB 管理语句很少，但非常实用：

• SHOW JOBS：列出集群作业

• DESCRIBE JOB：查看指定作业

• STOP JOB：停止作业

  • WITH SAVEPOINT：停止前做 savepoint，路径由execution.checkpointing.savepoint-dir决定（SET 优先）
  • WITH DRAIN：提升 watermark 到最大值，用于永久终止场景