createQueryBuilder

Function: createQueryBuilder()

Creates a new query builder instance with the specified ClickHouse configuration.

Connection Modes:

  1. Host-based configuration: Provide connection details for auto-detection (Node.js environments)
  2. Client-based configuration: Provide a pre-configured ClickHouse client (required for browser environments)

Type Safety: The function provides comprehensive TypeScript support with type guards and separate configuration types.

Type Parameters

Schema

Schema extends { [K in string | number | symbol]: (columnName: string) => ClickHouseType }

The database schema type that provides type safety for table and column names.

Parameters

config

The ClickHouse configuration. Can be either:

  • ClickHouseHostConfig: Host-based configuration with connection details
  • ClickHouseClientConfig: Client-based configuration with pre-configured client

Host-Based Configuration

For Node.js environments with auto-detection:

host

string

The ClickHouse server host URL (e.g., ‘http://localhost:8123’).

username?

string

Username for authentication. Defaults to ‘default’.

password?

string

Password for authentication.

database?

string

The database to connect to. Defaults to ‘default’.

http_headers?

Record<string, string>

Custom HTTP headers to include with each request.

request_timeout?

number

Request timeout in milliseconds.

compression?

{ request: boolean; response: boolean; }

Compression options for the connection.

compression.request?

boolean

Enable compression for request bodies.

compression.response?

boolean

Enable compression for response bodies.

application?

string

Application name to identify in ClickHouse server logs.

keep_alive?

{ enabled: boolean; }

Keep-alive connection settings.

keep_alive.enabled

boolean

Enable keep-alive connections.

log?

any

Logger configuration.

clickhouse_settings?

ClickHouseSettings

Additional ClickHouse-specific settings.

Client-Based Configuration

For browser environments or manual client injection:

client

ClickHouseClient

Pre-configured ClickHouse client instance.

Returns

object

A query builder instance with the following methods:

table()

Creates a query builder for a specific table.

Type Parameters

TableName

TableName extends string | number | symbol

The table name type from the schema.

Parameters

tableName

TableName

The name of the table to query.

Returns

QueryBuilder<Schema, Schema[TableName], false, {}>

A query builder instance configured for the specified table.