すべてのプロダクト
Search

このプロダクト

    Object Storage Service:Iceberg REST Catalog API の互換性

    ドキュメントセンター

    Object Storage Service:Iceberg REST Catalog API の互換性

    最終更新日:Jun 05, 2026

    OSS Tables は、Apache Iceberg REST Catalog および AWS S3 Tables と互換性のある API エンドポイントを提供します。このトピックでは、リクエストパラメーター、レスポンスフィールド、および期待される動作における、OSS Tables と Iceberg REST 標準プロトコルの差異を、エンドポイント、パラメーター、認証の 3 つの観点から説明します。この情報を使用して、独自のクライアントを構築する場合や、コンピューティングエンジンを選定する場合の互換性を評価してください。

    互換性の設計原則

    OSS Tables は、Iceberg REST Catalog インターフェイスでは、次の 3 つの原則に従います：

    • AWS S3 Tables との互換性：Iceberg 標準プロトコルが曖昧である、または複数の実装を許容する場合、OSS Tables は S3 Tables の動作との互換性を優先します。これにより、クロス-クラウドでのクライアント再利用とコード移行が容易になります。

    • 主流のオープンソース SDK との互換性：S3 Tables との互換性を損なわない範囲で、OSS Tables は特定のフィールド (ページネーショントークンなど) を 2 つの形式で書き込みます。これにより、公式の Apache Iceberg Java および C++ SDK を変更せずにそのまま使用できます。

    • 未サポート機能の明確化：未サポート機能には、ビュー、CTAS (CREATE TABLE AS SELECT)、マルチレベル名前空間、Plan API、OAuth2、および BearerAuth 認証が含まれます。

    エンドポイントの互換性

    次の表は、OSS Tables の Iceberg REST Catalog が公開する 13 個すべてのエンドポイントを示します。「S3 Tables の動作」列は Iceberg 仕様からの具体的な差異を示し、「OSS Tables の互換性」列は、OSS Tables が各ケースをどのように処理するか、およびクライアントへの影響を説明します。

    OSS Tables は、Iceberg クライアントがテーブルメタデータを管理するために使用する Iceberg REST Catalog エンドポイントを提供します。エンドポイント形式は次のとおりです：

    • プライベートネットワーク：https://{region}-internal.oss-tables.aliyuncs.com/iceberg

    • パブリックネットワーク：https://{region}.oss-tables.aliyuncs.com/iceberg

    次の表では、{prefix} パラメーターには、テーブルバケット ARN を URL エンコードした形式を指定します。ARN の形式は acs:osstables:{region}:{userId}:bucket/{tableBucketName} です。

    パス

    メソッド

    オペレーション

    S3 Tables の動作

    /v1/config

    GET

    getConfig

    レスポンスに endpoints フィールドを含めず、Iceberg 仕様から逸脱します。

    /v1/{prefix}/namespaces

    GET

    listNamespaces

    レスポンスには、nextPageToken と next-page-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 の両方のフィールドが含まれます。最後のページのレスポンスでは、トークンフィールドは省略されます。

    /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 (メタデータ変更アクション) という 2 つの配列を使用してトランザクションを送信します。

    サポートされている 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

    マルチレベル名前空間はサポートされません。マルチレベル名前空間を含むリクエストは失敗します。

    prefix

    サポートされています。

    table

    サポートされています。

    plan-id

    サポートされません。Plan API は実装されていません。

    view

    ビューはサポートされません。

    X-Iceberg-Access-Delegation

    サポートされません。リクエストヘッダーは無視されます。

    parent

    マルチレベル名前空間はサポートされません。このパラメーターを含むリクエストは失敗します。

    pageToken

    サポートされています。URL エンコードしたクエリ文字列パラメーターとして渡します。最終ページのレスポンスでは、このフィールドは返されません。

    pageSize

    サポートされています。

    ETag

    サポートされています。

    Idempotency-Key

    サポートされません。リクエストヘッダーは無視されます。

    認証の互換性

    OSS Tables の Iceberg REST Catalog は、SigV4 署名認証 (サービス名は osstables) のみをサポートします。Iceberg 仕様で定義されているその他の認証方式はサポートされません：

    認証方式

    互換性

    SigV4

    サポートされています (推奨)。署名のサービス名は osstables です。

    OAuth2

    サポートされません。Iceberg 仕様では DEPRECATED for REMOVAL としてマークされています。

    BearerAuth

    サポートされません。

    統合に関する推奨事項

    OSS Tables と統合する前に、次の 3 つの点に特に注意してください：

    • クライアントの選定：公式の Apache Iceberg Java または C++ SDK を使用してください。

    • テーブルの作成と削除：CTAS (CREATE TABLE AS SELECT) はサポートされません。まず createTable を呼び出して空のテーブルを作成し、その後データを書き込みます。テーブルを削除する場合は、purgeRequested=true を明示的に含める必要があります。含めないと、リクエストは 400 エラーを返します。

    • 未サポート機能：未サポート機能には、ビュー、マルチレベル名前空間、Plan API、Idempotency-Key、X-Iceberg-Access-Delegation、OAuth2、および BearerAuth 認証が含まれます。