Iceberg 的 Catalog API：Iceberg 表背后的原子指针管理器

Apache Iceberg极大地重塑了组织管理和与对象存储中的海量结构化分析数据集交互的方式。它带来了类似数据库的可靠性以及 ACID 事务、模式演化和时间旅行等强大功能。虽然这些功能通常被强调，但Iceberg Catalog API才是使这些表易于访问的关键。

Iceberg Catalog API 是一个用于管理表元数据的集中式接口，允许用户轻松地创建、读取、更新和删除表。该 API 有助于与各种数据处理引擎集成，并确保在不同环境中对数据的一致访问，从而增强组织内部的协作和数据治理。

许多目录实现（例如Apache Polaris）都遵循本规范中定义的操作，从而确保了互操作性的基准。然而，这些目录也经常提供超出标准规范的扩展。

在本文中，我们将探索 Iceberg Catalog API，明确其最关键的功能是元数据指针的原子管理。然后，我们将区分这些核心指针操作与其他提供便利的符合规范的 API，并讨论常见的扩展（尤其是治理功能）通常位于标准规范之外的原因。理解操作层次至关重要，因为大多数数据目录的核心目标是促进发现、提供元数据访问治理以及管理相关功能。通过提供指向表元数据的索引或指针，此结构可确保高效地发现表，同时允许对元数据进行受控的访问和管理。

基础：指针为何重要——导航和管理数据海洋

您的对象存储（如 Minio AIStor、Amazon S3、Google Cloud Storage）是一个巨大的数据海洋。它包含大量的数据，远远超出了结构化的 Iceberg 表；它可能包含原始日志、图像、视频，以及至关重要的 Iceberg 表的组成文件 - metadata.json、清单列表、清单文件和数据文件本身。

在浩瀚的数据海洋中，查找特定的 Iceberg 表就像在没有地图的情况下搜索特定的舰队一样困难。这时，Iceberg Catalog 就变得不可或缺。它的主要基本作用是作为这片海洋中 Iceberg 表的高度专业化的索引或地图。它能够在海量非结构化或结构化信息中发现结构化、可查询的数据。

它不存储数据或其相应的元数据；相反，它维护指向每个表的当前状态的指针，该指针由最新表状态的根元数据文件表示。

这使得传统计算引擎（例如Spark、 Trino、Impala）和现代引擎（例如 E6data、Dremio、Starburst和PuppyGraph）能够快速准确地找到 Iceberg 表的定义位置，而无需扫描数 TB 的无关数据。它会告诉您的查询引擎：“要查找表‘X’，请查阅对象存储中这个特定的metadata.json 文件。”

鉴于目录掌握着这些宝贵表定义的密钥，控制谁可以发现和访问这些定义变得至关重要。这就引出了治理的概念。虽然 Iceberg REST Catalog API 的核心规范主要关注管理这些元数据指针的机制（例如用于一致性的原子更新），但它本身并没有定义一个全面的安全模型。

Apache Polaris 等实现正是在此基础上扩展了基础功能。Polaris 引入了基于角色的访问控制 (RBAC) 等治理功能。然而，了解此功能的作用范围至关重要。由于 Iceberg 目录通常不保存表数据，因此Polaris 提供的 RBAC 主要并非用于直接数据治理（即控制对数据文件中特定行或列的访问，尽管凭证售卖等功能在确保数据访问安全方面发挥了间接作用）。

相反，在 Iceberg 目录的核心功能背景下，Polaris 提供的治理更准确地说是元数据指针治理。它控制：

• 谁能发现一个表（用指针表示）的存在？
• 谁可以读取元数据指针来了解表的结构及其数据文件的位置？
• 谁可以更新这些关键元数据指针（即谁有权修改表的状态）？

因此，虽然 Iceberg 目录的基本任务是维护并自动更新用于表发现和版本控制的指针，但像 Polaris 的 RBAC 这样的扩展功能增加了一个关键的控制层，用于控制谁可以与这些指针交互。这与对象存储本身的文件级 ACL 等不同，它为定义 Iceberg 资产的元数据提供了一个更结构化、更可感知表的安全模型。

Iceberg Catalog API：操作范围

任何与 Iceberg 兼容的目录（例如 Apache Polaris）都实现了 Iceberg REST Catalog API 规范。这确保了互操作性的基准，允许不同的计算引擎以一致的方式与表交互。然而，目录提供商通常会提供增值功能，例如增强的安全性、多目录视图或目录联合，这些功能是超出此规范的扩展。

然而，即使在 Iceberg REST Catalog API 规范规定的操作中，并非所有操作对表核心状态的影响都一样。有些操作对于指针管理至关重要，而另一些操作则提供了适当但辅助的功能。让我们来区分一下它们。

规范的核心：原子指针管理 API

这些操作创建、修改或删除定义 Iceberg 表状态的基本指针。它们是真正的“原子指针管理器”。

1、创建表（POST /v1/{prefix}/namespaces/{ns}/tables）：

• 指针操作：在目录中建立指向新表的第一个 metadata.json 文件的初始指针。此操作从目录的角度来看，使表得以存在。

