3. 元数据目录结构：Catalog、Namespace、Table 的层次关系及元数据存储位置

3.1 核心原理：三级命名空间如何组织 Iceberg 表

Iceberg 元数据管理的核心在于其 三级命名空间（Three-Level Namespace） 结构：Catalog → Namespace → Table。这一结构并非 Iceberg 独创，而是借鉴了传统数据库的“实例→数据库→表”模型，但 Iceberg 将其抽象为跨引擎的统一标准。理解这一层次关系，是掌握 Iceberg 元数据路由、权限控制以及多引擎协作的基础。

在 Iceberg 中，Catalog 是元数据服务的入口，它负责维护 Namespace 与 Table 的注册信息，并决定底层元数据文件（如 .metadata.json）的存储位置。一个 Catalog 可以对应一个 Hive Metastore、一个 AWS Glue 服务、一个 JDBC 数据库，甚至是一个内存中的目录实现。Catalog 本身并不存储表数据，它只提供“查找表”的能力。

Namespace 是表的逻辑分组，类似于关系数据库中的“数据库”或“Schema”。它用于隔离不同业务团队或不同应用的数据域。例如，我们可以创建 ods（操作数据存储）、dwd（数据明细层）、ads（应用数据层）等 Namespace，每个 Namespace 下可以包含多张表。Namespace 的层级可以嵌套，但 Iceberg 官方推荐保持扁平化，避免过深的目录层级导致管理复杂。

Table 是 Iceberg 元数据管理的最终对象。每张 Iceberg 表在 Catalog 中拥有唯一的标识符，形如 catalog_name.namespace_name.table_name。表本身并不直接存储数据文件路径的清单，而是通过一个“元数据指针”指向当前最新的元数据文件。这个指针存储在 Catalog 中，而元数据文件则存放在分布式文件系统（如 HDFS、S3）或对象存储的特定目录下。

核心要点：Iceberg 的元数据管理是“逻辑与物理分离”的。Catalog 只负责逻辑映射（表名 → 元数据文件位置），而真正的表结构、分区信息、快照历史、数据文件清单全部以 JSON 或 Avro 格式的文件形式存储在文件系统中。这种设计使得 Iceberg 表可以脱离特定引擎存在，任何支持 Iceberg 的引擎（Spark、Flink、Trino）只要拿到 Catalog 配置，就能读取同一张表。

Iceberg 元数据目录结构：Catalog → Namespace → Table Catalog 层（元数据服务入口） 实现：HiveMetastoreCatalog / GlueCatalog / JdbcCatalog / HadoopCatalog 职责：维护 Namespace 注册表 + Table 元数据指针（指向最新 metadata.json 位置） Catalog 元数据表 db1.table1 → s3://bucket/wh/db1/table1 db2.table2 → s3://bucket/wh/db2/table2 Namespace 层（逻辑分组 / 数据库） ods（操作数据层） 表：orders, users, payments 路径：/wh/ods/ dwd（明细数据层） 表：order_detail, user_detail 路径：/wh/dwd/ ads（应用数据层） 表：daily_sales, user_rpt 路径：/wh/ads/ Table 层（以 ods.orders 为例） 表目录：s3://warehouse/wh/ods/orders/ metadata/ ├── v1.metadata.json (初始元数据) ├── v2.metadata.json (当前最新) ├── snap-1234.avro (快照清单) └── manifest-list.avro 数据文件（Data Files） data/ ├── dt=2024-01-01/ │ └── 00000-0.parquet ├── dt=2024-01-02/ │ └── 00000-0.parquet Catalog 指针 → 最新 metadata.json

3.2 元数据存储位置与文件组织

Iceberg 表的元数据并非存储在 Catalog 服务内部，而是以文件形式存放在表目录（Table Root）下。表目录的路径由 Catalog 的配置项 warehouse 和 Namespace/Table 名称共同决定。以 S3 为例，默认布局如下：

s3://my-warehouse/
└── ods/                          # Namespace 目录
    └── orders/                   # 表目录（Table Root）
        ├── metadata/             # 元数据目录
        │   ├── v1.metadata.json  # 第1版元数据（初始 schema）
        │   ├── v2.metadata.json  # 第2版元数据（当前版本）
        │   ├── snap-1234567890.avro   # 快照1的 manifest 列表
        │   ├── snap-1234567891.avro   # 快照2的 manifest 列表
        │   └── 00000-0.avro           # manifest 文件（记录数据文件位置）
        └── data/                 # 数据文件目录
            ├── dt=2024-01-01/
            │   └── 00000-0.parquet
            └── dt=2024-01-02/
                └── 00000-0.parquet

