1# Cloudflare Workers Analytics Engine Reference
2 
3Expert guidance for implementing unlimited-cardinality analytics at scale using Cloudflare Workers Analytics Engine.
4 
5## What is Analytics Engine?
6 
7Time-series analytics database designed for high-cardinality data (millions of unique dimensions). Write data points from Workers, query via SQL API. Use for:
8- Custom user-facing analytics dashboards
9- Usage-based billing & metering
10- Per-customer/per-feature monitoring
11- High-frequency instrumentation without performance impact
12 
13**Key Capability:** Track metrics with unlimited unique values (e.g., millions of user IDs, API keys) without performance degradation.
14 
15## Core Concepts
16 
17| Concept | Description | Example |
18|---------|-------------|---------|
19| **Dataset** | Logical table for related metrics | `api_requests`, `user_events` |
20| **Data Point** | Single measurement with timestamp | One API request's metrics |
21| **Blobs** | String dimensions (max 20) | endpoint, method, status, user_id |
22| **Doubles** | Numeric values (max 20) | latency_ms, request_count, bytes |
23| **Indexes** | Filtered blobs for efficient queries | customer_id, api_key |
24 
25## Reading Order
26 
27| Task | Start Here | Then Read |
28|------|------------|-----------|
29| **First-time setup** | [configuration.md](configuration.md) → [api.md](api.md) → [patterns.md](patterns.md) | |
30| **Writing data** | [api.md](api.md) → [gotchas.md](gotchas.md) (sampling) | |
31| **Querying data** | [api.md](api.md) (SQL API) → [patterns.md](patterns.md) (examples) | |
32| **Debugging** | [gotchas.md](gotchas.md) → [api.md](api.md) (limits) | |
33| **Optimization** | [patterns.md](patterns.md) (anti-patterns) → [gotchas.md](gotchas.md) | |
34 
35## When to Use Analytics Engine
36 
37```
38Need to track metrics? → Yes
39  ↓
40Millions of unique dimension values? → Yes
41    ↓
42  Need real-time queries? → Yes
43      ↓
44    Use Analytics Engine ✓
45 
46Alternative scenarios:
47- Low cardinality (<10k unique values) → Workers Analytics (free tier)
48- Complex joins/relations → D1 Database
49- Logs/debugging → Tail Workers (logpush)
50- External tools → Send to external analytics (Datadog, etc.)
51```
52 
53## Quick Start
54 
551. Add binding to `wrangler.jsonc`:
56```jsonc
57{
58  "analytics_engine_datasets": [
59    { "binding": "ANALYTICS", "dataset": "my_events" }
60  ]
61}
62```
63 
642. Write data points (fire-and-forget, no await):
65```typescript
66env.ANALYTICS.writeDataPoint({
67  blobs: ["/api/users", "GET", "200"],
68  doubles: [145.2, 1],  // latency_ms, count
69  indexes: [customerId]
70});
71```
72 
733. Query via SQL API (HTTP):
74```sql
75SELECT blob1, SUM(double2) AS total_requests
76FROM my_events
77WHERE index1 = 'customer_123'
78  AND timestamp >= NOW() - INTERVAL '7' DAY
79GROUP BY blob1
80ORDER BY total_requests DESC
81```
82 
83## In This Reference
84 
85- **[configuration.md](configuration.md)** - Setup, bindings, TypeScript types, limits
86- **[api.md](api.md)** - `writeDataPoint()`, SQL API, query syntax
87- **[patterns.md](patterns.md)** - Use cases, examples, anti-patterns
88- **[gotchas.md](gotchas.md)** - Sampling, index selection, troubleshooting
89 
90## See Also
91 
92- [Cloudflare Analytics Engine Docs](https://developers.cloudflare.com/analytics/analytics-engine/)
93- [GraphQL Analytics API Reference](../graphql-api/) - Query built-in Cloudflare analytics (HTTP, Workers, DNS, Firewall, etc.)
94- [Observability Reference](../observability/) - Workers Logs, Traces, and real-time debugging
95