Apache Polaris と Apache Iceberg

Apache Polaris は Apache Iceberg テーブル向けのカタログサービスです。Apache Iceberg は、大規模な分析データセット向けのオープンテーブル形式です。どちらのプロジェクトも汎用計算エンジンではありません。

Polaris はテーブルを識別し、アクセスを管理し、現在の Iceberg メタデータへの変更を調整します。
Iceberg は、テーブルの状態、スナップショット、マニフェスト、データファイル、削除ファイルがどのように構成されるかを定義します。
Spark、Flink、Trino、その他のエンジンが計算を計画し、実行します。
HDFS またはオブジェクトストレージが Iceberg のメタデータとテーブルデータファイルを保持します。

これらの責務を分離することで、よくある分類上の誤りを防げます。 Polaris は Spark の代替ではありません。Spark デプロイメントは Polaris を Iceberg カタログとして使用できます。

各コンポーネントをスタック内に配置する #

一般的なデプロイメントには、4 つの明確に分離されたレイヤーがあります。

text

SQL client, notebook, scheduler, or application
                         |
                         v
Compute engine: Spark, Flink, Trino, or another Iceberg client
             |                              |
             | Iceberg REST requests        | file I/O
             v                              v
Apache Polaris                         Object storage or HDFS
             |                              |
             | current metadata pointer     | Iceberg metadata,
             `----------------------------> | manifests, and data files

コントロールパスとデータパスは分離されています。

エンジンは Polaris に名前空間とテーブルの解決を要求します。
Polaris は、現在の Iceberg テーブルメタデータを読み込むために必要な情報を返します。
エンジンはストレージからメタデータ、マニフェスト、データファイルを読み取ります。
エンジンはスキャン、結合、集計、書き込みを実行します。
書き込み時、エンジンは Polaris に新しいテーブルメタデータバージョンのアトミックなコミットを要求します。

テーブルの行が Polaris を経由することはありません。したがって、Polaris を追加しても計算能力は増えず、それだけで遅いクエリが高速になることもありません。

Iceberg が追加するものを理解する #

Parquet、ORC、Avro は個々のファイルを記述します。しかし、特定の時点でどのファイルがテーブルを構成するかは定義しません。Iceberg はテーブルレベルの状態を追加します。

Iceberg テーブルは、メタデータツリーとして表現されます。

text

Catalog entry
    |
    v
Current table metadata JSON
    |
    +--> schemas, partition specifications, properties
    |
    `--> snapshots
           |
           v
      manifest list
           |
           v
        manifests
           |
           +--> data files
           `--> delete files

コミットされた各スナップショットは、完全で一貫性のあるテーブル状態を記述します。古いスナップショットを読み込んだリーダーは、ライターが新しいスナップショットを準備してコミットしている間も、そのスナップショットを使い続けられます。

このモデルは、Parquet ファイルのディレクトリだけでは得られない次の機能を提供します。

アトミックなテーブル変更
スナップショット分離とタイムトラベル
安定したフィールド識別子に基づくスキーマ進化
隠しパーティショニングとパーティション仕様の進化
スキャン計画のためのファイルレベル統計
それをサポートするテーブル形式バージョンにおける行レベル削除および更新の表現
ライター間の楽観的同時実行制御

Iceberg は通常、データファイルとメタデータファイルを不変として扱います。書き込みでは新しいファイルを生成し、その後カタログの現在のメタデータポインターを置き換えようとします。新しいファイルは、コミットが成功した後にのみまとめて可視化されます。

Polaris が追加するものを理解する #

Iceberg は、論理テーブル名を現在のメタデータに対応付け、コミットを調整するためにカタログを必要とします。Apache Polaris は、Iceberg REST Catalog API を通じてそのカタログを提供します。

Polaris は、次のような事項を担当します。

カタログ、名前空間、テーブル識別子
現在の Iceberg テーブルメタデータへの権威あるポインター
アトミックなコミットチェックと競合検出
認証とカタログ認可
ストレージ認証情報との統合
複数のエンジンで使用できる標準 REST インターフェース

REST インターフェースが重要なのは、各計算エンジンがすべてのカタログバックエンドを個別に実装するのではなく、1 つの Iceberg REST クライアントを実装できるためです。役割は Hive Metastore Thrift API に似ていますが、テーブルモデルとトランザクションモデルは異なります。

Polaris は次のことを行いません。

SQL を実行する
YARN アプリケーションをスケジュールする
Spark executor を実行する
サービスデータベースにテーブル行を保存する
Parquet、ORC、Avro を置き換える
任意のファイルを自動的に Iceberg テーブルに変換する

Polaris と Hive Metastore を比較する #

Polaris と Hive Metastore はどちらもカタログサービスですが、同じメタデータモデルの置き換え可能な実装として扱うべきではありません。

Concern	Hive Metastore	Polaris with Iceberg
Primary API	HMS Thrift API	Iceberg REST Catalog API
Table state	Table, partition, and storage-descriptor records	Pointer to Iceberg’s current table metadata
File tracking	Commonly inferred from table and partition locations	Explicitly tracked through snapshots and manifests
Partitioning	Partition columns and catalog partition records	Hidden transforms stored in Iceberg metadata
Commit model	Depends on Hive table and transaction type	Optimistic Iceberg metadata commits
Multi-engine use	Engines implement HMS-compatible clients	Engines implement the Iceberg REST protocol

Hive の専門家にとって、次の近似が役立ちます。

text

HMS       = catalog plus Hive-oriented table and partition metadata
Polaris   = catalog and commit coordinator for Iceberg metadata
Iceberg   = table state that HMS-style tables traditionally lack

この近似は API 互換性を主張するものではありません。テーブルを HMS から Polaris に移行するには、Thrift URI を REST URI に変更するのではなく、Iceberg 対応の移行または登録手順が必要です。

Polaris と Spark を比較する #

Spark と Polaris は異なるレイヤーに属します。

Capability	Apache Polaris	Apache Spark
Resolve table names	Yes	Through a configured catalog
Coordinate Iceberg commits	Yes	Produces a commit and submits it
Execute SQL	No	Yes
Run distributed transformations	No	Yes
Schedule tasks and executors	No	Yes
Read and write data files	Normally no	Yes
Provide streaming or machine-learning APIs	No	Yes

通常の関係は次のとおりです。

text

Spark driver
   |---- load and commit table metadata ----> Polaris
   |
   `---- schedule tasks --------------------> Spark executors
                                                   |
                                                   `--> Iceberg files in storage

ドライバーは Iceberg クライアントを使用して Polaris と通信します。Executor は、計画された Iceberg スキャンまたは書き込みによって選択されたファイルを読み書きします。 Polaris は executor のデータパスには入りません。

計算エンジンを統合する #

各エンジンには、3 つの独立した接続が必要です。

Polaris REST エンドポイントへのネットワークおよび認証経路
Iceberg REST API で warehouse と呼ばれる Polaris カタログ識別子
オブジェクトストレージまたは HDFS 上の Iceberg ファイルにアクセスするためのサポート対象の方法

以下の例は、完全な本番構成ではなく、重要な統合境界を示しています。プロパティ名とサポートされる Iceberg 機能は、エンジンのリリースによって変わります。エンジン、コネクター、Iceberg、Polaris の各バージョンには、相互にサポートされる組み合わせを使用してください。

Apache Doris™ を統合する #

Apache Doris 3.1 以降では、Polaris を Iceberg REST カタログとして構成できます。 Doris は OAuth 2.0 認証情報を使用して Polaris トークンを取得し、Polaris に一時的なオブジェクトストレージ認証情報を要求できます。

sql

CREATE CATALOG polaris_vended PROPERTIES (
  'type' = 'iceberg',
  'warehouse' = 'analytics_catalog',
  'iceberg.catalog.type' = 'rest',
  'iceberg.rest.uri' = 'https://polaris.example.com/api/catalog',
  'iceberg.rest.security.type' = 'oauth2',
  'iceberg.rest.oauth2.credential' = '<client-id>:<client-secret>',
  'iceberg.rest.oauth2.server-uri' =
    'https://polaris.example.com/api/catalog/v1/oauth/tokens',
  'iceberg.rest.oauth2.scope' = 'PRINCIPAL_ROLE:doris_role',
  'iceberg.rest.vended-credentials-enabled' = 'true'
);

Doris フロントエンドは Polaris を通じて Iceberg オブジェクトを解決し、Doris のバックエンドまたは計算ノードはストレージから選択されたデータファイルを読み取ります。 Polaris プリンシパルには必要なカタログ権限だけを付与し、適切な範囲の認証情報を発行できるストレージロールを Polaris カタログに構成してください。

認証情報の発行を無効にする場合、Doris は独自のストレージ認証情報を必要とします。これによりストレージ認可の経路は変わりますが、Polaris カタログの経路は変わりません。あるアイデンティティがテーブルメタデータを読み込めても、データファイルへのアクセスまたは作成権限を持たない可能性があるため、読み取りと書き込みは別々にテストしてください。

Apache Flink® を統合する #

Flink は Iceberg コネクターを使用し、Polaris を Iceberg REST カタログとして登録します。代表的な Flink SQL カタログ定義は次のとおりです。

sql

CREATE CATALOG polaris WITH (
  'type' = 'iceberg',
  'catalog-impl' = 'org.apache.iceberg.rest.RESTCatalog',
  'uri' = 'https://polaris.example.com/api/catalog',
  'warehouse' = 'analytics_catalog',
  'credential' = '<client-id>:<client-secret>',
  'scope' = 'PRINCIPAL_ROLE:flink_role'
);

Flink ディストリビューションには、対象の Flink リリースと互換性のある Iceberg Flink ランタイムに加えて、ストレージバックエンドに必要なファイル I/O 依存関係を含める必要があります。REST レスポンスに発行された認証情報が含まれている場合でも、カタログ認証とストレージ認証は分離されています。

ストリーミング書き込みでは、Iceberg シンクがチェックポイントを正常にコミットした場合にのみファイルが可視になります。したがって、ストレージにファイルが存在していても、最新レコードが現在の Iceberg スナップショットにまだ含まれていない場合があります。ファイル作成をテーブル可視化の証拠とみなすのではなく、Flink のチェックポイントと Iceberg のコミットを併せて監視してください。

Apache Spark™ を統合する #

Spark は、バックエンドに REST カタログを持つ Iceberg SparkCatalog を構成します。

text

spark.sql.catalog.polaris=org.apache.iceberg.spark.SparkCatalog
spark.sql.catalog.polaris.type=rest
spark.sql.catalog.polaris.uri=https://polaris.example.com/api/catalog
spark.sql.catalog.polaris.warehouse=analytics_catalog
spark.sql.catalog.polaris.credential=<client-id>:<client-secret>
spark.sql.catalog.polaris.scope=PRINCIPAL_ROLE:spark_role

polaris.sales.orders のような複数部分の名前でカタログを使用します。Spark ドライバーは Polaris を通じてメタデータを読み込み、コミットします。Executor は Iceberg ファイルを直接読み書きします。Spark ディストリビューションには、Spark および Scala のバージョン向けにビルドされた Iceberg ランタイム成果物が必要です。

基本的な読み取りと書き込みを超えるプロシージャや行レベルコマンドには、Spark の Iceberg SQL 拡張機能が必要になる場合があります。サポート状況はテーブルの Iceberg 形式バージョンにも依存します。Polaris がコミットを受け付けても、その Spark バージョンが書き込んだ機能を他のすべてのエンジンが解釈できるとは限りません。

Dremio® OSS を統合する #

Dremio OSS は現在、Polaris へのサポート対象の直接接続に必要な Iceberg REST Catalog ソースを公開していません。Dremio OSS に Iceberg リーダーが存在することから REST カタログがサポートされると想定しないでください。また、Enterprise 専用ソースを OSS 統合として文書化しないでください。

Dremio Enterprise エディションは、Polaris エンドポイントと発行された認証情報を使用できる Iceberg REST Catalog Source を提供します。この構成は OSS エディションには移植できません。完全なオープンソースデプロイメントでは、Spark、Flink、Trino、 Doris、またはサポート対象の StarRocks リリースなど、Polaris 互換のエンジンを使用するか、将来の Dremio OSS リリースでこのソースが明示的に追加されたことを確認してから、その前提で設計してください。

StarRocks を統合する #

StarRocks は、外部 Iceberg カタログの REST バックエンドとして Polaris を構成します。

sql

CREATE EXTERNAL CATALOG polaris
PROPERTIES (
  "type" = "iceberg",
  "iceberg.catalog.type" = "rest",
  "iceberg.catalog.uri" =
    "https://polaris.example.com/api/catalog",
  "iceberg.catalog.warehouse" = "analytics_catalog",
  "iceberg.catalog.security" = "oauth2",
  "iceberg.catalog.oauth2.credential" =
    "<client-id>:<client-secret>",
  "iceberg.catalog.oauth2.scope" =
    "PRINCIPAL_ROLE:starrocks_role"
);

StarRocks のフロントエンドおよびバックエンドまたは計算ノードは、それぞれの役割に必要なカタログサービスとストレージサービスに到達できなければなりません。ストレージ認証情報のプロパティは、S3、S3 互換サービス、Azure、GCS、HDFS のいずれを使用するかによって異なります。REST カタログの認証情報発行はリリースに依存します。現在の StarRocks ドキュメントでは、バージョン 4.0 から利用可能とされています。

Iceberg v2 の削除ファイル、新しい形式バージョン、書き込み、保守操作を有効にする前に、 StarRocks のサポートマトリックスを確認してください。基本的な Parquet ベースのテーブルをクエリできても、別のエンジンがコミットするすべてのスナップショット機能をサポートしていることにはなりません。

Trino を統合する #

Trino は Iceberg コネクターで rest をカタログタイプとして使用します。カタログプロパティファイルには、次のような設定を含めます。

properties

connector.name=iceberg
iceberg.catalog.type=rest
iceberg.rest-catalog.uri=https://polaris.example.com/api/catalog
iceberg.rest-catalog.warehouse=analytics_catalog
iceberg.rest-catalog.security=OAUTH2
iceberg.rest-catalog.vended-credentials-enabled=true
fs.s3.enabled=true

サポートされる OAuth 認証情報、デプロイメントで必要な Polaris realm ヘッダー、ストレージ固有のプロパティは、保護されたシークレットおよび構成機構を通じて追加してください。実際のクライアントシークレットを、全ユーザーが読み取り可能なカタログプロパティファイルに直接記述しないでください。

Trino のコーディネーターは計画とコミット中に Polaris と通信し、ワーカーは Iceberg ファイルを読み書きします。Trino は Iceberg の保守プロシージャも公開しますが、その可用性とセマンティクスはコネクターのリリースによって異なります。独立した保守ジョブが競合する保持ポリシーを使用しないよう、スナップショットの期限切れ処理、孤立ファイルの削除、データファイルの最適化をエンジン間で調整してください。

Iceberg の読み取りを追跡する #

Spark SQL を通じて発行されたクエリを考えます。

sql

SELECT customer_id, SUM(amount)
FROM lake.sales.orders
WHERE order_date >= DATE '2026-08-01'
GROUP BY customer_id;

簡略化した読み取りは次のように進みます。

Spark は構成済み Polaris カタログを通じて lake.sales.orders を解決します。
Spark はテーブルの現在の Iceberg メタデータを読み込み、スナップショットを選択します。
Iceberg はパーティション情報とマニフェスト統計に対してクエリ述語を評価します。
Spark は一致する可能性があるデータファイルと削除ファイルだけを対象にタスクを計画します。
Executor はストレージからそれらのファイルを直接読み取ります。
Spark は集計を実行し、結果を返します。

Polaris は名前解決と認可に参加します。Iceberg はスナップショットとファイル計画モデルを提供します。Spark は SQL セマンティクス、オプティマイザー、スケジューラー、ランタイムを提供します。

Iceberg の書き込みを追跡する #

追加処理はコミット境界を示します。

エンジンは Polaris から現在の Iceberg テーブルメタデータを読み込みます。
分散タスクは新しいデータファイルをストレージに書き込みます。
エンジンは新しいマニフェスト、マニフェストリスト、テーブルメタデータを書き込みます。
エンジンは、ベースバージョンがまだ最新であることを条件として、古いメタデータポインターを新しいものに置き換えるよう Polaris に要求します。
Polaris はポインターをアトミックにコミットするか、古い更新を拒否します。
競合時には、Iceberg クライアントが新しい現在状態に対して安全に再試行できるか判断します。

コミット失敗前に書き込まれたファイルは、テーブルディレクトリに存在するだけではテーブルの一部になりません。後続の有効な操作で参照されるか、クリーンアップで削除されるまでは、孤立ファイルです。

したがって、アプリケーションは Iceberg テーブルの場所に直接書き込み、ファイルが出現することを期待してはなりません。可視性を制御するのはディレクトリ一覧ではなく、コミット済みの Iceberg メタデータです。

Lakehouse というラベルを説明する #

Lakehouse という用語は、次の 2 つの特性を組み合わせたものです。

Lake: テーブルデータは HDFS またはオブジェクトストレージに残り、一般にオープンなファイル形式で保存され、複数のエンジンからアクセスできます。
Warehouse: テーブルレイヤーがスキーマ、トランザクション、スナップショット、ガバナンス、予測可能な SQL 動作を提供します。

このスタックでは、このラベルは Polaris 単体ではなく、アーキテクチャ全体に適用されます。

text

Lake storage
    + Iceberg table semantics
    + Polaris catalog and governance
    + SQL compute engines
    = an open lakehouse architecture

Polaris はカタログ相互運用性とガバナンスに貢献します。Iceberg はレイクストレージ上にウェアハウスに似たテーブルセマンティクスを提供します。計算エンジンが実際の分析処理を提供します。

名前空間とストレージパスを分離する #

sales.orders のような論理識別子はファイルシステムパスではありません。Polaris はその識別子を Iceberg メタデータに解決し、そのメタデータが最終的にストレージ内のファイルを参照します。

この分離により、管理者は次のことを実現できます。

ユーザーにストレージレイアウトを公開せずに論理編成を変更する
カタログおよび名前空間の境界でアクセスを強制する
カタログまたは名前空間ごとに異なるストレージ場所を使用する
複数のエンジンに同じテーブルの一貫したビューを提供する

ストレージ権限も依然として重要です。カタログ認可でテーブル操作を許可していても、エンジンが参照オブジェクトを読み取る権限を持たない場合があります。逆に、ユーザーが制限のないバケット認証情報を受け取ると、直接のストレージアクセスによってカタログポリシーを回避できる場合があります。

認証とストレージアクセスを一体で設計する #

安全なリクエストは、少なくとも 2 つの認可境界を通過します。

text

User or workload
    |
    | authenticate and authorize catalog operation
    v
Polaris

Compute engine
    |
    | authorize object reads and writes
    v
Object storage or HDFS

デプロイメントでは、固定のエンジン認証情報またはサポートされる認証情報発行設計を使用できます。認証情報の発行では、広範で長期間有効なストレージ認証情報を配布する代わりに、認証済みクライアントへ範囲を限定した一時的なストレージアクセスを提供します。正確な動作は Polaris のリリース、ストレージバックエンド、エンジン統合によって異なります。

カタログポリシーとストレージポリシーは一致していなければなりません。コントロールプレーンの拒否とデータプレーンの拒否を両方テストしてください。

プリンシパルはカタログと名前空間を発見できるか
テーブルを読み込みまたは変更できるか
エンジンは既存のメタデータとデータファイルを読み取れるか
ライターはファイルを作成し、カタログコミットを完了できるか
操作後も認証情報で無関係なプレフィックスにアクセスできるか

TLS、シークレットストレージ、認証情報のローテーション、監査記録、クロック同期は、引き続きデプロイメントの責任です。

カタログをコントロールプレーンサービスとして運用する #

Polaris はクエリのデータパス外にありますが、その可用性はテーブルの検出とコミットに影響します。耐久性のあるコントロールプレーンインフラストラクチャとして運用してください。

サポートされる高可用性トポロジーを実行する
永続状態を保護し、バックアップする
リクエストレイテンシ、エラー率、認証失敗、コミット競合を監視する
カタログと権限の変更について監査記録を保持する
サポートされる Iceberg API に基づいてサーバーとクライアントのアップグレードを調整する
ストレージファイルだけでカタログオブジェクトやポリシーをすべて復元できるとは仮定せず、復元をテストする

ストレージについては、書き込み失敗による残骸、期限切れスナップショット、小さなファイル、過大なマニフェスト、削除ファイルの蓄積を別途監視してください。これらは Iceberg テーブル保守の問題であり、Polaris がテーブルデータをスキャンまたは書き換えるべきだという証拠ではありません。

よくある誤解を避ける #

Polaris は計算エンジンではない #

Polaris は Spark、Flink、Trino と競合しません。これらのエンジンが Polaris を使用します。

Iceberg はファイル形式ではない #

Iceberg はテーブル形式です。データファイルには通常、Parquet、ORC、Avro が使用されます。

カタログはテーブルのメタデータツリー全体ではない #

Polaris はカタログ状態と現在のテーブルメタデータ参照を管理します。Iceberg のメタデータファイルとマニフェストは通常、HDFS またはオブジェクトストレージでテーブルデータと一緒に保存されます。

オブジェクトストアのファイルは自動的にテーブル行にはならない #

コミット済み Iceberg スナップショットから参照されるファイルだけがテーブルに属します。ディレクトリに存在するだけでは不十分です。

REST 互換性は同一の SQL を保証しない #

2 つのエンジンは Polaris カタログと同じ Iceberg テーブルを共有できますが、SQL 構文、型処理、サポートされる Iceberg 機能、書き込みセマンティクス、認可統合は異なる可能性があります。対象のエンジン、コネクター、Iceberg 形式バージョン、Polaris リリースの組み合わせを確認してください。

コンポーネントを意図的に選択する #

複数の Iceberg 対応エンジンで共有する、ベンダー中立の REST カタログと中央の認可境界が必要な場合、Polaris は有用です。Iceberg テーブルが存在しない環境や、既存カタログが相互運用性、ガバナンス、運用要件をすでに満たしている場合、Polaris の有用性は低くなります。

各レイヤーを独立して評価してください。

Decision	Questions
Compute engine	Which SQL, batch, streaming, or ML workloads must run?
Catalog	Which engines support its API, and how are privileges managed?
Table format	Which Iceberg versions and features can every writer handle?
File format	Which types, compression codecs, and readers are required?
Storage	What consistency, latency, lifecycle, and credential model applies?

単一のコンポーネントだけでスタックがレイクハウスになるわけではありません。カタログ、テーブル形式、エンジン、ストレージが、コミット、セキュリティ、サポート対象機能について合意すると、アーキテクチャは機能します。

Apache Polaris と Apache Iceberg

各コンポーネントをスタック内に配置する #

Iceberg が追加するものを理解する #

Polaris が追加するものを理解する #

Polaris と Hive Metastore を比較する #

Polaris と Spark を比較する #

計算エンジンを統合する #

Apache Doris™ を統合する #

Apache Flink® を統合する #

Apache Spark™ を統合する #

Dremio® OSS を統合する #

StarRocks を統合する #

Trino を統合する #

Iceberg の読み取りを追跡する #

Iceberg の書き込みを追跡する #

Lakehouse というラベルを説明する #

名前空間とストレージパスを分離する #

認証とストレージアクセスを一体で設計する #

カタログをコントロールプレーンサービスとして運用する #

よくある誤解を避ける #

Polaris は計算エンジンではない #

Iceberg はファイル形式ではない #

カタログはテーブルのメタデータツリー全体ではない #

オブジェクトストアのファイルは自動的にテーブル行にはならない #

REST 互換性は同一の SQL を保証しない #

コンポーネントを意図的に選択する #

公式リファレンス #

コメント