データをクエリする

R2 Data Catalog が管理する Apache Iceberg ↗ テーブルをクエリします。R2 SQL のクエリは Wrangler または HTTP API で実行できます。

ウェアハウス名を取得する

R2 SQL でデータをクエリするには、カタログに紐づくウェアハウス名が必要です。取得するには、r2 bucket catalog get コマンドを実行します。

npx wrangler r2 bucket catalog get <BUCKET_NAME>

ダッシュボードで確認することもできます。R2 object storage ページを開き、バケットを選択し、Settings タブに切り替え、R2 Data Catalog までスクロールして Warehouse name を探します。

Wrangler でクエリする

まず npm ↗ をインストールします。次に Developer Platform CLI の Wrangler をインストールします。

Wrangler がクエリを実行するには、R2 Data Catalog、R2 ストレージ、R2 SQL にアクセスできる権限を持つ API トークンが必要です。r2 sql query コマンドは、WRANGLER_R2_SQL_AUTH_TOKEN 環境変数からトークンを読み取ります。

環境を設定します。

export WRANGLER_R2_SQL_AUTH_TOKEN=YOUR_API_TOKEN

または、次の内容で .env ファイルを作成します。

WRANGLER_R2_SQL_AUTH_TOKEN=YOUR_API_TOKEN

YOUR_API_TOKEN は、必要な権限で作成したトークンです。環境変数の設定方法は Wrangler のシステム環境変数を参照してください。

SQL クエリを実行するには、r2 sql query コマンドを実行します。

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

対応している SQL コマンドの一覧は R2 SQL リファレンスを参照してください。

API でクエリする

REST エンドポイントで R2 SQL を使う例は次のとおりです。

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

API では、Authorization ヘッダーに適切な権限を持つ API トークンが必要です。トークンの作成方法は認証を参照してください。

対応している SQL コマンドの一覧は R2 SQL リファレンスを参照してください。

認証

R2 SQL でデータをクエリするには、R2 SQL、R2 Data Catalog、R2 ストレージの権限を持つ Cloudflare API トークンが必要です。R2 SQL は、カタログのメタデータにアクセスし、R2 に保存されている実データファイルを読むために、これらの権限を使います。

ダッシュボードで API トークンを作成する

次の権限を持つ R2 API トークンを作成します。

R2 Data Catalog へのアクセス（読み取り専用）
R2 ストレージへのアクセス（管理者の読み取り / 書き込み）
R2 SQL へのアクセス（読み取り専用）

Wrangler でクエリするときは、このトークン値を WRANGLER_R2_SQL_AUTH_TOKEN 環境変数に使います。REST API を使うときは Authorization ヘッダーに使います。

API で API トークンを作成する

R2 SQL 向けの API トークンをプログラムから作成するには、Access Policy に R2 SQL、R2 Data 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": "f45430d92e2b4a6cb9f94f2594c141b8",
				"name": "Workers R2 SQL Read"
			},
			{
				"id": "d229766a2f7f4d299f20eaa8c9b1fde9",
				"name": "Workers R2 Data Catalog Write"
			},
			{
				"id": "bf7481a1826f439697cb59a20b22293e",
				"name": "Workers R2 Storage Write"
			}
		]
	}
]

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