Analytics Engine
Write event measurements and query aggregate results with SQL.
- Library
Runtime.Workers - npm
@cloudflare/workers-types5.20260906.1
Events and queries
Workers Analytics Engine collects event data such as route latency, usage, or job outcomes. A Worker writes through an AnalyticsEngineDataset binding; readers query the dataset through a separate SQL HTTP API. It is an analytics service with its own event model and sampling behavior.
Follow the dataset setup guide to configure the binding and query access. Define what each positional field means before several producers start writing to the dataset.
Record a request
The caller supplies its dataset binding, tenant identity, route, and measured duration. This convention places the tenant in the sampling index, the route in blob1, and elapsed milliseconds in double1.
open Fable.Core
module Workers = FSharp.CloudEdge.Runtime.Workers
let recordRequest (dataset: Workers.AnalyticsEngineDataset) (tenant: string) (route: string) (elapsedMs: float) =
dataset.writeDataPoint(
Workers.AnalyticsEngineDataPoint.Create(
indexes = [| Some (U2.Case1 tenant) |],
blobs = [| Some (U2.Case1 route) |],
doubles = [| elapsedMs |]))
writeDataPoint returns immediately; the runtime handles the write in the background. The return value is not an ingestion receipt. Read access uses the SQL API and its credentials separately from the Worker binding.
Query with sampling in mind
Analytics Engine can sample data on ingestion and querying. Its _sample_interval field supplies the weight for aggregates. For a dataset named REQUESTS, this query estimates request count and mean duration by route:
SELECT blob1 AS route,
SUM(_sample_interval) AS requests,
SUM(double1 * _sample_interval) / SUM(_sample_interval) AS mean_ms
FROM REQUESTS
WHERE timestamp > NOW() - INTERVAL '1' HOUR
GROUP BY route
Choose the sampling index deliberately; using the tenant here allows sampling to reflect that tenant's event volume. These aggregates describe telemetry. Keep application records that require exact transactional updates in a store such as D1.
Help verify the binding
Useful checks include positional field encoding, dataset configuration, ingestion visibility, and weighted query results. A compiling consumer does not establish hosted behavior. Record the package version, configuration, and observed result using the verification guide.