@clickhouse/client-web

ClickHouse JS client

About

Official JS client for ClickHouse, written purely in TypeScript, thoroughly tested with actual ClickHouse versions.

The repository consists of three packages:

• @clickhouse/client - a version of the client designed for Node.js platform only. It is built on top of HTTP and Stream APIs; supports streaming for both selects and inserts.
• @clickhouse/client-web - a version of the client built on top of Fetch and Web Streams APIs; supports streaming for selects. Compatible with Chrome/Firefox browsers and CloudFlare workers.
• @clickhouse/client-common - shared common types and the base framework for building a custom client implementation.

Documentation

See the ClickHouse website for the full documentation entry.

Usage examples

We have a wide range of examples, aiming to cover various scenarios of client usage. The overview is available in the examples README.

Contact us

If you have any questions or need help, feel free to reach out to us in the Community Slack (#clickhouse-js channel) or via GitHub issues.

Contributing

Check out our contributing guide.

Changelog

1.7.0 (Common, Node.js, Web)

Bug fixes

• (Web only) Fixed an issue where streaming large datasets could provide corrupted results. See #333 (PR) for more details.

New features

• Added JSONEachRowWithProgress format support, ProgressRow interface, and isProgressRow type guard. See this Node.js example for more details. It should work similarly with the Web version.

• (Experimental) Exposed the parseColumnType function that takes a string representation of a ClickHouse type (e.g., FixedString(16), Nullable(Int32), etc.) and returns an AST-like object that represents the type. For example:

  for (const type of [
    'Int32',
    'Array(Nullable(String))',
    `Map(Int32, DateTime64(9, 'UTC'))`,
  ]) {
    console.log(`##### Source ClickHouse type: ${type}`)
    console.log(parseColumnType(type))
  }
  

  The above code will output:

  ##### Source ClickHouse type: Int32
  { type: 'Simple', columnType: 'Int32', sourceType: 'Int32' }
  ##### Source ClickHouse type: Array(Nullable(String))
  {
    type: 'Array',
    value: {
      type: 'Nullable',
      sourceType: 'Nullable(String)',
      value: { type: 'Simple', columnType: 'String', sourceType: 'String' }
    },
    dimensions: 1,
    sourceType: 'Array(Nullable(String))'
  }
  ##### Source ClickHouse type: Map(Int32, DateTime64(9, 'UTC'))
  {
    type: 'Map',
    key: { type: 'Simple', columnType: 'Int32', sourceType: 'Int32' },
    value: {
      type: 'DateTime64',
      timezone: 'UTC',
      precision: 9,
      sourceType: "DateTime64(9, 'UTC')"
    },
    sourceType: "Map(Int32, DateTime64(9, 'UTC'))"
  }
  

  While the original intention was to use this function internally for Native/RowBinaryWithNamesAndTypes data formats headers parsing, it can be useful for other purposes as well (e.g., interfaces generation, or custom JSON serializers).

  NB: currently unsupported source types to parse:

  • Geo
  • (Simple)AggregateFunction
  • Nested
  • Old/new experimental JSON
  • Dynamic
  • Variant