カタログを管理する

次の操作を確認できます。

• バケットで R2 Data Catalog を有効／無効にする。
• コンパクションやスナップショット期限切れなどの テーブルメンテナンス 機能を有効／無効にする。
• API トークンで Iceberg エンジンを認証する。

バケットでカタログを有効にすると、REST catalog インターフェイスがオンになり、Iceberg クライアントに必要な Catalog URI と Warehouse name が提供されます。有効化後、そのバケットで Iceberg テーブルを作成・管理できます。

npx wrangler r2 bucket catalog enable <BUCKET_NAME>

バケットのカタログを無効にすると、カタログインターフェイスはすぐにリクエストへの応答を停止します。そのカタログに保存された Iceberg テーブル参照は、再有効化するまでアクセスできません。

npx wrangler r2 bucket catalog disable <BUCKET_NAME>

コンパクションは、データ取り込み時に作られる多数の小さなファイルを、設定した target file size に従ってより少ない大きなファイルへまとめることで、クエリ性能を上げます。コンパクションの内容と利点は、コンパクションについて を参照してください。

# Enable catalog-level compaction (all tables)
npx wrangler r2 bucket catalog compaction enable <BUCKET_NAME> --target-size 128 --token <API_TOKEN>

# Enable compaction for a specific table
npx wrangler r2 bucket catalog compaction enable <BUCKET_NAME> <NAMESPACE> <TABLE> --target-size 128

有効にすると、コンパクションは既存の全テーブル（カタログレベル）または指定したテーブル（テーブルレベル）にさかのぼって適用されます。

コンパクションを無効にすると、全テーブル（カタログレベル）または特定のテーブル（テーブルレベル）で処理が止まります。いつでも再有効化できます。

# Disable catalog-level compaction (all tables)
npx wrangler r2 bucket catalog compaction disable <BUCKET_NAME>

# Disable compaction for a specific table
npx wrangler r2 bucket catalog compaction disable <BUCKET_NAME> <NAMESPACE> <TABLE>

スナップショット期限切れは、古いテーブルスナップショットと参照されていないデータファイルを自動で削除し、メタデータのオーバーヘッドとストレージコストを下げます。次を設定できます。

• Max snapshot age - この期間より古いスナップショットは期限切れになります。値のあとに単位を付けます（日は d、時間は h、分は m、秒は s）。例: 7d は 7 日より古いスナップショットを期限切れにします。
• Min snapshots to keep - 経過時間に関係なく残すスナップショットの最小数です。

# Enable catalog-level snapshot expiration (all tables)
npx wrangler r2 bucket catalog snapshot-expiration enable <BUCKET_NAME> \
  --token <API_TOKEN> \
  --older-than-days 7 \
  --retain-last 10

# Enable snapshot expiration for a specific table
npx wrangler r2 bucket catalog snapshot-expiration enable <BUCKET_NAME> <NAMESPACE> <TABLE> \
  --older-than-days 2 \
  --retain-last 5

スナップショット期限切れを無効にすると、全テーブル（カタログレベル）または特定のテーブル（テーブルレベル）で処理が止まります。いつでも再有効化できます。

# Disable catalog-level snapshot expiration (all tables)
npx wrangler r2 bucket catalog snapshot-expiration disable <BUCKET_NAME>

# Disable snapshot expiration for a specific table
npx wrangler r2 bucket catalog snapshot-expiration disable <BUCKET_NAME> <NAMESPACE> <TABLE>

Iceberg エンジンを R2 Data Catalog に接続するには、R2 Data Catalog の権限と R2 ストレージの権限の 両方 を持つ Cloudflare API トークンが必要です。Iceberg エンジンは R2 Data Catalog とやり取りしてテーブル操作を行います。カタログはエンジンへ SigV4 認証情報も渡し、R2 に保存された実データファイルへのアクセスに使います。

R2 Data Catalog は読み取り専用トークンと読み書きトークンの両方に対応しています。

