ClickHouse JS

This is a subject to change in the future. See also: [Base parameters for all client methods](/docs/integrations/javascript#base-parameters-for-all-client-methods).

### Command method[​](#command-method "Direct link to Command method")

It can be used for statements that don't have any output, when the format clause isn't applicable, or when you're not interested in the response at all. An example of such a statement can be `CREATE TABLE` or `ALTER TABLE`.

Should be awaited.

The response stream is destroyed immediately, which means that the underlying socket is released.

```
interface CommandParams extends BaseQueryParams {
  // Statement to execute.
  query: string
}

interface CommandResult {
  query_id: string
}

interface ClickHouseClient {
  command(params: CommandParams): Promise<CommandResult>
}
```

See also: [Base parameters for all client methods](/docs/integrations/javascript#base-parameters-for-all-client-methods).

**Example:** (Node.js/Web) Create a table in ClickHouse Cloud.
[Source code](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/create_table_cloud.ts).

```
await client.command({
  query: `
    CREATE TABLE IF NOT EXISTS my_cloud_table
    (id UInt64, name String)
    ORDER BY (id)
  `,
  // Recommended for cluster usage to avoid situations where a query processing error occurred after the response code, 
  // and HTTP headers were already sent to the client.
  // See https://clickhouse.com/docs/interfaces/http/#response-buffering
  clickhouse_settings: {
    wait_end_of_query: 1,
  },
})
```

**Example:** (Node.js/Web) Create a table in a self-hosted ClickHouse instance.
[Source code](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/create_table_single_node.ts).

```
await client.command({
  query: `
    CREATE TABLE IF NOT EXISTS my_table
    (id UInt64, name String)
    ENGINE MergeTree()
    ORDER BY (id)
  `,
})
```

**Example:** (Node.js/Web) INSERT FROM SELECT

```
await client.command({
  query: `INSERT INTO my_table SELECT '42'`,
})
```

References

A request cancelled with `abort_signal` doesn't guarantee that the statement wasn't executed by the server.

### Exec method[​](#exec-method "Direct link to Exec method")

If you have a custom query that doesn't fit into `query`/`insert`,
and you're interested in the result, you can use `exec` as an alternative to `command`.

`exec` returns a readable stream that MUST be consumed or destroyed on the application side.

```
interface ExecParams extends BaseQueryParams {
  // Statement to execute.
  query: string
}

interface ClickHouseClient {
  exec(params: ExecParams): Promise<QueryResult>
}
```

See also: [Base parameters for all client methods](/docs/integrations/javascript#base-parameters-for-all-client-methods).

Stream return type is different in Node.js and Web versions.

Node.js:

```
export interface QueryResult {
  stream: Stream.Readable
  query_id: string
}
```

Web:

```
export interface QueryResult {
  stream: ReadableStream
  query_id: string
}
```

### Ping[​](#ping "Direct link to Ping")

The `ping` method provided to check the connectivity status returns `true` if the server can be reached.

If the server is unreachable, the underlying error is included in the result as well.

```
type PingResult =
  | { success: true }
  | { success: false; error: Error }

/** Parameters for the health-check request - using the built-in `/ping` endpoint. 
 *  This is the default behavior for the Node.js version. */
export type PingParamsWithEndpoint = {
  select: false
  /** AbortSignal instance to cancel a request in progress. */
  abort_signal?: AbortSignal
  /** Additional HTTP headers to attach to this particular request. */
  http_headers?: Record<string, string>
}
/** Parameters for the health-check request - using a SELECT query.
 *  This is the default behavior for the Web version, as the `/ping` endpoint does not support CORS.
 *  Most of the standard `query` method params, e.g., `query_id`, `abort_signal`, `http_headers`, etc. will work, 
 *  except for `query_params`, which does not make sense to allow in this method. */
export type PingParamsWithSelectQuery = { select: true } & Omit<
  BaseQueryParams,
  'query_params'
>
export type PingParams = PingParamsWithEndpoint | PingParamsWithSelectQuery

interface ClickHouseClient {
  ping(params?: PingParams): Promise<PingResult>
}
```

Ping might be a useful tool to check if the server is available when the application starts, especially with ClickHouse Cloud, where an instance might be idling and will wake up after a ping: in that case, you might want to retry it a few times with a delay in between.

Note that by default, Node.js version uses the `/ping` endpoint, while the Web version uses a simple `SELECT 1` query to achieve a similar result, as the `/ping` endpoint doesn't support CORS.

**Example:** (Node.js/Web) A simple ping to the ClickHouse server instance. NB: for the Web version, captured errors will be different.
[Source code](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/ping.ts).

```
const result = await client.ping();
if (!result.success) {
  // process result.error
}
```

**Example:** If you want to also check the credentials when calling the `ping` method, or specify additional params such as `query_id`, you could use it as follows:

```
const result = await client.ping({ select: true, /* query_id, abort_signal, http_headers, or any other query params */ });
```

The ping method will allow most of the standard `query` method parameters - see the `PingParamsWithSelectQuery` typing definition.

### Close (Node.js only)[​](#close-nodejs-only "Direct link to Close (Node.js only)")

Closes all the open connections and releases resources. No-op in the web version.

```
await client.close()
```

## Streaming files (Node.js only)[​](#streaming-files-nodejs-only "Direct link to Streaming files (Node.js only)")

There are several file streaming examples with popular data formats (NDJSON, CSV, Parquet) in the client repository.

- [Streaming from an NDJSON file](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/insert_file_stream_ndjson.ts)
- [Streaming from a CSV file](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/insert_file_stream_csv.ts)
- [Streaming from a Parquet file](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/insert_file_stream_parquet.ts)
- [Streaming into a Parquet file](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/select_parquet_as_file.ts)

Streaming other formats into a file should be similar to Parquet,
the only difference will be in the format used for `query` call (`JSONEachRow`, `CSV`, etc.) and the output file name.

## Supported data formats[​](#supported-data-formats "Direct link to Supported data formats")

The client handles data formats as JSON or text.

If you specify `format` as one from the JSON family of formats (`JSONEachRow`, `JSONCompactEachRow`, etc.), the client will serialize and deserialize data during the communication over the wire.

Data provided in the "raw" text formats (`CSV`, `TabSeparated` and `CustomSeparated` families) are sent over the wire without additional transformations.

Tip

There might be confusion between JSON as a general format and [ClickHouse JSON format](/docs/interfaces/formats/JSON).

The client supports streaming JSON objects with formats such as [JSONEachRow](/docs/interfaces/formats/JSONEachRow) (see the table overview for other streaming-friendly formats; see also the `select_streaming_` [examples in the client repository](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/node)).

It's only that formats like [ClickHouse JSON](/docs/interfaces/formats/JSON) and a few others are represented as a single object in the response and can't be streamed by the client.