Supabase Iceberg Wrapper:用 SQL 直接在 Postgres 中查询 Apache Iceberg 数据

Supabase Iceberg Wrapper:用 SQL 直接在 Postgres 中查询 Apache Iceberg 数据

【免费下载链接】supabaseThe Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.项目地址: https://gitcode.com/GitHub_Trending/supa/supabase

本文围绕 Supabase Studio 中的 Iceberg Wrapper 集成文档 overview.md 展开,讲清楚三件事:Iceberg 表格式为什么适合大规模分析场景、Iceberg Wrapper 作为 Postgres 外部数据包装器(FDW)如何把 Iceberg 表“接”进数据库,以及 Supabase 在 Studio 中围绕该集成提供的完整落地路径——从创建 FDW、管理 namespace 与表,到将 Iceberg namespace 导入为本地 schema,最终让分析表直接出现在 SQL Editor 的表列表中。

什么是 Iceberg Wrapper

官方文档对它的定义很凝练:

Apache Iceberg 是一种面向海量分析型数据集的开放表格式,支持 schema 演化、隐藏分区、时间旅行(time travel)和版本回滚,可以用 SQL 查询处理大规模数据。

Iceberg Wrapper 是一个外部数据包装器(FDW),让你直接在 Postgres 数据库内查询 Apache Iceberg 表中的数据。该集成让你用标准 SQL 查询 Iceberg 表。

将 Iceberg 连接到你的 Supabase 项目后,可以把 Postgres 的能力与 Iceberg 管理大规模分析负载的能力结合起来。

换句话说,Iceberg 负责“存”——以开放格式把海量分析数据以数据文件的形式存放在对象存储(S3 兼容存储)上;Iceberg Wrapper 负责“查”——在 Postgres 侧注册一个 FDW 和一个 external server,让分析数据以外部表的形式出现在数据库元数据中。业务库(OLTP)和分析库(OLAP)不必物理合并,一条JOIN就能跨两边取数,而查询本身仍走标准 SQL。

在 Studio 的代码中,该集成对应一个固定条目:在 Wrappers.constants.ts 中,iceberg_wrapper声明如下:

• handlerName为iceberg_fdw_handler,validatorName为iceberg_fdw_validator(见 WRAPPER_HANDLERS);
• 底层数据库扩展名为icebergFdw;
• minimumExtensionVersion为0.5.3——从源码结构看,启用该集成要求项目的wrappers扩展版本不低于 0.5.3。useIcebergWrapperExtension 正是基于“wrappers扩展是否安装 + 版本是否达标”给出installed/needs-upgrade/not-installed三种状态,作为 UI 的前置校验。

集成配置参数:Studio 定义的 Server Options

与 Stripe、Slack 等 API 类 wrapper 不同,Iceberg wrapper 的 server options 全部指向“对象存储 + 目录(catalog)”这条链路。Wrappers.constants.ts 中定义了如下字段:

源码中有一处值得注意的设计注释:这些字段在配置层面“故意不标记为必填”,因为必填约束由创建 Iceberg wrapper 的专用表单负责执行,而在“编辑 wrapper”弹窗中所有字段都可选展示、便于只改部分项。此外,sourceSchemaOption被命名为Namespace,并带有描述“It should match the namespace of the Iceberg catalog.”——这体现了 Iceberg 的catalog → namespace → table三级结构与 Postgresschema → table二级的映射关系。

创建流程:一步命令完成“凭证 + FDW + Server”

Studio 中的创建动作由 useIcebergWrapperCreateMutation 封装,其内部是严格的三步编排:

1. 创建 S3 访问密钥:调用useS3AccessKeyCreateMutation为分析桶生成一对 S3 access/secret key(描述名为getAnalyticsBucketS3KeyName(bucketName)生成的桶专属名称),而不是让用户手动粘贴长期密钥;

2. 拼装 FDW 参数:wrapper_name取自getAnalyticsBucketFDWName(bucketName),server_name固定为${wrapperName}_server;vault_aws_access_key_id/vault_aws_secret_access_key填入第 1 步生成的密钥;vault_token优先取项目的 secret key,其次 service key(读取密钥需要SECRETS_READ权限);warehouse即分析桶名;

3. 计算端点:s3.endpoint和catalog_uri由 StorageSettings.utils.ts 基于项目的protocol与可选的自定义endpoint派生:

   • getConnectionURL把路径设为/storage/v1/s3,作为 S3 数据端点;
   • getCatalogURI把路径设为/storage/v1/iceberg,作为 Iceberg 目录的 REST 端点;
   • 未配置自定义 endpoint 时,基础地址回退为https://{projectRef}.storage.supabase.co。

   从源码结构看,这意味着 Supabase Storage 本身同时暴露 S3 兼容端点和 Iceberg REST Catalog 端点,Iceberg 表的数据文件与目录元数据都托管在同一存储桶体系中。

4. 以mode: 'skip'提交:useFDWCreateMutation的mode参数取'skip'(fdw-create-mutation.ts)。注释明确:skip 模式表示跳过“把 schema/表绑定到外部数据”的最后一步——也就是说,创建 FDW 后并不会立刻看到任何表,绑定发生在后面的“导入外部 schema”环节(见下文)。整个创建 SQL 由@supabase/pg-meta的getCreateFDWSql生成,并用事务包裹执行。

