R2 SQL 说明文档

# Cloudflare R2 SQL 技能参考 针对 Cloudflare R2 SQL 的专家指南——用于 Apache Iceberg 表的无服务器分布式查询引擎。 ## 阅读顺序 **初次接触 R2 SQL？** 从这里开始： 1. 阅读下方的“什么是 R2 SQL？”和“何时使用” 2. [configuration.md](configuration.md) - 启用目录，创建令牌 3. [patterns.md](patterns.md) - Wrangler CLI 和集成示例 4. [api.md](api.md) - SQL 语法和查询参考 5. [gotchas.md](gotchas.md) - 限制和故障排除 **快速参考？** 跳转至： - [通过 Wrangler 运行查询](patterns.md#wrangler-cli-query) - [SQL 语法参考](api.md#sql-syntax) - [ORDER BY 限制](gotchas.md#order-by-limitations) ## 什么是 R2 SQL？ R2 SQL 是 Cloudflare 的**无服务器分布式分析查询引擎**，用于查询 R2 数据目录中的 Apache Iceberg 表。特点： - **无服务器** - 无需管理集群，无需基础设施 - **分布式** - 利用 Cloudflare 全球网络进行并行执行 - **SQL 接口** - 用于分析查询的熟悉 SQL 语法 - **零出口费用** - 从任何云/区域查询，无需数据传输成本 - **公开测试版** - 测试期间免费（标准 R2 存储成本适用） ### 什么是 Apache Iceberg？ 用于对象存储中大规模分析数据集的开放表格式： - **ACID 事务** - 安全的并发读/写 - **元数据优化** - 无需全表扫描即可实现快速查询 - **模式演进** - 无需重写即可添加/重命名/删除列 - **分区** - 组织数据以实现高效修剪 ## 何时使用 **使用 R2 SQL 进行：** - **日志分析** - 使用 WHERE 过滤器和聚合查询应用程序/系统日志 - **BI 仪表板** - 从大型分析数据集生成报告 - **欺诈检测** - 使用 GROUP BY/HAVING 分析交易模式 - **多云分析** - 从任何云查询数据，无需出口费用 - **即席探索** - 通过 Wrangler CLI 在 Iceberg 表上运行 SQL 查询 **不要使用 R2 SQL 进行：** - **Workers/Pages 运行时** - R2 SQL 没有 Workers 绑定，请从外部系统使用 HTTP API - **实时查询 (<100ms)** - 针对分析型批处理查询优化，而非 OLTP - **复杂连接/CTE** - SQL 功能集有限（目前不支持 JOIN、子查询、CTE） - **小型数据集 (<1GB)** - 设置开销不划算 ## 决策树：需要查询 R2 数据吗？ 你需要查询 R2 中的结构化数据吗？ ├─ 是，数据在 Iceberg 表中 │ ├─ 需要 SQL 接口？ → 使用 R2 SQL (th