Analytics SQL 绑定

使用 Analytics SQL 绑定从 Worker 查询分析数据集。

配置绑定

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

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

[analytics]
binding = "ANALYTICS_SQL"

binding 值决定在 Worker 的 env 对象上用于访问该绑定的属性。

使用绑定

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 COUNT(*) AS requests FROM events.httpRequests WHERE timestamp >= $start",
			params: { start },
		});

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

interface Env {
	ANALYTICS_SQL: AnalyticsSQLBinding;
}

type CountRow = {
	requests: number;
};

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<CountRow>({
			query: "SELECT COUNT(*) AS requests FROM events.httpRequests WHERE timestamp >= $start",
			params: { start },
		});

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

有关可用数据集和支持的 SQL 语法，请参阅 Analytics SQL 文档。

`query()`

query() 方法执行一条 SQL SELECT 语句：

query<T extends Record<string, unknown> = Record<string, unknown>>(
	request: AnalyticsSQLQuery,
): Promise<AnalyticsSQLResult<T>>;

可选类型参数定义每一行结果的形状。

请求

AnalyticsSQLQuery 对象具有以下属性：

属性	类型	必填	描述
`query`	`string`	是	要执行的 SQL 语句。使用 `$1` 表示位置参数，或使用 `$name` 表示命名参数。
`params`	数组或对象	否	`query` 中占位符的值。

AnalyticsSQLParameter 可以是 string、number、boolean 或 null。

绑定从 Worker 派生账户作用域。它不接受 scope 或 time_range 请求属性。

结果

AnalyticsSQLResult<T> 对象具有以下属性：

属性	类型	描述
`data`	`T[]`	按所选列名作为键的查询结果行。
`rows`	`number`	`data` 中的行数。
`statistics`	`AnalyticsSQLStatistics`	查询的执行统计。

statistics 对象包含 elapsed_ms、rows_read 和 bytes_read。有关这些值的详情，请参阅查询 SQL API。

错误

查询失败时，该方法会拒绝其 Promise。抛出的错误有一个布尔属性 retryable。仅当此属性为 true 时，才使用有界指数退避重试。

绑定不会自动重试查询。有关查询和服务错误，请参阅 SQL API 错误。