Setting the file. One moment.
Chapter 04 · Cloudflare Deploy
Subchapter 4.21
references/analytics-engine/README.mdMarkdown3 KBView on GitHub
Expert guidance for implementing unlimited-cardinality analytics at scale using Cloudflare Workers Analytics Engine.
Time-series analytics database designed for high-cardinality data (millions of unique dimensions). Write data points from Workers, query via SQL API. Use for:
Key Capability: Track metrics with unlimited unique values (e.g., millions of user IDs, API keys) without performance degradation.
| Concept | Description | Example |
|---|---|---|
| Dataset | Logical table for related metrics | api_requests, user_events |
| Data Point | Single measurement with timestamp | One API request’s metrics |
| Blobs | String dimensions (max 20) | endpoint, method, status, user_id |
| Doubles | Numeric values (max 20) | latency_ms, request_count, bytes |
| Indexes | Filtered blobs for efficient queries | customer_id, api_key |
| Task | Start Here | Then Read |
|---|---|---|
| First-time setup | configuration.md → api.md → patterns.md | |
| Writing data | api.md → gotchas.md (sampling) | |
| Querying data | api.md (SQL API) → patterns.md (examples) | |
| Debugging | gotchas.md → api.md (limits) | |
| Optimization | patterns.md (anti-patterns) → gotchas.md |
Need to track metrics? → Yes
↓
Millions of unique dimension values? → Yes
↓
Need real-time queries? → Yes
↓
Use Analytics Engine ✓
Alternative scenarios:
- Low cardinality (<10k unique values) → Workers Analytics (free tier)
- Complex joins/relations → D1 Database
- Logs/debugging → Tail Workers (logpush)
- External tools → Send to external analytics (Datadog, etc.)wrangler.jsonc:{
"analytics_engine_datasets": [
{ "binding": "ANALYTICS", "dataset": "my_events" }
]
}env.ANALYTICS.writeDataPoint({
blobs: ["/api/users", "GET", "200"],
doubles: [145.2, 1], // latency_ms, count
indexes: [customerId]
});SELECT blob1, SUM(double2) AS total_requests
FROM my_events
WHERE index1 = 'customer_123'
AND timestamp >= NOW() - INTERVAL '7' DAY
GROUP BY blob1
ORDER BY total_requests DESCwriteDataPoint(), SQL API, query syntax