Skip to content

Commit 5a67919

Browse files
jonesphillipjonesphillip
committed
Small formatting + other changes
1 parent 8318059 commit 5a67919

File tree

11 files changed

+150
-156
lines changed

11 files changed

+150
-156
lines changed

‎src/content/docs/r2-sql/index.mdx‎

Lines changed: 22 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,37 @@
11
---
2-
pcx_content_type: navigation
32
title: R2 SQL
3+
4+
pcx_content_type: overview
45
sidebar:
5-
order: 7
6+
order: 1
7+
badge:
8+
text: Beta
69
head:
710
- tag: title
811
content: R2 SQL
912
description: A distributed SQL engine for R2 Data Catalog
1013
---
1114

12-
## Query Apache Iceberg tables in R2 Data Catalog Using R2 SQL
13-
15+
import {
16+
CardGrid,
17+
Description,
18+
Feature,
19+
LinkTitleCard,
20+
Plan,
21+
RelatedProduct,
22+
} from "~/components";
1423

1524
:::note
16-
R2 SQL is in public beta, and any developer with an R2 subscription can start using it. Currently, outside of standard R2 storage and operations, you will not be billed for your use of R2 SQL. We will update [the pricing page](/r2-sql/platform/pricing) and provide at least 30 days notice before enabling billing.
25+
R2 SQL is in **open beta**, and any developer with an [R2 subscription](/r2/pricing/) can start using it. Currently, outside of standard R2 storage and operations, you will not be billed for your use of R2 SQL. We will update [the pricing page](/r2-sql/platform/pricing) and provide at least 30 days notice before enabling billing.
1726
:::
1827

19-
R2 SQL is Cloudflare's serverless, distributed, analytics query engine for querying [Apache Iceberg](https://iceberg.apache.org/) tables stored in [R2 data catalog](/r2/data-catalog/). R2 SQL is designed to efficiently query large amounts of data by automatically utilizing file pruning, Cloudflare's distributed compute, and R2 object storage.
28+
<Description>
29+
30+
Query Apache Iceberg tables managed by R2 Data Catalog using SQL.
31+
32+
</Description>
33+
34+
R2 SQL is Cloudflare's serverless, distributed, analytics query engine for querying [Apache Iceberg](https://iceberg.apache.org/) tables stored in [R2 Data Catalog](/r2/data-catalog/). R2 SQL is designed to efficiently query large amounts of data by automatically utilizing file pruning, Cloudflare's distributed compute, and R2 object storage.
2035

2136
```sh
2237
❯ npx wrangler r2 sql query "3373912de3f5202317188ae01300bd6_data-catalog" \
@@ -52,4 +67,4 @@ Read 11.3 kB across 4 files from R2
5267
On average, 3.36 kB / s
5368
```
5469

55-
Create an end to end data pipeline and query your first table in R2 SQL by following [this step by step guide](/r2-sql/tutorials/end-to-end-pipeline/), learn how to create a data pipeline that takes a stream of events and automatically creates an Apache Iceberg table, making them accessible with R2 SQL.
70+
Create an end-to-end data pipeline by following [this step by step guide](/r2-sql/get-started/), which shows you how to stream events into an Apache Iceberg table and query it with R2 SQL.

‎src/content/docs/r2-sql/platform/index.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
title: Platform
33
pcx_content_type: navigation
44
sidebar:
5+
order: 7
56
group:
67
hideIndex: true
78
---

‎src/content/docs/r2-sql/platform/pricing.mdx‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,10 @@ sidebar:
66
head:
77
- tag: title
88
content: R2 SQL - Pricing
9-
109
---
1110

12-
During the first phase of the R2 SQL open beta, you will not be billed for R2 SQL usage. You will only be billed for R2 usage.
11+
R2 SQL is in open beta and available to any developer with an [R2 subscription](/r2/pricing/).
12+
13+
We are not currently billing for R2 SQL during open beta. However, you will be billed for standard [R2 storage and operations](/r2/pricing/) for data accessed by queries.
1314

14-
We plan to price based on the volume of data queried by R2 SQL. We will provide at least 30 days notice and exact pricing before charging.
15+
We plan to bill based on the volume of data queried by R2 SQL. We'll provide at least 30 days notice before we make any changes or start charging for R2 SQL usage.

‎src/content/docs/r2-sql/platform/wrangler-commands.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,4 +11,4 @@ import { Render, Type, MetaInfo } from "~/components";
1111

1212
## Global commands
1313

14-
<Render file="wrangler-commands/global-flags" product="workers" />
14+
<Render file="wrangler-commands/global-flags" product="workers" />

‎src/content/docs/r2-sql/query-data.mdx‎

