Flink SQL 的 UNLOAD MODULE 模块卸载、会话隔离与常见坑

1、UNLOAD MODULE 是干什么的？

一句话：

UNLOAD MODULE xxx 会把模块从当前会话的"已加载模块集合"中移除。

它适用于：

• 测试/调试时加载了额外模块，用完想清理环境
• SQL 网关/平台多会话场景，避免模块在同一会话内"污染"后续操作
• 排查函数冲突时，临时卸载某个模块验证问题来源

2、Java 示例：executeSql 返回 OK，SHOW MODULES 立刻变空

示例（你给的原文）：

StreamExecutionEnvironment env = StreamExecutionEnvironment.getExecutionEnvironment();
StreamTableEnvironment tEnv = StreamTableEnvironment.create(env);

// 卸载 core 模块
tEnv.executeSql("UNLOAD MODULE core");
tEnv.executeSql("SHOW MODULES").print();
// Empty set

这里特别关键的现象是：

卸载 core 后，SHOW MODULES 直接变成 Empty set。

这说明：

• core 并不是"永远存在不可动"的东西（在当前会话里它也属于可卸载模块）
• 一旦把默认模块卸掉，后续函数解析能力会发生巨大变化（很多内置函数可能就没了）

3、语法：就一句话

UNLOAD MODULE module_name

没有 WITH 参数，纯卸载。

4、UNLOAD、USE、SHOW 的区别：别把"卸载"和"禁用"混了

这是最容易混淆的一点：

• USE MODULES ：控制"启用哪些模块 + 解析顺序"
  没被列出来的模块会变成 used=false（禁用），但它仍然可能是"loaded"的
• UNLOAD MODULE：把模块从 loaded 集合里移除（彻底卸载）

一个更直观的理解：

USE 更像"开关和优先级"；UNLOAD 更像"卸载插件"。

所以你在排查模块相关问题时，建议流程是：

1）先看全量状态

SHOW FULL MODULES;

2）如果只是想切换优先级/启用与否

USE MODULES hive, core;

3）如果你要彻底移除某个模块（避免后续任何解析命中它）

UNLOAD MODULE hive;

5、实战建议：什么时候用 UNLOAD 更合理？

场景 A：SQL 平台/网关里的"会话污染"治理

如果你做的是类似 SQL Gateway 的能力，用户可能在同一 session 里：

• LOAD 了 hive
• USE MODULES 切了顺序
• 过一会又执行另一套 SQL

这很容易造成"前一个用户/前一次执行"对"后一次执行"产生影响。

此时常见做法是：

• 每次执行前重建 session（最彻底）
• 或者执行完成后做清理：UNLOAD 非默认模块、恢复默认 USE MODULES（更轻量）

场景 B：验证"函数冲突/解析来源"到底来自哪个模块

当你怀疑某个函数在不同模块里同名实现导致行为差异，可以：

• 先 SHOW FULL MODULES 看解析顺序
• 再 UNLOAD 掉一个模块，看行为是否随之变化（A/B 对照非常快）

6、常见坑：卸载 core 之后很多东西会"突然不可用"

你给的例子直接卸载了 core，这在生产里要非常谨慎。因为 core 通常是默认模块，包含大量基础能力。

如果你看到：

• SHOW MODULES 变成 Empty set
• 后续 SQL 报"函数找不到 / 类型解析失败"

优先怀疑：

• 你是不是卸载了 core
• 你是否需要重新 LOAD MODULE core（如果允许）并 USE MODULES core 恢复

7、总结

• UNLOAD MODULE xxx：卸载模块（从当前会话 loaded 集合中移除）

• Java 中用 executeSql() 执行，成功返回 OK，失败抛异常

• 与 USE MODULES 的区别：

  • USE：启用/禁用 + 顺序（模块可能仍然 loaded）
  • UNLOAD：彻底卸载（插件级移除）

• 生产建议：

  • 排障可用 UNLOAD 快速做对照
  • 平台/网关建议用它做会话清理，但慎卸 core