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

FlinkSQL>ADDJAR'/path/hello.jar';[INFO]Executestatement succeeded.

2.2 添加远程 jar（例如 HDFS）

FlinkSQL>ADDJAR'hdfs:///udf/common-udf.jar';[INFO]Executestatement succeeded.

2.3 查看已添加 jar

FlinkSQL>SHOWJARS;+----------------------------+|jars|+----------------------------+|/path/hello.jar||hdfs:///udf/common-udf.jar |+----------------------------+

2.4 移除 jar

FlinkSQL>REMOVE JAR'/path/hello.jar';[INFO]The specified jarisremovedfromsessionclassloader.

3. ADD JAR：语法与能力

3.1 语法

ADDJAR'<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 语法

SHOWJARS

5.2 作用

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

适用场景：

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

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

6.1 语法

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（本地或远程）

ADDJAR'/path/my-udf.jar';

2）确认 jar 已加载

SHOWJARS;

3）创建函数（示意）

CREATEFUNCTIONmy_funcAS'com.example.MyFunc';

4）验证函数可用

SHOWUSERFUNCTIONS;SELECTmy_func(col)FROMt;

5）调试结束清理

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 生效