Icevue为 Apache Iceberg REST Catalog 打造一个轻量、只读的可视化入口Apache Iceberg 已经成为数据湖和 Lakehouse 场景中广泛使用的开放表格式。它提供了 Schema Evolution、Hidden Partitioning、Snapshot、Time Travel、分支与标签等丰富能力但这些能力背后的元数据信息通常散落在 Catalog、metadata JSON、manifest 和对象存储中。当我们只是想回答一些很基础的问题时往往仍然需要打开 SQL 引擎、执行命令甚至直接阅读元数据文件当前 Catalog 中有哪些 Namespace 和 Iceberg 表一张表现在使用什么 Schema历史上发生过哪些变化表采用了什么分区规则当前有哪些分区最近一次 Snapshot 是 Append、Delete、Overwrite还是文件合并产生的 Replace一次 Compaction 重写了多少输入文件又生成了多少输出文件表上配置了哪些 Iceberg Properties、Sort Order、Branch 和 Tag这正是 Icevue 出现的原因。Icevue 是一个面向 Apache Iceberg REST Catalog 的开源、轻量、只读 Web UI。它直接使用 PyIceberg 访问 Catalog 和 Iceberg 元数据不依赖 Spark、Flink、Trino 等计算引擎目标是为平台工程师、数据工程师和数据湖运维人员提供一个简单、统一、低风险的元数据查看入口。当前版本v0.1.0GitHubhttps://github.com/norrishuang/Icevue为什么要做 Icevue1. Iceberg 元数据丰富但缺少一个聚合视图Iceberg 表并不只是一个 Schema 和一组数据文件。它还包含 Snapshot 历史、Partition Spec、Sort Order、Properties、References、Manifest 等大量元数据。这些信息可以通过不同 API、系统表或元数据文件获取但日常排查时用户真正需要的是一个可以快速浏览、比较和定位问题的统一界面。2. 查看元数据不应该依赖重型计算引擎如果只是为了确认表的分区规则或查看最近几次 Snapshot启动一个 Spark Session 或连接一套 SQL 引擎显得过于沉重。它增加了部署、权限、资源和运维成本也让一个原本简单的元数据查看动作变得复杂。Icevue 直接通过 PyIceberg 和 REST Catalog 工作不负责执行 SQL也不会扫描表数据。3. REST Catalog 的使用体验仍然偏 API 化Iceberg REST Catalog 提供了标准化的 Catalog 访问协议但用户通常仍然需要通过代码、CLI 或其他引擎与其交互。随着 Amazon S3 Tables、AWS Glue Data Catalog 等服务提供 Iceberg REST 接口一个能够管理多个连接并快速切换的 UI 会更有价值。4. 元数据排查需要一个明确的只读边界生产环境中的 Iceberg 表往往非常重要。为了避免误操作Icevue 第一版有意不提供建表、改表、写数据、回滚 Snapshot 或修改 Properties 的能力。Icevue 对 Iceberg Catalog 和表始终只读。页面中唯一会被写入的是 Icevue 自己的本地 Catalog 连接配置文件。Icevue 是什么Icevue 是一个单机部署的 Web 应用由 React 前端和 FastAPI 后端组成。后端通过 PyIceberg 创建 Catalog Client将 Iceberg 元数据转换为稳定的 JSON API再由前端以适合浏览和排查的方式展示。它当前提供以下能力管理和切换多个 Iceberg REST Catalog浏览 Namespace、Database 和 Table搜索 Namespace 与表名查看表的 Overview 和当前状态查看当前及历史 Schema查看 Partition Spec 和分区列表查看 Snapshot 历史及文件、记录变化查看 Sort Order、Branch、Tag 和 Table Properties支持通用 Iceberg REST Catalog支持 Amazon S3 Tables REST Catalog支持 AWS Glue Data Catalog 的 Iceberg REST Endpoint提供内置 Demo Catalog便于快速体验支持 Docker 和 Docker Compose 单机部署功能体验1. Overview快速理解一张表进入一张表后Overview 页面集中展示当前记录数、数据文件数量、表大小、Snapshot 数量、物理位置、metadata 文件、当前 Snapshot ID、Partition Spec、Sort Order 和 References。这个页面适合作为排查入口用户不需要先理解 Iceberg 元数据文件的结构就能快速建立对当前表状态的整体认识。2. 多 Catalog 连接管理Icevue 支持在同一个实例中保存多个 Catalog 连接。用户可以在页面中新增、编辑、测试、删除和切换 Catalog也可以指定默认连接。配置最终保存在本地 YAML 文件中。Token 和 Client Credential 不会通过配置查询 API 返回在 AWS 环境中更推荐使用 EC2 Instance Profile、ECS Task Role 或 EKS Workload Identity而不是长期 Access Key。3. Schema查看当前结构和历史版本Schema 页面展示字段 ID、字段名、数据类型、是否必填以及字段说明并保留 Iceberg Schema 的历史版本。字段 ID 对 Iceberg 很重要。即使列发生重命名Iceberg 仍然通过字段 ID 识别列。相比只查看 SQL DDL这个页面能够更准确地帮助用户理解 Schema Evolution。4. Partitions不扫描表数据也能查看分区Partitions 页面通过 PyIceberg 的table.inspect.partitions()获取分区信息。这个过程读取 Iceberg metadata 和 manifest而不是扫描业务数据文件。页面支持分区搜索和分页并展示每个分区对应的记录数、文件数、数据大小等可用统计信息。这对以下场景很有帮助确认新分区是否已经写入检查分区值是否符合预期发现文件数异常多的分区初步判断是否存在小文件问题检查 Hidden Partitioning 的实际结果需要注意的是当前版本会先读取完整的 Partition Inspection 结果再在 API 层进行搜索和分页。对于拥有海量分区或 Manifest 的表首次加载仍然可能产生一定的元数据读取开销。后续版本可以进一步加入缓存和流式处理。5. Snapshots看懂一次写入或 Compaction 做了什么Snapshots 页面按时间展示表的提交历史并显示 Operation、Snapshot ID、Sequence Number、当前 Snapshot 状态以及每次提交带来的文件和记录变化。当前页面重点展示Added files本次 Snapshot 新增的数据文件Removed files本次 Snapshot 从表中移除的数据文件Rewrite in → out对于replace操作展示重写输入文件数和输出文件数Total files提交完成后的数据文件总数Rows in added files新增数据文件中包含的记录数Rows in removed files被移除数据文件中包含的记录数Total records提交后的记录总数Total size提交后的文件总大小这里有一个容易误解的细节added-records和deleted-records并不一定代表业务层面的新增行和删除行。对于 Compaction旧文件中的记录会被完整重写到新文件因此Rows in added files和Rows in removed files可能是两个完全相同的非零值。此时57 → 8表示 57 个输入文件被合并为 8 个输出文件但表中的逻辑数据并没有因此增加或减少。6. Properties查看影响表行为的配置Iceberg Table Properties 会影响文件格式、压缩算法、目标文件大小、Snapshot 保留策略等行为。Properties 页面将这些键值集中展示并提供搜索能力。相比直接打开 metadata JSON这种方式更适合快速确认某项配置是否已经生效。技术架构Icevue 有意保持简单不引入数据库或分布式计算引擎。HTTP / JSONManage connectionsREST Catalog protocolRead metadataBrowser / React UIFastAPILocal catalogs.yamlPyIcebergIceberg REST CatalogObject Storage / Metadata / Manifests前端前端使用 React、TypeScript 和 Vite 构建提供 Catalog 导航、表级 Tab、搜索、分页和响应式布局。生产构建产物由 FastAPI 直接提供因此部署时只需要一个容器。后端FastAPI 后端负责读取和保存catalogs.yaml创建并缓存 PyIceberg Catalog Client隐藏 Token 和 Credential将 PyIceberg 对象转换为稳定的 API Model提供 Namespace、Table、Partition 等只读 API托管前端静态资源和 OpenAPI 文档为什么选择 PyIcebergPyIceberg 足够轻量并且能够直接理解 Iceberg 的 Schema、Snapshot、Manifest、Partition 和 Table Metadata。对于一个只读元数据浏览器它比引入 Spark 或其他查询引擎更符合需求。Icevue 不执行 SQL也不读取业务数据内容。它只读取完成页面展示所需的 Catalog 和 Iceberg 元数据。多种 REST Catalog通用 Iceberg REST Catalog通用 REST Catalog 只需要提供 URI、Warehouse以及 Catalog 所要求的 Token、OAuth2 或其他 PyIceberg Properties。Amazon S3 TablesAmazon S3 Tables 使用 AWS SigV4id:s3tablesname:Amazon S3 Tablestype:resturi:https://s3tables.us-east-1.amazonaws.com/icebergwarehouse:arn:aws:s3tables:us-east-1:123456789012:bucket/my-table-bucketproperties:rest.sigv4-enabled:truerest.signing-name:s3tablesrest.signing-region:us-east-1AWS Glue Data CatalogAWS Glue Data Catalog 同样可以通过 Iceberg REST Endpoint 接入id:glue-prodname:AWS Glue Productiontype:resturi:https://glue.us-east-1.amazonaws.com/icebergwarehouse:123456789012properties:rest.sigv4-enabled:truerest.signing-name:gluerest.signing-region:us-east-1Glue Data Catalog 中可能同时存在 Parquet、Delta、Hudi 和 Iceberg 表。Icevue 会保留 Database 视图但只展示 Glue Metadata 能够识别为 Iceberg 的表避免非 Iceberg 表在加载时影响整个 Catalog。只读不是限制而是第一版的安全边界Icevue 的“管理”对象是 Catalog 连接而不是 Iceberg 表本身。当前版本不会提供以下操作创建或删除 Iceberg 表修改 Schema、Partition Spec 或 PropertiesAppend、Update、Delete 或 Merge 数据回滚、过期或删除 Snapshot执行 Compaction这样的边界让 Icevue 可以使用最小化的只读权限部署到生产环境。即使 UI 暴露在更多用户面前也不会因为一个按钮误操作而改变表状态。需要注意的是Icevue 当前不内置用户登录系统。生产部署时应当将它放在带身份认证的 HTTPS Reverse Proxy、Ingress 或企业网关之后同时为 Catalog Principal 配置最小只读权限。快速开始最简单的体验方式是使用内置 Demo Cataloggitclone https://github.com/norrishuang/Icevue.gitcdIcevuedockercompose up--build-d打开http://localhost:8000OpenAPI 文档位于http://localhost:8000/api/docsCatalog 配置会保存在 Docker Volume 中。也可以通过 UI 新增连接并执行Test connection连接成功后再保存。当前限制与后续方向Icevue 的第一版聚焦于“把 Iceberg 元数据看清楚”因此仍有一些可以继续演进的方向为超大 Catalog 增加 Namespace 和 Table 分页为 Partition 和 Manifest Inspection 增加缓存支持流式读取和增量加载超大分区列表增加 Snapshot 对比视图展示 Manifest、Data File 和 Delete File 的更细粒度信息增加可选的用户认证和授权集成增加更多 REST Catalog 的兼容性测试提供可观测性指标和审计日志这些能力仍然会遵守一个核心原则默认只读不把查看工具变成新的生产变更入口。总结Icevue 解决的不是如何执行更复杂的 Iceberg 计算而是如何更简单地理解一张 Iceberg 表。它希望把原本分散在 REST API、metadata JSON、manifest、命令行和 SQL 系统表中的信息整理成一个轻量、直观、可以随时打开的工作界面。如果你正在使用 Apache Iceberg、Amazon S3 Tables 或 AWS Glue Data Catalog并且也遇到过“只是想看一下表的元数据却要先启动一套引擎”的问题欢迎试用 Icevue也欢迎通过 Issue 和 Pull Request 提供反馈。项目地址https://github.com/norrishuang/Icevue
Icevue：为 Apache Iceberg REST Catalog 打造一个轻量、只读的可视化入口
Icevue为 Apache Iceberg REST Catalog 打造一个轻量、只读的可视化入口Apache Iceberg 已经成为数据湖和 Lakehouse 场景中广泛使用的开放表格式。它提供了 Schema Evolution、Hidden Partitioning、Snapshot、Time Travel、分支与标签等丰富能力但这些能力背后的元数据信息通常散落在 Catalog、metadata JSON、manifest 和对象存储中。当我们只是想回答一些很基础的问题时往往仍然需要打开 SQL 引擎、执行命令甚至直接阅读元数据文件当前 Catalog 中有哪些 Namespace 和 Iceberg 表一张表现在使用什么 Schema历史上发生过哪些变化表采用了什么分区规则当前有哪些分区最近一次 Snapshot 是 Append、Delete、Overwrite还是文件合并产生的 Replace一次 Compaction 重写了多少输入文件又生成了多少输出文件表上配置了哪些 Iceberg Properties、Sort Order、Branch 和 Tag这正是 Icevue 出现的原因。Icevue 是一个面向 Apache Iceberg REST Catalog 的开源、轻量、只读 Web UI。它直接使用 PyIceberg 访问 Catalog 和 Iceberg 元数据不依赖 Spark、Flink、Trino 等计算引擎目标是为平台工程师、数据工程师和数据湖运维人员提供一个简单、统一、低风险的元数据查看入口。当前版本v0.1.0GitHubhttps://github.com/norrishuang/Icevue为什么要做 Icevue1. Iceberg 元数据丰富但缺少一个聚合视图Iceberg 表并不只是一个 Schema 和一组数据文件。它还包含 Snapshot 历史、Partition Spec、Sort Order、Properties、References、Manifest 等大量元数据。这些信息可以通过不同 API、系统表或元数据文件获取但日常排查时用户真正需要的是一个可以快速浏览、比较和定位问题的统一界面。2. 查看元数据不应该依赖重型计算引擎如果只是为了确认表的分区规则或查看最近几次 Snapshot启动一个 Spark Session 或连接一套 SQL 引擎显得过于沉重。它增加了部署、权限、资源和运维成本也让一个原本简单的元数据查看动作变得复杂。Icevue 直接通过 PyIceberg 和 REST Catalog 工作不负责执行 SQL也不会扫描表数据。3. REST Catalog 的使用体验仍然偏 API 化Iceberg REST Catalog 提供了标准化的 Catalog 访问协议但用户通常仍然需要通过代码、CLI 或其他引擎与其交互。随着 Amazon S3 Tables、AWS Glue Data Catalog 等服务提供 Iceberg REST 接口一个能够管理多个连接并快速切换的 UI 会更有价值。4. 元数据排查需要一个明确的只读边界生产环境中的 Iceberg 表往往非常重要。为了避免误操作Icevue 第一版有意不提供建表、改表、写数据、回滚 Snapshot 或修改 Properties 的能力。Icevue 对 Iceberg Catalog 和表始终只读。页面中唯一会被写入的是 Icevue 自己的本地 Catalog 连接配置文件。Icevue 是什么Icevue 是一个单机部署的 Web 应用由 React 前端和 FastAPI 后端组成。后端通过 PyIceberg 创建 Catalog Client将 Iceberg 元数据转换为稳定的 JSON API再由前端以适合浏览和排查的方式展示。它当前提供以下能力管理和切换多个 Iceberg REST Catalog浏览 Namespace、Database 和 Table搜索 Namespace 与表名查看表的 Overview 和当前状态查看当前及历史 Schema查看 Partition Spec 和分区列表查看 Snapshot 历史及文件、记录变化查看 Sort Order、Branch、Tag 和 Table Properties支持通用 Iceberg REST Catalog支持 Amazon S3 Tables REST Catalog支持 AWS Glue Data Catalog 的 Iceberg REST Endpoint提供内置 Demo Catalog便于快速体验支持 Docker 和 Docker Compose 单机部署功能体验1. Overview快速理解一张表进入一张表后Overview 页面集中展示当前记录数、数据文件数量、表大小、Snapshot 数量、物理位置、metadata 文件、当前 Snapshot ID、Partition Spec、Sort Order 和 References。这个页面适合作为排查入口用户不需要先理解 Iceberg 元数据文件的结构就能快速建立对当前表状态的整体认识。2. 多 Catalog 连接管理Icevue 支持在同一个实例中保存多个 Catalog 连接。用户可以在页面中新增、编辑、测试、删除和切换 Catalog也可以指定默认连接。配置最终保存在本地 YAML 文件中。Token 和 Client Credential 不会通过配置查询 API 返回在 AWS 环境中更推荐使用 EC2 Instance Profile、ECS Task Role 或 EKS Workload Identity而不是长期 Access Key。3. Schema查看当前结构和历史版本Schema 页面展示字段 ID、字段名、数据类型、是否必填以及字段说明并保留 Iceberg Schema 的历史版本。字段 ID 对 Iceberg 很重要。即使列发生重命名Iceberg 仍然通过字段 ID 识别列。相比只查看 SQL DDL这个页面能够更准确地帮助用户理解 Schema Evolution。4. Partitions不扫描表数据也能查看分区Partitions 页面通过 PyIceberg 的table.inspect.partitions()获取分区信息。这个过程读取 Iceberg metadata 和 manifest而不是扫描业务数据文件。页面支持分区搜索和分页并展示每个分区对应的记录数、文件数、数据大小等可用统计信息。这对以下场景很有帮助确认新分区是否已经写入检查分区值是否符合预期发现文件数异常多的分区初步判断是否存在小文件问题检查 Hidden Partitioning 的实际结果需要注意的是当前版本会先读取完整的 Partition Inspection 结果再在 API 层进行搜索和分页。对于拥有海量分区或 Manifest 的表首次加载仍然可能产生一定的元数据读取开销。后续版本可以进一步加入缓存和流式处理。5. Snapshots看懂一次写入或 Compaction 做了什么Snapshots 页面按时间展示表的提交历史并显示 Operation、Snapshot ID、Sequence Number、当前 Snapshot 状态以及每次提交带来的文件和记录变化。当前页面重点展示Added files本次 Snapshot 新增的数据文件Removed files本次 Snapshot 从表中移除的数据文件Rewrite in → out对于replace操作展示重写输入文件数和输出文件数Total files提交完成后的数据文件总数Rows in added files新增数据文件中包含的记录数Rows in removed files被移除数据文件中包含的记录数Total records提交后的记录总数Total size提交后的文件总大小这里有一个容易误解的细节added-records和deleted-records并不一定代表业务层面的新增行和删除行。对于 Compaction旧文件中的记录会被完整重写到新文件因此Rows in added files和Rows in removed files可能是两个完全相同的非零值。此时57 → 8表示 57 个输入文件被合并为 8 个输出文件但表中的逻辑数据并没有因此增加或减少。6. Properties查看影响表行为的配置Iceberg Table Properties 会影响文件格式、压缩算法、目标文件大小、Snapshot 保留策略等行为。Properties 页面将这些键值集中展示并提供搜索能力。相比直接打开 metadata JSON这种方式更适合快速确认某项配置是否已经生效。技术架构Icevue 有意保持简单不引入数据库或分布式计算引擎。HTTP / JSONManage connectionsREST Catalog protocolRead metadataBrowser / React UIFastAPILocal catalogs.yamlPyIcebergIceberg REST CatalogObject Storage / Metadata / Manifests前端前端使用 React、TypeScript 和 Vite 构建提供 Catalog 导航、表级 Tab、搜索、分页和响应式布局。生产构建产物由 FastAPI 直接提供因此部署时只需要一个容器。后端FastAPI 后端负责读取和保存catalogs.yaml创建并缓存 PyIceberg Catalog Client隐藏 Token 和 Credential将 PyIceberg 对象转换为稳定的 API Model提供 Namespace、Table、Partition 等只读 API托管前端静态资源和 OpenAPI 文档为什么选择 PyIcebergPyIceberg 足够轻量并且能够直接理解 Iceberg 的 Schema、Snapshot、Manifest、Partition 和 Table Metadata。对于一个只读元数据浏览器它比引入 Spark 或其他查询引擎更符合需求。Icevue 不执行 SQL也不读取业务数据内容。它只读取完成页面展示所需的 Catalog 和 Iceberg 元数据。多种 REST Catalog通用 Iceberg REST Catalog通用 REST Catalog 只需要提供 URI、Warehouse以及 Catalog 所要求的 Token、OAuth2 或其他 PyIceberg Properties。Amazon S3 TablesAmazon S3 Tables 使用 AWS SigV4id:s3tablesname:Amazon S3 Tablestype:resturi:https://s3tables.us-east-1.amazonaws.com/icebergwarehouse:arn:aws:s3tables:us-east-1:123456789012:bucket/my-table-bucketproperties:rest.sigv4-enabled:truerest.signing-name:s3tablesrest.signing-region:us-east-1AWS Glue Data CatalogAWS Glue Data Catalog 同样可以通过 Iceberg REST Endpoint 接入id:glue-prodname:AWS Glue Productiontype:resturi:https://glue.us-east-1.amazonaws.com/icebergwarehouse:123456789012properties:rest.sigv4-enabled:truerest.signing-name:gluerest.signing-region:us-east-1Glue Data Catalog 中可能同时存在 Parquet、Delta、Hudi 和 Iceberg 表。Icevue 会保留 Database 视图但只展示 Glue Metadata 能够识别为 Iceberg 的表避免非 Iceberg 表在加载时影响整个 Catalog。只读不是限制而是第一版的安全边界Icevue 的“管理”对象是 Catalog 连接而不是 Iceberg 表本身。当前版本不会提供以下操作创建或删除 Iceberg 表修改 Schema、Partition Spec 或 PropertiesAppend、Update、Delete 或 Merge 数据回滚、过期或删除 Snapshot执行 Compaction这样的边界让 Icevue 可以使用最小化的只读权限部署到生产环境。即使 UI 暴露在更多用户面前也不会因为一个按钮误操作而改变表状态。需要注意的是Icevue 当前不内置用户登录系统。生产部署时应当将它放在带身份认证的 HTTPS Reverse Proxy、Ingress 或企业网关之后同时为 Catalog Principal 配置最小只读权限。快速开始最简单的体验方式是使用内置 Demo Cataloggitclone https://github.com/norrishuang/Icevue.gitcdIcevuedockercompose up--build-d打开http://localhost:8000OpenAPI 文档位于http://localhost:8000/api/docsCatalog 配置会保存在 Docker Volume 中。也可以通过 UI 新增连接并执行Test connection连接成功后再保存。当前限制与后续方向Icevue 的第一版聚焦于“把 Iceberg 元数据看清楚”因此仍有一些可以继续演进的方向为超大 Catalog 增加 Namespace 和 Table 分页为 Partition 和 Manifest Inspection 增加缓存支持流式读取和增量加载超大分区列表增加 Snapshot 对比视图展示 Manifest、Data File 和 Delete File 的更细粒度信息增加可选的用户认证和授权集成增加更多 REST Catalog 的兼容性测试提供可观测性指标和审计日志这些能力仍然会遵守一个核心原则默认只读不把查看工具变成新的生产变更入口。总结Icevue 解决的不是如何执行更复杂的 Iceberg 计算而是如何更简单地理解一张 Iceberg 表。它希望把原本分散在 REST API、metadata JSON、manifest、命令行和 SQL 系统表中的信息整理成一个轻量、直观、可以随时打开的工作界面。如果你正在使用 Apache Iceberg、Amazon S3 Tables 或 AWS Glue Data Catalog并且也遇到过“只是想看一下表的元数据却要先启动一套引擎”的问题欢迎试用 Icevue也欢迎通过 Issue 和 Pull Request 提供反馈。项目地址https://github.com/norrishuang/Icevue