2、更新表/提交更改（POST /v1/{prefix}/namespaces/{ns}/tables/{table} 或 POST /v1/{prefix}/transactions/commit）：

• 指针操作：这是表修改的核心操作。它以原子方式将目录指针从旧的 metadata.json 交换到新的。通过这种方式，追加、覆盖、模式更改和其他修改操作将被持久地提交到表中。提交端点专门处理多表原子事务的此操作。

3、删除表（DELETE /v1/{prefix}/namespaces/{ns}/tables/{table}）：

• 指针操作：从目录中移除指针，实际上是从目录视图中删除该表。底层数据和元数据文件可能仍存在于对象存储中，直到清理过程（例如，使旧快照过期）将其删除。

4、注册表 (POST /v1/{prefix}/namespaces/{ns}/register)：

• 指针操作：允许目录“采用”并指向现有的、非托管的 Iceberg 表元数据（即对象存储中现有的 metadata.json）。它会在目录中创建一个指向此现有 metadata.json 的新指针。

5、重命名表（POST /v1/{prefix}/tables/rename）：

• 指针操作：修改与目录内部注册表中的现有指针关联的标识符（名称），而不更改指向的实际 metadata.json 文件。

这些操作不可或缺。没有它们，目录就无法通过精确且原子的指针操作来实现其主要作用，即对表状态进行版本控制。

规范中的便利性：命名空间和扫描规划

Iceberg 规范还包括一些 API，虽然它们对组织和性能有用，但不会直接改变定义表状态的核心元数据指针。

1、命名空间操作（GET/POST/DELETE /v1/{prefix}/namespaces/...）：

• 功能：这些 API 允许创建、列出和删除命名空间（逻辑分组，通常类似于数据库或模式）。
• 区别：命名空间用于组织表指针在目录中的存储位置或分类。它们提供了用于管理表的层次结构，但不会改变指向 metadata.json 文件的基本指针。它们与目录的内部组织以及表的分组方式有关。

2、扫描计划 API (POST /v1/{prefix}/namespaces/{ns}/tables/{table}/plan, /tasks)：

• 功能：这些端点允许计算引擎将查询计划的部分内容（例如基于分区过滤器的文件修剪）卸载到目录服务。
• 区别：扫描 API读取当前元数据指针定义的状态（例如，通过访问清单文件）以优化查询执行。它们不会修改指针；而是根据这些指针定义的状态进行操作，以返回文件或任务的子集供引擎处理。

这些功能对于可用性和查询性能很有价值，但对于管理状态定义指针的核心任务来说是次要的。

超越规范的扩展：Apache Polaris 中的治理、多目录等

许多实际的目录实现（例如 Apache Polaris）提供的功能远远超出了 Iceberg REST Catalog API 规范中概述的要求。这些增强功能通常特定于供应商或项目。

• 基于角色的访问控制 (RBAC) 和安全：Iceberg 规范并未定义安全模型，因此这一问题在很大程度上尚未得到解决。相比之下，像 Polaris 这样的目录实现了 API 和机制来管理目录、命名空间和表的权限。例如，Polaris 使用 /api/management/v1/roles 和 /grants 等端点，正如其使用模式和文档中所示。此治理层围绕核心指针操作设计，以有效地控制访问。
• 多目录管理与联合：管理多个不同的目录是一项宝贵的功能，但 Iceberg 目录 API 规范并未明确规定。此架构功能在各个 Iceberg 目录规范之上提供了一个统一的管理视图或平面。
• 审计日志：全面跟踪谁访问或修改了表的元数据（例如它们的指针）以及这些操作发生的时间通常是目录实现提供的扩展，而不是规范要求。

这些扩展显著增强了目录在企业环境中的实用性。尽管如此，它们并非所有符合 Iceberg 标准的引擎都能在无需特定集成的情况下理解的标准化接口的一部分。

目录的主要指令：掌握指针

虽然 Iceberg 目录 API（由 Apache Polaris 等解决方案实现）提供了一系列功能，但其最关键且不可或缺的作用是对元数据指针进行原子管理。这确保了数据一致性，支持 ACID 事务，并允许多个计算引擎进行安全的并发访问。直接处理这些指针的操作构成了 Iceberg 规范的真正核心。其他符合规范的 API（例如用于命名空间管理或扫描规划的 API）则提供了便利性和组织优势。

关键的企业功能，特别是与治理和安全相关的功能，通常由 Apache Polaris、Gravitino、Nessie、Lakekeeper等供应商作为有价值但非标准的扩展来实现。Iceberg 的目录市场正在成为创新的竞争场所，专注于扩展标准规范的独家功能集。

对于任何使用 Iceberg 表及其目录的开发人员或架构师来说，理解其层次结构（包括核心指针管理器、规范定义的便利功能以及供应商/项目扩展）都至关重要。这种理解可以阐明真正的事务完整性和状态管理位于何处，以及不同的目录实现如何基于这个强大的、以指针为中心的基础来提供更广泛的数据管理功能。