AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

basin

Build and troubleshoot Cloudflare Basin analytics workflows with Basin Pipelines, Basin Catalog, and Basin SQL. Use for streaming data into R2 Iceberg tables, managing catalogs, or querying those tables; also use for requests using the former Data Platform, Pipelines, R2 Data Catalog, or R2 SQL names.

Original source
cloudflare
License
Apache-2.0
Pinned revision
e44f580f9c4fa3bf268e284ae7706c7954ba31fd

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read cloudflare--basin at revision e44f580f9c4fa3bf268e284ae7706c7954ba31fd, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 17

references/sql/README.md

Basin SQL

Serverless, distributed, read-only query engine (Apache DataFusion) for Apache Iceberg tables in Basin Catalog.

Documentation

For full function lists, data types, and pricing, retrieve the live docs — use the Cloudflare MCP docs tool if available, otherwise webfetch.

| Topic | URL | |-------|-----| | Overview / get started | https://developers.cloudflare.com/basin-sql/get-started/index.md | | Query data | https://developers.cloudflare.com/basin-sql/query-data/index.md | | SQL reference | https://developers.cloudflare.com/basin-sql/sql-reference/index.md | | Aggregate functions | https://developers.cloudflare.com/basin-sql/sql-reference/aggregate-functions/index.md | | Scalar functions | https://developers.cloudflare.com/basin-sql/sql-reference/scalar-functions/index.md | | Complex types | https://developers.cloudflare.com/basin-sql/sql-reference/complex-types/index.md | | Limitations & best practices | https://developers.cloudflare.com/basin-sql/reference/limitations-best-practices/index.md | | Wrangler commands | https://developers.cloudflare.com/basin-sql/reference/wrangler-commands/index.md | | Pricing | https://developers.cloudflare.com/basin-sql/platform/pricing/index.md |

Connection Values

| Value | Format | |-------|--------| | REST endpoint | https://api.sql.cloudflarestorage.com/api/v1/accounts/{ACCOUNT_ID}/basin-sql/query/{BUCKET} | | Wrangler | npx wrangler basin sql query "{WAREHOUSE}" "<SQL>" with WRANGLER_BASIN_SQL_AUTH_TOKEN set | | Warehouse | {ACCOUNT_ID}_{BUCKET} |

The REST endpoint is api.sql.cloudflarestorage.com — not the account API host. The legacy /r2-sql/query/ path may still work, but use /basin-sql/query/ for new integrations.

Quick Start

npx wrangler basin catalog enable my-bucket           # 1. enable catalog
export WRANGLER_BASIN_SQL_AUTH_TOKEN=<r2-token>              # 2. auth (Admin R&W + Basin SQL Read)
npx wrangler basin sql query "$ACCOUNT_ID"_my-bucket \
  "SELECT * FROM default.my_table LIMIT 10"                # 3. query

SQL Surface

Basin SQL is read-only and supports a broad analytical SQL surface (SELECT, JOINs, subqueries, CTEs, set operations, window functions, and aggregate/scalar/JSON functions over complex types). For the authoritative, current list of supported syntax, functions, and limitations, see the SQL reference and limitations docs linked above. api.md has query templates.

When to Use

Use for: SQL analytics over Iceberg (logs, BI, fraud, ad-hoc), multi-cloud queries without egress, dashboards (query from a Worker via HTTP).

Don't use for: writes (use PySpark/PyIceberg) or real-time OLTP (<100 ms).

No Workers Binding

There is no env.R2_SQL binding. Query from a Worker via fetch() to the REST endpoint with the token as a secret (see patterns.md).

Reading Order

  1. configuration.md — enable catalog, tokens, env setup
  2. api.md — SQL syntax templates, JOIN/window examples, response format, data types
  3. patterns.md — CLI/REST/Worker queries, use cases, pagination, performance
  4. gotchas.md — what works vs. not, performance, troubleshooting

See Also