本页面总结了受支持的功能、限制和最佳实践。
| 功能 | 支持 | 备注 |
|---|---|---|
| SELECT, WHERE, GROUP BY, HAVING, ORDER BY, LIMIT | 是 | |
列别名 (AS) |
是 | |
| 表达式 (CASE, CAST, LIKE, BETWEEN, IN, arithmetic) | 是 | 完全支持表达式 |
| EXPLAIN | 是 | 将执行计划以文本或 JSON 格式返回 |
| 标量函数（Scalar functions） | 是 | 数学、字符串、日期时间、正则表达式、加密、数组、映射、结构、JSON |
| 聚合函数（Aggregate functions） | 是 | 基础的、近似的、统计的、位运算的、布尔型的、位置的 |
| 近似聚合（Approximate aggregates） | 是 | approx_distinct, approx_median, approx_percentile_cont, approx_top_k |
| Struct / Array / Map 列类型 | 是 | 方括号表示法, get_field(), 数组函数, map 函数 |
CTE (WITH ... AS) |
是 | 可引用不同表并可包含 JOIN |
| JOIN (INNER, LEFT, RIGHT, FULL OUTER, CROSS) | 是 | 所有标准的连接类型 |
| 隐式连接 (逗号 FROM) | 是 | |
子查询 (IN, NOT IN) |
是 | NOT IN 不支持在可为空（nullable）的列上使用 — 请改用 NOT EXISTS |
子查询 (EXISTS, NOT EXISTS) |
是 | 半连接和反连接模式 |
| 标量子查询（Scalar subqueries） | 是 | 用在 SELECT, WHERE, HAVING 中 |
| 派生表 (FROM 子查询) | 是 | 可以嵌套和连接。不支持 LATERAL 派生表。 |
| 自连接（Self-joins） | 是 | 带有不同别名的同一张表 |
窗口函数 (OVER) |
是 | 仅限内联 OVER (...) — 不支持命名的 WINDOW 子句 |
QUALIFY |
是 | 在窗口函数结果上进行过滤 |
SELECT DISTINCT / DISTINCT ON |
是 | |
func(DISTINCT ...) |
是 | COUNT, SUM, AVG, 和其他聚合函数 |
集合操作 (UNION, UNION ALL, INTERSECT, EXCEPT) |
是 | |
GROUPING SETS / ROLLUP / CUBE |
是 | |
OFFSET |
否 | |
INSERT / UPDATE / DELETE |
否 | 仅只读 |
CREATE / DROP / ALTER |
否 | 仅只读 |
有关完整的 SQL 语法，请参阅 SQL 参考。
| 功能 | 错误 |
|---|---|
OFFSET |
unsupported feature: OFFSET clause is not supported |
命名的 WINDOW 子句 |
unsupported feature: WINDOW clause is not supported |
INSERT / UPDATE / DELETE |
only read-only queries are allowed |
CREATE / DROP / ALTER |
only read-only queries are allowed |
UNNEST / PIVOT / UNPIVOT |
不支持 |
通配符修饰符 (在 * 上的 ILIKE, EXCLUDE, EXCEPT, REPLACE, RENAME) |
不支持 |
| 嵌套（带括号）连接 | 不支持 |
LATERAL 派生表 / LATERAL VIEW |
不支持 |
PERCENTILE_DISC |
不支持 — 请使用 PERCENTILE_CONT |
| 模式 | 替代方案 |
|---|---|
可为空列上的 NOT IN 子查询 |
请改用带有相关子查询的 NOT EXISTS |
支持精确聚合，例如 COUNT(DISTINCT ...)、MEDIAN、PERCENTILE_CONT、ARRAY_AGG 和 STRING_AGG。但在大型数据集上，请优先选择近似替代方法（approx_distinct、approx_median、approx_percentile_cont）以减少内存和计算资源开销。请参阅聚合函数。
| 约束 | 详细信息 |
|---|---|
| 资源密集型查询 | 在公开测试（open beta）期间，需要大量内存或计算资源的查询可能会超时。这包括多向连接（三张或更多大表）、跨连接或高基数列的 COUNT(DISTINCT) 和其他 func(DISTINCT ...)、ARRAY_AGG / STRING_AGG、对大量输入去重的集合操作、大分区上的窗口函数，以及大规模排序或高基数的 GROUP BY。添加 WHERE 过滤器和 LIMIT，并优先选择 approx_* 聚合以降低超时风险。 |
| 受预算控制的函数 | MEDIAN、PERCENTILE_CONT、ARRAY_AGG、STRING_AGG、用作聚合的 NTH_VALUE、任何带 DISTINCT 的聚合以及窗口函数（包括那些通过 QUALIFY 使用的）都会被预先进行预算控制。R2 SQL 在运行查询之前预估所需的内存，如果需要扫描太多数据，则会以 400 错误拒绝。请添加 GROUP BY 或 WHERE 过滤器来减少处理的行数。 |
| 多表查询 | 支持 JOIN、子查询（IN、EXISTS、标量、派生表）和多表 CTE。性能取决于中间结果的大小；请使用 WHERE 过滤器管理连接的选择性。 |
| 分区和未分区表 | 同时支持已分区和未分区的 Iceberg 表。 |
| 仅限 Parquet 格式 | 不支持 CSV、JSON 或其他格式。 |
| 只读 | R2 SQL 是一种查询引擎，不是数据库。不能写入。 |
now() / current_time() 精度 |
量化为 10ms 边界并强制转为 UTC。 |
| 代码 | 含义 |
|---|---|
| 40003 | 无效的 SQL 语法 |
| 40004 | 无效的查询（不支持的功能、未知的列、类型不匹配） |
| 80001 | 边缘服务连接失败（重试） |
- 在
WHERE中包含时间范围过滤器，以限制扫描的数据量。 - 使用特定的列名代替
SELECT *从而获得更好的性能。 - 使用
LIMIT控制结果集的大小。 - 在大型数据集上，使用近似聚合函数（
approx_distinct、approx_median、approx_percentile_cont）代替精确替代方案。 - 在 R2 Data Catalog 中启用压缩，以减少每次查询扫描的文件数量。
- 使用
EXPLAIN检查执行计划并验证谓词下推。 - 在多向连接时使用
WHERE过滤器，以减小中间结果的大小。直接连接三个或更多没有过滤器的大表可能会超出资源限制。 - 通过维度表连接大型事实表，而不是直接连接两张大型事实表。例如，通过共享的
zones维度连接http_requests和firewall_events，而不是对这两张事实表进行交叉连接。 - 跨多向连接使用
COUNT(DISTINCT)时要小心。这种组合可能会产生巨大的中间结果。考虑使用approx_distinct()或将查询拆分为更小的步骤。 - 使用显式的
JOIN语法代替隐式连接（逗号分隔的FROM），以提高可读性并确保优化器可以选择最佳的连接顺序。