MicroAd Developers Blog

マイクロアドのエンジニアブログです。インフラ、開発、分析について発信していきます。

Apache Icebergのメタデータを追跡してみた話

はじめに

こんにちは、マイクロアドでサーバーサイドエンジニアをしている本間です。

今回は Apache Icebergのメタデータが、実際の操作に応じてどのように変化するのかを追ってみました。


Apache Iceberg とは

マイクロアドでは、広告配信や分析、機械学習、各種バッチ処理など、さまざまな用途でデータを扱っています。

以前は Hadoopエコシステム(Hive、HDFS)を中心とした環境でデータを扱っていましたが、現在はApache Sparkと Apache Icebergを軸にした構成へ移行しています。

このような構成では、実データファイルをそのまま活用しながら、テーブルの整合性を保って更新できることや、複数の処理系から同じテーブルを一貫した状態で参照できることが重要になります。Apache Iceberg(以下Iceberg)は、そうした要件に対応しやすいテーブルフォーマットです。Parquetなどの実データファイルをそのまま使いながら、テーブルの状態をメタデータで管理することで、スナップショット単位での整合性や安全な更新、各種メンテナンス操作を実現できます。

一方で、Icebergを触り始めた段階では「実際に何がどう管理されているのか」が少し見えにくいという感覚もありました。INSERTやUPDATEのたびに何が増え、どのファイルが差し替わり、どこを見れば現在のテーブル状態が分かるのか。このあたりを追うことができれば運用時の理解も進みそうです。


Icebergのメタデータは、どこを見れば分かるのか

Icebergのエコシステムは大きく分けて次の 3 層に分けられます。

  • カタログ: 各テーブルの最新の状態を示すメタデータのロケーション情報を管理
  • メタデータレイヤー: Icebergテーブルのスキーマや統計情報、スナップショットに関するデータを保持
  • データレイヤー: Parquetファイルなどの実ファイル

全体の参照関係をイメージ図にすると、次のようになります。

Apache Icebergのメタデータのイメージ図
Apache Icebergのメタデータのイメージ図 1

イメージ図に出てくる主な要素を、メタデータレイヤーとデータレイヤーに絞って整理すると、次のようになります。

要素 レイヤー 主な役割
metadata file (metadata.json) メタデータレイヤー テーブル全体の状態を表す起点となるファイル。現在のスキーマ、パーティション定義、snapshot の一覧などを持つ
manifest list メタデータレイヤー 1 つの snapshot に紐づく manifest file の一覧を持つ Avro ファイル
manifest file メタデータレイヤー どの実データファイルや削除ファイルが現在のテーブル状態に含まれるかを、追加・削除の状態とともに持つ Avro ファイル
実データファイル データレイヤー Parquet などの実データ本体を保持するファイル
削除ファイル データレイヤー 行削除や位置削除の情報を保持するファイル

つまり、テーブル全体の情報は metadata file から始まり、snapshot、manifest list、manifest file をたどることで、最終的にどの実データファイルや削除ファイルが現在のテーブル状態を構成しているのかを確認できます。


検証内容

検証内容は大きく3つです。

  1. INSERT後に生成されるメタデータを確認する
  2. UPDATE後にメタデータがどのように変化するのかを確認する
  3. 実データファイルを大量に作り、コンパクション処理(rewrite_data_files, rewrite_manifests)の結果を確認する

検証環境

  • Apache Spark
  • Apache Iceberg REST Catalog
  • MinIO

今回はローカルでdocker-composeを使用してミニデータ基盤を構築し検証しました。

以下が今回の構成です。

