R2 SQL 常见陷阱

# R2 SQL 陷阱 R2 SQL 的限制、故障排除和常见陷阱。 ## 关键限制 ### 无 Workers 绑定 **无法从 Workers/Pages 代码调用 R2 SQL** - 不存在绑定。 typescript // ❌ 不存在此功能 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/Spark - 对于 Workers，请使用 D1 或外部数据库 ### ORDER BY 限制 仅能按以下方式排序： 1. **分区键列** - 始终支持 2. **聚合函数** - 通过 shuffle 策略支持 **无法按**常规非分区列排序。 sql -- ✅ 有效：按分区键排序 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 非分区 | ❌ | 运行时失败 | | JOINs, 子查询, CTEs | ❌ | 在写入时反规范化 | | 窗口函数, UNION | ❌ | 使用外部引擎 | | INSERT/UPDATE/DELETE | ❌ | 使用 PyIceberg/流水线 | | 嵌套列, 数组, JSON | ❌ | 在写入时扁平化 | **变通方法：** - 无 JOIN：反规范化数据或使用 Spark/PyIceberg - 无子查询：拆分为多个查询 - 无别名：接受生成的名称，在应用中转换 ## 常见错误 ### "Column not found" (找不到列) **原因：** 拼写错误、列不存在或大小写不匹配 **解决方案：** 使用 `DESCRIBE namespace.table_name` 检查模式 ### "Type mismatch" (类型不匹配) sql -- ❌ 类型错误 WHERE status = '200' -- 字符串而非整数 WHERE timestamp > '2025-01-01' -- 缺少时间/时区 -- ✅ 正确类型