Getting started

import { createQueryBuilder } from '@hypequery/clickhouse';
import { Session } from 'chdb';
import { chdbAdapter } from 'chdb/hypequery';

const session = new Session('./analytics.chdb');   // or new Session() for in-memory
const db = createQueryBuilder<Schema>({ adapter: chdbAdapter({ session }) });

await db.table('trips')
  .where('passenger_count', 'gte', 2)
  .select(['passenger_count'])
  .count('trip_id', 'trip_count')
  .sum('total_amount', 'revenue')
  .groupBy(['passenger_count'])
  .orderBy('passenger_count', 'ASC')
  .execute();

Nothing else changes: toSQL(), rawQuery(), and streaming all work, and the adapter renders SQL with hypequery's own exported helpers, so the queries are byte-identical to what the built-in HTTP adapter sends to a ClickHouse server.

Why Run Embedded?

• Testing and CI — run your hypequery analytics against a real ClickHouse engine with no container and no shared staging environment. The builder code your tests exercise is the code you ship.
• Local development — build a dashboard against a local Parquet file or an in-memory database, then point the same code at remote ClickHouse for production by swapping the adapter.
• Serverless — chDB runs in any Node.js environment, including AWS Lambda (note: chDB's native binary is large; verify your deployment package stays within Lambda's 250 MB unzipped limit). Edge runtimes that run in V8 isolates (Cloudflare Workers, Vercel Edge Runtime) cannot load native Node.js addons and are not supported.
• Local files and beyond — chDB reads Parquet, CSV, S3, and more through ClickHouse table functions, queryable via rawQuery().

Zero-Server Scaffolding

hypequery init can scaffold a project straight onto the embedded engine — no server, no credentials, and no .env created or updated:

npx hypequery init --database chdb

You can also run npx hypequery init and choose chDB (embedded, no server) from the interactive database prompt.

The scaffolded client.ts uses the adapter instead of an HTTP connection, chdb is installed as a dependency automatically, and the credential prompts are skipped. Choose an on-disk session directory (e.g. ./analytics.chdb) to persist data between runs, or stay in-memory for a throwaway runtime sandbox. After creating tables in an on-disk session, pass that same directory when refreshing types:

npx hypequery generate --database chdb --chdb-path ./analytics.chdb

An in-memory session is discarded when its process exits. Use an on-disk path when tables created by your application must also be visible to a later hypequery generate process.

Installing chdb does not prevent the CLI from connecting to ClickHouse Cloud or another remote server. CLICKHOUSE_* environment variables and .env configuration take precedence over dependency-based chDB detection. If neither remote configuration nor a chdb dependency is present, generation asks you to select a database explicitly. You can also select the remote driver explicitly:

npx hypequery generate --database clickhouse

See the CLI reference for all init and generate flags.

Setup

npm install chdb @hypequery/clickhouse

chDB ships prebuilt binaries for Linux x64/arm64 (glibc) and macOS x64/arm64 — no node-gyp step. Windows isn't supported natively; use WSL2.

Swapping between embedded and remote is a one-line change:

// Local / test
const db = createQueryBuilder<Schema>({ adapter: chdbAdapter({ session }) });

// Production
const db = createQueryBuilder<Schema>({ url: process.env.CLICKHOUSE_URL, password: '...' });

How It Works

The adapter implements hypequery's DatabaseAdapter contract: hypequery compiles your query to SQL client-side, and the adapter executes it in-process via a chDB Session, returning JSONEachRow rows. The adapter is maintained by the chDB team — issues with the adapter itself belong on chdb-io/chdb-node.