Analytics SQL binding

Use the Analytics SQL binding to query analytics datasets from a Worker.

Add an Analytics SQL binding to your Worker's Wrangler configuration. The analytics key requires Wrangler 4.145.0 or later.

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

[analytics]
binding = "ANALYTICS_SQL"

The binding value determines the property used to access the binding on your Worker's env object.

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>;

For available datasets and supported SQL syntax, refer to the Analytics SQL documentation.

The query() method executes one SQL SELECT statement:

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

The optional type parameter defines the shape of each result row.

The AnalyticsSQLQuery object has the following properties:

An AnalyticsSQLParameter can be a string, number, boolean, or null.

The binding derives account scope from the Worker. It does not accept scope or time_range request properties.

The AnalyticsSQLResult<T> object has the following properties:

The statistics object contains elapsed_ms, rows_read, and bytes_read. For details about these values, refer to Query the SQL API.

The method rejects its promise when a query fails. The thrown error has a boolean retryable property. Retry with bounded exponential backoff only when this property is true.

The binding does not retry queries automatically. For query and service errors, refer to SQL API errors.