Cloudflare R2 SQL 实战指南用 Wrangler 与 HTTP API 查询 Apache Iceberg 表【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skillsR2 SQL 是 Cloudflare 推出的无服务器分布式分析查询引擎它让你直接对存储在 R2 Data Catalog 中的 Apache Iceberg 表执行标准 SQL无需管理任何集群或基础设施。本文以本仓库 skills/.curated/cloudflare-deploy/references/r2-sql 系列文档为主体完整覆盖从启用 Catalog、创建 API Token 到编写聚合查询、规避 SQL 限制的端到端实战流程。读完本文你将掌握如何用 Wrangler CLI 与 HTTP API 完成日志分析、欺诈检测、BI 报表等典型分析任务并理解其多层级裁剪与并行执行的底层原理。R2 SQL 是什么R2 SQL 是 Cloudflare 面向 R2 Data Catalog 中 Apache Iceberg 表的无服务器分布式分析查询引擎核心特性包括Serverless无服务器无需管理集群也没有需要运维的基础设施Distributed分布式利用 Cloudflare 全球网络并行执行查询SQL 接口使用熟悉的 SQL 语法编写分析查询零出口费用Zero egress fees从任何云/区域查询数据均不产生数据传输成本Open beta开放测试测试期间免费仅需支付标准 R2 存储费用。什么是 Apache IcebergIceberg 是面向对象存储中大规模分析数据集的开源表格式也是 R2 Data Catalog 的基础ACID 事务安全的并发读写元数据优化无需全表扫描即可快速查询Schema 演化无需重写即可增删改列分区Partitioning组织数据以实现高效的裁剪pruning。何时该用 / 不该用 R2 SQL适合使用 R2 SQL 的场景日志分析用 WHERE 过滤与聚合查询应用/系统日志BI 看板从大规模分析数据集生成报表欺诈检测用 GROUP BY / HAVING 分析交易模式多云分析跨云查询数据且无出口费用临时探索通过 Wrangler CLI 对 Iceberg 表直接跑 SQL。不建议使用 R2 SQL 的场景Workers/Pages 运行时R2 SQL 没有 Workers binding需从外部系统调用 HTTP API详见下文“关键限制”实时查询100ms它面向分析型批量查询而非 OLTP复杂 JOIN/CTE当前 SQL 功能集有限不支持 JOIN、子查询、CTE小数据集1GB搭建成本不值得。决策树如何查询 R2 数据Do you need to query structured data in R2? ├─ YES, data is in Iceberg tables │ ├─ Need SQL interface? → Use R2 SQL (this reference) │ ├─ Need Python API? → See r2-data-catalog reference (PyIceberg) │ └─ Need other engine? → See r2-data-catalog reference (Spark, Trino, etc.) │ ├─ YES, but not in Iceberg format │ ├─ Streaming data? → Use Pipelines to write to Data Catalog, then R2 SQL │ └─ Static files? → Use PyIceberg to create Iceberg tables, then R2 SQL │ └─ NO, just need object storage → Use R2 reference (not R2 SQL)若数据尚未组织成 Iceberg 表可以先通过 Pipelines 将流式数据写入 Data Catalog或通过 PyIcebergr2-data-catalog 参考 创建 Iceberg 表之后再用 R2 SQL 查询。架构原理从查询规划到并行执行查询规划器Query Planner自上而下的元数据侦查 多层裁剪支持分区级partition-level、列级column-level与行组级row-group裁剪跳过不必要的数据流式管道执行在规划完成前就已启动减少首结果延迟LIMIT 提前终止结果集一旦完整即停止计算。查询执行Query ExecutionCoordinator 分发协调器将工作分发给 Cloudflare 网络上的 workers 并行执行Apache DataFusionworker 使用开源 DataFusion 引擎做并行查询Parquet 列裁剪只读取查询所需的列R2 范围读取ranged reads按需读取提升 IO 效率。聚合策略Aggregation StrategiesScatter-gather用于简单聚合SUM、COUNT、AVGShuffling对聚合结果做 ORDER BY / HAVING 时通过哈希分区重组数据。快速开始完成端到端查询只需四步# 1. 在 bucket 上启用 R2 Data Catalog npx wrangler r2 bucket catalog enable my-bucket # 2. 创建 API tokenAdmin Read Write # Dashboard: R2 → Manage API tokens → Create API token # 3. 设置环境变量 export WRANGLER_R2_SQL_AUTH_TOKENyour-token # 4. 运行查询 npx wrangler r2 sql query my-bucket SELECT * FROM default.my_table LIMIT 10配置指南完整配置细节见 configuration.md。前置条件已启用 Data Catalog 的 R2 bucket具备 R2 权限的 API token已安装 Wrangler CLI用于 CLI 查询。启用 R2 Data CatalogR2 SQL 查询的是 R2 Data Catalog 中的 Apache Iceberg 表必须先在 bucket 上启用 Catalog。通过 Wrangler CLInpx wrangler r2 bucket catalog enable bucket-name输出包含两项关键信息Warehouse name通常与 bucket 名一致Catalog URIREST 目录操作的端点。示例输出Catalog enabled successfully Warehouse: my-bucket Catalog URI: https://abc123.r2.cloudflarestorage.com/iceberg/my-bucket通过 Dashboard进入R2 Object Storage→ 选择 bucket点击Settings标签页滚动到R2 Data Catalog区域点击Enable记下Catalog URI与Warehouse名称。注意启用 Catalog 会在 bucket 中创建元数据目录但不会修改已有对象。创建 API Token所需权限R2 Admin Read Write已包含 R2 SQL Read 权限。Dashboard 操作路径R2 Object Storage →Manage API tokens右上角→Create API token→ 选择Admin Read Write权限 → 创建后立即复制 token 值仅展示一次。权限范围对照权限授予的访问能力R2 Admin Read WriteR2 存储操作 R2 SQL 查询 Data Catalog 操作R2 SQL Read仅 SQL 查询无存储写入注意R2 SQL Read 权限目前还无法通过 Dashboard 创建请使用 Admin Read Write。配置环境变量Wrangler CLI 方式二选一export WRANGLER_R2_SQL_AUTH_TOKENyour-token或创建.env文件Wrangler 运行命令时会自动加载WRANGLER_R2_SQL_AUTH_TOKENyour-tokenHTTP API 方式非 Wrangler 的程序化访问将 token 放入 Authorization 头curl -X POST https://api.cloudflare.com/client/v4/accounts/{account_id}/r2/sql/query \ -H Authorization: Bearer your-token \ -H Content-Type: application/json \ -d { warehouse: my-bucket, query: SELECT * FROM default.my_table LIMIT 10 }注HTTP API 端点 URL 可能变化以 patterns.md 的 HTTP API Query 小节 为准。验证配置用系统表system tables测试连接# 列出命名空间 npx wrangler r2 sql query my-bucket SHOW DATABASES # 列出命名空间中的表 npx wrangler r2 sql query my-bucket SHOW TABLES IN default成功时返回 JSON 数组结果。配置故障排查报错原因解决方案Token authentication failedtoken 无效或缺失确认设置了WRANGLER_R2_SQL_AUTH_TOKEN检查 token 是否具有 Admin Read Write 权限过期则重新创建Catalog not enabled on bucket未启用 Data Catalog运行npx wrangler r2 bucket catalog enable bucket-name或在 Dashboard 中启用Permission deniedtoken 权限不足确认 token 具备Admin Read Write权限或创建正确权限的新 tokenSQL 语法与 API 参考完整语法与类型说明见 api.md。语法骨架SELECT column_list | aggregation_function FROM [namespace.]table_name WHERE conditions [GROUP BY column_list] [HAVING conditions] [ORDER BY column | aggregation_function [DESC | ASC]] [LIMIT number]Schema 发现SHOW DATABASES; -- 列出命名空间 SHOW NAMESPACES; -- SHOW DATABASES 的别名 SHOW SCHEMAS; -- SHOW DATABASES 的别名 SHOW TABLES IN namespace; -- 列出命名空间中的表 DESCRIBE namespace.table; -- 显示表 schema 与分区键SELECT 子句-- 全部列 SELECT * FROM logs.http_requests; -- 指定列 SELECT user_id, timestamp, status FROM logs.http_requests;限制不支持列别名、表达式与嵌套列访问。WHERE 子句操作符操作符示例,!,,,,status 200LIKEuser_agent LIKE %Chrome%BETWEENtimestamp BETWEEN 2025-01-01T00:00:00Z AND 2025-01-31T23:59:59ZIS NULL,IS NOT NULLemail IS NOT NULLAND,ORstatus 200 AND method GET用括号控制优先级例如(status 404 OR status 500) AND method POST。聚合函数函数说明COUNT(*)统计全部行COUNT(column)统计非空值COUNT(DISTINCT column)统计唯一值SUM(column),AVG(column)数值聚合MIN(column),MAX(column)最小/最大值-- GROUP BY 搭配多聚合 SELECT region, COUNT(*), SUM(amount), AVG(amount) FROM sales.transactions WHERE sale_date 2024-01-01 GROUP BY region;HAVING 子句在 GROUP BY 之后过滤聚合结果SELECT category, SUM(amount) FROM sales.transactions GROUP BY category HAVING SUM(amount) 10000;ORDER BY 子句支持两类排序目标分区键列始终支持聚合函数通过 shuffle 策略支持。-- 按分区键排序 SELECT * FROM logs.requests ORDER BY timestamp DESC LIMIT 100; -- 按聚合排序须重复书写函数不支持别名 SELECT region, SUM(amount) FROM sales.transactions GROUP BY region ORDER BY SUM(amount) DESC;限制不能按非分区列排序详见 gotchas.md 的 ORDER BY 限制。LIMIT 子句设置值最小1最大10,000默认500务必显式使用 LIMIT以启用提前终止优化。数据类型与字面量类型SQL 字面量示例integer不带引号的数字42,-10float十进制数3.14,-0.5string单引号hello,GETboolean关键字true,falsetimestampRFC3339 字符串2025-01-01T00:00:00ZdateISO 8601 日期2025-01-01类型安全要点字符串用单引号时间戳必须为 RFC3339 且包含时区日期用 ISO 8601YYYY-MM-DD不存在隐式类型转换。-- 正确写法 WHERE status 200 AND method GET AND timestamp 2025-01-01T00:00:00Z -- 错误写法 WHERE status 200 -- 字符串替代了整数 WHERE timestamp 2025-01-01 -- 缺少时间/时区 WHERE method GET -- 字符串未加引号查询结果格式返回 JSON 对象数组[ {user_id: user_123, timestamp: 2025-01-15T10:30:00Z, status: 200}, {user_id: user_456, timestamp: 2025-01-15T10:31:00Z, status: 404} ]实战模式CLI、HTTP API 与生态集成Wrangler CLI 查询# 基础查询 npx wrangler r2 sql query my-bucket SELECT * FROM default.logs LIMIT 10 # 多行查询 npx wrangler r2 sql query my-bucket SELECT status, COUNT(*), AVG(response_time) FROM logs.http_requests WHERE timestamp 2025-01-01T00:00:00Z GROUP BY status ORDER BY COUNT(*) DESC LIMIT 100 # 使用环境变量传递 warehouse export R2_SQL_WAREHOUSEmy-bucket npx wrangler r2 sql query $R2_SQL_WAREHOUSE SELECT * FROM default.logsHTTP API 查询面向外部系统的程序化访问注意不能从 Workers 内调用curl -X POST https://api.cloudflare.com/client/v4/accounts/{account_id}/r2/sql/query \ -H Authorization: Bearer your-token \ -H Content-Type: application/json \ -d { warehouse: my-bucket, query: SELECT * FROM default.my_table WHERE status 200 LIMIT 100 }响应示例{ success: true, result: [{user_id: user_123, timestamp: 2025-01-15T10:30:00Z, status: 200}], errors: [] }Pipelines 流式集成先通过 Pipelines 把流数据写入 Iceberg 表再用 R2 SQL 查询# 搭建 pipeline选择 Data Catalog Table 作为目标 npx wrangler pipelines setup # 关键设置 # - Destination: Data Catalog Table # - Compression: zstd推荐 # - Roll file time: 生产 300 秒开发 10 秒 # 向 pipeline 发送数据 curl -X POST https://{stream-id}.ingest.cloudflare.com \ -H Content-Type: application/json \ -d [{user_id: user_123, event_type: purchase, timestamp: 2025-01-15T10:30:00Z, amount: 29.99}] # 等待滚动间隔后查询已入库数据 npx wrangler r2 sql query my-bucket SELECT event_type, COUNT(*), SUM(amount) FROM default.events WHERE timestamp 2025-01-15T00:00:00Z GROUP BY event_type 详细搭建过程见 pipelines/patterns.md。PyIceberg 集成用 PyIceberg 创建并填充 Iceberg 表再用 R2 SQL 查询from pyiceberg.catalog.rest import RestCatalog import pyarrow as pa import pandas as pd # 配置 catalog catalog RestCatalog( namemy_catalog, warehousemy-bucket, urihttps://account-id.r2.cloudflarestorage.com/iceberg/my-bucket, tokenyour-token, ) catalog.create_namespace_if_not_exists(analytics) # 创建表 schema pa.schema([ pa.field(user_id, pa.string(), nullableFalse), pa.field(event_time, pa.timestamp(us, tzUTC), nullableFalse), pa.field(page_views, pa.int64(), nullableFalse), ]) table catalog.create_table((analytics, user_metrics), schemaschema) # 追加数据 df pd.DataFrame({ user_id: [user_1, user_2], event_time: pd.to_datetime([2025-01-15 10:00:00, 2025-01-15 11:00:00], utcTrue), page_views: [10, 25], }) table.append(pa.Table.from_pandas(df, schemaschema))查询npx wrangler r2 sql query my-bucket SELECT user_id, SUM(page_views) FROM analytics.user_metrics WHERE event_time 2025-01-15T00:00:00Z GROUP BY user_id 更多高级模式见 r2-data-catalog/patterns.md。连接外部引擎R2 Data Catalog 暴露 Iceberg REST API可连接 Spark、Snowflake、Trino、DuckDB 等引擎// Apache Spark 示例 val spark SparkSession.builder() .config(spark.sql.catalog.my_catalog, org.apache.iceberg.spark.SparkCatalog) .config(spark.sql.catalog.my_catalog.catalog-impl, org.apache.iceberg.rest.RESTCatalog) .config(spark.sql.catalog.my_catalog.uri, https://account-id.r2.cloudflarestorage.com/iceberg/my-bucket) .config(spark.sql.catalog.my_catalog.token, token) .getOrCreate() spark.sql(SELECT * FROM my_catalog.default.my_table LIMIT 10).show()典型业务用例日志分析-- 按端点统计错误率 SELECT path, COUNT(*), SUM(CASE WHEN status 400 THEN 1 ELSE 0 END) as errors FROM logs.http_requests WHERE timestamp BETWEEN 2025-01-01T00:00:00Z AND 2025-01-31T23:59:59Z GROUP BY path ORDER BY errors DESC LIMIT 20; -- 响应时间统计 SELECT method, MIN(response_time_ms), AVG(response_time_ms), MAX(response_time_ms) FROM logs.http_requests WHERE timestamp 2025-01-15T00:00:00Z GROUP BY method; -- 按状态码统计流量 SELECT status, COUNT(*) FROM logs.http_requests WHERE timestamp 2025-01-15T00:00:00Z AND method GET GROUP BY status ORDER BY COUNT(*) DESC;欺诈检测-- 大额交易 SELECT location, COUNT(*), SUM(amount), AVG(amount) FROM fraud.transactions WHERE transaction_timestamp 2025-01-01T00:00:00Z AND amount 1000.0 GROUP BY location ORDER BY SUM(amount) DESC LIMIT 20; -- 标记交易 SELECT merchant_category, COUNT(*), AVG(amount) FROM fraud.transactions WHERE is_fraud_flag true AND transaction_timestamp 2025-01-01T00:00:00Z GROUP BY merchant_category HAVING COUNT(*) 10 ORDER BY COUNT(*) DESC;业务智能BI-- 按部门统计销售额 SELECT department, SUM(revenue), AVG(revenue), COUNT(*) FROM sales.transactions WHERE sale_date 2024-01-01 GROUP BY department ORDER BY SUM(revenue) DESC LIMIT 10; -- 产品表现 SELECT category, COUNT(DISTINCT product_id), SUM(units_sold), SUM(revenue) FROM sales.product_sales WHERE sale_date BETWEEN 2024-10-01 AND 2024-12-31 GROUP BY category ORDER BY SUM(revenue) DESC;关键限制与陷阱完整说明见 gotchas.md。关键限制没有 Workers Binding无法从 Workers/Pages 代码中直接调用 R2 SQL不存在 binding// 以下写法不存在 export default { async fetch(request, env) { const result await env.R2_SQL.query(SELECT * FROM table); // 不可行 return Response.json(result); } };替代方案从外部系统调用 HTTP API不能从 Workers 内通过 r2-data-catalog 的 REST API 使用 PyIceberg/SparkWorkers 场景改用 D1 或外部数据库。ORDER BY 限制只能按以下两类排序分区键列始终支持、聚合函数shuffle 策略支持。普通非分区列不能排序。-- 合法按分区键排序 SELECT * FROM logs.requests ORDER BY timestamp DESC LIMIT 100; -- 合法按聚合排序 SELECT region, SUM(amount) FROM sales.transactions GROUP BY region ORDER BY SUM(amount) DESC; -- 非法按非分区列排序 SELECT * FROM logs.requests ORDER BY user_id; -- 非法按别名排序必须重复写聚合函数 SELECT region, SUM(amount) as total FROM sales.transactions GROUP BY region ORDER BY total; -- 应写 ORDER BY SUM(amount)用DESCRIBE namespace.table_name检查分区规范。SQL 功能限制一览功能支持说明SELECT, WHERE, GROUP BY, HAVING支持标准支持COUNT, SUM, AVG, MIN, MAX支持标准聚合ORDER BY 分区/聚合列支持见上文LIMIT支持最大 10,000列别名不支持无 AS 别名SELECT 中的表达式不支持如 col1 col2按非分区列 ORDER BY不支持运行时报错JOIN、子查询、CTE不支持写入时反规范化窗口函数、UNION不支持改用外部引擎INSERT/UPDATE/DELETE不支持用 PyIceberg/Pipelines嵌套列、数组、JSON不支持写入时展平变通方案无 JOIN 时反规范化数据或使用 Spark/PyIceberg无子查询时拆分为多次查询无别名时接受自动生成的列名并在应用层转换。常见错误与解法报错原因解决方案Column not found拼写错误、列不存在或大小写不匹配用DESCRIBE namespace.table_name检查 schemaType mismatch类型不匹配如status 200、缺时区的时间戳整数不加引号时间戳用 RFC3339 全格式ORDER BY column not in partition key对非分区列排序改用分区键/聚合或去掉 ORDER BYDESCRIBE检查Token authentication failedtoken 缺失/无效echo $WRANGLER_R2_SQL_AUTH_TOKEN检查或写入.envTable not foundCatalog 或表未就绪SHOW DATABASES/SHOW TABLES IN namespace并确认已catalog enableLIMIT exceeds maximum超过 10000 上限用分区键上的 WHERE 过滤做分页No data returned意外数据为空或类型不符SELECT COUNT(*)验证 → 逐步移除 WHERE →LIMIT 10检查实际数据性能问题慢查询的成因分区过多、LIMIT 过大、缺少过滤条件、文件过小。-- 慢无过滤 SELECT * FROM logs.requests LIMIT 10000; -- 快按分区键过滤 SELECT * FROM logs.requests WHERE timestamp 2025-01-15T00:00:00Z AND timestamp 2025-01-16T00:00:00Z LIMIT 1000; -- 更快多重过滤 SELECT * FROM logs.requests WHERE timestamp 2025-01-15T00:00:00Z AND status 404 AND method GET LIMIT 1000;文件优化目标 Parquet 文件大小 100–500MB压缩后Pipelines 滚动间隔生产 300 秒、开发 10 秒定期做 compaction 合并小文件。查询超时添加更严格的 WHERE 过滤、缩小时间范围、查询更小的区间。-- 会超时全年聚合 SELECT status, COUNT(*) FROM logs.requests WHERE timestamp 2024-01-01T00:00:00Z GROUP BY status; -- 更快按月聚合 SELECT status, COUNT(*) FROM logs.requests WHERE timestamp 2025-01-01T00:00:00Z AND timestamp 2025-02-01T00:00:00Z GROUP BY status;最佳实践与调试清单分区策略时序数据按 timestamp 做 day/hour 分区地理数据按 region/country 分区避免高基数键如 user_id、超过 10,000 个分区。from pyiceberg.partitioning import PartitionSpec, PartitionField from pyiceberg.transforms import DayTransform PartitionSpec(PartitionField(source_id1, field_id1000, transformDayTransform(), nameday))查询书写始终加 LIMIT触发提前终止先过滤分区键实现高效裁剪用 AND 组合多个过滤条件裁剪更彻底WHERE timestamp 2025-01-15T00:00:00Z AND status 404 AND method GET LIMIT 100类型安全字符串加单引号GET而非GET时间戳用 RFC33392025-01-01T00:00:00Z而非2025-01-01日期用 ISO2025-01-15而非01/15/2025。数据组织Pipelines开发roll_file_time: 10生产roll_file_time: 300压缩使用zstd维护对小文件做 compaction过期旧快照。调试检查清单npx wrangler r2 bucket catalog enable bucket—— 验证 Catalogecho $WRANGLER_R2_SQL_AUTH_TOKEN—— 检查 tokenSHOW DATABASES—— 列出命名空间SHOW TABLES IN namespace—— 列出表DESCRIBE namespace.table—— 检查 schemaSELECT COUNT(*) FROM namespace.table—— 验证数据SELECT * FROM namespace.table LIMIT 10—— 测试简单查询逐步添加过滤条件。相关参考R2 SQL 配置指南 —— 启用 Catalog、创建 token、环境配置R2 SQL API 参考 —— SQL 语法、函数、操作符、数据类型R2 SQL 实战模式 —— Wrangler CLI、HTTP API、Pipelines、PyIceberg 示例R2 SQL 限制与排障 —— 限制、常见错误、性能建议r2-data-catalog 参考 —— PyIceberg、REST API、外部引擎接入pipelines 参考 —— 流式写入 Iceberg 表r2 参考 —— R2 对象存储基础cloudflare-deploy 技能总览 —— 各 Cloudflare 产品参考索引存储决策树中 R2 SQL 的定位见 I need to store data 一节【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考