ClickHouse JS
The JavaScript query builder built for ClickHouse
@clickhouse/client gives you a connection. hypequery gives you a full JavaScript analytics layer — schema-generated types, a composable query builder, typed HTTP APIs, and React hooks. Built specifically for ClickHouse, not adapted from a Postgres tool.
Language
JavaScript & TypeScript
Type source
Generated from schema
Best for
Analytics-heavy JS apps
@clickhouse/client returns any — no type safety
The official ClickHouse JS client executes queries and returns untyped results. Every response is effectively `any`. You hand-write interfaces that drift from the real schema, and TypeScript cannot catch the mismatch.
ClickHouse types do not map to JavaScript cleanly
DateTime columns come back as strings, not Date objects. UInt64 values come back as strings to avoid precision loss. Nullable columns return null. If you are guessing the mappings, you are introducing silent bugs.
Raw SQL strings do not scale in a JavaScript codebase
The same analytics query gets copy-pasted into API routes, background jobs, dashboards, and internal tools. When the schema changes, you find and fix it everywhere — or miss one and ship a bug.
How hypequery works
Generate types from ClickHouse, then build composable queries in JS
Run `npx @hypequery/cli generate` against your ClickHouse instance. You get a typed schema file that maps every table and column to the correct JavaScript type. Then use the query builder to write composable, reusable analytics queries without touching a SQL string.
- Schema types generated from your live ClickHouse database
- Correct JS runtime type mappings — DateTime→string, UInt64→string, Nullable→T|null
- Composable builder with filters, groupBy, orderBy, and aggregations
- Composable builder plus raw SQL escape hatches for ClickHouse-specific clauses
- Works in Node.js, Next.js, Bun, and any JS runtime that supports fetch
Before vs after
From raw @clickhouse/client to typed hypequery
The raw client returns untyped results. hypequery returns results typed from your generated schema — correct ClickHouse-to-JavaScript mappings included.
Multi-context execution
Define once, run anywhere in your JS stack
hypequery is not just a query builder. The same query definition that runs inline can be served as an HTTP endpoint with OpenAPI docs, or wrapped as a typed React hook — without duplicating logic.
This is the difference between a ClickHouse JS client and a ClickHouse JS analytics layer. A client runs queries. An analytics layer makes those queries reusable, typed, and composable across your entire JavaScript product.
If you are evaluating your options, read the full comparison of @clickhouse/client, Kysely, Cube, and hypequery side by side.
Multi-context
One query, three execution contexts
Define your analytics query once in JavaScript or TypeScript. Run it inline, serve it over HTTP, or use it as a React hook — the same definition, zero duplication.
Why teams search for this
Common implementation questions this page should solve
ClickHouse JavaScript client
@clickhouse/client is the official option — but it returns untyped results and requires you to hand-write interfaces. hypequery wraps your ClickHouse connection with generated types and a composable query builder on top.
ClickHouse Node.js query builder
Most query builders are built for Postgres and adapted for ClickHouse. hypequery is built specifically for ClickHouse workloads, with typed query composition and room to drop to raw SQL when a ClickHouse-specific clause is needed.
ClickHouse JS types — DateTime, UInt64, Nullable
The ClickHouse-to-JavaScript type mapping is where most teams hit silent bugs. DateTime returns as a string. UInt64 returns as a string. hypequery generates these mappings from your live schema so you never guess.
ClickHouse HTTP API in JavaScript
If you want a typed HTTP API on top of ClickHouse without hand-writing each route, @hypequery/serve exposes your query definitions as HTTP endpoints with full OpenAPI docs automatically.
Further reading
Go deeper with comparison posts and implementation guides
hypequery vs @clickhouse/client
What you actually gain when you move from raw queries to generated types and a reusable JS analytics layer.
Open guide
ClickHouse query builders compared
Every realistic JavaScript and TypeScript option in 2026 — with honest tradeoffs on each.
Open guide
The ClickHouse TypeScript type problem
Why DateTime, UInt64, Nullable, and Decimal return the wrong types in JavaScript and how to fix it.
Open guide
hypequery vs Kysely
Where Kysely is excellent, where ClickHouse changes the tradeoffs, and when hypequery is the better fit.
Open guide
Next step
Add hypequery to your JavaScript project
Install the package, run schema generation against your ClickHouse instance, and write your first typed query in under five minutes.