全部產品
Search

搜尋本產品

    Object Storage Service：Iceberg REST Catalog API 相容情況說明

    文件中心

    Object Storage Service：Iceberg REST Catalog API 相容情況說明

    更新時間：Jun 04, 2026

    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

    通用規則

    1. 欄位類型嚴格匹配：所有 JSON 欄位類型必須正確（字串不能傳數字、對象不能傳數組等），否則會報錯。

    2. action 欄位必須匹配：每個請求的 action 欄位值必須與對應的 action 名稱嚴格一致。

    3. ID 為 -1 的語義：set-current-schema、set-default-spec、set-default-sort-order 中 *-id 為 -1 時表示"指向最近一次添加的對應對象"，遵循 Iceberg 協議約定。

    4. 等冪性：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 鑒權。