Iceberg REST Catalog API 兼容情况说明-对象存储(OSS)-阿里云帮助中心

OSS Tables 提供兼容 Apache Iceberg REST Catalog 的 API 端点，兼容 AWS S3 Tables。本文按接口、参数、鉴权三个维度，逐条说明 OSS Tables 与 Iceberg REST 标准协议在请求参数、响应字段、行为预期上的差异，帮助您在自研客户端或选型计算引擎时评估兼容范围。

兼容设计原则

OSS Tables 的 Iceberg REST Catalog 接口在设计上遵循以下三条原则：

兼容 AWS S3 Tables：在 Iceberg 标准协议存在歧义或多种实现路径时，OSS Tables 优先兼容 S3 Tables行为，便于跨云客户端复用与代码迁移。
兼容主流开源 SDK：在不破坏 S3 Tables 兼容性的前提下，OSS Tables 对部分字段（例如分页 token）做了双写，保证 Apache Iceberg 官方 Java、C++ SDK 可直接对接而无需改造。
明确暂不支持的能力：包括视图（View）、CTAS（CREATE TABLE AS SELECT）、多级 Namespace、Plan API、OAuth2 与 BearerAuth 鉴权等。

接口兼容情况

下表覆盖 OSS Tables Iceberg REST Catalog 对外暴露的全部 13 个接口。S3 Tables 行为列描述与 Iceberg 规范不一致的具体细节，OSS Tables 兼容情况列给出 OSS Tables 的处理方式与对客户端的影响。

OSS Tables 提供 Iceberg REST Catalog 端点，Iceberg 客户端通过该端点管理表元数据。Endpoint 格式如下：

内网：https://{region}-internal.oss-tables.aliyuncs.com/iceberg
外网：https://{region}.oss-tables.aliyuncs.com/iceberg

表中 {prefix} 参数取值为表存储桶 ARN 的 URL-encode 形式，ARN 格式为 acs:osstables:{region}:{userId}:bucket/{tableBucketName}。

路径	方法	操作	兼容情况
`/v1/config`	GET	`getConfig`	响应不包含 `endpoints` 字段，客户端将使用 Iceberg 规范定义的默认 endpoint 列表（与本接口实际支持的列表不完全一致）。
`/v1/{prefix}/namespaces`	GET	`listNamespaces`	响应中同时返回 `nextPageToken` 和 `next-page-token` 两种字段名；最后一页响应中省略 token 字段。
`/v1/{prefix}/namespaces`	POST	`createNamespace`	不接受除owner以外的任何属性。
`/v1/{prefix}/namespaces/{namespace}`	GET	`loadNamespaceMetadata`	响应中不包含 `properties` 字段。
`/v1/{prefix}/namespaces/{namespace}`	HEAD	`namespaceExists`	符合 Iceberg 规范。
`/v1/{prefix}/namespaces/{namespace}`	DELETE	`dropNamespace`	符合 Iceberg 规范。
`/v1/{prefix}/namespaces/{namespace}/tables`	GET	`listTables`	支持 `pageToken` 分页；响应中同时返回 `nextPageToken` 和 `next-page-token` 两种字段名；最后一页响应中省略 token 字段。
`/v1/{prefix}/namespaces/{namespace}/tables`	POST	`createTable`	不支持 `stage-create=true`，请求时该字段必须为 `false`，因此不支持 CREATE TABLE AS SELECT（CTAS）语法。
`/v1/{prefix}/namespaces/{namespace}/tables/{table}`	GET	`loadTable`	支持 `snapshots` 查询参数（默认 `all`，可选 `all` 和 `refs`，区分大小写）；支持 `If-None-Match` 请求头，不区分大小写。
`/v1/{prefix}/namespaces/{namespace}/tables/{table}`	POST	`updateTable`	符合 Iceberg 规范。具体 `requirements` 与 `updates` 类型支持范围见updateTable 兼容情况。
`/v1/{prefix}/namespaces/{namespace}/tables/{table}`	DELETE	`dropTable`	必须显式传入 `purgeRequested=true`，否则返回 `400 Bad Request`。Iceberg 规范中该参数默认为 `false`。
`/v1/{prefix}/namespaces/{namespace}/tables/{table}`	HEAD	`tableExists`	符合 Iceberg 规范。
`/v1/{prefix}/tables/rename`	POST	`renameTable`	符合 Iceberg 规范。

updateTable 兼容情况

updateTable 端点通过 requirements（乐观锁前置条件）和 updates（元数据变更动作）两个数组提交事务。

支持的 Requirements

支持 Iceberg 规范定义的全部 8 种 requirement 类型：

assert-create
assert-table-uuid
assert-ref-snapshot-id
assert-last-assigned-field-id
assert-current-schema-id
assert-last-assigned-partition-id
assert-default-spec-id
assert-default-sort-order-id

支持的 Updates（元数据变更动作）

assign-uuid
upgrade-format-version
add-schema
set-current-schema
add-spec
set-default-spec
set-partition-statistics
remove-partition-statistics
add-sort-order
set-default-sort-order
add-snapshot
set-snapshot-ref
remove-snapshot-ref
remove-snapshots
set-properties
remove-properties
set-statistics
remove-statistics

不支持的 Updates

remove-schemas
remove-partition-specs
set-location
add-encryption-key
remove-encryption-key
add-view-version
set-current-view-version

通用规则

字段类型严格匹配：所有 JSON 字段类型必须正确（字符串不能传数字、对象不能传数组等），否则会报错。
action 字段必须匹配：每个请求的 action 字段值必须与对应的 action 名称严格一致。
ID 为 -1 的语义：set-current-schema、set-default-spec、set-default-sort-order 中 *-id 为 -1 时表示"指向最近一次添加的对应对象"，遵循 Iceberg 协议约定。
幂等性：add-schema、add-spec、add-sort-order、add-snapshot 等操作在目标对象已存在时会跳过，不会重复添加。

参数兼容情况

下表覆盖 Iceberg REST 标准协议中常见的路径参数、查询参数和请求头的兼容情况。

参数	兼容情况
`namespace`	不支持多级 Namespace，传入多级时报错。
`prefix`	支持。
`table`	支持。
`plan-id`	不支持，未实现 Plan API。
`view`	不支持视图（View）。
`X-Iceberg-Access-Delegation`	不支持，请求头被忽略。
`parent`	不支持多级 Namespace，传入时报错。
`pageToken`	支持。需 URL Encode 后通过 query string 传入；最后一页响应中不返回该字段。
`pageSize`	支持。
`ETag`	支持。
`Idempotency-Key`	不支持，请求头被忽略。

鉴权机制兼容情况

OSS Tables Iceberg REST Catalog 仅支持 SigV4 签名鉴权（签名服务名为 osstables）。Iceberg 规范定义的其他鉴权方式均不支持：

鉴权方式	兼容情况
SigV4	支持（推荐）。签名服务名为 `osstables`。
OAuth2	不支持。Iceberg 规范层面已标记 `DEPRECATED for REMOVAL`。
BearerAuth	不支持。

接入建议

接入 OSS Tables前，请重点关注以下三类影响：

客户端选型：推荐使用 Apache Iceberg 官方 Java 或 C++ SDK。
建表与删表：当前不支持 CTAS（CREATE TABLE AS SELECT），需先调用 createTable 创建空表后再写入数据；删除表时必须显式带上 purgeRequested=true，否则返回 400 错误。
暂不支持的能力：包括视图（View）、多级 Namespace、Plan API、Idempotency-Key、X-Iceberg-Access-Delegation、OAuth2 与 BearerAuth 鉴权。