/cloudflare-deploy

Cloudflare Workers Analytics Engine Reference

Expert guidance for implementing unlimited-cardinality analytics at scale using Cloudflare Workers Analytics Engine.

What is 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:

• Custom user-facing analytics dashboards
• Usage-based billing & metering
• Per-customer/per-feature monitoring
• High-frequency instrumentation without performance impact

Key Capability: Track metrics with unlimited unique values (e.g., millions of user IDs, API keys) without performance degradation.

Core Concepts

Reading Order

When to Use Analytics Engine

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.)

Quick Start

1. Add binding to wrangler.jsonc:

{
  "analytics_engine_datasets": [
    { "binding": "ANALYTICS", "dataset": "my_events" }
  ]
}

2. Write data points (fire-and-forget, no await):

env.ANALYTICS.writeDataPoint({
  blobs: ["/api/users", "GET", "200"],
  doubles: [145.2, 1],  // latency_ms, count
  indexes: [customerId]
});

3. Query via SQL API (HTTP):

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 DESC

In This Reference

• configuration.md - Setup, bindings, TypeScript types, limits
• api.md - writeDataPoint(), SQL API, query syntax
• patterns.md - Use cases, examples, anti-patterns
• gotchas.md - Sampling, index selection, troubleshooting

See Also

• Cloudflare Analytics Engine Docs