跳转到内容
本站为社区维护的非官方中文翻译，与 Cloudflare, Inc. 无关联。本站不提供账户登录，请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档：developers.cloudflare.com
CF 中文文档非官方翻译
搜索文档
↵选择
↑↓导航
ESC关闭

管理 catalog

最后更新 查看 MarkdownAgent 设置

了解如何：

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

在存储桶上启用 Basin Catalog

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

  1. 在 Cloudflare 仪表板中，前往 Basin Catalog 页面。

    前往 Basin Catalog ↗

  2. 选择 Create catalog（创建目录）。

  3. 输入 R2 存储桶名称。可以选择现有存储桶，或输入新存储桶名称以创建一个。如果创建新存储桶，可选地选择位置提示。

  4. 选择 Next（下一步） 配置表维护。在设置过程中可选地启用压缩和快照过期。

  5. 查看配置并选择 Create catalog（创建目录）。

  6. 创建完成后，catalog 详情页会显示 Catalog URI 和 Warehouse name。

要在存储桶上启用 catalog，请运行 basin catalog enable 命令：

npx wrangler basin catalog enable <BUCKET_NAME>

启用后，Wrangler 将返回 catalog URI 和 warehouse 名称。

在存储桶上禁用 Basin Catalog

在存储桶上禁用 catalog 后，catalog 接口会立即停止处理请求。存储在该 catalog 中的任何 Iceberg 表引用在重新启用之前将无法访问。

  1. 在 Cloudflare 仪表板中，前往 Basin Catalog 页面。

    前往 Basin Catalog ↗

  2. 选择要禁用的 catalog。

  3. 前往 Settings（设置） 选项卡，滚动到 Disable（禁用） 部分。

  4. 选择 Disable（禁用） 并确认。

要在存储桶上禁用 catalog，请运行 basin catalog disable 命令：

npx wrangler basin catalog disable <BUCKET_NAME>

启用压缩

压缩通过将数据摄取过程中创建的许多小文件合并为更少、更大的文件（根据设定的 target file size）来提高查询性能。有关压缩及其价值的更多信息，请参阅关于压缩。

  1. 在 Cloudflare 仪表板中，前往 Basin Catalog 页面。

    前往 Basin Catalog ↗

  2. 选择要启用压缩的 catalog。

  3. 前往 Settings（设置） 选项卡，滚动到 Table Maintenance（表维护） 部分。

  4. 选择压缩旁边的 Enable（启用） 或 Edit（编辑）。

  5. 开启压缩，可选地设置目标文件大小。默认值为 128 MB。

  6. 选择 Save（保存）。

要在 catalog 上启用压缩，请运行 basin catalog compaction enable 命令：

启用 catalog 级压缩：

npx wrangler basin catalog compaction enable <BUCKET_NAME> --target-size 128 --token <API_TOKEN>

为特定表启用压缩：

npx wrangler basin catalog compaction enable <BUCKET_NAME> <NAMESPACE> <TABLE> --target-size 128

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

禁用压缩

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

  1. 在 Cloudflare 仪表板中，前往 Basin Catalog 页面。

    前往 Basin Catalog ↗

  2. 选择要禁用压缩的 catalog。

  3. 前往 Settings（设置） 选项卡，滚动到 Table Maintenance（表维护） 部分。

  4. 选择压缩旁边的 Edit（编辑）。

  5. 关闭压缩。

  6. 选择 Save（保存）。

要在 catalog 上禁用压缩，请运行 basin catalog compaction disable 命令：

禁用 catalog 级压缩：

npx wrangler basin catalog compaction disable <BUCKET_NAME>

为特定表禁用压缩：

npx wrangler basin catalog compaction disable <BUCKET_NAME> <NAMESPACE> <TABLE>

启用快照过期

快照过期会自动删除旧表快照及任何未引用的数据文件，以减少元数据开销和存储成本。您可以配置：

  • Max snapshot age（最大快照时长） — 超过此时长的快照将被过期。指定数值后跟单位（d 表示天，h 表示小时，m 表示分钟，s 表示秒）。例如，7d 表示过期超过 7 天的快照。
  • Min snapshots to keep（最少保留快照数） — 无论年龄如何，始终保留的最少快照数量。

  1. 在 Cloudflare 仪表板中，前往 Basin Catalog 页面。

    前往 Basin Catalog ↗

  2. 选择要启用快照过期的 catalog。

  3. 前往 Settings（设置） 选项卡，滚动到 Table Maintenance（表维护） 部分。

  4. 选择快照过期旁边的 Enable（启用） 或 Edit（编辑）。

  5. 开启快照过期。

  6. 设置 Max snapshot age（最大快照时长） 和 Min snapshots to keep（最少保留快照数） 值。

  7. 选择 Save（保存）。

