[ PROMPT_NODE_23946 ]
Analytics Engine API 参考
[ SKILL_DOCUMENTATION ]
# Analytics Engine API 参考
## 写入数据
### `writeDataPoint()`
即发即弃（返回 `void`，而非 Promise）。写入操作是异步执行的。
typescript
interface AnalyticsEngineDataPoint {
blobs?: string[]; // 最多 20 个字符串（维度），每个 16KB
doubles?: number[]; // 最多 20 个数字（指标）
indexes?: string[]; // 1 个用于高基数过滤的索引字符串
}
env.ANALYTICS.writeDataPoint({
blobs: ["/api/users", "GET", "200"],
doubles: [145.2, 1], // latency_ms, count
indexes: ["customer_abc123"]
});
**行为：** 无需 await，不会抛出错误（请检查 tail 日志），高流量下自动采样，自动添加时间戳。
**Blob 与 Index 的区别：** Blob 用于 GROUP BY（<100k 唯一值），Index 仅用于过滤（数百万唯一值）。
### 完整示例
typescript
export default {
async fetch(request: Request, env: Env): Promise {
const start = Date.now();
const url = new URL(request.url);
try {
const response = await handleRequest(request);
env.ANALYTICS.writeDataPoint({
blobs: [url.pathname, request.method, response.status.toString()],
doubles: [Date.now() - start, 1],
indexes: [request.headers.get("x-api-key") || "anonymous"]
});
return response;
} catch (error) {
env.ANALYTICS.writeDataPoint({
blobs: [url.pathname, request.method, "500"],
doubles: [Date.now() - start, 1, 0],
});
throw error;
}
}
};
## SQL API (仅限外部)
bash
curl -X POST https://api.cloudflare.com/client/v4/accounts/{account_id}/analytics_engine/sql
-H "Authorization: Bearer $TOKEN"
-d "SELECT blob1 AS endpoint, COUNT(*) AS requests FROM dataset WHERE timestamp >= NOW() - INTERVAL '1' HOUR GROUP BY blob1"
### 列引用
sql
-- blob1..blob20, double1..double20, index1, timestamp
SELECT blob1 AS endpoint, SUM(double1) AS latency, COUNT(*) AS requests
FROM my_dataset
WHERE index1 = 'customer_123' AND timestamp >= NOW() - INTERVAL '7' DAY
GROUP BY blob1
HAVING COUNT(*) > 100
ORDER BY requests DESC LIMIT 100
**聚合函数：** `SUM()`, `AVG()`, `COUNT()`, `MIN()`, `MAX()`, `quantile(0.95)()`
**时间范围：** `NOW() - INTERVAL '1' HOUR`, `BETWEEN '2026-01-01' AND '2026-01-31'`
### 查询示例
sql
-- 热门端点
SELECT blob1, COUNT(*) AS requests, AVG(double1) AS avg_latency
FROM api_requests WHERE timestamp >= NOW() - INTERVAL '24' HOUR
GROUP BY blob1 ORDER BY requests DESC LIMIT 20
-- 错误率
粤公网安备44030002003366号