@clickhouse/client

What is @clickhouse/client?

@clickhouse/client is an npm package that provides a client for interacting with ClickHouse, a columnar database management system. It allows you to perform various database operations such as querying, inserting data, and managing database schemas.

What are @clickhouse/client's main functionalities?

Querying Data

This feature allows you to execute SQL queries against a ClickHouse database. The code sample demonstrates how to create a client instance and perform a SELECT query.

const { ClickHouse } = require('@clickhouse/client');

const client = new ClickHouse({
  url: 'http://localhost:8123',
  basicAuth: {
    username: 'default',
    password: '',
  },
});

async function queryData() {
  const rows = await client.query('SELECT * FROM my_table').toPromise();
  console.log(rows);
}

queryData();

Inserting Data

This feature allows you to insert data into a ClickHouse table. The code sample demonstrates how to create a client instance and perform an INSERT operation.

const { ClickHouse } = require('@clickhouse/client');

const client = new ClickHouse({
  url: 'http://localhost:8123',
  basicAuth: {
    username: 'default',
    password: '',
  },
});

async function insertData() {
  const result = await client.insert('INSERT INTO my_table (column1, column2) VALUES', [
    [1, 'value1'],
    [2, 'value2'],
  ]).toPromise();
  console.log(result);
}

insertData();

Managing Database Schemas

This feature allows you to manage database schemas, such as creating or altering tables. The code sample demonstrates how to create a new table in a ClickHouse database.

const { ClickHouse } = require('@clickhouse/client');

const client = new ClickHouse({
  url: 'http://localhost:8123',
  basicAuth: {
    username: 'default',
    password: '',
  },
});

async function createTable() {
  const result = await client.query(`
    CREATE TABLE IF NOT EXISTS my_table (
      id UInt32,
      name String
    ) ENGINE = MergeTree()
    ORDER BY id
  `).toPromise();
  console.log(result);
}

createTable();

Other packages similar to @clickhouse/client

clickhouse

The 'clickhouse' npm package is another client for interacting with ClickHouse databases. It offers similar functionalities such as querying and inserting data, but may have different API conventions and additional features.

node-clickhouse

The 'node-clickhouse' npm package is a client for ClickHouse that supports both HTTP and native protocols. It offers comprehensive functionalities for interacting with ClickHouse databases, including querying, inserting, and managing schemas.

README

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.10.0 (Common, Node.js, Web)

New features

• Added support for JWT authentication (ClickHouse Cloud feature) in both Node.js and Web API packages. JWT token can be set via access_token client configuration option.

  const client = createClient({
    // ...
    access_token: '<JWT access token>',
  })
  

  Access token can also be configured via the URL params, e.g., https://host:port?access_token=....

  It is also possible to override the access token for a particular request (see BaseQueryParams.auth for more details).

  NB: do not mix access token and username/password credentials in the configuration; the client will throw an error if both are set.