要在 catalog 上启用快照过期，请运行 basin catalog snapshot-expiration enable 命令：

启用 catalog 级快照过期：

npx wrangler basin catalog snapshot-expiration enable <BUCKET_NAME> --token <API_TOKEN> --older-than-days 7 --retain-last 10

为特定表启用快照过期：

npx wrangler basin catalog snapshot-expiration enable <BUCKET_NAME> <NAMESPACE> <TABLE> --older-than-days 2 --retain-last 5

禁用快照过期

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

  1. 在 Cloudflare 仪表板中，前往 Basin Catalog 页面。

    前往 Basin Catalog ↗

  2. 选择要禁用快照过期的 catalog。

  3. 前往 Settings（设置） 选项卡，滚动到 Table Maintenance（表维护） 部分。

  4. 选择快照过期旁边的 Edit（编辑）。

  5. 关闭快照过期。

  6. 选择 Save（保存）。

禁用 catalog 级快照过期：

npx wrangler basin catalog snapshot-expiration disable <BUCKET_NAME>

为特定表禁用快照过期：

npx wrangler basin catalog snapshot-expiration disable <BUCKET_NAME> <NAMESPACE> <TABLE>

为 Iceberg 引擎进行身份验证

要将 Iceberg 引擎连接到 Basin Catalog，您必须提供同时 具有 Basin Catalog 权限和 R2 存储权限的 Cloudflare API 令牌。Iceberg 引擎与 Basin Catalog 交互以执行表操作。catalog 还会向引擎提供 SigV4 凭据，这是访问存储在 R2 中的底层数据文件所必需的。

Basin Catalog 支持只读和读写令牌：

  • 只读 操作（例如，列出 namespace、加载表和查询数据）需要具有 Basin Catalog 和 R2 存储读取权限的令牌。
  • 写入 操作（例如，创建或删除表和提交事务）需要具有 Basin Catalog 和 R2 存储读写权限的令牌。

对于仅读取数据的查询引擎和客户端（如 Basin SQL、DuckDB 或 PyIceberg 读取器），使用只读令牌；对于创建表或写入数据的引擎和管道，使用读写令牌。

在仪表板中创建 API 令牌

创建与工作负载权限匹配的 R2 API 令牌：

  • Admin Read & Write（管理员读取和写入） — 适用于读写数据的引擎和管道。包括对 Basin Catalog 和 R2 存储的读写访问。
  • Admin Read only（仅管理员读取） — 适用于仅读取数据的查询引擎和客户端。包括对 Basin Catalog 和 R2 存储的读取访问。

将生成的令牌值提供给 Iceberg 引擎，使其能够管理 catalog 元数据并处理数据操作（对 R2 的读取或写入）。

通过 API 创建 API 令牌

要以编程方式为 Basin Catalog 创建 API 令牌，需要在 Access Policy 中同时指定 Basin Catalog 和 R2 存储权限组。

读写 Access Policy 示例

对于创建表或写入数据的引擎和管道，使用读写权限组：

[
	{
		"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"
			}
		]
	}
]

只读 Access Policy 示例

对于仅读取数据的查询引擎和客户端，使用读取权限组：

[
	{
		"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 为 Basin Catalog 创建 API 令牌（包括所需权限组和使用示例），请参阅通过 API 创建 API 令牌文档。

R2 Local Uploads

Local Uploads 将对象数据写入附近位置，然后异步复制到存储桶。数据可立即查询并保持强一致性。这可以显著改善 Basin Catalog 存储桶所在区域之外的 Apache Iceberg 客户端的写入延迟。

要启用 R2 Local Uploads，可以使用以下 Wrangler 命令：

npx wrangler r2 bucket local-uploads enable <BUCKET_NAME>

限制

  • Basin Catalog 目前不支持非默认管辖区域的 R2 存储桶。

了解更多

快速入门

了解如何在存储桶上启用 Basin Catalog、加载示例数据并运行首次查询。

这篇文档对您有帮助吗？