ClickHouse Query Builder
The TypeScript-first ClickHouse query builder
This page is about writing the query itself: selecting columns, filtering, grouping, and composing something you can keep in a real codebase. hypequery gives you typed schema access and native ClickHouse ergonomics without forcing everything through raw SQL strings.
Type source
Generated from schema
ClickHouse syntax
Native support
Best for
Analytics-heavy TS apps
Hand-written result types drift fast
If you build queries with raw strings and cast the result afterwards, you end up maintaining a second version of the schema in TypeScript. That breaks the moment a column changes or a query shape evolves.
Most general-purpose builders are shaped around Postgres
ClickHouse query code tends to lean on date bucketing, aggregates, CTEs, and engine-specific syntax. A builder that treats ClickHouse as an edge case turns normal analytics work into workaround-heavy code.
Teams still need a way out when SQL is the right tool
A good ClickHouse builder should cover the common path well and stay honest about the rest. You do not want a fake abstraction that makes basic queries pleasant but blocks real ClickHouse work.
What the builder gives you
Start from the real schema, then write normal ClickHouse query code
Run schema generation once, point the query builder at the generated type, and then write queries against real table and column names. That is the useful part: less casting, better autocomplete, and fewer mistakes when a query gets edited six months later.
- Schema types generated from your live ClickHouse database
- Column names and return shapes inferred from that schema
- A fluent builder for the common path: filters, grouping, ordering, aggregates
- Helpers for composing query fragments instead of copying strings between files
- Raw SQL escape hatches for the parts ClickHouse specialists actually need
Builder example
A typed query without post-query casting
The important part is not the fluent syntax. It is that the builder knows the schema it is operating on, so table names, columns, and result shapes stay aligned with the database.
When the query stops being local
Promote a useful query into a named API definition
This is where the page should stay concrete: the query builder helps you author and test the query. If that same query later needs to power a dashboard or internal API, move it into a named definition with `initServe()` rather than rewriting it in a route file.
That is the boundary between this page and the broader analytics pages. Start here if you are replacing raw query strings. Move to the REST or React pages only when the query needs consumers outside the current process.
If you are comparing libraries, the companion article walks through @clickhouse/client, Kysely, Cube, and hypequery with the tradeoffs spelled out.
Serve example
Turn a working query into a reusable endpoint
The query-builder page should not pretend everything is a React hook immediately. The natural next step is usually a named query that can be served and reused.
Where teams usually get stuck
The questions this page should answer
What makes a ClickHouse builder useful
Fluent syntax alone is not enough. The builder has to understand ClickHouse return types, stay out of the way on aggregates and grouping, and avoid forcing a relational model onto analytics queries.
Where raw SQL still wins
Some queries are clearer as SQL, especially when you are leaning on more advanced ClickHouse features. A good builder should let you drop down deliberately instead of pretending that never happens.
How this differs from Kysely
Kysely is excellent in relational stacks. This page is for teams whose center of gravity is ClickHouse analytics, where schema introspection and ClickHouse-native query patterns matter more than SQL portability.
When to leave this page
If your next problem is HTTP delivery, not query authoring, jump to the REST API page. If your problem is browser consumers, jump to the React or Next.js pages.
Further reading
Go deeper where it actually helps
ClickHouse query builders compared
Every realistic option in 2026 — raw client, Kysely, Cube, and hypequery — with honest tradeoffs.
Open guide
The ClickHouse TypeScript type problem
Why DateTime, UInt64, Nullable, and Decimal all return the wrong types and how to fix it.
Open guide
hypequery vs @clickhouse/client
What you actually gain when you move from raw queries to generated types and a reusable query layer.
Open guide
hypequery vs Kysely
Where Kysely is excellent, where ClickHouse changes the tradeoffs, and when hypequery is the better fit.
Open guide
Drizzle ORM for ClickHouse
A dedicated landing page for the Drizzle-on-ClickHouse search intent and the closest alternative.
Open guide
Next step
Write one real query against your schema
Generate the schema file, point the builder at it, and replace one raw query in your codebase. That is the fastest way to tell whether the workflow fits how your team actually writes ClickHouse code.