[hypequery](https://hypequery.com/) › ClickHouse Analytics | hypequery
Index for agents: https://hypequery.com/llms.txt
Canonical page: https://hypequery.com/clickhouse-analytics

> Build ClickHouse analytics that can be reused across product code instead of re-implementing the same metrics in routes, jobs, and dashboards.

[Open sourceApache 2.0](https://github.com/hypequery/hypequery)

ClickHouse Analytics

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

Once the first few queries work, the same metrics start showing up in route handlers, exports, dashboards, and internal tools. hypequery gives each one a single definition, in TypeScript or Python, in the codebase you already have. Dashboards, APIs, and AI agents all answer from it.

[Start with hypequery ](https://hypequery.com/docs/quick-start)[Read the architecture essay](https://hypequery.com/blog/the-analytics-language-layer-why-real-time-data-needs-typed-apis-not-just-faster-databases)

Core pattern

Schema-driven analytics layer

Execution targets

Local, HTTP, React

Best fit

Product and internal analytics

## Metrics get reimplemented everywhere

A team writes one version of “active users” for a dashboard, another for an export, and another for an API. Each one is close enough to feel safe until the numbers stop matching.

## The useful queries never stay local

The query that starts in one file usually ends up feeding several consumers. Without a named definition, every new consumer becomes another copy and another place for the logic to drift.

## ClickHouse speed does not solve application sprawl

Fast scans are not the bottleneck once several teams or surfaces depend on the same numbers. The real problem is keeping access, filters, and result shapes consistent as usage expands.

What changes

## Give important queries names and reuse them on purpose

The main shift is simple: stop treating analytics queries as loose implementation detail. Generate the schema, define the query once, and make that definition the thing other parts of the product call.

- Generate schema types from ClickHouse so query code matches runtime reality
- Define named datasets in TypeScript or Python instead of scattering SQL strings
- Call those definitions locally or expose them over HTTP when needed
- Keep input validation and response typing next to the query itself
- Add new consumers without rewriting the underlying metric logic

Named query

### One shared definition for a metric the product keeps using

what-changes.ts

```
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 },
});
```

The unit being shared is a named query with typed input and one obvious place to change it later.

What reuse looks like

## The query stays the same even when the consumer changes

A server call, an HTTP endpoint, and a browser hook can all depend on the same query instead of growing their own local version.

The claim here is narrow. Analytics logic that gets reused should live in one place instead of being copied from file to file.

If your current pain is runtime types, go to the TypeScript page. If your current pain is tenant-scoped customer analytics, go to the SaaS analytics page.

Consumers

### Three places the same metric can show up

what-reuse-looks-like.ts

```
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 and the definition stays the same.

Where teams usually get stuck

## Questions teams ask

### When this architecture matters

It matters once a few queries stop being one-off reports and start feeding product features, internal tools, or several teams at the same time.

### What this is not

hypequery is a code-first way to stop duplicating analytics logic inside a TypeScript or Python application. It is not a large BI platform and is not trying to become one.

### What teams actually gain

Fewer mismatched numbers, fewer route-specific rewrites, and one obvious place to change a metric when the definition moves.

### Where to go next

Use the TypeScript page for runtime type problems, the REST page for delivery over HTTP, and the dashboard page for the browser-side consumption story.

Examples

## Guides with SQL that runs in CI

Every example runs against the same seeded ClickHouse dataset. Scaffold one with `npx @hypequery/cli create <slug> -y`, or browse the [full list](https://hypequery.com/examples).

[Guide · ClickHouse 25.8](https://hypequery.com/guides/clickhouse-vs-postgres-app-analytics)

### [ClickHouse vs Postgres for app analytics: when Postgres is enough, and how to add ClickHouse](https://hypequery.com/guides/clickhouse-vs-postgres-app-analytics)

[Measured on the same million events: which analytics queries Postgres handles, which need ClickHouse, and how to move data with CDC, dual writes or batch pulls.](https://hypequery.com/guides/clickhouse-vs-postgres-app-analytics)

[QuantileTo date](https://hypequery.com/guides/clickhouse-vs-postgres-app-analytics)

[Open guide](https://hypequery.com/guides/clickhouse-vs-postgres-app-analytics)

Further reading

## Go deeper where it actually helps

### [ClickHouse with Python](https://hypequery.com/clickhouse-python)

[The same datasets and APIs for Python backends and notebooks.](https://hypequery.com/clickhouse-python)

[Open guide](https://hypequery.com/clickhouse-python)

### [ClickHouse semantic layer alternative](https://hypequery.com/clickhouse-semantic-layer)

[The honest positioning page: what hypequery does today, what a full semantic layer would mean, and where Cube fits.](https://hypequery.com/clickhouse-semantic-layer)

[Open guide](https://hypequery.com/clickhouse-semantic-layer)

### [Why real-time data needs typed APIs](https://hypequery.com/blog/the-analytics-language-layer-why-real-time-data-needs-typed-apis-not-just-faster-databases)

[The blog post that sets out the analytics-layer argument behind these pages.](https://hypequery.com/blog/the-analytics-language-layer-why-real-time-data-needs-typed-apis-not-just-faster-databases)

[Open guide](https://hypequery.com/blog/the-analytics-language-layer-why-real-time-data-needs-typed-apis-not-just-faster-databases)

### [ClickHouse TypeScript](https://hypequery.com/clickhouse-typescript)

[Focus on schema types, query safety, and runtime type mapping.](https://hypequery.com/clickhouse-typescript)

[Open guide](https://hypequery.com/clickhouse-typescript)

### [ClickHouse multi-tenant analytics](https://hypequery.com/clickhouse-multi-tenant-analytics)

[Focus on tenant isolation and safer SaaS analytics delivery.](https://hypequery.com/clickhouse-multi-tenant-analytics)

[Open guide](https://hypequery.com/clickhouse-multi-tenant-analytics)

Related pillars

[ClickHouse with TypeScript and Python](https://hypequery.com/clickhouse)[ClickHouse Semantic Layer](https://hypequery.com/clickhouse-semantic-layer)[ClickHouse TypeScript](https://hypequery.com/clickhouse-typescript)[ClickHouse Python](https://hypequery.com/clickhouse-python)[ClickHouse Python Analytics](https://hypequery.com/clickhouse-python-analytics)[ClickHouse Next.js](https://hypequery.com/clickhouse-nextjs)[ClickHouse React](https://hypequery.com/clickhouse-react)[ClickHouse Multi-Tenant Analytics](https://hypequery.com/clickhouse-multi-tenant-analytics)

Next step

## Take one repeated metric and give it a single definition

Pick a metric that already exists in more than one place, move it into a named query, and wire one consumer to it. That is the fastest way to decide whether to adopt this model in your codebase.

Open source, and it runs in your own backend. Want it hosted?

[Start with hypequery ](https://hypequery.com/docs/quick-start)[See TypeScript specifics](https://hypequery.com/clickhouse-typescript)
