当前位置：首页 > news >正文

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

news 2026/7/3 6:01:56

USECATALOG cat1;

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

SHOWDATABASES;CREATETABLEt1(...);

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

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

USEdb1;

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

也可以写全一点：

USEcat1.db1;

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

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

USEMODULES hive;

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

当你执行：

SELECTmy_func(x)FROMt;

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

USEMODULES hive,core;

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

文档含义是：

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

所以你会看到类似：

SHOWFULLMODULES;-- hive true-- core false

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

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

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

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

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

任何 DDL/DML 执行前，显式 USE CATALOG + USE db
避免默认的default_catalog.default_database导致表建错位置。
模块切换要谨慎：USE MODULES hive会导致 core 被禁用（不在列表里）
如果你依赖 core 的函数或规则，记得把它放进列表里：
```
USEMODULES hive,core;
```
对外提供 SQL 执行能力时：建议每个会话隔离上下文
因为USE改的是“会话级的当前上下文”，很容易造成串环境问题。