• 読み取り専用 の操作（名前空間の一覧、テーブルの読み込み、データのクエリなど）には、R2 Data Catalog と R2 ストレージへの読み取り権限を持つトークンが必要です。
• 書き込み の操作（テーブルの作成や削除、トランザクションのコミットなど）には、R2 Data Catalog と R2 ストレージへの読み取りと書き込み権限を持つトークンが必要です。

データの読み取りだけを行うクエリエンジンやクライアント（R2 SQL、DuckDB、PyIceberg のリーダーなど）には読み取り専用トークンを使い、テーブル作成やデータ書き込みを行うエンジンやパイプラインには読み書きトークンを使います。

ワークロードに合う権限で R2 API トークン を作成します。

• Admin Read & Write — データの読み書きを行うエンジンやパイプライン向けです。R2 Data Catalog と R2 ストレージの両方への読み取りと書き込み権限を含みます。
• Admin Read only — データの読み取りだけを行うクエリエンジンやクライアント向けです。R2 Data Catalog と R2 ストレージの両方への読み取り権限を含みます。

発行されたトークン値を Iceberg エンジンへ渡すと、カタログメタデータの管理と、データ操作（R2 への読み取りまたは書き込み）ができます。

R2 Data Catalog 向けの API トークンをプログラムから作成するには、Access Policy に R2 Data Catalog と R2 ストレージの両方の権限グループを指定します。

テーブル作成やデータ書き込みを行うエンジンやパイプラインには、読み取りと書き込みの権限グループを使います。

[
	{
		"id": "f267e341f3dd4697bd3b9f71dd96247f",
		"effect": "allow",
		"resources": {
			"com.cloudflare.edge.r2.bucket.4793d734c0b8e484dfc37ec392b5fa8a_default_my-bucket": "*",
			"com.cloudflare.edge.r2.bucket.4793d734c0b8e484dfc37ec392b5fa8a_eu_my-eu-bucket": "*"
		},
		"permission_groups": [
			{
				"id": "d229766a2f7f4d299f20eaa8c9b1fde9",
				"name": "Workers R2 Data Catalog Write"
			},
			{
				"id": "2efd5506f9c8494dacb1fa10a3e7d5b6",
				"name": "Workers R2 Storage Bucket Item Write"
			}
		]
	}
]

データの読み取りだけを行うクエリエンジンやクライアントには、読み取りの権限グループを使います。

[
	{
		"id": "f267e341f3dd4697bd3b9f71dd96247f",
		"effect": "allow",
		"resources": {
			"com.cloudflare.edge.r2.bucket.4793d734c0b8e484dfc37ec392b5fa8a_default_my-bucket": "*",
			"com.cloudflare.edge.r2.bucket.4793d734c0b8e484dfc37ec392b5fa8a_eu_my-eu-bucket": "*"
		},
		"permission_groups": [
			{
				"id": "45db74139a62490b9b60eb7c4f34994b",
				"name": "Workers R2 Data Catalog Read"
			},
			{
				"id": "6a018a9f2fc74eb6b293b0c548f38b39",
				"name": "Workers R2 Storage Bucket Item Read"
			}
		]
	}
]

API で R2 Data Catalog 向けの API トークンを作成する方法、必要な権限グループ、利用例は、API で API トークンを作成する を参照してください。

Local Uploads は、オブジェクトデータを近くの場所へ書き込んだあと、非同期でバケットへコピーします。データはすぐにクエリでき、強い一貫性を保ちます。対象の R2 Data Catalog バケットがあるリージョン外の Apache Iceberg クライアントからの書き込みレイテンシを、大きく改善できます。

R2 Local Uploads を有効にするには、次の Wrangler コマンドを使えます。

npx wrangler r2 bucket catalog local-uploads enable <R2_Data_Catalog_BUCKET_NAME>

• R2 Data Catalog は現在、デフォルト以外の管轄にある R2 バケットに対応していません。