语句与子句

SELECT

SQL API 每个请求接受一条 SELECT 语句。

SELECT select_expression [, ...]
FROM schema.dataset
[WHERE predicate]
[GROUP BY expression [, ...]]
[HAVING aggregate_predicate]
[ORDER BY expression [ASC | DESC] [, ...]]
[LIMIT non_negative_integer [OFFSET non_negative_integer]]
[FORMAT JSON | JSONEachRow | TabSeparated | TSV]

使用带 schema 限定的数据集名称，例如 events.httpRequests。不支持裸数据集名称。

使用 AS 设置结果字段名：

SELECT
  clientRequestHttpHost AS host,
  edgeResponseStatus AS status
FROM events.httpRequests
WHERE accountTag = '<ACCOUNT_TAG>'
  AND timestamp >= NOW() - INTERVAL '1' DAY
LIMIT 100

SELECT * 返回调用方可使用的每个字段。如果权限拒绝仅通过 * 访问到的字段，API 会省略它。显式选择被拒绝的字段会返回 HTTP 403。当数据集增加字段时，显式字段列表可提供更稳定的响应。

WHERE

使用 WHERE 设置租户、时间和数据筛选器。

WHERE accountTag = '<ACCOUNT_TAG>'
  AND timestamp >= NOW() - INTERVAL '1' DAY
  AND edgeResponseStatus >= 500

每个 HTTP API 查询都需要账户或 zone 范围。你可以通过 JSON 请求而不是 SQL 提供范围。Workers 绑定会自动提供账户范围，因此不要在绑定查询中包含租户谓词。HTTP API 查询支持的 SQL 租户形式为：

accountTag = '<ACCOUNT_TAG>'
zoneTag = '<ZONE_TAG>'
zoneTag IN ('<ZONE_TAG_1>', '<ZONE_TAG_2>')

一个查询只能选择一个账户。在一个 zoneTag 谓词中指定 zone 租户。使用 IN 选择多个 zone。租户谓词必须是用 AND 连接的顶级条件。不要将 accountTag 或 zoneTag 放在 OR、NOT 或 NOT IN 表达式中。

任何包含 zoneTag 的查询都需要每个命名 zone 的 Zone Analytics Read 权限，或其所属账户的 Account Analytics Read 权限。

每个查询还需要数据集时间戳字段的下限。使用 >、>= 或 BETWEEN 提供下限，或使用请求级 time_range。时间戳字段名因数据集而异。

GROUP BY

将 GROUP BY 与聚合函数一起使用，为每个唯一分组返回一行。

SELECT edgeResponseStatus AS status, COUNT(*) AS requests
FROM events.httpRequests
WHERE accountTag = '<ACCOUNT_TAG>'
  AND timestamp >= NOW() - INTERVAL '1' HOUR
GROUP BY edgeResponseStatus

HAVING

使用 HAVING 筛选分组结果。HAVING 表达式必须引用聚合函数。

SELECT clientRequestHttpHost AS host, COUNT(*) AS requests
FROM events.httpRequests
WHERE accountTag = '<ACCOUNT_TAG>'
  AND timestamp >= NOW() - INTERVAL '1' HOUR
GROUP BY clientRequestHttpHost
HAVING COUNT(*) > 100

ORDER BY

使用 ORDER BY 按升序（ASC）或降序（DESC）对结果排序。ASC 是默认值。

每个使用 ORDER BY 的查询也必须使用 LIMIT。Workers Analytics Engine 数据集保留没有 LIMIT 的 ORDER BY 兼容性。

ORDER BY requests DESC
LIMIT 10

不支持 NULLS FIRST 和 NULLS LAST。

LIMIT

LIMIT 接受非负整数字面量。不支持将参数和表达式作为限制值。

LIMIT 100

OFFSET

ClickHouse 支持的数据集在 LIMIT 之后支持 OFFSET。两个值都必须是非负整数字面量。Log Explorer 支持的数据集不支持 OFFSET。

LIMIT 100 OFFSET 200

Workers Analytics Engine 数据集还保留没有 LIMIT 的 OFFSET 兼容性。

FORMAT

添加顶级 FORMAT 子句以选择响应格式：

FORMAT JSON
FORMAT JSONEachRow
FORMAT TabSeparated
FORMAT TSV

TSV 是 TabSeparated 的别名。内容类型和响应形态请参阅响应格式。不支持派生表内的 FORMAT 子句。

派生表投影

当外层查询仅投影内层查询中的表达式时，SQL API 支持一个受限的派生表：

SELECT value
FROM (
  SELECT COUNT(*) AS value
  FROM events.httpRequests
  WHERE accountTag = '<ACCOUNT_TAG>'
    AND timestamp >= NOW() - INTERVAL '1' HOUR
)

外层查询不能添加筛选、分组、聚合、排序或限制。内层查询可以包含受支持的排序和限制。不支持派生表别名和嵌套派生表。