Lines changed: 72 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,88 @@
11
---
2-
title: Query data in R2 Data Catalog
2+
title: Query data
33
pcx_content_type: configuration
44
description: Understand how to query data with R2 SQL
55
sidebar:
66
order: 3
77
---
8-
import {
9-
Render,
10-
LinkCard,
11-
Tabs,
12-
TabItem,
13-
Steps
14-
} from "~/components";
158

16-
:::note
17-
R2 SQL is currently in open beta.
18-
:::
9+
import { Render, LinkCard, Tabs, TabItem, Steps } from "~/components";
1910

20-
Learn how to:
21-
- Create an API key with the necessary permissions.
22-
- Query data with R2 SQL.
11+
Query [Apache Iceberg](https://iceberg.apache.org/) tables managed by [R2 Data Catalog](/r2/data-catalog/). R2 SQL queries can be made via [Wrangler](/workers/wrangler/) or HTTP API.
2312

24-
R2 SQL can currently be accessed via Wrangler commands or a REST API.
13+
## Get your warehouse name
2514

26-
## Create an API key with the right permissions
15+
To query data with R2 SQL, you'll need your warehouse name associated with your [catalog](/r2/data-catalog/manage-catalogs/). To retrieve it, you can run the [`r2 bucket catalog get` command](/workers/wrangler/commands/#r2-bucket-catalog-get):
2716

28-
To query Apache Iceberg tables in R2 Data Catalog, you must provide a Cloudflare API token with R2 SQL, R2 Data Catalog, and R2 storage permissions.
17+
```bash
18+
npx wrangler r2 bucket catalog get <BUCKET_NAME>
19+
```
20+
21+
Alternatively, you can find it in the dashboard by going to the **R2 object storage** page, selecting the bucket, switching to the **Settings** tab, scrolling to **R2 Data Catalog**, and finding **Warehouse name**.
22+
23+
## Query via Wrangler
24+
25+
To begin, install [`npm`](https://docs.npmjs.com/getting-started). Then [install Wrangler, the Developer Platform CLI](/workers/wrangler/install-and-update/).
26+
27+
Wrangler needs an API token with permissions to access R2 Data Catalog, R2 storage, and R2 SQL to execute queries. The `r2 sql query` command looks for the token in the `WRANGLER_R2_SQL_AUTH_TOKEN` environment variable.
28+
29+
Set up your environment:
30+
31+
```bash
32+
export WRANGLER_R2_SQL_AUTH_TOKEN=YOUR_API_TOKEN
33+
```
34+
35+
Or create a `.env` file with:
36+
37+
```
38+
WRANGLER_R2_SQL_AUTH_TOKEN=YOUR_API_TOKEN
39+
```
40+
41+
Where `YOUR_API_TOKEN` is the token you created with the [required permissions](#authentication). For more information on setting environment variables, refer to [Wrangler system environment variables](/workers/wrangler/system-environment-variables/).
42+
43+
To run a SQL query, run the [`r2 sql query` command](/workers/wrangler/commands/#r2-sql-query):
44+
45+
```bash
46+
npx wrangler r2 sql query <WAREHOUSE> "SELECT * FROM namespace.table_name limit 10;"
47+
```
48+
49+
For a full list of supported sql commands, refer to the [R2 SQL reference page](/r2-sql/reference/sql-reference).
50+
51+
## Query via API
52+
53+
Below is an example of using R2 SQL via the REST endpoint:
54+
55+
```bash
56+
curl -X POST \
57+
"https://api.sql.cloudflarestorage.com/api/v1/accounts/{ACCOUNT_ID}/r2-sql/query/{BUCKET_NAME}" \
58+
-H "Authorization: Bearer ${WRANGLER_R2_SQL_AUTH_TOKEN}" \
59+
-H "Content-Type: application/json" \
60+
-d '{
61+
"query": "SELECT * FROM namespace.table_name limit 10;"
62+
}'
63+
```
64+
65+
The API requires an API token with the appropriate permissions in the Authorization header. Refer to [Authentication](#authentication) for details on creating a token.
66+
67+
For a full list of supported sql commands, refer to the [R2 SQL reference page](/r2-sql/reference/sql-reference).
2968

30-
<Tabs syncKey='CLIvDash'>
31-
<TabItem label='Dashboard'>
32-
Create an [API token](https://dash.cloudflare.com/profile/api-tokens) with:
69+
## Authentication
3370

34-
- Access to R2 Data Catalog (**minimum**: edit)
35-
- Access to R2 storage (**minimum**: read-only)
36-
- Access to R2 SQL (**minimum**: read-only)
71+
To query data with R2 SQL, you must provide a Cloudflare API token with R2 SQL, R2 Data Catalog, and R2 storage permissions. R2 SQL requires these permissions to access catalog metadata and read the underlying data files stored in R2.
3772

38-
Wrangler now supports the environment variable `WRANGLER_R2_SQL_AUTH_TOKEN` which you can use to `export` your token.
73+
### Create API token in the dashboard
3974

40-
</TabItem>
41-
<TabItem label='Via API'>
42-
To create an API token programmatically for use with R2 SQL, you will need to specify R2 SQL, R2 Data Catalog, and R2 storage permission groups in your [Access Policy](/r2/api/tokens/#access-policy).
75+
Create an [R2 API token](/r2/api/tokens/#permissions) with **Admin Read only** permission. This permission includes:
76+
77+
- Access to R2 Data Catalog (read-only)
78+
- Access to R2 storage (read-only)
79+
- Access to R2 SQL (read-only)
80+
81+
Use this token value for the `WRANGLER_R2_SQL_AUTH_TOKEN` environment variable when querying with Wrangler, or in the Authorization header when using the REST API.
82+
83+
### Create API token via API
84+
85+
To create an API token programmatically for use with R2 SQL, you'll need to specify R2 SQL, R2 Data Catalog, and R2 storage permission groups in your [Access Policy](/r2/api/tokens/#access-policy).
4386

4487
#### Example Access Policy
4588

@@ -63,68 +106,14 @@ To create an API token programmatically for use with R2 SQL, you will need to sp
63106
},
64107
{
65108
"id": "f45430d92e2b4a6cb9f94f2594c141b8",
66-
"name": "Workers R2 SQL Read"
109+
"name": "Workers R2 SQL Read"
67110
}
68111
]
69112
}
70113
]
71114
```
72-
</TabItem>
73-
</Tabs>
74-
75-
## Query data via Wrangler
76-
77-
Export your R2 API token as an environment variable:
78-
79-
```bash
80-
export WRANGLER_R2_SQL_AUTH_TOKEN=your_token_here
81-
```
82-
83-
If this is your first time using Wrangler, make sure to login.
84-
85-
```bash
86-
npx wrangler login
87-
```
88-
89-
:::note
90-
You will want to copy the `Warehouse` of the R2 Data Catalog:
91-
:::
92-
93-
```sh
94-
❯ npx wrangler r2 bucket catalog get [BUCKET_NAME]
95-
96-
⛅️ wrangler 4.38.0
97-
────────────────────────────────────────────────────────────────────────────
98-
▲ [WARNING] 🚧 `wrangler r2 bucket catalog get` is an open-beta command. Please report any issues to https://github.com/cloudflare/workers-sdk/issues/new/choose
99-
100-
101-
Catalog URI: https://catalog.cloudflarestorage.com/[ACCOUNT_ID]/[BUCKET_NAME]
102-
Warehouse: [ACCOUNT_ID]_[BUCKET_NAME]
103-
Status: active
104-
```
105115

106-
To query R2 SQL with Wrangler, simply run:
107-
108-
```sh
109-
npx wrangler r2 sql query "YOUR_WAREHOUSE" "SELECT * FROM namespace.table_name limit 10;"
110-
```
111-
112-
For a full list of supported sql commands, refer to the [R2 SQL reference page](/r2-sql/reference/sql-reference).
113-
114-
115-
## REST API
116-
117-
Below is an example of using R2 SQL via the REST endpoint:
118-
119-
```bash
120-
curl -X POST \
121-
"https://api.sql.cloudflarestorage.com/api/v1/accounts/{ACCOUNT_ID}/r2-sql/query/{BUCKET_NAME}" \
122-
-H "Authorization: Bearer ${WRANGLER_R2_SQL_AUTH_TOKEN}" \
123-
-H "Content-Type: application/json" \
124-
-d '{
125-
"query": "SELECT * FROM namespace.table_name limit 10;"
126-
}'
127-
```
116+
To learn more about how to create API tokens for R2 SQL using the API, including required permission groups and usage examples, refer to the [Create API tokens via API documentation](/r2/api/tokens/#create-api-tokens-via-api).
128117

129118
## Additional resources
130119

‎src/content/docs/r2-sql/reference/index.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
title: Reference
33
pcx_content_type: navigation
44
sidebar:
5+
order: 8
56
group:
67
hideIndex: true
78
---

‎src/content/docs/r2-sql/reference/limitations-best-practices.mdx‎

Lines changed: 14 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,12 @@
11
---
2-
title: Limitations and Best Practices
2+
title: Limitations and best practices
33
pcx_content_type: concept
44
tags:
55
- SQL
66
sidebar:
77
order: 5
8-
98
---
109

11-
## Overview
12-
1310
:::note
1411
R2 SQL is in open beta. Limitations and best practices will change over time.
1512
:::
@@ -18,18 +15,18 @@ R2 SQL is designed for querying **partitioned** Apache Iceberg tables in your R2
1815

1916
## Quick Reference
2017

21-
| Feature | Supported | Notes |
22-
| :---- | :---- | :---- |
23-
| Basic SELECT | Yes | Columns, \* |
24-
| Aggregation functions | No | No COUNT, AVG, etc. |
25-
| Single table FROM | Yes | Note, aliasing not supported |
26-
| WHERE clause | Yes | Filters, comparisons, equality, etc |
27-
| JOINs | No | No table joins |
28-
| Array filtering | No | No array type support |
29-
| JSON filtering | No | No nested object queries |
30-
| Simple LIMIT | Yes | 1-10,000 range, no pagination support |
31-
| ORDER BY | Yes | Any columns of the partition key only|
32-
| GROUP BY | No | Not supported |
18+
| Feature | Supported | Notes |
19+
| :-------------------- | :-------- | :------------------------------------ |
20+
| Basic SELECT | Yes | Columns, \* |
21+
| Aggregation functions | No | No COUNT, AVG, etc. |
22+
| Single table FROM | Yes | Note, aliasing not supported |
23+
| WHERE clause | Yes | Filters, comparisons, equality, etc |
24+
| JOINs | No | No table joins |
25+
| Array filtering | No | No array type support |
26+
| JSON filtering | No | No nested object queries |
27+
| Simple LIMIT | Yes | 1-10,000 range, no pagination support |
28+
| ORDER BY | Yes | Any columns of the partition key only |
29+
| GROUP BY | No | Not supported |
3330

3431
## Supported SQL Clauses
3532

@@ -51,7 +48,6 @@ R2 SQL supports a limited set of SQL clauses: `SELECT`, `FROM`, `WHERE`, `ORDER
5148
- **No synthetic data**: Cannot create synthetic columns like `SELECT 1 AS what, "hello" AS greeting`
5249
- **No field aliasing**: `SELECT field AS another_name`
5350

54-
5551
### Examples
5652

5753
```sql
@@ -204,4 +200,4 @@ The following SQL clauses are **not supported**:
204200
2. Use specific column selection instead of `SELECT *` when possible for better performance.
205201
3. Structure your data to avoid nested JSON objects if you need to filter on those fields.
206202

207-
---
203+
---

‎src/content/docs/r2-sql/reference/sql-reference.mdx‎ renamed to ‎src/content/docs/r2-sql/sql-reference.mdx‎

Lines changed: 11 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,13 @@
11
---
2-
title: SQL Reference
2+
title: SQL reference
33
pcx_content_type: concept
4+
description: Comprehensive reference for SQL syntax and data types supported in R2 SQL.
45
tags:
56
- SQL
67
sidebar:
7-
order: 5
8+
order: 4
89
---
910

10-
# R2 SQL Language Reference
11-
12-
## Overview
13-
14-
1511
:::note
1612
R2 SQL is in public beta. Supported SQL grammar may change over time.
1713
:::
@@ -64,7 +60,6 @@ SELECT timestamp, user_id, response_code FROM table_name
6460
SELECT * FROM table_name
6561
```
6662

67-
6863
---
6964

7065
## WHERE Clause
@@ -215,14 +210,14 @@ LIMIT 500
215210

216211
### Supported Types
217212

218-
| Type | Description | Example Values |
219-
| :---- | :---- | :---- |
220-
| `integer` | Whole numbers | `1`, `42`, `-10`, `0` |
221-
| `float` | Decimal numbers | `1.5`, `3.14`, `-2.7`, `0.0` |
222-
| `string` | Text values | `'hello'`, `'GET'`, `'2024-01-01'` |
223-
| `boolean` | Boolean values | `true`, `false` |
224-
| `timestamp` | RFC3339 | `'2025-09-24T01:00:00Z'` |
225-
| `date` | 'YYYY-MM-DD' | `'2025-09-24'` |
213+
| Type | Description | Example Values |
214+
| :---------- | :-------------- | :--------------------------------- |
215+
| `integer` | Whole numbers | `1`, `42`, `-10`, `0` |
216+
| `float` | Decimal numbers | `1.5`, `3.14`, `-2.7`, `0.0` |
217+
| `string` | Text values | `'hello'`, `'GET'`, `'2024-01-01'` |
218+
| `boolean` | Boolean values | `true`, `false` |
219+
| `timestamp` | RFC3339 | `'2025-09-24T01:00:00Z'` |
220+
| `date` | 'YYYY-MM-DD' | `'2025-09-24'` |
226221

227222
### Type Usage in Conditions
228223

@@ -256,4 +251,3 @@ SELECT * FROM table_name WHERE (status = 404 OR status = 500) AND method = 'GET'
256251
```
257252

258253
---
259-

0 commit comments

Comments
 (0)