@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
mdx 137 lines 4.26 KB
Raw
1 ---
2 title: Analytics Engine
3 description: Write time-series data points from a Worker with Workers Analytics Engine — declare a dataset, bind it with WriteDataset, and query it later over Cloudflare's SQL API.
4 sidebar:
5 order: 24
6 ---
7
8 Workers Analytics Engine is Cloudflare's write-heavy time-series
9 store: Workers write unlimited-cardinality data points (events,
10 metrics, usage counters) at request time, and you query them later
11 with SQL. In alchemy a dataset is a one-line declaration and the
12 Worker writes to it through a typed binding.
13
14 ## Declare a dataset
15
16 ```typescript
17 // src/dataset.ts
18 import * as Cloudflare from "@alchemy.run/cloudflare";
19
20 export const Events = Cloudflare.AnalyticsEngine.Dataset("Events", {
21 dataset: "app_events",
22 });
23 ```
24
25 A dataset is pure configuration — there is no create/delete API call
26 behind it. Cloudflare materializes the dataset the first time a
27 Worker writes to it, so declaring one costs nothing. `dataset` is the
28 name you'll reference in SQL queries; omit it and the logical ID
29 (`"Events"`) is used.
30
31 ## Write data points from a Worker
32
33 Bind the dataset with `WriteDataset` in the Worker's Construction phase and
34 provide `WriteDatasetBinding` as a layer:
35
36 ```typescript
37 // src/worker.ts
38 import * as Cloudflare from "@alchemy.run/cloudflare";
39 import * as Effect from "effect/Effect";
40 import { HttpServerRequest } from "effect/http/HttpServerRequest";
41 import * as HttpServerResponse from "effect/http/HttpServerResponse";
42 import { Events } from "./dataset.ts";
43
44 export default Cloudflare.Worker(
45 "Worker",
46 { main: import.meta.url },
47 Effect.gen(function* () {
48 const analytics = yield* Cloudflare.AnalyticsEngine.WriteDataset(Events);
49
50 return {
51 fetch: Effect.gen(function* () {
52 const request = yield* HttpServerRequest;
53 const url = new URL(request.url, "http://localhost");
54
55 if (url.pathname === "/signup") {
56 yield* analytics.writeDataPoint({
57 indexes: ["account-1"],
58 blobs: ["signup"],
59 doubles: [1],
60 });
61 return yield* HttpServerResponse.json({ ok: true });
62 }
63
64 return HttpServerResponse.text("ok");
65 }).pipe(
66 Effect.catchTag("DatasetError", (error) =>
67 Effect.succeed(
68 HttpServerResponse.text(error.message, { status: 500 }),
69 ),
70 ),
71 ),
72 };
73 }).pipe(Effect.provide(Cloudflare.AnalyticsEngine.WriteDatasetBinding)),
74 );
75 ```
76
77 A data point has three optional field groups — `indexes` (the
78 sampling key, typically a customer or tenant ID), `blobs` (string
79 dimensions to group by), and `doubles` (numeric values to aggregate).
80 Writes are fire-and-forget at the edge; a failure surfaces as a typed
81 `DatasetError` that Effect keeps in the type system until you handle
82 it. The client also exposes `raw` if you need the underlying native
83 binding object directly.
84
85 ## Deploy it
86
87 ```typescript
88 // alchemy.run.ts
89 import * as Alchemy from "alchemy";
90 import * as Cloudflare from "@alchemy.run/cloudflare";
91 import * as Effect from "effect/Effect";
92 import Worker from "./src/worker.ts";
93
94 export default Alchemy.Stack(
95 "AnalyticsApp",
96 {
97 providers: Cloudflare.providers(),
98 state: Cloudflare.state(),
99 },
100 Effect.gen(function* () {
101 const worker = yield* Worker;
102 return { url: worker.url.as<string>() };
103 }),
104 );
105 ```
106
107 ```sh
108 bun alchemy deploy
109 ```
110
111 Deploying the Worker attaches the `analytics_engine` binding; hit
112 `/signup` and the data point lands in `app_events`.
113
114 ## Querying your data
115
116 The binding is write-only — that mirrors the platform, where Workers
117 can only write to Analytics Engine. Reads go through Cloudflare's
118 [SQL API](https://developers.cloudflare.com/analytics/analytics-engine/sql-api/),
119 an HTTP endpoint you query with an API token:
120
121 ```sql
122 SELECT blob1 AS event, SUM(_sample_interval * double1) AS count
123 FROM app_events
124 WHERE timestamp > NOW() - INTERVAL '1' DAY
125 GROUP BY event
126 ```
127
128 Alchemy doesn't ship a query binding yet, so run queries from
129 dashboards, cron jobs, or your backend via plain HTTP.
130
131 ## Where next
132
133 - [Workers](/cloudflare/compute/workers) — the two-phase Worker model the
134 binding lives inside.
135 - [Axiom](/axiom) — full observability (logs, traces, dashboards)
136 when you outgrow roll-your-own analytics.
137 - [WriteDataset API reference](/providers/cloudflare/analyticsengine/writedataset)