Flink SQL 的 JAR 语句ADD JAR / SHOW JARS / REMOVE JAR（SQL CLI 实战 + 避坑指南）

1. JAR 语句是干什么的？

官方定义：

JAR 语句用于在运行时把用户 jar 加入 classpath、从 classpath 移除，或查看已经添加的 jar。

它们主要面向 SQL CLI 的交互式会话使用。

2. SQL CLI 示例：三连击（ADD → SHOW → REMOVE）

2.1 添加本地 jar

sql 复制代码

Flink SQL> ADD JAR '/path/hello.jar';
[INFO] Execute statement succeeded.

2.2 添加远程 jar（例如 HDFS）

sql 复制代码

Flink SQL> ADD JAR 'hdfs:///udf/common-udf.jar';
[INFO] Execute statement succeeded.

2.3 查看已添加 jar

sql 复制代码

Flink SQL> SHOW JARS;
+----------------------------+
|                       jars |
+----------------------------+
|            /path/hello.jar |
| hdfs:///udf/common-udf.jar |
+----------------------------+

2.4 移除 jar

sql 复制代码

Flink SQL> REMOVE JAR '/path/hello.jar';
[INFO] The specified jar is removed from session classloader.

3. ADD JAR：语法与能力

3.1 语法

sql 复制代码

ADD JAR '<path_to_filename>.jar'

3.2 能力说明

将指定 jar 加入资源列表（会话 classpath）
支持 本地文件系统 或远程文件系统路径
加完后可通过 SHOW JARS 查看

4. 重要限制：不要用 ADD JAR 去加载 Hive 相关（避坑必读）

官方限制（非常关键）：

不要使用 ADD JAR 来加载 Hive source/sink/function/catalog。

这是 Hive connector 的已知限制，未来版本会修复。当前推荐按官方 Hive 集成指引进行 Hive 集成。

这句话的含义是：

即便你把 Hive 相关依赖 jar "塞进" classpath，也可能出现各种奇怪问题（类冲突、发现不到、行为不一致等）。Hive 集成通常要走更"规范"的方式（例如按官方集成步骤配置 Hive 相关依赖与模块/目录结构）。

5. SHOW JARS：查看当前会话 jar 列表

5.1 语法

sql 复制代码

SHOW JARS

5.2 作用

列出所有通过 ADD JAR 添加的 jar。

适用场景：

确认 jar 是否加成功（路径是否正确）
排查"类找不到 / UDF 找不到"时确认环境
会话复用时确认是否被别人加过 jar（避免污染）

6. REMOVE JAR：移除指定 jar（仅 SQL CLI）

6.1 语法

sql 复制代码

REMOVE JAR '<path_to_filename>.jar'

6.2 说明

移除指定的、由 ADD JAR 添加的 jar
注意：REMOVE JAR 只在 SQL CLI 中生效（官方强调）

适用场景：

临时调试用 jar，用完清理
发生依赖冲突，移除某个 jar 做 A/B 验证
会话长期复用，防止 jar 越加越多导致不可控

7. 一套实战工作流：用 JAR 语句管理 UDF

你在 SQL CLI 里注册 UDF 的常见节奏一般是：

1）添加 jar（本地或远程）

sql 复制代码

ADD JAR '/path/my-udf.jar';

2）确认 jar 已加载

sql 复制代码

SHOW JARS;

3）创建函数（示意）

sql 复制代码

CREATE FUNCTION my_func AS 'com.example.MyFunc';

4）验证函数可用

sql 复制代码

SHOW USER FUNCTIONS;
SELECT my_func(col) FROM t;

5）调试结束清理

sql 复制代码

REMOVE JAR '/path/my-udf.jar';

这套流程的价值：可控、可复现、可回滚。

8. 总结

Flink SQL 目前支持三种 JAR 语句：ADD JAR、SHOW JARS、REMOVE JAR
核心作用：管理 SQL CLI 会话 classloader 中的用户 jar
ADD JAR 支持本地/远程文件系统路径
重要限制 ：不要用 ADD JAR 加载 Hive source/sink/function/catalog（Hive connector 已知限制）
REMOVE JAR 仅在 SQL CLI 生效