Public API

ClickHouseClient

import { ClickHouseClient } from '@clickhouse/client-common'

class ClickHouseClient<Stream> {
  query(params: QueryParams): Promise<ResultSet>
  insert<T>(params: InsertParams<Stream, T>): Promise<InsertResult>
  exec(params: ExecParams): Promise<ExecResult<Stream>>
  command(params: CommandParams): Promise<CommandResult>
  ping(params?: PingParams): Promise<PingResult>
  close(): Promise<void>
}

The central class for all ClickHouse interactions. Use query for SELECT statements, insert for writing rows, command for DDL (CREATE/DROP), and exec when you need raw streaming access to results.

ClickHouseError

import { ClickHouseError, parseError } from '@clickhouse/client-common'

class ClickHouseError extends Error {
  code: string
  message: string
}

function parseError(error: unknown): ClickHouseError

Thrown by the client whenever ClickHouse returns an error response. Use parseError to normalise caught unknowns into a typed ClickHouseError for consistent error handling across query and insert paths.

DataFormat / SupportedJSONFormats

import {
  type DataFormat,
  SupportedJSONFormats,
  SupportedRawFormats,
  StreamableFormats,
} from '@clickhouse/client-common'

type DataFormat =
  | JSONDataFormat
  | RawDataFormat
  | StreamableDataFormat
  | StreamableJSONDataFormat
  | SingleDocumentJSONFormat

const SupportedJSONFormats: Set<DataFormat>
const SupportedRawFormats: Set<DataFormat>
const StreamableFormats: Set<DataFormat>

Use DataFormat as the type for the format field in QueryParams. The Supported* sets let you validate or branch logic based on whether a format produces JSON, raw bytes, or a streamable response.

TupleParam / formatQueryParams

import { TupleParam, formatQueryParams } from '@clickhouse/client-common'

class TupleParam {
  constructor(values: unknown[])
}

function formatQueryParams(key: string, value: unknown): string

Use TupleParam to pass ClickHouse tuple values as named query parameters. formatQueryParams serialises a parameter key/value pair into the wire format expected by the ClickHouse HTTP interface.

Working examples

Scenario - Basic SELECT with JSON streaming

Query ClickHouse and stream rows one at a time without loading the entire result into memory. Suitable for large result sets in a Node.js backend.

import { createClient } from '@clickhouse/client'

const client = createClient({
  url: process.env.CLICKHOUSE_URL ?? 'http://localhost:8123',
  username: process.env.CLICKHOUSE_USER ?? 'default',
  password: process.env.CLICKHOUSE_PASSWORD ?? '',
  database: process.env.CLICKHOUSE_DATABASE ?? 'default',
})

async function streamRows() {
  const resultSet = await client.query({
    query: 'SELECT number, toString(number) AS str FROM system.numbers LIMIT 100',
    format: 'JSONEachRow',
  })

  const stream = resultSet.stream()
  for await (const rows of stream) {
    for (const row of rows) {
      const data = row.json<{ number: string; str: string }>()
      console.log(data)
    }
  }

  await client.close()
}

streamRows().catch(console.error)

Scenario - INSERT rows from an array

Insert structured data into ClickHouse using the JSONEachRow format. The Node.js client accepts a plain JavaScript array directly.

import { createClient } from '@clickhouse/client'
import type { InsertParams } from '@clickhouse/client-common'

interface EventRow {
  event_id: string
  event_type: string
  ts: number
}

const client = createClient({
  url: process.env.CLICKHOUSE_URL ?? 'http://localhost:8123',
  username: process.env.CLICKHOUSE_USER ?? 'default',
  password: process.env.CLICKHOUSE_PASSWORD ?? '',
})

async function insertEvents(events: EventRow[]) {
  const result = await client.insert<EventRow>({
    table: 'events',
    values: events,
    format: 'JSONEachRow',
    clickhouse_settings: {
      async_insert: 1,
      wait_for_async_insert: 0,
    },
  })
  console.log('Insert summary:', result.summary)
}

insertEvents([
  { event_id: 'abc-1', event_type: 'click', ts: Date.now() },
  { event_id: 'abc-2', event_type: 'view',  ts: Date.now() },
]).catch(console.error)

Scenario - Error handling with ClickHouseError

Catch and inspect typed errors from ClickHouse. Useful for surfacing query errors to API callers with meaningful HTTP status codes.

import { createClient } from '@clickhouse/client'
import { ClickHouseError, parseError } from '@clickhouse/client-common'

const client = createClient({
  url: process.env.CLICKHOUSE_URL ?? 'http://localhost:8123',
})

async function runQuery(sql: string) {
  try {
    const rs = await client.query({ query: sql, format: 'JSON' })
    return await rs.json()
  } catch (err) {
    const chErr = parseError(err)
    if (chErr instanceof ClickHouseError) {
      console.error(`ClickHouse error [${chErr.code}]: ${chErr.message}`)
      // map to HTTP 400, 503, etc. based on chErr.code
    }
    throw chErr
  }
}

runQuery('SELECT * FROM non_existent_table').catch(() => process.exit(1))

File walkthrough

