Installation

Get started using hypequery in your project by following these simple steps.

Prerequisites

Before installing hypequery, make sure you have:

  • Node.js v20 or higher
  • npm or yarn package manager
  • A ClickHouse instance to connect to

Installing the Package

For Node.js environments:

# npm
npm install @hypequery/clickhouse

# yarn
yarn add @hypequery/clickhouse

# pnpm
pnpm add @hypequery/clickhouse

For browser environments:

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

# yarn
yarn add @hypequery/clickhouse @clickhouse/client-web

# pnpm
pnpm add @hypequery/clickhouse @clickhouse/client-web

Basic Setup

Node.js Environment

  1. First, create an .env file in your project root:
CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password
CLICKHOUSE_DATABASE=default
  1. Create a new file for your database configuration (e.g., db.ts). Alternatively, you can pass the client directly as demonstrated in the browser envrionment example below.
import { createQueryBuilder } from '@hypequery/clickhouse';

export const db = createQueryBuilder({
  host: process.env.CLICKHOUSE_HOST,
  username: process.env.CLICKHOUSE_USER,
  password: process.env.CLICKHOUSE_PASSWORD,
  database: process.env.CLICKHOUSE_DATABASE,
});

Browser Environment

For browser environments, you need to manually inject the ClickHouse client:

import { createClient } from '@clickhouse/client-web';
import { createQueryBuilder } from '@hypequery/clickhouse';

const client = createClient({
  host: 'https://your-clickhouse-proxy.com',
  username: 'default',
  password: 'password',
  database: 'default'
});

export const db = createQueryBuilder({
  client // Explicitly provide the client
});

Adding Type Safety

For the best development experience, generate TypeScript types for your ClickHouse schema:

  1. Generate types for your schema:
npx hypequery-generate-types
  1. Update your configuration to use the generated types:
import { createQueryBuilder } from '@hypequery/clickhouse';
import { IntrospectedSchema } from './generated/schema';

export const db = createQueryBuilder<IntrospectedSchema>({
  host: process.env.CLICKHOUSE_HOST,
  username: process.env.CLICKHOUSE_USER,
  password: process.env.CLICKHOUSE_PASSWORD,
  database: process.env.CLICKHOUSE_DATABASE,
});

Your First Query

Here’s a simple example to get you started:

// Import the db instance from your configuration file
import { db } from './db';

async function getRecentOrders() {
  const results = await db
    .table('orders')
    .select(['id', 'customer_name', 'amount'])
    .where('created_at', 'gt', '2024-01-01')
    .orderBy('created_at', 'DESC')
    .execute();

  console.log('Recent orders:', results);
}

Now you’ll get full TypeScript support, including:

  • Autocomplete for table names
  • Type-safe column selection
  • Validation of filter conditions
  • Type checking for aggregations

Next Steps