R2 SQL Query

Query Apache Iceberg tables managed by R2 Data Catalog using the R2 SQL HTTP API. There is no Workers binding — this experiment uses account secrets and fetch. Without credentials it returns sample rows with mode: "demo".

FeaturesCopy Anchor Link

• SELECT / SHOW only (mutating SQL rejected)
• Live queries against R2 SQL, or demo rows when secrets are missing
• Per-request warehouse override

API ReferenceCopy Anchor Link

GET /queryCopy Anchor Link

Run a read-only SQL query.

q / query string (required)

SQL statement (SELECT or SHOW, max 4000 characters).

warehouse string (optional)

Override the warehouse / bucket name (defaults to WAREHOUSE var).

Example RequestCopy Anchor Link

curl "https://your-worker.workers.dev/query?q=SELECT%20*%20FROM%20default.events%20LIMIT%2010"

Success Response (demo)Copy Anchor Link

{
  "mode": "demo",
  "query": "SELECT * FROM default.events LIMIT 10",
  "warehouse": "demo-warehouse",
  "rows": [],
  "note": "Configure CLOUDFLARE_ACCOUNT_ID and R2_SQL_AUTH_TOKEN for live R2 SQL queries"
}

Error CodesCopy Anchor Link

• 400 - Missing or oversized query (INVALID_QUERY)
• 400 - Non-read-only SQL (FORBIDDEN_SQL)
• 502 - Upstream R2 SQL failure (QUERY_ERROR)

POST /queryCopy Anchor Link

Same behavior with a JSON body:

{
  "query": "SELECT * FROM default.ecommerce LIMIT 10",
  "warehouse": "optional-override"
}

Use CasesCopy Anchor Link

• Explore Iceberg tables written by Cloudflare Pipelines
• Prototype analytics over R2 Data Catalog without a separate warehouse
• Pair with Event Pipeline for ingest → query demos
• Validate SELECT/SHOW guardrails for public query APIs

LimitationsCopy Anchor Link

• Requires account ID + R2 SQL API token for live queries
• Only SELECT and SHOW are allowed
• No Workers binding — uses the HTTP API
• Demo mode returns sample rows, not real catalog data

DeploymentCopy Anchor Link

npx wrangler secret put CLOUDFLARE_ACCOUNT_ID
npx wrangler secret put R2_SQL_AUTH_TOKEN

curl "https://your-worker.workers.dev/query?q=SHOW%20TABLES"

Local DevelopmentCopy Anchor Link

cd apps/experiments/r2-sql-query
npm install
npm run dev

curl "http://localhost:8787/query?q=SELECT%201"

Without secrets, responses use mode: "demo".

ConfigurationCopy Anchor Link

• Secrets CLOUDFLARE_ACCOUNT_ID, R2_SQL_AUTH_TOKEN
• Var WAREHOUSE (or R2_BUCKET_NAME) — default demo-warehouse

Cloudflare Features UsedCopy Anchor Link

• Workers - Edge compute runtime
• R2 SQL - Serverless SQL over Iceberg tables
• R2 Data Catalog - Managed Apache Iceberg catalog