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：列出集群作业

sql 复制代码

Flink SQL> SHOW JOBS;
+----------------------------------+----------+---------+-------------------------+
|                           job id | job name |  status |              start time |
+----------------------------------+----------+---------+-------------------------+
| 228d70913eab60dda85c5e7f78b5782c |    myjob | RUNNING | 2023-02-11T05:03:51.523 |
+----------------------------------+----------+---------+-------------------------+

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

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

sql 复制代码

Flink SQL> DESCRIBE JOB '228d70913eab60dda85c5e7f78b5782c';
+----------------------------------+----------+---------+-------------------------+
|                           job id | job name |  status |              start time |
+----------------------------------+----------+---------+-------------------------+
| 228d70913eab60dda85c5e7f78b5782c |    myjob | RUNNING | 2023-02-11T05:03:51.523 |
+----------------------------------+----------+---------+-------------------------+

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

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

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

sql 复制代码

Flink SQL> SET 'execution.checkpointing.savepoint-dir'='file:/tmp/';
[INFO] Execute statement succeeded.

然后停止作业并触发 savepoint：

sql 复制代码

Flink SQL> STOP JOB '228d70913eab60dda85c5e7f78b5782c' WITH SAVEPOINT;
+-----------------------------------------+
|                          savepoint path |
+-----------------------------------------+
| file:/tmp/savepoint-3addd4-0b224d9311e6 |
+-----------------------------------------+

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

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

3.1 SHOW JOBS

sql 复制代码

SHOW JOBS

作用：显示 Flink 集群中的作业。

限制：只在 SQL CLI 或 SQL Gateway 可用。

3.2 DESCRIBE / DESC JOB

sql 复制代码

{ DESCRIBE | DESC } JOB '<job_id>'

作用：显示指定 job_id 的作业信息。

限制：只在 SQL CLI 或 SQL Gateway 可用。

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

sql 复制代码

STOP JOB '<job_id>' [WITH SAVEPOINT] [WITH DRAIN]

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

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

这时优先：

sql 复制代码

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

并保存返回的 savepoint path。

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

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

sql 复制代码

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 到最大值，用于永久终止场景