ClickHouse Node.js
Use ClickHouse from Node.js without hand-maintained query types
Most Node.js teams do not need an abstract database platform. They need a reliable way to query ClickHouse from scripts, API servers, jobs, and dashboards without retyping result shapes by hand. hypequery gives that Node.js workflow a typed center of gravity.
Runtime
Node.js and Bun
Frameworks
Express, Next.js, custom Node servers
Type source
Generated from schema
@clickhouse/client returns untyped results in Node.js
The official Node.js ClickHouse client runs queries and returns any. Every response requires a manual type cast to an interface you hand-wrote and have to maintain as the schema changes.
Building a Node.js analytics API from scratch is slow
Once you need to expose ClickHouse data over HTTP in Node.js, you write server routes with validation, error handling, auth, and response typing. That layer is not trivial and it is not your core product.
ClickHouse type mappings trip up Node.js developers
Node.js developers familiar with Postgres expect Date objects and numbers from a database query. ClickHouse returns DateTime as a formatted string and UInt64 as a string. Silent bugs follow.
Setup
A typed Node.js query layer for ClickHouse in minutes
Run schema generation to get a typed DB interface from your live ClickHouse database. Pass it to createQueryBuilder() and you have a fully typed query builder — autocomplete on table names, column names, and return values across your Node.js codebase.
- Works well in Node.js services, scripts, and Bun runtimes
- Schema types generated from your live ClickHouse instance
- Correct ClickHouse-to-Node.js type mappings — no guessing
- Composable query builder with support for typed filters, joins, CTEs, and raw SQL when needed
- Optional HTTP serving layer via @hypequery/serve handlers
Setup
Typed ClickHouse client for Node.js
Import the generated DB type and pass it to createQueryBuilder(). From that point every query is fully typed — table names autocomplete, column names autocomplete, and return types are inferred from the schema.
With Express
Mount typed ClickHouse analytics on any Node.js server
If you are building an analytics API on top of ClickHouse in Node.js, @hypequery/serve handles the HTTP layer. Define your queries, pass them to serve(), and mount `api.handler` through the Node adapter in Express or another Node server.
The Node adapter is the stable integration point for Express-style servers. For fetch-based runtimes such as Next.js App Router route handlers, Cloudflare Workers, or Deno, the fetch adapter is the right fit.
For standalone scripts and jobs, skip serve() entirely and call .execute() directly. The query builder works the same way regardless of context.
Express integration
Typed analytics endpoints on Express
Define your analytics queries and mount them through createNodeHandler(api.handler). Input validation, typed responses, and OpenAPI docs are all handled by hypequery.
Why teams search for this
Common implementation questions this page should solve
ClickHouse Node.js client TypeScript
The official client gets data in and out. The harder Node.js problem is reusing those queries across scripts, jobs, servers, and dashboards without rewriting types around each call site.
ClickHouse Node.js query builder
A useful Node.js query builder for ClickHouse should give you typed composition for the common path and a raw SQL escape hatch for the clauses that still need it.
ClickHouse Express.js API
If those same Node.js queries later need an API surface, the serve layer can expose them without pushing the query logic into Express-specific files.
ClickHouse Node HTTP adapter
The HTTP adapter matters because it keeps the query layer separate from the web framework. That separation is what lets the same analytics code serve scripts, jobs, and endpoints.
Further reading
Go deeper with comparison posts and implementation guides
ClickHouse JavaScript
The broader JavaScript and TypeScript guide — the same patterns in a framework-agnostic context.
Open guide
ClickHouse Next.js
Integrating ClickHouse into Next.js App Router — server components and API routes.
Open guide
ClickHouse REST API
Full guide to serving typed ClickHouse queries as HTTP endpoints with @hypequery/serve.
Open guide
ClickHouse TypeScript
The full TypeScript workflow — schema types, typed queries, HTTP APIs, and React hooks.
Open guide
Next step
Add hypequery to your Node.js project
Install the package, run schema generation, and write your first typed ClickHouse query in Node.js. Works with any Node.js framework or runtime.