对应到数据库层面,这一流程等价于:

-- 1. 创建外部服务器(参数与上方 formState 一致) CREATE SERVER {wrapper_name}_server FOREIGN DATA WRAPPER {wrapper_name} OPTIONS ( vault_aws_access_key_id '...', vault_aws_secret_access_key '...', vault_token '...', warehouse '{bucketName}', "s3.endpoint" 'https://.../storage/v1/s3', catalog_uri 'https://.../storage/v1/iceberg' ); -- 2. (绑定阶段) 把 Iceberg namespace 导入为本地 schema IMPORT FOREIGN SCHEMA "{namespace}" FROM SERVER {wrapper_name}_server INTO {target_schema};

管理 Iceberg 目录:Namespace 与表的 CRUD

FDW 建好之后,Studio 在 Storage 页的分析桶详情里提供了一套目录管理能力,对应一组 REST 调用,全部挂在/platform/storage/{ref}/analytics-buckets/{id}路径下:

• 列出 namespace:iceberg-namespaces-query.ts 请求.../namespaces,返回桶目录下的所有 namespace 名称列表;
• 列出某 namespace 下的表:iceberg-namespace-tables-query.ts 请求.../namespaces/{namespace}/tables,返回表名列表;
• 创建 namespace:iceberg-namespace-create-mutation.ts POST.../namespaces,请求体为{ namespace };遇到 409 会提示“A namespace named ... already exists in the catalog”,并对icebergNamespaces查询键做缓存失效;
• 删除 namespace / 表:iceberg-namespace-delete-mutation.ts 与 iceberg-namespace-table-delete-mutation.ts 分别处理两个层级的删除;
• 创建表:iceberg-namespace-table-create-mutation.ts POST.../namespaces/{namespace}/tables,请求体为{ name, fields },其中fields的类型直接取自 OpenAPI 的CreateNamespaceTableBody,即按列名 + 类型声明表结构。

UI 侧的对应组件位于 AnalyticsBuckets 目录:NamespaceWithTables展示 namespace/表的层级浏览与行数据,CreateTable/CreateTableSheet负责可视化建表,BucketCallouts与SimpleConfigurationDetails展示桶的配置状态。

导入外部 Schema:让 Iceberg 表进入 SQL Editor

真正让“Iceberg 表在 Postgres 里可查”这一步,发生在 ImportForeignSchemaDialog 中。其提交流程为:

1. 表单校验目标 schema 名(targetSchema)必填且不与现有 schema 重名,默认值为fdw_analytics_{namespace};源字段sourceNamespace默认填入当前 namespace;
2. createSchema先创建目标本地 schema;
3. importForeignSchema调用IMPORT FOREIGN SCHEMA,把指定 Iceberg namespace 下的表导入为该 server 的外部表,落入目标 schema;
4. 通过getFDWs找到server_name匹配的 wrapper,再用getDecryptedParameters读出当前 server options 并更新 FDW,把supabase_target_schema指向刚创建的 schema,成功后提示“Successfully connected “{bucket}” to the database”。

supabase_target_schema这个隐藏只读选项在 Wrappers.constants.ts 中统一定义(hidden: true, readOnly: true),是所有 Supabase wrapper 的公共机制:它决定了外部表落在哪个 schema,而 Iceberg wrapper 同时声明了canTargetSchema: true,允许用户在导入对话框中自行指定。

完成导入后,Iceberg namespace 中的每张表都会以外部表的形式出现在 Studio 的数据库视图里,即可像普通表一样在 SQL Editor 中执行SELECT、JOIN,与 Postgres 原生表、RLS、视图体系无缝协作。

小结与适用前提

回到集成文档的三句话核心,配合源码可以得出完整的落地认知:

• 概念层:Iceberg 提供 schema 演化、隐藏分区、时间旅行、版本回滚等分析型表格式能力;Iceberg Wrapper 以 FDW 形式让 Postgres 用标准 SQL 直查 Iceberg 表(overview.md);
• 配置层:需要wrappers扩展 ≥ 0.5.3;server options 覆盖 AWS 凭证(经 Vault 加密)、S3 端点、Iceberg REST Catalog 端点、warehouse 名称等 8 个参数,Supabase 托管场景下端点由项目 ref 自动派生;
• 操作层:创建 FDW(mode 为 skip)→ 管理 namespace/表 →IMPORT FOREIGN SCHEMA绑定到本地 schema,三步完成“连接 Iceberg 到 Supabase 项目”,之后分析负载即可与 Postgres 事务数据在同一个 SQL 世界内联合查询。

需要说明的限制:本文所有参数、端点与流程均以当前仓库apps/studio下的实现为准,针对 Supabase 托管项目的 Storage 体系(自带 S3 兼容端点与 Iceberg REST Catalog 端点);若自建部署或更换为第三方 Iceberg Catalog(如 AWS S3 Tables),catalog_uri、vault_aws_s3table_bucket_arn等选项的取值需按实际环境配置。

【免费下载链接】supabaseThe Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.项目地址: https://gitcode.com/GitHub_Trending/supa/supabase