SQL API

Workers Analytics Engine SQL API 是一个 HTTP API，允许对 Workers Analytics Engine dataset 执行 SQL 查询。

API 托管在 https://api.cloudflare.com/client/v4/accounts/<account_id>/analytics_engine/sql。

认证

通过 bearer token 进行认证。每次向 API 发送请求时必须提供 Authorization: Bearer <token> header。

使用仪表板创建具有读取账户 analytics 数据权限的 token：

访问 Cloudflare 仪表板中的 API tokens ↗ 页面。
选择 Create Token（创建令牌）。
选择 Create Custom Token（创建自定义令牌）。
按以下方式填写 Create Custom Token（创建自定义令牌） 表单：
- 为 token 指定描述性名称。
- 对于 Permissions（权限），选择 Account | Account Analytics | Read
- 可选配置 account 和 IP 限制以及 TTL。
- 提交并确认表单以创建 token。
记录 token 字符串。

查询 API

在 API 地址的 POST 请求 body 中提交查询文本。可以使用查询中的 FORMAT 选项选择返回数据的格式。

你可以使用 cURL 测试 API，将 <account_id> 替换为你的 32 字符 account ID（可在仪表板中获取），将 <token> 替换为上面生成的 token 字符串。

curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/analytics_engine/sql" \
--header "Authorization: Bearer <API_TOKEN>" \
--data "SELECT 'Hello Workers Analytics Engine' AS message"

如果已发布一些数据，可以尝试执行以下命令以确认 dataset 已在 DB 中创建。

curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/analytics_engine/sql" \
--header "Authorization: Bearer <API_TOKEN>" \
--data "SHOW TABLES"

有关支持的完整查询语法，请参阅 Workers Analytics Engine SQL 参考。

表结构

一旦你从 worker 开始向 dataset 写入事件，每个 dataset 将自动创建新表。

表将包含以下列：

Name	Type	Description
dataset	string	此列在每行中包含 dataset 名称。
timestamp	DateTime	事件在 worker 中记录的时间戳。
_sample_interval	integer	如果数据已被采样，此列指示此行（即原始数据中有多少行由这一行代表）的采样率。更多信息请参阅下方的采样部分。
index1	string	与事件一起记录的 index 值。此列中的值用作采样的 key。
blob1 ... blob20	string	与事件一起记录的 blob 值。
double1 ... double20	double	与事件一起记录的 double 值。

采样

在非常高的数据量下，Analytics Engine 将降采样数据以维持性能。采样可在写入和读取时发生。采样基于 dataset 的 index，因此只有接收大量事件的 index 才会被采样。例如，如果你的 worker 服务多个客户，你可能考虑将 customer ID 作为 index field。这意味着如果一个客户开始以高速率发出请求，该客户的事件可能被采样，而其他客户的数据保持未采样。

我们在 Cloudflare 测试此采样系统已有数年，它使我们能够将 web analytics 系统扩展到非常高的吞吐量，同时无论网站接收多少流量都能提供 statistically meaningful 的结果。

数据采样率通过 _sample_interval 列暴露。这意味着如果你对数据进行 statistical analysis，可能需要考虑此列。例如：

Original query	Query taking into account sampling
`SELECT COUNT() FROM ...`	`SELECT SUM(_sample_interval) FROM ...`
`SELECT SUM(double1) FROM ...`	`SELECT SUM(_sample_interval * double1) FROM ...`
`SELECT AVG(double1) FROM ...`	`SELECT SUM(_sample_interval * double1) / SUM(_sample_interval) FROM ...`

此外，QUANTILEEXACTWEIGHTED 函数设计为将 sample interval 作为第三个参数使用。

示例查询

使用列别名选择数据

可以在查询中使用列别名为 dataset 中的 blob 和 double 命名：

SELECT
    timestamp,
    blob1 AS location_id,
    double1 AS inside_temp,
    double2 AS outside_temp
FROM temperatures
WHERE timestamp > NOW() - INTERVAL '1' DAY

考虑 sample interval 的聚合

计算过去 7 天每个位置的读数数量。在此情况下，我们按 index field 分组，因此即使数据已被采样也可以计算精确计数：

SELECT
    index1 AS location_id,
    SUM(_sample_interval) AS n_readings
FROM temperatures
WHERE timestamp > NOW() - INTERVAL '7' DAY
GROUP BY index1

计算过去 7 天每个位置的平均温度。考虑 sample interval：

SELECT
    index1 AS location_id,
    SUM(_sample_interval * double1) / SUM(_sample_interval) AS average_temp
FROM temperatures
WHERE timestamp > NOW() - INTERVAL '7' DAY
GROUP BY index1