Flink Catalogs 元数据统一入口、JDBC/Hive/自定义 Catalog、Time Travel、Catalog Store 与监听器

1. Catalog 是什么，为什么重要

Catalog 负责提供并管理元数据，例如：

catalogs / databases
tables / partitions / views
functions（持久化 UDF）
访问外部系统所需的连接信息（如 JDBC、Hive Metastore 等）

Catalog 的核心价值有两点：

统一元数据 API：无论后端是 Hive Metastore、MySQL、Postgres、内存，都用一套 Table API / SQL 访问
减少重复 DDL：例如 JDBC Catalog 能把数据库里的表映射成 Flink table，避免你在 Flink 里重复写一堆 CREATE TABLE

2. Catalog Types：有哪些实现

2.1 GenericInMemoryCatalog

纯内存 Catalog
只在当前 session 生命周期内有效
默认存在：default_catalog + default_database

2.2 JdbcCatalog

通过 JDBC 连接关系型数据库
目前主要实现：Postgres Catalog、MySQL Catalog（属于 JDBC Catalog 的实现）
用途：把 RDB 的库表"映射进 Flink"，减少 DDL 工作量

2.3 HiveCatalog

两个作用：
1. 作为 Flink 元数据的持久化存储
2. 读写已有 Hive 元数据（Hive Metastore）
注意点：Hive Metastore 会把 meta-object 名字存成小写，这和 GenericInMemoryCatalog 的大小写敏感不同（迁移/兼容时常踩坑）

2.4 User-Defined Catalog

通过实现 Catalog 接口实现自定义 Catalog（比如对接你们内部元数据系统）
如果要在 Flink SQL 里 CREATE CATALOG ... WITH (...) 这种方式使用，还需要实现 CatalogFactory
Factory 通过 Java SPI 发现：把实现类写到 META-INF/services/org.apache.flink.table.factories.Factory

补充（很关键）：从 Flink 1.16 开始，TableEnvironment 引入 user classloader（为了 SQL Client / SQL Gateway / table program 一致）。自定义 Catalog 加载类时别用 Thread.currentThread().getContextClassLoader()，要用 CatalogFactory.Context#getClassLoader()，否则会出现 ClassNotFoundException。

3. Catalog 的基本使用：注册、切换与引用

3.1 注册 Catalog

你可以往 session 注册多个 Catalog。

Java 示例（HiveCatalog）：

java 复制代码

Catalog catalog = new HiveCatalog("myhive", null, "<path_of_hive_conf>");
tableEnv.registerCatalog("myhive", catalog);

3.2 切换当前 catalog/database

Flink 查找表、视图、函数时，默认只在"当前 catalog + 当前 database"里找：

java 复制代码

tableEnv.useCatalog("myCatalog");
tableEnv.useDatabase("myDb");

3.3 跨 catalog 访问：三段式全限定名

不在当前 catalog/database 下的对象，用：
catalog.database.object

例如：

java 复制代码

tableEnv.from("not_the_current_catalog.not_the_current_db.my_table");

3.4 常用 list

listCatalogs()
listDatabases()
listTables()

4. 如何把表写进 Catalog：SQL DDL / API 两种方式

4.1 SQL DDL（Table API 里也能 executeSql）

典型路径：

CREATE DATABASE ...
CREATE TABLE ... WITH (...)

4.2 Programmatic API（更适合平台代码生成）

你可以直接构建 Schema + TableDescriptor，然后 createTable("catalog.db.table", ...)。

5. Catalog API 能做哪些元数据操作

Catalog API 按对象类型覆盖一整套 CRUD：

Database：create / drop / alter / get / exists / list
Table：create / drop / alter / rename / get / exists / list
View：本质也是 table（CatalogViewImpl）
Partition：create / drop / alter / get / exists / list（支持按表达式过滤）
Function：create / drop / alter / get / exists / list

如果你在做"元数据治理平台"，这些接口基本就是你的底层原语。

6. 从 1.18 开始：Catalog 支持 Time Travel

Flink 1.18 引入了"按时间点查询历史表"的能力，Catalog 侧需要实现：
getTable(ObjectPath tablePath, long timestamp)

你需要在这个方法里：

根据 timestamp 构建对应的 Schema（如果 schema 会变化）
构建 options（告诉 source 从哪个 snapshot 读）
返回带 snapshot(timestamp) 的 CatalogTable

然后在 DynamicTableSourceFactory 里通过：
context.getCatalogTable().getSnapshot() 拿到 snapshot，创建能读历史数据的 source。

这个设计本质上是：把"时间旅行"能力拆成两段

Catalog 决定"这个时间点的表长啥样、怎么读"
Connector/source 决定"怎么按 snapshot 读数据"

7. Catalog Modification Listener：监听 DDL 做联动

Flink 支持注册 CatalogModificationListener：

你可以在 CREATE/ALTER/DROP database/table 时收到事件
用途：同步到外部元数据系统、做审计、做变更通知、触发自动化流程等

实现要点：

实现 CatalogModificationListenerFactory（提供 identifier）
实现 CatalogModificationListener（处理事件）
同样通过 SPI 注册 factory
通过配置项启用：TableConfigOptions.TABLE_CATALOG_MODIFICATION_LISTENERS

SQL Gateway 侧也能通过 flink 配置项启用（适合多 session 场景）

8. Catalog Store：把"Catalog 配置"持久化下来

Catalog Store 解决的问题不是"表元数据"，而是"catalog 本身的配置 "。

例如：你在 session 里 CREATE CATALOG my_pg ...，希望 session 重启后还能自动恢复。

两种配置方式：

Table API：EnvironmentSettings.withCatalogStore(catalogStore)
配置文件/YAML：table.catalog-store.kind, table.catalog-store.file.path

内置实现：

GenericInMemoryCatalogStore：默认，session 结束就没了
FileCatalogStore：把每个 catalog 的配置存成一个 yaml 文件（支持 Flink FileSystem 抽象的本地/远程 FS）

注意：FileCatalogStore 初始化失败会导致 SQL Client / SQL Gateway 直接不可用（因为启动阶段就需要它）。

9. 实战建议：Catalog 在平台化里的典型落地

如果你在做数据平台/SQL 工作台，一般会这么用：

用 HiveCatalog/JdbcCatalog 对接企业已有元数据
用自定义 Catalog 对接你们内部数据目录（Data Catalog / Meta Service）
用 Catalog Store 固化 catalog 配置，让 SQL Gateway 每个 session 自动拥有同一套 catalog
用 Catalog Modification Listener 做 DDL 审计 + 元数据同步
需要历史查询时，为核心表实现 time travel（尤其是湖仓格式/版本表）

如果你希望我把这一节改写成可直接发 CSDN 的"技术博客版"，我可以按这个结构继续扩展：

Catalog vs Module 的边界与组合用法（函数来源冲突、解析顺序）
以 MySQL JdbcCatalog 为例：从 "注册 catalog → 列表 → 直接查询表" 的完整演示
自定义 CatalogFactory + SPI 的最小可运行骨架（包含 user classloader 的正确用法）
Time Travel 的一个"伪 Iceberg/Hudi 风格"的实现思路与 options 设计