查询数据

查询由 Basin Catalog 管理的 Apache Iceberg ↗ 表。可以通过 Wrangler 或 HTTP API 发出 Basin SQL 查询。

要使用 Basin SQL 查询数据，需要与目录关联的仓库名称。可以运行 basin catalog get 命令来获取：

npx wrangler basin catalog get <BUCKET_NAME>

yarn wrangler basin catalog get <BUCKET_NAME>

pnpm wrangler basin catalog get <BUCKET_NAME>

也可以在仪表板中找到：前往 R2 object storage（R2 对象存储） 页面，选择存储桶，切换到 Settings（设置） 选项卡，滚动到 Basin Catalog，然后查看 Warehouse name。

首先，安装 npm ↗。然后安装 Wrangler（开发者平台 CLI）。

Wrangler 需要具有访问 Basin Catalog、R2 存储和 Basin SQL 权限的 API 令牌才能执行查询。basin sql query 命令会在 WRANGLER_BASIN_SQL_AUTH_TOKEN 环境变量中查找该令牌。

设置环境：

export WRANGLER_BASIN_SQL_AUTH_TOKEN=YOUR_API_TOKEN

或者创建一个包含以下内容的 .env 文件：

WRANGLER_BASIN_SQL_AUTH_TOKEN=YOUR_API_TOKEN

其中 YOUR_API_TOKEN 是您使用所需权限创建的令牌。有关设置环境变量的更多信息，请参阅 Wrangler 系统环境变量。

要运行 SQL 查询，请执行 basin sql query 命令：

npx wrangler basin sql query <WAREHOUSE> "SELECT * FROM namespace.table_name limit 10;"

yarn wrangler basin sql query <WAREHOUSE> "SELECT * FROM namespace.table_name limit 10;"

pnpm wrangler basin sql query <WAREHOUSE> "SELECT * FROM namespace.table_name limit 10;"

有关支持的 SQL 命令完整列表，请参阅 Basin SQL 参考。

以下是通过 REST 端点使用 Basin SQL 的示例：

curl -X POST \
  "https://api.sql.cloudflarestorage.com/api/v1/accounts/{ACCOUNT_ID}/basin-sql/query/{BUCKET_NAME}" \
  -H "Authorization: Bearer ${WRANGLER_BASIN_SQL_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT * FROM namespace.table_name limit 10;"
  }'

API 要求在 Authorization 请求头中提供具有相应权限的 API 令牌。有关创建令牌的详细信息，请参阅身份验证。

有关支持的 SQL 命令完整列表，请参阅 Basin SQL 参考。

要使用 Basin SQL 查询数据，必须提供具有 Basin SQL、Basin Catalog 和 R2 存储权限的 Cloudflare API 令牌。Basin SQL 需要这些权限来访问目录元数据并读取存储在 R2 中的底层数据文件。

创建具有以下权限的 R2 API 令牌：

• 访问 Basin Catalog（只读）
• 访问 R2 存储（管理员读写）
• 访问 Basin SQL（只读）

通过 Wrangler 查询时，将此令牌值用于 WRANGLER_BASIN_SQL_AUTH_TOKEN 环境变量；通过 REST API 查询时，将其用于 Authorization 请求头。

要以编程方式创建用于 Basin SQL 的 API 令牌，请在 Access Policy 中指定 Basin SQL、Basin 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": "f45430d92e2b4a6cb9f94f2594c141b8",
				"name": "Workers R2 SQL Read"
			},
			{
				"id": "d229766a2f7f4d299f20eaa8c9b1fde9",
				"name": "Workers R2 Data Catalog Write"
			},
			{
				"id": "bf7481a1826f439697cb59a20b22293e",
				"name": "Workers R2 Storage Write"
			}
		]
	}
]

要了解如何通过 API 为 Basin SQL 创建 API 令牌（包括所需权限组和使用示例），请参阅通过 API 创建 API 令牌。