Building a Real-Time ClickHouse Dashboard with React and hypequery

ClickHouse is fast at aggregations. A query that scans 100 million rows and returns aggregated results in under a second makes polling a perfectly reasonable strategy for real-time dashboards — no WebSockets, no streaming, just fetch and refresh. This post walks through the full stack: schema, query definitions, typed HTTP endpoints, React hooks, and a live dashboard component.

Step 1: Generate the Schema

With a ClickHouse instance running and an events table created, generate TypeScript types:

This produces a typed schema object. All subsequent query builder calls are validated against it.

Step 2: Define the Analytics Queries

Create a server-side module with the queries your dashboard needs:

Step 3: Expose Typed HTTP Endpoints with @hypequery/serve

Step 4: Create React Hooks with @hypequery/react

Step 5: Build the Dashboard

How Type Safety Flows End-to-End

The type guarantees chain from bottom to top:

1. ClickHouse schema → npx @hypequery/cli generate → TypeScript types in schema.ts
2. schema.ts → createQueryBuilder<Schema>({...}) → query builder methods typed against real columns
3. Query builder → function return types → TypeScript knows the shape of each query result
4. @hypequery/serve → typed endpoint definitions → response types exported
5. createHooks() → useQuery('dau', ...) → data is typed as { dau: number }

If you rename a column in ClickHouse and regenerate the schema, TypeScript will flag every query that references the old column name. You catch the breakage before it reaches production.

Why Polling Works Well Here

Polling every 15–30 seconds is simple to implement, easy to reason about, and perfectly adequate for most analytics dashboards. ClickHouse's aggregation speed means a refresh query typically completes in under 500ms even on large datasets. The result: a dashboard that feels live without any streaming infrastructure.

If you need sub-second updates, ClickHouse also supports HTTP streaming and you can pipe results as they arrive — but for a management dashboard showing DAU and event breakdowns, polling is the right default.