ClickHouse Analytics

Turn ClickHouse into a reusable analytics layer instead of a pile of raw queries

ClickHouse is excellent at running analytical workloads. The harder problem is making analytics safe and reusable across dashboards, APIs, internal tools, and product features. hypequery gives TypeScript teams a practical analytics layer on top of ClickHouse.

Open quick start Read the architecture essay

Core pattern

Schema-driven analytics layer

Execution targets

Local, HTTP, React

Best fit

Product and internal analytics

Raw SQL scales poorly across consumers

The same metric is reimplemented in dashboards, routes, jobs, exports, and internal tools. Even if ClickHouse is fast, the application layer turns brittle.

Analytics contracts are rarely explicit

Teams know they need “active users” or “revenue by day”, but those definitions live as code fragments instead of named, reviewed, reusable assets.

Database speed does not solve governance

As more product surfaces, teams, and agents hit ClickHouse, the problem becomes safe access and reuse rather than just query execution speed.

The operating model

Define analytics once, then deliver them to every consumer

A healthy ClickHouse analytics stack treats metrics and queries as code-level contracts. They are typed, named, reviewed, and transportable across runtime boundaries.

Generate schema types from ClickHouse so contracts reflect reality
Define named queries in TypeScript instead of scattering SQL strings
Run those definitions locally or expose them over HTTP
Document and validate inputs with the same source of truth
Add React hooks or external consumers without rewriting the metric

Shared definition

Create an analytics contract once

const { query, serve } = initServe({
  context: () => ({ db }),
});

const activeUsers = query({
  input: z.object({ days: z.number().int().positive() }),
  query: ({ ctx, input }) =>
    ctx.db
      .table('events')
      .where('created_at', 'gte', daysAgo(input.days))
      .countDistinct('user_id', 'active_users')
      .execute(),
});

export const api = serve({
  queries: { activeUsers },
});

This is the core shift from “database client” to “analytics layer”. The query is a named contract that multiple consumers can share.

Delivery paths

Support multiple consumers without rewriting the metric

Once analytics are defined as contracts, the same definition can feed server-side calls, browser clients, dashboards, scheduled jobs, and eventually AI or agent workflows.

That is the practical reason to build an analytics layer: not because SQL is impossible, but because organizations need one durable definition per metric as the number of consumers grows.

If your concern is the TypeScript mapping problem specifically, pair this page with the ClickHouse TypeScript pillar. If your concern is isolation in SaaS products, continue to the multi-tenant analytics pillar.

Multiple consumers

One analytics definition, several execution paths

const serverResult = await api.run('activeUsers', { input: { days: 30 } });
const httpResult = await fetch('/api/analytics/active-users');
const reactResult = useQuery('activeUsers', { days: 30 });

The consumer changes. The underlying metric definition does not. That is what keeps analytics coherent as a codebase grows.

Why teams search for this

Common implementation questions this page should solve

ClickHouse analytics architecture

If you are evaluating how to structure product analytics on ClickHouse, the main choice is whether metrics stay as raw SQL snippets or become shared application contracts.

ClickHouse semantic layer alternative

Some teams want the benefits of a semantic layer but prefer a code-first, TypeScript-native approach that fits directly into their application stack.

Reusable metrics on ClickHouse

Reusable metrics matter when multiple teams and product surfaces need the same numbers with the same filtering and validation rules.

Typed analytics APIs

A typed analytics API turns ClickHouse access into governed application behavior instead of ad-hoc database calls spread across the stack.

Go deeper with comparison posts and implementation guides

Next step

Use the quick start to make your first named analytics contract real

Once you see a schema-generated query run locally and over HTTP from the same definition, the analytics-layer pattern becomes concrete.

Open quick start See TypeScript specifics