Flink SQL 的 USE / USE CATALOG / USE MODULES（Catalog、Database、Module 三件套）

1、USE CATALOG：切换当前 Catalog

USECATALOG cat1;

含义：把“当前 catalog”设置为cat1。
之后你写：

SHOWDATABASES;CREATETABLEt1(...);

如果没有显式写catalog.db.table的全限定名，Flink 会默认把对象解析到cat1这个 catalog 里。

默认值：default_catalog
不存在会怎样：直接抛异常（这点非常重要，很多人以为会自动创建）。

2、USE：切换当前 Database（可带 catalog 前缀）

USEdb1;

含义：把当前 database 设置成db1。
之后你写CREATE TABLE Orders (...)，它会落在：
当前catalog.db1.Orders

也可以写全一点：

USEcat1.db1;

这相当于一次性把 catalog + database 都切到目标位置（具体支持程度以你环境对 catalog/database 的实现为准，但语义就是“按前缀解析”）。

默认 database：default_database
db 不存在：抛异常。

3、USE MODULES：切换“函数/类型/规则”的解析顺序（非常实用，也非常容易忽略）

USEMODULES hive;

这句不是切 catalog/db，而是控制“元数据解析优先级”。它影响的典型对象包括：

• 内置/扩展函数（比如 hive 内置函数）
• 用户自定义类型（UDT）
• 规则、元数据解析（文档里统称 metadata）

3.1 什么是解析顺序？

当你执行：

SELECTmy_func(x)FROMt;

Flink 会按USE MODULES声明的顺序去查找my_func到底来自哪个模块。
如果你启用了多个模块，还能指定优先级：

USEMODULES hive,core;

意思就是：优先在 hive 模块里找，找不到再去 core 里找。

3.2 “loaded” 与 “used”的区别（核心坑点）

文档含义是：

• 模块被load后，默认是used=true（可用）
• 但一旦你执行USE MODULES ...，只有出现在列表里的模块会保持 used
  没出现在列表里的，即使已经 loaded，也会变成disabled（used=false）

所以你会看到类似：

SHOWFULLMODULES;-- hive true-- core false

这就是为什么“我之前还能用的函数突然找不到了”的典型原因之一：你换了模块启用列表。

4、Java 里怎么用？（executeSql 返回 OK 的那种）

在 Java（TableEnvironment / StreamTableEnvironment）里，你直接：

tEnv.executeSql("USE CATALOG cat1");tEnv.executeSql("USE db1");tEnv.executeSql("USE MODULES hive");

成功会返回OK（或者对应的 TableResult 可打印），失败则抛异常。
建议你在平台化/脚本执行场景里，把每一次USE都当成“可能失败的边界”，明确 catch 并记录上下文（当前 catalog/db/modules）。

5、一套推荐的“工程化用法”（避免环境漂移）

如果你在写作业/平台，强烈建议遵循这三条：

1. 任何 DDL/DML 执行前，显式 USE CATALOG + USE db
   避免默认的default_catalog.default_database导致表建错位置。

2. 模块切换要谨慎：USE MODULES hive会导致 core 被禁用（不在列表里）
   如果你依赖 core 的函数或规则，记得把它放进列表里：

   USEMODULES hive,core;

3. 对外提供 SQL 执行能力时：建议每个会话隔离上下文
   因为USE改的是“会话级的当前上下文”，很容易造成串环境问题。

6、总结

• USE CATALOG xxx：切换当前 catalog（默认default_catalog）
• USE db或USE catalog.db：切换当前数据库（默认default_database）
• USE MODULES ...：控制函数/类型/规则等元数据解析来源与优先级（默认模块core）
• 三者组合决定：你不写全限定名时，SQL 到底解析到哪里、函数到底用哪个实现