Workers Analytics Engine 快速入门 · Cloudflare Analytics docs

1. 命名 dataset 并添加到 Worker

将以下内容添加到 Wrangler 配置文件以创建 binding 到 Workers Analytics Engine dataset。Dataset 类似 SQL 中的表：行和列应具有一致的含义。

{
	"analytics_engine_datasets": [
		{
			"binding": "<BINDING_NAME>",
			"dataset": "<DATASET_NAME>"
		}
	]
}

[[analytics_engine_datasets]]
binding = "<BINDING_NAME>"
dataset = "<DATASET_NAME>"

2. 从 Worker 写入数据点

你可以通过调用刚创建的 binding 上暴露的 writeDataPoint() 方法向 Worker 写入数据点。

async fetch(request, env) {
  env.WEATHER.writeDataPoint({
    'blobs': ["Seattle", "USA", "pro_sensor_9000"], // City, State
    'doubles': [25, 0.5],
    'indexes': ["a3cd45"]
  });
  return new Response("OK!");
}

数据点是由以下组成的结构化事件：

Blobs（字符串）— 用于分组和筛选的维度。在其他指标系统中有时称为 labels。
Doubles（数字）— 你希望在数据点中记录的数值。
Indexes（字符串）— 用作采样键。

在上面的示例中，假设你正在收集空气质量样本。每个写入的数据点代表天气传感器的一次读数。Blobs 定义城市、州/地区和传感器型号 — 即你希望稍后用于筛选查询的维度。Double 定义数字温度和气压读数。Index 是客户的 ID。你可能希望包含关于传入请求的上下文（例如地理位置），以向数据点添加额外数据。

目前，writeDataPoint() API 接受有序的值数组。这意味着你必须以一致的顺序提供 field。虽然 indexes field 接受数组，但目前只能提供一个 index。如果尝试提供多个 index，数据点将不会被记录。

3. 使用 SQL API 查询数据

你可以通过两种方式查询已写入的数据：

SQL API — 最适合编写自己的查询并与 Grafana 等外部工具集成。
GraphQL API — 与为 Cloudflare 仪表板提供支持的 API 相同。

在本示例中，我们将使用 SQL API。

创建 API token

创建 API Token ↗ ，具有 Account Analytics Read 权限。

编写第一个查询

以下查询返回温度高于零时平均湿度读数最高的前 10 个城市：

SELECT
  blob1 AS city,
  SUM(_sample_interval * double2) / SUM(_sample_interval) AS avg_humidity
FROM WEATHER
WHERE double1 > 0
GROUP BY city
ORDER BY avg_humidity DESC
LIMIT 10

你可以通过向 SQL API 发送 HTTP 请求来运行此查询：

curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/analytics_engine/sql" \
--header "Authorization: Bearer <API_TOKEN>" \
--data "SELECT blob1 AS city, SUM(_sample_interval * double2) / SUM(_sample_interval) AS avg_humidity FROM WEATHER WHERE double1 > 0 GROUP BY city ORDER BY avg_humidity DESC LIMIT 10"

请参阅 the Workers Analytics Engine SQL Reference 了解支持的 SQL 功能完整列表。

处理时序数据

Workers Analytics Engine 针对可使用 Grafana 等工具可视化的时序 analytics 进行了优化。从 runtime 写入的每个事件都会自动填充 timestamp 字段。大多数时序预期会对 timestamp 取整，然后 GROUP BY。例如：

SELECT
  intDiv(toUInt32(timestamp), 300) * 300 AS t,
  blob1 AS city,
  SUM(_sample_interval * double2) / SUM(_sample_interval) AS avg_humidity
FROM WEATHER
WHERE
  timestamp >= NOW() - INTERVAL '1' DAY
  AND double1 > 0
GROUP BY t, city
ORDER BY t, avg_humidity DESC

此查询首先将 timestamp field 取整到最近的五分钟。然后，它按该 field 和 city 分组，并计算每个城市五分钟内的平均湿度。

请参阅 Querying Workers Analytics Engine from Grafana 了解如何针对 Workers Analytics Engine 创建高效 Grafana 查询的更多详情。