Iceberg REST Catalogは、Apache Icebergのカタログ操作をHTTP APIとして標準化したものです。現在ではさまざまなOSS実装やクラウドサービスで採用が進んでおり、Icebergエコシステムの重要なインターフェースになりつつあります。
とはいえ、Iceberg REST Catalogを含む検証環境を一から用意するのは意外と大変です。そのため、名前は聞いたことがあっても、実際に手を動かして試したことのある方はまだ多くないのではないでしょうか。
本記事では、Hive Metastore組み込みのIceberg REST Catalog APIをDockerで起動し、PyIcebergから接続して動作確認する手順をチュートリアル形式で紹介します。詳しい仕様には深入りせず、まずはローカルでIceberg REST CatalogとApache Icebergを手軽に体験することを目的とします。
English version: Iceberg REST Catalog in No Time: A Quickstart with Hive Metastore and PyIceberg
カタログの役割
Apache Icebergでは、データファイルに加え、テーブルのスキーマ、パーティション情報、スナップショットなど、多くのメタデータがオブジェクトストレージや分散ファイルシステム上のファイルとして管理されます。
一方で、クライアントがIcebergテーブルを利用するには、テーブル名に対応する現在のメタデータファイルがどこにあるのかを解決し、テーブル更新時にはその参照を安全に更新する仕組みが必要です。Icebergの文脈では、この役割を担うものを「カタログ」と呼びます。Iceberg REST Catalogは、このカタログ操作をHTTP APIとして標準化する取り組みです。近年は、Apache Spark、Trino、PyIcebergなどのクライアントが共通のREST APIを通じてIcebergテーブルを扱えるようにするインターフェースとして注目されています。
カタログの種類やそれぞれの特徴はベリング氏の記事で詳しく解説されているので、このあたりの概念に馴染みのない方は先にそちらを一読するとよいでしょう。
Hive MetastoreとIceberg REST Catalog
古くからIcebergを使用している方はHive MetastoreとIceberg REST Catalogという組み合わせに少し混乱しているかもしれません。
Hive MetastoreはApache Icebergが誕生するより前から存在するメタデータリポジトリです。広く普及したThrift APIを通じて、Icebergに限らず、さまざまなテーブルのメタデータを管理できます。Icebergテーブルもその対象で、このThrift APIを用いてIcebergテーブルを管理する方式は「Hive Catalog」と呼ばれています。
一方でApache Hiveプロジェクトは、Apache Icebergとの連携をさらに強化するため、Hive MetastoreにIcebergネイティブなREST Catalog APIを実装しました。これにより、IcebergネイティブなクライアントがREST APIでHive Metastoreと通信したり、ベンダーをまたいでIcebergテーブルの情報を連携したり、Iceberg REST Catalogならではの機能をHive Metastore側に取り込んだりできるようになります。たとえば、現在開発中の機能として、一時認証情報の払い出し機能やIceberg特有メトリクスの受信機能があります。
要するに、Hive Metastoreは従来のThrift APIに加えて、Icebergクライアント向けのREST APIもサポートするようになりました。Thrift APIを使う方式がHive Catalog、REST APIを使う方式がIceberg REST Catalogです。本記事では後者を扱います。
チュートリアル環境
チュートリアルではApache Hive公式Dockerイメージを用います。Hiveの standalone-metastore- で始まるイメージタグを用いると、Hive Metastoreに組み込まれたIceberg REST Catalogを追加設定なしで起動できます。デフォルト設定ではテーブルのメタデータやデータファイルがコンテナ内のローカルファイルシステムに置かれるため、curlやPyIcebergも同じコンテナ内で実行します。これにより、オブジェクトストレージや共有ボリュームを用意しなくても、Iceberg REST Catalogの基本的な動きを確認できます。
チュートリアル
Iceberg REST Catalogの起動
Hive Metastoreを起動します。Iceberg REST Catalogはコンテナ内の9001番ポートで起動します。
$ docker run --rm --name hms apache/hive:standalone-metastore-4.2.0
curlによるテーブル作成
まずはHive Metastoreが起動しているコンテナにログインします。
$ docker exec -it --user root hms /bin/bash
curlコマンドを用いて、id と name カラムを持つテーブルを作成してみましょう。
$ curl -X POST \ http://localhost:9001/iceberg/v1/namespaces/default/tables \ -H "Content-Type: application/json" \ -d '{ "name": "test", "schema": { "type": "struct", "fields": [ {"id": 1, "name": "id", "type": "long", "required": false}, {"id": 2, "name": "name", "type": "string", "required": false} ] }, "write-disposition": "create" }' {"metadata-location":"file:/opt/hive/data/warehouse/test/metadata/00000-854efeae-f861-4735-b1c1-74913975ce74.metadata.json",...}
作成したテーブルや関連するメタデータファイルがローカルファイルシステムに追加されています。
$ curl http://localhost:9001/iceberg/v1/namespaces/default/tables/test {"metadata-location":"file:/opt/hive/data/warehouse/test/metadata/00000-854efeae-f861-4735-b1c1-74913975ce74.metadata.json",...} $ ls -lR /opt/hive/data/warehouse/test/ /opt/hive/data/warehouse/test/: total 4 drwxr-xr-x 2 hive hive 4096 May 5 04:18 metadata /opt/hive/data/warehouse/test/metadata: total 4 -rw-r--r-- 1 hive hive 724 May 5 04:18 00000-854efeae-f861-4735-b1c1-74913975ce74.metadata.json
メタデータファイルの中身を見ると、Icebergテーブルのスキーマ情報などが保存されていることが分かります。
$ cat /opt/hive/data/warehouse/test/metadata/00000-854efeae-f861-4735-b1c1-74913975ce74.metadata.json
{"format-version":2,"table-uuid":"cc014a2f-c920-4562-80dc-f5e88a9bc147","location":"file:/opt/hive/data/warehouse/test",...}
PyIcebergによるテーブル操作
ここから先はPyIcebergを使用します。PyIcebergを使うと、curlよりも自然にIcebergテーブルを操作できます。
先にコンテナ上で関連パッケージをインストールします。
microdnf update -y microdnf install -y python3 python3-pip pip install --upgrade pip pip install 'pyiceberg[pandas]' python -c "import pyiceberg; print(pyiceberg.__version__)"
次に python コマンドでREPLを起動し、REST Catalogに接続します。
$ python >>> from pyiceberg.catalog import load_catalog >>> import pandas as pd >>> import pyarrow as pa >>> catalog = load_catalog(type="rest", uri="http://localhost:9001/iceberg") >>> catalog.list_tables(namespace="default") [('default', 'test')]
先ほど curl コマンドで作成したテーブルにデータを追加します。
>>> table = catalog.load_table("default.test") >>> df = pd.DataFrame({"id": [1, 2, 3], "name": ["alice", "bob", "carol"]}) >>> table.append(pa.Table.from_pandas(df, preserve_index=False)) >>> table.scan().to_arrow() pyarrow.Table id: int64 name: string ---- id: [[1,2,3]] name: [["alice","bob","carol"]]
データファイルと新たなメタデータが追加されていることが確認できます。
$ ls -lR /opt/hive/data/warehouse/test/ /opt/hive/data/warehouse/test/: total 8 drwxr-xr-x 2 root root 4096 May 5 04:25 data drwxr-xr-x 2 hive hive 4096 May 5 04:25 metadata /opt/hive/data/warehouse/test/data: total 4 -rw-r--r-- 1 root root 950 May 5 04:25 00000-0-106bcea1-a4cf-4d1a-ba8c-f87009a910e8.parquet /opt/hive/data/warehouse/test/metadata: total 20 -rw-r--r-- 1 hive hive 724 May 5 04:18 00000-854efeae-f861-4735-b1c1-74913975ce74.metadata.json -rw-r--r-- 1 hive hive 1493 May 5 04:25 00001-0240b423-d07c-4451-bf3a-155060a46219.metadata.json -rw-r--r-- 1 root root 4279 May 5 04:25 106bcea1-a4cf-4d1a-ba8c-f87009a910e8-m0.avro -rw-r--r-- 1 root root 1777 May 5 04:25 snap-7865978314307043386-0-106bcea1-a4cf-4d1a-ba8c-f87009a910e8.avro
まとめ
以上、Hive MetastoreとPyIcebergを使ったIceberg REST Catalogの簡単チュートリアルでした。Hive Metastoreを使用することでクラウドサービスや分散ファイルシステムを用意しなくてもIceberg REST Catalogを手軽に試すことができます。また、Iceberg REST APIはcurlコマンドからも呼び出せるため、Icebergクライアントがカタログとどのようにやり取りしているのかを理解する入口にもなります。
チュートリアル用途だけでなく、Hive MetastoreのIceberg REST Catalog APIは、認証・認可を含む本番利用を想定した構成にも対応しています。今回のDocker例ではテストしやすいように認証なしで起動していますが、本番利用ではOAuth 2やApache Rangerなどを組み合わせた構成が想定されます。2026年5月20日に開催されるApache Iceberg Meetup Japanではそのあたりも含めた詳しい話をする予定です。都合がつく方はぜひ会場までお越しください！
