Workers 绑定

Analytics SQL 绑定允许 Cloudflare Worker 查询 SQL API 数据集，而无需发出 HTTP 请求或管理 API 令牌。每个绑定都限定到拥有该 Worker 的 Cloudflare 账户。

配置绑定

向 Worker 的 Wrangler 配置添加 Analytics SQL 绑定。analytics 键需要 Wrangler 4.145.0 或更高版本。

{
	"analytics": {
		"binding": "ANALYTICS_SQL"
	}
}

[analytics]
binding = "ANALYTICS_SQL"

binding 值决定你如何在 Worker 的 env 对象上访问该绑定。

从 Worker 查询

使用 SQL 语句和可选参数调用绑定的 query() 方法：

export default {
	async fetch(_request, env) {
		const start = new Date(Date.now() - 60 * 60 * 1000).toISOString();
		const result = await env.ANALYTICS_SQL.query({
			query: `
        SELECT edgeResponseStatus AS status, COUNT(*) AS requests
        FROM events.httpRequests
        WHERE timestamp >= $start
        GROUP BY edgeResponseStatus
        ORDER BY requests DESC
        LIMIT 10
      `,
			params: { start },
		});

		return Response.json(result);
	},
};

interface Env {
	ANALYTICS_SQL: AnalyticsSQLBinding;
}

export default {
	async fetch(_request, env): Promise<Response> {
		const start = new Date(Date.now() - 60 * 60 * 1000).toISOString();
		const result = await env.ANALYTICS_SQL.query({
			query: `
        SELECT edgeResponseStatus AS status, COUNT(*) AS requests
        FROM events.httpRequests
        WHERE timestamp >= $start
        GROUP BY edgeResponseStatus
        ORDER BY requests DESC
        LIMIT 10
      `,
			params: { start },
		});

		return Response.json(result);
	},
} satisfies ExportedHandler<Env>;

不要在绑定查询中包含 accountTag 或 zoneTag 谓词。绑定会单独提供 Worker 的账户范围，API 会拒绝同时在 SQL 中指定租户的查询。

绑定只能查询支持账户范围的数据集。

绑定可以通过 events.analyticsEngine."example-dataset" 等名称查询 Workers Analytics Engine 数据集。访问仍取决于账户的 Workers Analytics Engine 权益。

请求

query() 方法接受以下字段：

字段	类型	必填	描述
`query`	string	是	一条 SQL `SELECT` 语句。
`params`	array or object	否	位置或命名的字符串、数字、布尔值或 `null` 值。

绑定不接受 scope，因为它从 Worker 派生范围。它目前不暴露请求级 time_range。请在 SQL 中包含时间约束。

响应

该方法返回默认的 ClickHouse 支持的结果结构：

{
	"data": [
		{
			"status": 200,
			"requests": 125430
		}
	],
	"rows": 1,
	"statistics": {
		"elapsed_ms": 42,
		"rows_read": 250000,
		"bytes_read": 18000000
	}
}

不要在绑定查询中添加 FORMAT 子句。绑定期望带 statistics 的默认 JSON 响应。Log Explorer 支持的数据集目前返回不同的响应形态，并且不通过绑定支持。

绑定不会自动重试失败的请求。抛出的错误包含布尔 retryable 属性，指示重试是否可能成功。仅当 retryable 为 true 时应用有界指数退避。