From 2c1ace96dc3bdccef87a27ea31ee8a822f9b9433 Mon Sep 17 00:00:00 2001 From: slvrtrn Date: Wed, 17 Jan 2024 14:54:07 +0100 Subject: [PATCH 1/3] Update clickhouse-js docs as of 0.2.8 --- docs/en/integrations/language-clients/js.md | 74 +++++++++++++++++++-- 1 file changed, 70 insertions(+), 4 deletions(-) diff --git a/docs/en/integrations/language-clients/js.md b/docs/en/integrations/language-clients/js.md index 55a38f8feb0..97964ffc3b7 100644 --- a/docs/en/integrations/language-clients/js.md +++ b/docs/en/integrations/language-clients/js.md @@ -49,7 +49,7 @@ npm i @clickhouse/client-web | Client version | ClickHouse | |----------------|--------------| -| 0.2.6 | 22.8 - 23.10 | +| 0.2.8 | 22.8 - 23.12 | ## ClickHouse Client API @@ -391,7 +391,7 @@ function pushData(stream: Stream.Readable) { ``` **Example:** (Node.js only) Insert a stream of strings in CSV format from a CSV file. -[Source code](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/insert_file_stream_csv.ts). +[Source code](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/insert_file_stream_csv.ts). ```ts await client.insert({ @@ -401,7 +401,60 @@ await client.insert({ }) ``` -If you have a custom INSERT statement that is difficult to model with this method, consider using [command](#command-method) +**Example**: Exclude certain columns from the insert statement. + +Assuming the table definition such as: + +```sql +CREATE OR REPLACE TABLE mytable +(id UInt32, message String) +ENGINE MergeTree() +ORDER BY (id) +``` + +Insert only a specific column: + +```ts +// Generated statement: INSERT INTO mytable (message) FORMAT JSONEachRow +await client.insert({ + table: 'mytable', + values: [{ message: 'foo' }], + format: 'JSONEachRow', + // `id` column value for this row will be zero (default for UInt32) + columns: ['message'], +}) +``` + +Exclude certain columns: + +```ts +// Generated statement: INSERT INTO mytable (* EXCEPT (message)) FORMAT JSONEachRow +await client.insert({ + table: tableName, + values: [{ id: 144 }], + format: 'JSONEachRow', + // `message` column value for this row will be an empty string + columns: { + except: ['message'], + }, +}) +``` + +See the [source code](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/insert_exclude_columns.ts) for additional details. + +**Example**: Insert into a database different from the one provided to the client instance. [Source code](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/insert_into_different_db.ts). + +```ts +await client.insert({ + table: 'mydb.mytable', // Fully qualified name including the database + values: [{ id: 42, message: 'foo' }], + format: 'JSONEachRow', +}) +``` + +:::tip +If you have a custom INSERT statement that is difficult to model with this method, consider using [command](#command-method). +::: #### Web version limitations @@ -952,6 +1005,20 @@ const client = createClient({ }) ``` +## Read-only users + +As read-only user cannot change the response compression level, and it is enabled by default, explicitly disable it when creating a client instance for a read-only user: + +```ts +const client = createClient({ + compression: { + response: false, // cannot enable HTTP compression for a read-only user + }, +}) +``` + +See the [example](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/read_only_user.ts) for more details. + ## Known limitations (Node.js/Web) - There are no data mappers for the result sets, so only language primitives are used. @@ -963,7 +1030,6 @@ const client = createClient({ ## Known limitations (Web) - Streaming for select queries works, but it is disabled for inserts (on the type level as well). -- KeepAlive is disabled and not configurable yet. - Request compression is disabled and configuration is ignored. Response compression works. - No logging support yet. From 9907d7a8db06acdc09d20d5cd80aeced3c743837 Mon Sep 17 00:00:00 2001 From: slvrtrn Date: Wed, 17 Jan 2024 14:59:42 +0100 Subject: [PATCH 2/3] Update Keep-Alive entry --- docs/en/integrations/language-clients/js.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/en/integrations/language-clients/js.md b/docs/en/integrations/language-clients/js.md index 97964ffc3b7..fd9ffa2e0b1 100644 --- a/docs/en/integrations/language-clients/js.md +++ b/docs/en/integrations/language-clients/js.md @@ -93,6 +93,7 @@ When creating a client instance, the following connection settings can be adjust - **clickhouse_settings?: ClickHouseSettings** - ClickHouse settings to apply to all requests. Default value: `{}`. - **log?: { LoggerClass?: Logger, level?: ClickHouseLogLevel }** - configure logging. [Logging docs](#logging) - **session_id?: string** - optional ClickHouse Session ID to send with every request. +- **keep_alive?: { enabled?: boolean }** - enabled by default in both Node.js and Web versions. #### Node.js-specific configuration parameters @@ -964,7 +965,7 @@ for [basic](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/basic and [mutual](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/mutual_tls.ts) TLS in the repository. -## Keep Alive (Node.js only) +## Keep-Alive configuration (Node.js only) By default, client enables Keep-Alive in the underlying HTTP agent. If you are experiencing `socket hang up` errors, there are several options to resolve this issue: From 781a1f87d99c4bd3cc30d2cb46928f14c68914cb Mon Sep 17 00:00:00 2001 From: slvrtrn Date: Wed, 17 Jan 2024 15:05:06 +0100 Subject: [PATCH 3/3] Update InsertParams overview --- docs/en/integrations/language-clients/js.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/en/integrations/language-clients/js.md b/docs/en/integrations/language-clients/js.md index fd9ffa2e0b1..23e301567a6 100644 --- a/docs/en/integrations/language-clients/js.md +++ b/docs/en/integrations/language-clients/js.md @@ -329,6 +329,12 @@ interface InsertParams { abort_signal?: AbortSignal // query_id override; if not specified, a random identifier will be generated automatically. query_id?: string + // Allows to specify which columns the data will be inserted into. + // - An array such as `['a', 'b']` will generate: `INSERT INTO table (a, b) FORMAT DataFormat` + // - An object such as `{ except: ['a', 'b'] }` will generate: `INSERT INTO table (* EXCEPT (a, b)) FORMAT DataFormat` + // By default, the data is inserted into all columns of the table, + // and the generated statement will be: `INSERT INTO table FORMAT DataFormat`. + columns?: NonEmptyArray | { except: NonEmptyArray } } ``` @@ -481,6 +487,12 @@ interface InsertParams { abort_signal?: AbortSignal // query_id override; if not specified, a random identifier will be generated automatically. query_id?: string + // Allows to specify which columns the data will be inserted into. + // - An array such as `['a', 'b']` will generate: `INSERT INTO table (a, b) FORMAT DataFormat` + // - An object such as `{ except: ['a', 'b'] }` will generate: `INSERT INTO table (* EXCEPT (a, b)) FORMAT DataFormat` + // By default, the data is inserted into all columns of the table, + // and the generated statement will be: `INSERT INTO table FORMAT DataFormat`. + columns?: NonEmptyArray | { except: NonEmptyArray } } ```