SQL Iceberg 的表格式与 catalog（Hive / Glue / REST）的多引擎兼容实践

iceberg表格式不绑定catalog，跨引擎共享元数据需统一catalog实现与配置；推荐restcatalog（版本≥0.14.0、server/client一致）、hivecatalog（关自动建库、统一metastore连接）或gluecatalog（显式region/role），避免混用catalog导致snapshot冲突。

Iceberg 表格式本身不绑定 catalog，但 engine 对 catalog 的支持程度差异极大

Iceberg 是表格式（table format），不是存储系统或元数据服务。它只定义了快照、清单、数据文件的组织方式；catalog 才负责存 table 到 snapshot 的映射关系。所以你用 spark 写入 HiveCatalog，Trino 可能读不到——不是 Iceberg 有问题，而是 Trino 没配对的 catalog 实现，或者版本不匹配。

常见错误现象：Table not found 或 Failed to load table metadata，往往不是路径错了，是 catalog 类型没对上、URI 拼错、或 engine 根本不支持该 catalog。

• Spark 3.3+ 原生支持 HiveCatalog、GlueCatalog、RestCatalog（需启用 iceberg-spark-runtime）
• Trino 400+ 支持 hive 和 glue catalog，但 RestCatalog 需要插件（trino-iceberg + 配置 iceberg.rest-catalog.uri）
• flink 1.17+ 仅支持 HiveCatalog 和 RestCatalog，GlueCatalog 无官方实现（社区有 patch，但不稳定）
• 所有引擎都要求 catalog 的序列化协议一致：比如 HiveCatalog 必须用相同的 hive-site.xml 路径和 metastore URI，否则看到的表可能“存在但空”

GlueCatalog 在跨引擎时最容易出权限和 region 不一致问题

GlueCatalog 看似“云原生即开即用”，但实际依赖 AWS 凭据链、region 配置、以及 Glue 数据库/表的 ACL。Spark 和 Trino 如果用不同 role 或不同 region 初始化 Glue 客户端，会各自看到不同的命名空间视图。

典型表现：Spark can list tables, but Trino returns empty result，或 AccessDeniedException 即使用了同一 IAM role。

• 必须显式配置 glue.region，不能依赖默认 region（尤其在跨 region 部署时）
• Glue 数据库名区分大小写，且不支持下划线开头；Spark 默认把 my_db 当成 my-db 处理，导致表注册到错误库
• Trino 的 glue connector 默认禁用 hive 兼容模式，若 Iceberg 表是用 HiveCatalog 创建的，直接切 GlueCatalog 会读不到 schema（字段类型映射不一致）
• GlueCatalog 不支持 atomic rename，所以 Spark 用 replace 操作后，Trino 可能短暂看到旧 snapshot

RestCatalog 是目前多引擎兼容性最稳的选择，但 server 端必须统一版本

RestCatalog 把元数据操作转成 http 请求，天然解耦 engine 和 metastore 实现。只要所有 client 都连同一个 rest-catalog.uri，且 server（如 Nessie、Amundsen、或 Iceberg REST Server）版本 >= 0.14.0，基本不会出现“一个引擎写，另一个读不到”的问题。

但容易踩的坑是 client 和 server 的 Iceberg 版本 mismatch：比如 Spark 用 1.4.2，server 用 1.3.0，snapshot-id 解析失败，报 Unknown field: sequence-number。

• client 端必须设置 warehouse（S3/hdfs 路径）与 server 端完全一致，否则 listTables 返回空
• REST server 必须开启 CORS（如果 client 是 notebook 或 web ui），否则 fetch metadata 403
• RestCatalog 不支持 createNamespace 的递归创建，createTable 前必须确保 database 已存在（server 端手动 or 脚本预置）
• 认证方式要对齐：Spark 用 rest-catalog.Token，Trino 用 iceberg.rest-catalog.authentication.type=BEARER，漏配就 401

HiveCatalog 跨引擎共享最简单，但必须关掉 metastore 的自动建库行为

HiveCatalog 本质是 JDBC 访问 Hive Metastore，只要所有 engine 连同一套 mysql/postgresql，理论上最易共享。但 Hive Metastore 默认开启 hive.metastore.schema.evolution 和自动建库，会导致 Spark 写入时悄悄新建 database，而 Trino 因权限限制看不到新库。

更隐蔽的问题是：Hive Metastore 对 Iceberg 表的 parameters 字段长度有限制（默认 4000 字符），超长就截断，导致 current-snapshot-id 错误，engine 读到 stale 数据。

• 务必关闭 hive.metastore.autocreate，所有 database 必须提前由 dba 创建并授予权限
• 调大 metastore.thrift.max.message.size 和 datanucleus.rdbms.max.connection.pool.size，避免高并发写 snapshot 时连接池耗尽
• Spark 和 Trino 的 hive-site.xml 必须完全一致，尤其是 hive.metastore.uris 和 javax.jdo.option.ConnectionURL
• 不要混用 HiveCatalog 和其它 catalog 注册同一张物理表——Iceberg 不禁止，但 snapshot 清单路径冲突，expire_snapshots 会误删

事情说清了就结束。真正麻烦的从来不是选哪个 catalog，而是让所有 engine 对同一份元数据达成“原子级共识”——这要求 client 配置、server 版本、网络策略、权限模型全部对齐，缺一不可。