Installation

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

Prerequisites

Before installing hypequery, make sure you have:

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

Installing the Package

Install hypequery using npm:

npm install @hypequery/clickhouse

Or using yarn:

yarn add @hypequery/clickhouse

Basic Setup

  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):
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,
});

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 { Schema } from './generated/schema';

export const db = createQueryBuilder<Schema>({
  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