1# Analytics Engine Configuration
2 
3## Setup
4 
51. Add binding to `wrangler.jsonc`
62. Deploy Worker
73. Dataset created automatically on first write
84. Query via SQL API
9 
10## wrangler.jsonc
11 
12```jsonc
13{
14  "name": "my-worker",
15  "analytics_engine_datasets": [
16    { "binding": "ANALYTICS", "dataset": "my_events" }
17  ]
18}
19```
20 
21Multiple datasets for separate concerns:
22```jsonc
23{
24  "analytics_engine_datasets": [
25    { "binding": "API_ANALYTICS", "dataset": "api_requests" },
26    { "binding": "USER_EVENTS", "dataset": "user_activity" }
27  ]
28}
29```
30 
31## TypeScript
32 
33```typescript
34interface Env {
35  ANALYTICS: AnalyticsEngineDataset;
36}
37 
38export default {
39  async fetch(request: Request, env: Env) {
40    // No await - returns void, fire-and-forget
41    env.ANALYTICS.writeDataPoint({
42      blobs: [pathname, method, status],      // String dimensions (max 20)
43      doubles: [latency, 1],                   // Numeric metrics (max 20)
44      indexes: [apiKey]                        // High-cardinality filter (max 1)
45    });
46    return response;
47  }
48};
49```
50 
51## Data Point Limits
52 
53| Field | Limit | SQL Access |
54|-------|-------|------------|
55| blobs | 20 strings, 16KB each | `blob1`...`blob20` |
56| doubles | 20 numbers | `double1`...`double20` |
57| indexes | 1 string, 16KB | `index1` |
58 
59## Write Behavior
60 
61| Scenario | Behavior |
62|----------|----------|
63| <1M writes/min | All accepted |
64| >1M writes/min | Automatic sampling |
65| Invalid data | Silent failure (check tail logs) |
66 
67**Mitigate sampling:** Pre-aggregate, use multiple datasets, write only critical metrics.
68 
69## Query Limits
70 
71| Resource | Limit |
72|----------|-------|
73| Query timeout | 30 seconds |
74| Data retention | 90 days (default) |
75| Result size | ~10MB |
76 
77## Cost
78 
79**Free tier:** 10M writes/month, 1M reads/month
80 
81**Paid:** $0.05 per 1M writes, $1.00 per 1M reads
82 
83## Environment-Specific
84 
85```jsonc
86{
87  "analytics_engine_datasets": [
88    { "binding": "ANALYTICS", "dataset": "prod_events" }
89  ],
90  "env": {
91    "staging": {
92      "analytics_engine_datasets": [
93        { "binding": "ANALYTICS", "dataset": "staging_events" }
94      ]
95    }
96  }
97}
98```
99 
100## Monitoring
101 
102```bash
103npx wrangler tail  # Check for sampling/write errors
104```
105 
106```sql
107-- Check write activity
108SELECT DATE_TRUNC('hour', timestamp) AS hour, COUNT(*) AS writes
109FROM my_dataset
110WHERE timestamp >= NOW() - INTERVAL '24' HOUR
111GROUP BY hour
112```
113