テーブルメンテナンス

テーブルメンテナンスは、Apache Iceberg テーブルの性能とコスト効率を長期的に保つ一連の操作です。データの書き込み、更新、削除が進むと、テーブルにはメタデータとファイルが蓄積し、クエリ性能が低下することがあります。

R2 Data Catalog は、次の 2 つの重要なメンテナンス操作を自動化します。

• コンパクション: 小さなデータファイルをより大きく効率的なファイルにまとめ、クエリ性能を向上します
• スナップショットの期限切れ: 古いテーブルスナップショットと、参照されていないデータファイルを削除し、メタデータのオーバーヘッドとストレージコストを下げます

定期メンテナンスがないと、テーブルは次の影響を受けます。

• クエリ性能の低下: スキャンするファイルが増え、クエリが遅くなり、コンピュートコストが上がります
• ストレージコストの増加: 小さなファイルと古いスナップショットの蓄積が、不要なストレージを使います
• メタデータのオーバーヘッド: 大きなメタデータファイルは、クエリ計画とテーブル操作を遅くします

自動テーブルメンテナンスを有効にすると、R2 Data Catalog がテーブルを最適化し続けます。手動実行は不要です。

各テーブルの Maintenance タブには、コンパクションとスナップショット期限切れの設定、スケジュール、次回対象時刻が表示されます。ステータスと所要時間付きのメンテナンス実行履歴も、ページ分割して確認できます。

Recent runs セクションは、1 ページあたり 5 件の実行を表示します。実行を展開すると、マニフェスト書き換え、コンパクション、スナップショット期限切れのメトリクスを確認できます。手動でキュー投入した実行では、展開した詳細に検索可能な request_id が含まれます。

手動キュー投入は、選択したテーブルのコンパクションを要求します。要求は自動メンテナンスと同じキューに入り、スケジューラーが次に対象作業をポーリングしたときに開始します。

ダッシュボードは、要求を受け付ける前に権限を確認します。キュー投入は次のエラーを返すこともあります。

• 40903: メンテナンス実行者の競合により、要求をキューに入れられません。
• 42901: 1 日あたりの受付リクエスト上限に達しました。

Apache Iceberg ↗ では、大小にかかわらず、すべての書き込み操作が新しいファイル一式を生成します。時間が経つと、ファイル数は上限なく増えることがあります。その結果、次が起きます。

• クエリの低下と I/O の増加: コンパクションがないと、クエリエンジンは各ファイルを開いて読む必要があり、クエリ時間が延び、コストが増えます。
• メタデータのオーバーヘッド増加: クエリエンジンは、読むファイルを決めるためにメタデータファイルをスキャンします。小さなファイルが数千あると、データにアクセスする前のクエリ計画が長くなります。
• 圧縮効率の低下: 小さなファイルは大きなファイルより圧縮効率が悪く、ストレージコストが上がり、クエリ時に転送するデータも増えます。

R2 Data Catalog は、R2 に保存された Apache Iceberg テーブルの コンパクションを管理 できるようになりました。有効にすると、コンパクションは自動実行され、まだコンパクションされていない新しいファイルをまとめます。

コンパクション済みファイルは、該当テーブルの /data/ ディレクトリで compacted- プレフィックスが付きます。

# Enable catalog-level compaction (all tables)
npx wrangler r2 bucket catalog compaction enable my-bucket \
  --target-size 128 \
  --token $R2_CATALOG_TOKEN

# Enable compaction for a specific table
npx wrangler r2 bucket catalog compaction enable my-bucket my-namespace my-table \
  --target-size 256

# Disable catalog-level compaction
npx wrangler r2 bucket catalog compaction disable my-bucket

# Disable compaction for a specific table
npx wrangler r2 bucket catalog compaction disable my-bucket my-namespace my-table

コンパクション管理の詳細は、カタログの管理 を参照してください。

コンパクションのターゲットファイルサイズは設定できます。現在、最小は 64 MB、最大は 512 MB です。

コンピュートエンジンごとに最適なファイルサイズは異なるため、各ドキュメントを確認します。

性能のトレードオフは用途によって変わります。たとえば、少量のデータだけを返すクエリは、小さなファイルの方がよい場合があります。大きなファイルだと不要なデータを読むことがあるためです。

• レイテンシに敏感なワークロードでは、小さめのターゲットファイルサイズ（64 MB〜128 MB など）を検討します
• ストリーミング取り込みでは、中程度のファイルサイズ（128 MB〜256 MB など）を検討します
• 大量データをスキャンする OLAP スタイルのクエリでは、大きめのファイルサイズ（256 MB〜512 MB など）を検討します

Iceberg テーブルへの書き込み（挿入、更新、削除のいずれでも）は、新しいスナップショットを作ります。時間が経つとスナップショットが蓄積し、次の性能問題を起こすことがあります。

• メタデータのオーバーヘッド: 各スナップショットはテーブルのメタデータファイルにエントリを追加します。スナップショットが増えるとメタデータファイルが大きくなり、クエリ計画とテーブル操作が遅くなります
• ストレージコストの増加: 古いスナップショットは、もう不要なデータファイルを参照していることがあります。スナップショットの期限切れがないと、これらのファイルは不要なストレージを使い続けます
• テーブル操作の低下: スナップショット一覧やテーブル履歴へのアクセスは、時間とともに遅くなります

スナップショット期限切れは、削除するスナップショットを決めるために 2 つのパラメーターを使います。

• --older-than-days: この日数より古いスナップショットを削除します（デフォルト: 30 日）
• --retain-last: 最近のスナップショットを、この最小件数だけ常に残します（デフォルト: 5 スナップショット）

スナップショットが期限切れになるには、両方の条件を満たす必要があります。年齢のしきい値より古くても、最近のスナップショットは常に残します。

# Enable snapshot expiration for entire catalog
# Keep minimum 10 snapshots, expire those older than 7 days
npx wrangler r2 bucket catalog snapshot-expiration enable my-bucket \
  --token $R2_CATALOG_TOKEN \
  --older-than-days 7 \
  --retain-last 10

# Enable for specific table
# Keep minimum 5 snapshots, expire those older than 2 days
npx wrangler r2 bucket catalog snapshot-expiration enable my-bucket my-namespace my-table \
  --token $R2_CATALOG_TOKEN \
  --older-than-days 2 \
  --retain-last 5

# Disable snapshot expiration for a catalog
npx wrangler r2 bucket catalog snapshot-expiration disable my-bucket

ワークロードごとに、必要なスナップショット保持戦略は異なります。

• 開発 / テストテーブル: ストレージコストを抑えるため、短い保持（2〜7 日、5 スナップショット）
• 本番分析テーブル: デバッグと分析のため、中程度の保持（7〜30 日、10〜20 スナップショット）
• コンプライアンス / 監査テーブル: 規制要件を満たすため、長い保持（30〜90 日、50 スナップショット以上）
• 高頻度取り込み: より細かい履歴を残すため、最小スナップショット数を多めにする

これらは一般的な推奨です。次も考慮してください。

• タイムトラベルの要件
• コンプライアンス要件
• ストレージコスト

• コンパクションが現在対応しているのは、Parquet 形式で保存されたデータファイルだけです。
• 以前スナップショットから参照されていなかったファイル（孤立ファイル）は、クリーンアップされません。
• コンパクションのターゲットファイルサイズは、最小 64 MB、最大 512 MB です。