其中 metadata.json 是元数据的“入口文件”，它包含了表结构（Schema）、分区规范（Partition Spec）、快照列表、当前快照 ID、历史快照的过期时间等关键信息。每次对表执行 DDL（如 ALTER TABLE）或 DML（如 INSERT、MERGE）操作，Iceberg 都会生成一个新的 vN.metadata.json 文件，并更新 Catalog 中的指针指向最新版本。这种“不可变快照”机制保证了元数据操作的事务性和并发安全性。

Manifest 文件（.avro 格式）则负责记录数据文件与快照的对应关系。每个 Manifest 文件包含一组数据文件的路径、分区值、列统计信息（如 min/max 值）、文件大小等。通过 Manifest 的过滤，Iceberg 可以在查询时快速跳过不相关的数据文件，这是 Iceberg 高性能查询的关键。

3.3 方法流程：如何通过 Catalog 定位并读取一张表

当 Spark 或 Flink 执行 SELECT * FROM ods.orders 时，Iceberg 的解析流程如下：

  1. 加载 Catalog：根据 Spark 会话中的 spark.sql.catalog.my_catalog 配置，实例化对应的 Catalog 实现类（如 HiveCatalog）。
  2. 解析 Namespace：将 ods 解析为 Namespace 名称，Catalog 检查该 Namespace 是否存在，并获取其元数据（如存储路径前缀）。
  3. 查找 Table：在 Catalog 内部的表注册表中查找 ods.orders，获取该表当前元数据文件的完整路径（例如 s3://my-warehouse/ods/orders/metadata/v2.metadata.json）。
  4. 加载元数据：从文件系统读取 v2.metadata.json，解析出表结构、当前快照 ID、Manifest 列表位置。
  5. 读取 Manifest：根据当前快照 ID，读取对应的 snap-*.avro 文件，获得 Manifest 文件列表，再加载 Manifest 文件获取数据文件清单。
  6. 规划扫描：结合查询条件（如 WHERE dt = '2024-01-01'），利用 Manifest 中的分区统计信息过滤掉无关数据文件，生成扫描计划。

这一流程中，Catalog 只参与第 1～3 步，后续步骤全部由 Iceberg 的客户端库直接与文件系统交互。因此，即使 Catalog 服务短暂不可用，已经加载了元数据缓存的查询任务仍可继续执行（取决于具体实现）。

3.4 案例：多引擎共享同一 Iceberg 表

假设数据团队使用 Spark 进行夜间批处理，使用 Flink 进行实时流写入，使用 Trino 进行即席查询。三者通过同一个 Hive Metastore 作为 Catalog，指向同一份 S3 数据仓库。

引擎 Catalog 配置 操作 元数据变化
Flink hive_catalog (Hive Metastore) 实时写入 ods.orders 每次 checkpoint 生成新快照，更新 v3.metadata.json
Spark hive_catalog (Hive Metastore) 批处理读取 dwd.order_detail 读取最新快照，无元数据变更
Trino hive_catalog (Hive Metastore) 即席查询 ads.daily_sales 读取最新快照，无元数据变更

由于 Iceberg 的元数据文件存储在 S3 上，且 Catalog 中的指针始终指向最新版本，三个引擎无需任何锁或协调机制即可并发读写同一张表。Flink 写入新快照时，Spark 可能正在读取旧快照，两者互不阻塞。这正是 Iceberg 相比 Hive 表（依赖 Hive Metastore 的锁机制）的巨大优势。

3.5 误区与复盘：常见理解偏差

误区一：认为 Catalog 存储了表数据或数据文件路径。实际上，Catalog 只存储“表名 → 元数据文件路径”的映射关系，数据文件路径记录在 Manifest 文件中，而 Manifest 文件路径记录在 metadata.json 中。Catalog 不直接感知数据文件的存在。

误区二：将 Namespace 等同于 HDFS 目录。Namespace 是逻辑概念，虽然默认情况下 Namespace 名称会映射为表目录路径的一部分（如 ods → /wh/ods/），但 Namespace 的权限控制、属性设置（如 location 覆盖）完全由 Catalog 管理，与物理目录并非一一对应。用户可以指定 Namespace 的 location 属性，使其指向任意存储位置。

复盘建议：在排查 Iceberg 表无法读取的问题时，应按照“Catalog 配置 → Namespace 是否存在 → Table 元数据文件是否可访问 → Manifest 文件是否损坏”的顺序逐层排查。最常见的错误是 Catalog 中表的指针指向了一个已被删除或移动的 metadata.json 文件，此时需要检查 Catalog 的元数据刷新策略。

理解 Catalog、Namespace、Table 的三级结构，是掌握 Iceberg 元数据管理的第一步。在实际生产环境中，合理规划 Namespace 的层级（建议不超过两层），并为每个 Catalog 配置独立的 warehouse 路径，可以有效避免元数据混乱和权限越界问题。

← 上一章 📖 返回目录 下一章 →