Yandex ClickHouse driver for nodejs
Latest commit 228a3d5 Jul 25, 2016 @apla committed on GitHub Merge pull request #1 from tbkba/master
Failed to load latest commit information.
src slice before concat, not after Jul 24, 2016
tests disable torture on CI builds Jul 24, 2016
.gitignore Initial commit Jul 23, 2016
.travis.yml need to reconfigure from IPv6 Jul 23, 2016
LICENSE Initial commit Jul 23, 2016 Update Jul 25, 2016
package.json documentation update Jul 25, 2016

Database interface for

npm install @apla/clickhouse

travis codecov


var ch = new ClickHouse ({host:});

// stream is an object stream. you can pipe it
var stream = ch.query ("SELECT 1");

// or collect records yourself
var rows = [];

stream.on ('metadata', function (columns) {
  // do something with column list

stream.on ('data', function (row) {
  rows.push (row);

stream.on ('error', function (err) {
  // TODO: handler error

stream.on ('end', function () {
  // all rows are collected, let's verify count
  assert (rows.length === stream.supplemental.rows);
  // how many rows in result are set without windowing:
  console.log ('rows in result set', stream.supplemental.rows_before_limit_at_least);


new ClickHouse (options)

var options = {
  host: "clickhouse.msk",
  queryOptions: {
    profile: "web",
    database: "test"
  omitFormat: false

var clickHouse = new ClickHouse (options);

If you provide options as a string, they are assumed as a host parameter in connection options

Connection options (accept all options documented for http.request):

  • auth: authentication as user:password, optional
  • host: host to connect, can contain port name
  • pathname: pathname of ClickHouse server or / if omited,

queryOptions object can contain any option from Settings (docs: en ru )

For example:

  • database: default database name to lookup tables etc.
  • profile: settings profile to use
  • readonly: don't allow to change data
  • max_rows_to_read: self explanatory

Driver options:

  • omitFormat: FORMAT JSONCompact will be added by default to every query. You can change this behaviour by providing this option. In this case you should add FORMAT JSONCompact by yourself.
  • syncParser: collect data, then parse entire response. Should be faster, but for large datasets all your dataset goes into memory (actually, entire response + entire dataset). Default: false
  • dataObjects: use FORMAT JSON instead of FORMAT JSONCompact for output. By default (false), you'll receive array of values for each row. If you set dataObjects to true, every row will become an object with format: {fieldName: fieldValue, …}

var stream = clickHouse.query (statement, [options], [callback])

Query sends a statement to a server

Stream is a regular nodejs object stream, it can be piped to process records.

Stream events:

  • metadata: when a column information is parsed,
  • data: when a row is available,
  • error: something is wrong,
  • end: when entire response is processed

After response is processed, you can read a supplemental response data, such as row count via stream.supplemental.

Options are the same for query and constructor excluding connection.

Callback is optional and will be called upon completion with a standard node (error, result) signature. ()

Sends an empty query and check if it "Ok.\n"