• client-common/src/client.ts - Abstract ClickHouseClient class with query/insert/exec/command/ping methods and all associated param/result types
• client-common/src/config.ts - BaseClickHouseClientConfigOptions interface defining URL, auth, TLS, HTTP settings shared by all platforms
• client-common/src/connection.ts - Abstract connection interface and shared connection utilities
• client-common/src/result.ts - BaseResultSet, Row, RowOrProgress, ResultJSONType, and streaming result types
• client-common/src/data_formatter/formatter.ts - Format enum definitions and format classification sets (SupportedJSONFormats, etc.)
• client-common/src/data_formatter/format_query_params.ts - TupleParam class and formatQueryParams for HTTP query parameter serialisation
• client-common/src/data_formatter/format_query_settings.ts - formatQuerySettings for serialising ClickHouse session settings
• client-common/src/error/error.ts - ClickHouseError class and parseError utility
• client-common/src/parse/column_types.ts - ClickHouse column type parsing helpers
• client-common/src/parse/json_handling.ts - JSON parsing utilities for ClickHouse response formats
• client-common/src/logger.ts - Logger interface, ClickHouseLogLevel enum, and log param types
• client-common/src/settings.ts - ClickHouse server settings type definitions
• client-common/src/clickhouse_types.ts - Shared ClickHouse domain types (ClickHouseSummary, ResponseJSON, ProgressRow, etc.)
• client-node/src/client.ts - Node.js createClient factory returning a fully configured Node.js client
• client-node/src/connection/node_base_connection.ts - Base HTTP connection using Node.js http/https modules
• client-node/src/connection/socket_pool.ts - Keep-alive socket pool for connection reuse
• client-node/src/result_set.ts - Node.js ResultSet wrapping stream.Readable
• client-node/src/config.ts - Node.js-specific config extending base (TLS, socket timeout, custom agent)
• client-web/src/client.ts - Web createClient factory for Fetch-based environments
• client-web/src/connection/web_connection.ts - Fetch-based HTTP connection implementation
• client-web/src/result_set.ts - Web ResultSet wrapping ReadableStream

Common pitfalls and fixes

• CLICKHOUSE_URL missing scheme - The URL must include http:// or https://; bare hostnames throw a parse error. Fix: always prefix with the scheme.
• Node.js < 18 compatibility - Versions below 18 lack stable fetch but @clickhouse/client (Node.js) does not use it; avoid mixing the web package on older Node. Fix: use @clickhouse/client on Node.js, @clickhouse/client-web only in browsers/edge.
• Forgetting to consume the stream - ResultSet.stream() holds an open HTTP connection; if you abandon it without consuming, sockets leak. Fix: always await full iteration or call resultSet.close().
• ESM/CJS dual-package hazard - Bundlers that resolve both CJS and ESM copies may instantiate two ClickHouseError classes, causing instanceof checks to fail. Fix: pin moduleResolution to bundler or node16 and ensure a single resolution path.
• async_insert without wait_for_async_insert - Enabling async_insert: 1 without also setting wait_for_async_insert: 1 means inserts may silently fail post-response. Fix: set wait_for_async_insert: 1 in production or check insert summary explicitly.
• TypeScript path aliases not applied at runtime - If you import from source via tsconfig paths, Node.js runtime ignores them. Fix: use tsconfig-paths/register or compile first; prefer the published npm packages for runtime use.

Vibe-coding prompt template

I have purchased the clickhouse-js source block. The source lives at `source/`
relative to this file, and a full integration guide is in `USAGE.md`.

The upstream packages are:
  - @clickhouse/client        (Node.js)
  - @clickhouse/client-web    (Browser / Cloudflare Workers)
  - @clickhouse/client-common (Shared types)

My project is: <describe your project, e.g. "an Express REST API in TypeScript
that needs to query ClickHouse and return JSON to frontend clients">

Please do the following step by step:
1. Read `USAGE.md` and the relevant files under `source/` to understand the
   real exports and signatures.
2. Add `@clickhouse/client` (or `@clickhouse/client-web`) to my project's
   dependencies as shown in USAGE.md § Required dependencies.
3. Create a `src/db/clickhouse.ts` singleton that initialises `createClient`
   using environment variables CLICKHOUSE_URL, CLICKHOUSE_USER,
   CLICKHOUSE_PASSWORD, and CLICKHOUSE_DATABASE.
4. Add typed query helpers for my use case: <describe your tables/queries>.
5. Wire error handling using `ClickHouseError` and `parseError` from
   `@clickhouse/client-common`.
6. Show me how to call `client.close()` on process shutdown.
Only use symbols documented in USAGE.md § Public API. Do not invent any APIs.

License and credit

The upstream project is released under the Apache License 2.0. See source/LICENSE if present, or refer to the official repository.

Upstream packages: @clickhouse/client, @clickhouse/client-web, @clickhouse/client-common by ClickHouse, Inc.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

전체 설치 가이드와 연동 프롬프트는 구매 후 열람할 수 있습니다.

Knex.js Multi-Dialect SQL Query Builder for Node.js

Automation, Utilities & Developer Tools

무료