管理 catalog

了解如何：

• 在存储桶上启用和禁用 R2 Data Catalog。
• 启用和禁用表维护功能，如压缩和快照过期。
• 使用 API 令牌为 Iceberg 引擎进行身份验证。

在存储桶上启用 catalog 会打开 REST catalog 接口，并提供 Iceberg 客户端所需的 Catalog URI 和 Warehouse name。启用后，您可以在该存储桶中创建和管理 Iceberg 表。

npx wrangler r2 bucket catalog enable <BUCKET_NAME>

在存储桶上禁用 catalog 后，catalog 接口会立即停止处理请求。存储在该 catalog 中的任何 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

启用后，压缩会追溯应用于所有现有表（catalog 级压缩）或指定表（表级压缩）。

禁用压缩将阻止该过程对所有表（catalog 级）或特定表（表级）运行。您可以随时重新启用。

# 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

禁用快照过期将阻止该过程对所有表（catalog 级）或特定表（表级）运行。您可以随时重新启用快照过期。

# 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 交互以执行表操作。catalog 还会向引擎提供 SigV4 凭据，这是访问存储在 R2 中的底层数据文件所必需的。

R2 Data Catalog 支持只读和读写令牌：

• 只读操作（例如，列出 namespace、加载表和查询数据）需要具有 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 引擎，使其能够管理 catalog 元数据并处理数据操作（对 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 存储桶。