Setup & Connection

Get started with the standalone @hypequery/clickhouse query builder in minutes.

Installation

npm install @hypequery/clickhouse 

For browser environments:

npm install  @hypequery/clickhouse  @clickhouse/client-web

Create a .env file in the project root

CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password
CLICKHOUSE_DATABASE=default

Generate Types

Generate TypeScript types from your ClickHouse schema:

npx hypequery generate-types

This creates a generated-schema.ts file with your database structure.

Options:

• --output <path> - Output file path (default: ./generated-schema.ts)
• --tables <names> - Generate types for specific tables only
• --exclude <pattern> - Exclude tables matching pattern

Create Query Builder

The simplest approach for Node.js environments:

import { createQueryBuilder } from '@hypequery/clickhouse';
import type { IntrospectedSchema } from './generated-schema';

const db = createQueryBuilder<IntrospectedSchema>({
  host: 'http://localhost:8123',
  username: 'default',
  password: 'your-password',
  database: 'default'
});

Browser/Universal (Manual Client)

To use hypequery in a browser environment, you need to explicitly provide the client:

import { createQueryBuilder } from '@hypequery/clickhouse';
import { createClient } from '@clickhouse/client-web';
import type { IntrospectedSchema } from './generated-schema';

const client = createClient({
  host: 'http://localhost:8123',
  username: 'default',
  password: '',
  database: 'default'
});

const db = createQueryBuilder<IntrospectedSchema>({ client });

Verify Connection

Start building queries with full type safety!

const result = await db.table('users')
  .select(['id'])
  .limit(1)
  .execute();

console.log('Connected!', result);

Next Steps

Continue: Direct Execution - Learn how to execute queries

Or explore: Building Queries - Master the query builder API