services:
  # Spark
  spark-iceberg:
    build:
      context: .
      dockerfile: Dockerfile.spark-iceberg
    image: test-iceberg/spark-iceberg:local
    container_name: spark-iceberg
    depends_on:
      - rest
      - minio
    environment:
      - AWS_ACCESS_KEY_ID=admin
      - AWS_SECRET_ACCESS_KEY=password
      - AWS_REGION=us-east-1
    volumes:
      - ./warehouse:/home/iceberg/warehouse
      - ./notebooks:/home/iceberg/notebooks
      - ./spark-defaults.conf:/opt/spark/conf/spark-defaults.conf
    ports:
      - "8888:8888"   # Jupyter Notebook
      - "8080:8080"   # Spark Master UI
      - "4040:4040"   # Spark Application UI
      - "10000:10000" # Spark Thrift Server
      - "10001:10001" # Spark Thrift Server (HTTP)
    networks:
      - iceberg-net

  # Iceberg REST Catalog
  rest:
    image: apache/iceberg-rest-fixture:latest
    container_name: iceberg-rest
    environment:
      - AWS_ACCESS_KEY_ID=admin
      - AWS_SECRET_ACCESS_KEY=password
      - AWS_REGION=us-east-1
      - CATALOG_WAREHOUSE=s3://warehouse/
      - CATALOG_IO__IMPL=org.apache.iceberg.aws.s3.S3FileIO
      - CATALOG_S3_ENDPOINT=http://minio:9000
    ports:
      - "8181:8181"
    networks:
      - iceberg-net

  # MinIO (S3-compatible storage)
  minio:
    image: minio/minio:latest
    container_name: minio
    environment:
      - MINIO_ROOT_USER=admin
      - MINIO_ROOT_PASSWORD=password
      - MINIO_DOMAIN=minio
    ports:
      - "9000:9000"
      - "9001:9001"
    command: ["server", "/data", "--console-address", ":9001"]
    networks:
      iceberg-net:
        aliases:
          - warehouse.minio
    volumes:
      - minio-data:/data

  # MinIO Client
  mc:
    image: minio/mc:latest
    container_name: mc
    depends_on:
      - minio
    environment:
      - AWS_ACCESS_KEY_ID=admin
      - AWS_SECRET_ACCESS_KEY=password
      - AWS_REGION=us-east-1
    entrypoint: >
      /bin/sh -c "
      until (/usr/bin/mc alias set minio http://minio:9000 admin password) do echo 'Waiting for MinIO...' && sleep 1; done;
      /usr/bin/mc mb minio/warehouse --ignore-existing;
      /usr/bin/mc policy set public minio/warehouse;
      echo 'Bucket created successfully';
      tail -f /dev/null
      "
    networks:
      - iceberg-net

networks:
  iceberg-net:

volumes:
  minio-data:

Icebergの実データとメタデータはMinIO上のs3://warehouse/配下に保存されます。


1. INSERT 後に生成されるメタデータを確認する

まずは、シンプルなテーブルを作成し2行だけ挿入します。

CREATE TABLE demo.test_db.test_table (
        id INT,
        name STRING,
        category STRING,
        created_at TIMESTAMP
) USING iceberg
TBLPROPERTIES (
    'format-version' = '2'
);

INSERT INTO demo.test_db.test_table VALUES
        (1, 'Alice', 'seed', timestamp '2026-04-18 09:00:00'),
        (2, 'Bob',   'seed', timestamp '2026-04-18 09:05:00');

テーブルを確認します。

SELECT * FROM demo.test_db.test_table ORDER BY id;
+---+-----+--------+-------------------+
|id |name |category|created_at         |
+---+-----+--------+-------------------+
|1  |Alice|seed    |2026-04-18 09:00:00|
|2  |Bob  |seed    |2026-04-18 09:05:00|
+---+-----+--------+-------------------+

次にメタデータを見ます。ここでは、以下を順番に確認します。

  • INSERT後にmetadata.jsonがどこにあるか
  • 最新のsnapshotがどのmanifest listを参照しているか
  • どのmanifest fileと実データファイルが現在のテーブル状態として見えているか

まずは metadata_log_entries です。ここを見ると、現在有効になっているmetadata.jsonの履歴を追えます。

SELECT *
FROM demo.test_db.test_table.metadata_log_entries
ORDER BY timestamp;
+-----------------------+----------------------------------------------------------------------------------------------------+-------------------+----------------+----------------------+
|timestamp              |file                                                                                                |latest_snapshot_id |latest_schema_id|latest_sequence_number|
+-----------------------+----------------------------------------------------------------------------------------------------+-------------------+----------------+----------------------+
|2026-04-27 04:43:18.627|s3://warehouse/test_db/test_table/metadata/00000-3e0a467b-c048-447b-8816-02cd2a410eb0.metadata.json |NULL               |NULL            |NULL                  |
|2026-04-27 04:43:19.897|s3://warehouse/test_db/test_table/metadata/00001-6a3ccbdf-4754-437d-ad32-ee94fc52b0b2.metadata.json |2506382081627402822|0               |1                     |
+-----------------------+----------------------------------------------------------------------------------------------------+-------------------+----------------+----------------------+

00000-3e0a467b-c048-447b-8816-02cd2a410eb0.metadata.jsonはテーブル作成時点のメタデータファイルで、その時点ではまだsnapshotがありません。初回INSERTの後に 00001-6a3ccbdf-4754-437d-ad32-ee94fc52b0b2.metadata.json が追加され、ここから最新snapshotへたどれるようになっているのが分かります。

次はsnapshotsです。

SELECT committed_at, snapshot_id, parent_id, operation, manifest_list
FROM demo.test_db.test_table.snapshots
ORDER BY committed_at;
+-----------------------+-------------------+---------+---------+----------------------------------------------------------------------------------------------------------------+
|committed_at           |snapshot_id        |parent_id|operation|manifest_list                                                                                                   |
+-----------------------+-------------------+---------+---------+----------------------------------------------------------------------------------------------------------------+
|2026-04-27 04:43:19.897|2506382081627402822|NULL     |append   |s3://warehouse/test_db/test_table/metadata/snap-2506382081627402822-1-1ad3affb-69ec-47a4-9710-d5727d234f3b.avro |
+-----------------------+-------------------+---------+---------+----------------------------------------------------------------------------------------------------------------+

ここでmanifest_listの中身を確認します。Avroファイルの中身もすべて載せると長くなるので、重要な項目だけ抜き出すと次のようになります。紐づくmanifest fileのパスが記載されています。

manifest list Avroファイル 抜粋
{
  "manifest_path": "s3://warehouse/test_db/test_table/metadata/1ad3affb-69ec-47a4-9710-d5727d234f3b-m0.avro",
  "added_snapshot_id": 2506382081627402822
}

続いてmanifestsを確認します。

SELECT path, added_snapshot_id, added_data_files_count
FROM demo.test_db.test_table.manifests
ORDER BY path;
+-------------------------------------------------------------------------------------------+-------------------+----------------------+
|path                                                                                       |added_snapshot_id  |added_data_files_count|
+-------------------------------------------------------------------------------------------+-------------------+----------------------+
|s3://warehouse/test_db/test_table/metadata/1ad3affb-69ec-47a4-9710-d5727d234f3b-m0.avro    |2506382081627402822|2                     |
+-------------------------------------------------------------------------------------------+-------------------+----------------------+

さらにmanifest fileのAvroファイルの中から重要な項目だけ抜くと、どの実データファイルが現在のテーブル状態に入っているかが見えてきます。

manifest file の Avroファイル 抜粋
{
  "status": 1,
  "data_file": {
    "file_path": "s3://warehouse/test_db/test_table/data/00000-0-d908c8e8-e8eb-43da-a81b-97c57053beda-0-00001.parquet",
    "record_count": 1
  }
}
{
  "status": 1,
  "data_file": {
    "file_path": "s3://warehouse/test_db/test_table/data/00001-1-d908c8e8-e8eb-43da-a81b-97c57053beda-0-00001.parquet",
    "record_count": 1
  }
}

最後に files を見ると、現在のテーブル状態として参照されている実データファイルが分かります。

SELECT content, file_path, record_count, file_size_in_bytes
FROM demo.test_db.test_table.files
ORDER BY file_path;

今回の初期 INSERT 後は、次の2ファイルが現在のテーブル状態として見えていました。

+-------+---------------------------------------------------------------------------------------------------+------------+------------------+
|content|file_path                                                                                          |record_count|file_size_in_bytes|
+-------+---------------------------------------------------------------------------------------------------+------------+------------------+
|0      |s3://warehouse/test_db/test_table/data/00000-0-d908c8e8-e8eb-43da-a81b-97c57053beda-0-00001.parquet|1           |1222              |
|0      |s3://warehouse/test_db/test_table/data/00001-1-d908c8e8-e8eb-43da-a81b-97c57053beda-0-00001.parquet|1           |1208              |
+-------+---------------------------------------------------------------------------------------------------+------------+------------------+

結果を上から順に並べると以下のつながりが確認できます。

  • snapshots.manifest_listがmanifest listのAvroファイル
  • manifests.path がmanifest fileのAvroファイル
  • files.file_pathが実データファイル

初回のINSERTだけでも、Icebergが単に2行のデータを保存しているのではなく、「どのsnapshotがどの実データファイルを現在のテーブル状態として採用しているか」をメタデータで表現していることが見えてきます。


2. UPDATE後にメタデータがどのように変化するのかを確認する

次に1行だけUPDATEします。

UPDATE demo.test_db.test_table
SET category = 'updated',
        name = 'Alice_updated'
WHERE id = 1;

更新後のデータを確認します。

SELECT *
FROM demo.test_db.test_table
ORDER BY id;
+---+-------------+--------+-------------------+
|id |name         |category|created_at         |
+---+-------------+--------+-------------------+
|1  |Alice_updated|updated |2026-04-18 09:00:00|
|2  |Bob          |seed    |2026-04-18 09:05:00|
+---+-------------+--------+-------------------+

UPDATE 後にもう一度snapshotsを見ると、manifest listのパスが新しくなっています。

SELECT committed_at, snapshot_id, parent_id, operation, manifest_list
FROM demo.test_db.test_table.snapshots
ORDER BY committed_at;
+-----------------------+-------------------+-------------------+---------+----------------------------------------------------------------------------------------------------------------+
|committed_at           |snapshot_id        |parent_id          |operation|manifest_list                                                                                                   |
+-----------------------+-------------------+-------------------+---------+----------------------------------------------------------------------------------------------------------------+
|2026-04-27 04:43:19.897|2506382081627402822|NULL               |append   |s3://warehouse/test_db/test_table/metadata/snap-2506382081627402822-1-1ad3affb-69ec-47a4-9710-d5727d234f3b.avro |
|2026-04-27 04:43:27.901|6528636876310369759|2506382081627402822|overwrite|s3://warehouse/test_db/test_table/metadata/snap-6528636876310369759-1-24b3e610-3502-4d21-92a3-07f63efcce97.avro |
+-----------------------+-------------------+-------------------+---------+----------------------------------------------------------------------------------------------------------------+

operationがoverwriteになっており、新しいsnapshotが前のsnapshotを親として紐づいているのが分かります。

manifestsの結果も見ると、UPDATE後はmanifest fileが2本に増えています。

SELECT path, added_snapshot_id, added_data_files_count, existing_data_files_count, deleted_data_files_count
FROM demo.test_db.test_table.manifests
ORDER BY path;
+-------------------------------------------------------------------------------------------+-------------------+----------------------+-------------------------+------------------------+
|path                                                                                       |added_snapshot_id  |added_data_files_count|existing_data_files_count|deleted_data_files_count|
+-------------------------------------------------------------------------------------------+-------------------+----------------------+-------------------------+------------------------+
|s3://warehouse/test_db/test_table/metadata/24b3e610-3502-4d21-92a3-07f63efcce97-m0.avro    |6528636876310369759|0                     |1                        |1                       |
|s3://warehouse/test_db/test_table/metadata/24b3e610-3502-4d21-92a3-07f63efcce97-m1.avro    |6528636876310369759|1                     |0                        |0                       |
+-------------------------------------------------------------------------------------------+-------------------+----------------------+-------------------------+------------------------+

UPDATE後の manifest listのAvroファイルを見ると、参照先のmanifest fileの構成が変わっていることも確認できます。初回INSERTの時点では manifest fileは1つだけでしたが、UPDATE 後は2つのmanifest fileを参照する形になっています。

manifest list Avroファイル 抜粋
[
  {"manifest_path": "s3://warehouse/test_db/test_table/metadata/24b3e610-3502-4d21-92a3-07f63efcce97-m1.avro"},
  {"manifest_path": "s3://warehouse/test_db/test_table/metadata/24b3e610-3502-4d21-92a3-07f63efcce97-m0.avro"}
]

files テーブルを見ると、UPDATE 後は 1 つの実データファイルが新しいパスに置き換わっていました。

+-------+----------------------------------------------------------------------------------------------------+------------+------------------+
|content|file_path                                                                                           |record_count|file_size_in_bytes|
+-------+----------------------------------------------------------------------------------------------------+------------+------------------+
|0      |s3://warehouse/test_db/test_table/data/00000-17-00b5bc10-c2db-499a-af21-f7864ccea410-0-00001.parquet|1           |1339              |
|0      |s3://warehouse/test_db/test_table/data/00001-1-d908c8e8-e8eb-43da-a81b-97c57053beda-0-00001.parquet |1           |1208              |
+-------+----------------------------------------------------------------------------------------------------+------------+------------------+

ここで注目したいのは、UPDATE後も実データファイルは2本のままだという点です。そのうち1本はUPDATE前と同じパスのまま残っており、もう1本だけが新しいパスに置き換わっています。つまり今回のUPDATEでは、更新された1行を含む実データファイルだけが新しく作られ、それ以外の実データファイルはそのまま再利用されていることが分かります。

SQL の見た目は単純なUPDATEでも、内部的にはsnapshotが増え、manifest listが差し替わり、必要な実データファイルだけが新しい状態へ置き換えられます。テーブルを更新するときに何がどの粒度で変わるのかを知るうえで、filesとsnapshotsを一緒に見るのはかなり有効でした。


3. 実データファイルを大量に作り、コンパクション処理(rewrite_data_files, rewrite_manifests)の結果を確認する

ここから先は、INSERT/UPDATEのような単発の変更ではなく、運用寄りのメンテナンスを意識した検証です。先に今回検証する処理が何をするものなのかを整理しておきます。

  • rewrite_data_files: 細かく分かれた実データファイルをまとめ直し、読み取り時に参照するファイル数を減らす
  • rewrite_manifests: 増えたmanifestをまとめ直し、メタデータ参照のオーバーヘッドを減らす

今回は、実データファイルが多数あるテーブルに対してこれらを実行した場合、想定通りに動作するか確認します。

  1. rewrite_data_files で実データファイル数が減るか
  2. rewrite_manifests でmanifest数が減るか

まず、テーブルを作成して同じ形式のINSERTを50回に分けて実行し、合計500,000 行を投入しました。

CREATE TABLE demo.test_db.compaction_table (
    id BIGINT,
    name STRING,
    category STRING,
    created_at TIMESTAMP
) USING iceberg
PARTITIONED BY (bucket(32, id))
TBLPROPERTIES (
    'format-version' = '2'
);
# pysparkで実行
for batch_index in range(50):
    start_id = batch_index * 10000 + 1
    end_id = (batch_index + 1) * 10000 + 1
    spark.sql(
        f"""
        INSERT INTO demo.test_db.compaction_table
        SELECT
            id,
            concat('user_', cast(id AS string)) AS name,
            concat('batch_', cast({batch_index} AS string)) AS category,
            timestamp'2026-04-18 09:00:00' AS created_at
        FROM range({start_id}, {end_id})
        """
    )
SELECT count(*) AS row_count
FROM demo.test_db.compaction_table;
+---------+
|row_count|
+---------+
|500000   |
+---------+

続いて filesを見ると、現在のテーブル状態には1600個の実データファイルが見えています。content = 0は実データを表しています。

SELECT content, count(*) AS file_count, sum(record_count) AS total_records
FROM demo.test_db.compaction_table.files
GROUP BY content
ORDER BY content;
+-------+----------+-------------+
|content|file_count|total_records|
+-------+----------+-------------+
|0      |1600      |500000       |
+-------+----------+-------------+

さらに manifestsを見ると、各INSERTに対応するmanifestが積み上がっていることも分かります。

SELECT count(*) AS manifest_count
FROM demo.test_db.compaction_table.manifests;
+--------------+
|manifest_count|
+--------------+
|50            |
+--------------+

manifestsの詳細を見ると、各manifest がadded_data_files_count = 32を持っていました。今回のテーブルはbucket(32, id)でパーティションしているので、1回の投入ごとに 32 個ずつ実データファイルが増え、それが 50 回分積み上がって最終的に 1600 ファイルになっています。

rewrite_data_files を実行

実行したSQLは次の通りです。

CALL demo.system.rewrite_data_files(
  table => 'test_db.compaction_table'
);

結果は次の通りでした。

+--------------------------+----------------------+---------------------+-----------------------+
|rewritten_data_files_count|added_data_files_count|rewritten_bytes_count|failed_data_files_count|
+--------------------------+----------------------+---------------------+-----------------------+
|1600                      |32                    |4255768              |0                      |
+--------------------------+----------------------+---------------------+-----------------------+

再度filesを確認します。

SELECT content, count(*) AS file_count, sum(record_count) AS total_records
FROM demo.test_db.compaction_table.files
GROUP BY content
ORDER BY content;
+-------+----------+-------------+
|content|file_count|total_records|
+-------+----------+-------------+
|0      |32        |500000       |
+-------+----------+-------------+

ここで見えているのは次の2点です。

  1. 実データファイルは1600個から32個まで圧縮された
  2. total_recordsは500,000のままで、データ自体は失われていない

想定どおり、rewrite_data_filesは、実データファイルが多数に分かれてしまったテーブルをまとめ直すための処理だと分かります。

今回の結果では、rewritten_data_files_count = 1600、added_data_files_count = 32、failed_data_files_count = 0となっており、1600 個の実データファイルが32個まで整理されました。実データファイルが細かく分かれすぎると、読み取り時に参照すべきファイル数が増え、計画やスキャンのオーバーヘッドも大きくなります。コンパクションによってファイル数を減らせると、データ量が多いテーブルでも比較的早くデータをスキャンすることができます。

rewrite_manifestsを実行

rewrite_data_filesのあとに、メタデータ側を整理するため rewrite_manifestsも実行しました。

実行したSQLは以下です。

CALL demo.system.rewrite_manifests(
  table => 'test_db.compaction_table'
);

結果は次の通りです。

+-------------------------+---------------------+
|rewritten_manifests_count|added_manifests_count|
+-------------------------+---------------------+
|51                       |1                    |
+-------------------------+---------------------+

さらに manifestsテーブルを確認すると、現在のテーブル状態で参照されるmanifest数は1個まで整理されていました。

SELECT count(*) AS manifest_count
FROM demo.test_db.compaction_table.manifests;
+--------------+
|manifest_count|
+--------------+
|1             |
+--------------+

実際のmanifestsの中身は次のようになっていました。

SELECT path, added_snapshot_id, added_data_files_count, existing_data_files_count, deleted_data_files_count
FROM demo.test_db.compaction_table.manifests
ORDER BY path;
+----------------------------------------------------------------------------------------------------------+-------------------+----------------------+-------------------------+------------------------+
|path                                                                                                      |added_snapshot_id  |added_data_files_count|existing_data_files_count|deleted_data_files_count|
+----------------------------------------------------------------------------------------------------------+-------------------+----------------------+-------------------------+------------------------+
|s3://warehouse/test_db/compaction_table/metadata/optimized-m-1c3cb5aa-3fb2-49a7-987d-bf9fea8c9770.avro    |26644394748273399  |0                     |32                       |0                       |
+----------------------------------------------------------------------------------------------------------+-------------------+----------------------+-------------------------+------------------------+

こちらも想定どおり、rewrite_data_files直後のsnapshotが持っていた51個のmanifest が rewrite_manifestsによって読み直され、最終的には1個のマニフェストファイルに整理されました。実データファイルだけでなく、その参照に使うメタデータ側もまとめ直せることが確認できました。


今後の展望

現在はコンパクションなどの最適化作業を一定期間ごとに手動で行なっていますが、いずれは rewrite_data_filesと rewrite_manifestsを含めて自動化していきたいです。

また、今回の検証ではメタデータの見え方をかなり素朴に追いましたが、実運用では「どの条件でコンパクションを走らせるか」、「どこまで実データファイルやmanifestが増えたら再編成をかけるか」といった基準作りも重要になります。このあたりは今後もう少し詰めていきたいところです。


まとめ

今回はIcebergのメタデータについて検証結果を書きました。まだまだIcebergの機能を理解できていないので引き続き学習を進めていきたいです。