@clickhouse/client 1.20.0 → 1.21.0

package/skills/clickhouse-js-node-coding/reference/client-configuration.md

@@ -30,16 +30,16 @@ When answering configuration questions, include the relevant points:
 ## Minimal client
 
 ```ts
-import { createClient } from '@clickhouse/client'
+import { createClient } from "@clickhouse/client";
 
 const client = createClient({
   url: process.env.CLICKHOUSE_URL, // defaults to 'http://localhost:8123'
   username: process.env.CLICKHOUSE_USER, // defaults to 'default'
   password: process.env.CLICKHOUSE_PASSWORD, // defaults to ''
-  database: 'analytics', // defaults to 'default'
-})
+  database: "analytics", // defaults to 'default'
+});
 // ... your queries ...
-await client.close()
+await client.close();
 ```
 
 `url` accepts a string or a `URL` object. The accepted string format is:
@@ -62,7 +62,7 @@ export CLICKHOUSE_URL='https://bob:secret@my.host:8124/analytics'
 
 ```ts
 // In your Node.js code — no URL construction needed:
-const client = createClient({ url: process.env.CLICKHOUSE_URL })
+const client = createClient({ url: process.env.CLICKHOUSE_URL });
 ```
 
 ## Per-client vs per-request `clickhouse_settings` ⭐
@@ -79,14 +79,14 @@ const client = createClient({
   clickhouse_settings: {
     output_format_json_quote_64bit_integers: 0, // applied to every request
   },
-})
+});
 
 const rows = await client.query({
-  query: 'SELECT number FROM system.numbers LIMIT 2 FORMAT JSONEachRow',
+  query: "SELECT number FROM system.numbers LIMIT 2 FORMAT JSONEachRow",
   clickhouse_settings: {
     output_format_json_quote_64bit_integers: 1, // overrides client default for this call
   },
-})
+});
 ```
 
 ## `default_format` for `exec()`
@@ -96,17 +96,17 @@ query has no trailing `FORMAT …` clause, set `default_format` so the server
 knows what to send back, then wrap the response in a `ResultSet`:
 
 ```ts
-import { createClient, ResultSet } from '@clickhouse/client'
+import { createClient, ResultSet } from "@clickhouse/client";
 
-const client = createClient()
-const format = 'JSONCompactEachRowWithNamesAndTypes'
+const client = createClient();
+const format = "JSONCompactEachRowWithNamesAndTypes";
 const { stream, query_id } = await client.exec({
-  query: 'SELECT database, name, engine FROM system.tables LIMIT 5',
+  query: "SELECT database, name, engine FROM system.tables LIMIT 5",
   clickhouse_settings: { default_format: format },
-})
-const rs = new ResultSet(stream, format, query_id)
-console.log(await rs.json())
-await client.close()
+});
+const rs = new ResultSet(stream, format, query_id);
+console.log(await rs.json());
+await client.close();
 ```
 
 For ordinary `SELECT`s prefer `client.query({ format })` — `default_format` is

package/skills/clickhouse-js-node-coding/reference/custom-json.md

@@ -35,38 +35,38 @@ A custom `{ parse, stringify }` lets you plug in `JSONBig`,
 ## Recipe: BigInt-safe stringify, custom Date handling
 
 ```ts
-import { createClient } from '@clickhouse/client'
+import { createClient } from "@clickhouse/client";
 
 const valueSerializer = (value: unknown): unknown => {
   // Serialize Date as a UNIX millis number (instead of toJSON's ISO string)
   if (value instanceof Date) {
-    return value.getTime()
+    return value.getTime();
   }
 
   // Serialize BigInt as a string so JSON.stringify won't throw
-  if (typeof value === 'bigint') {
-    return value.toString()
+  if (typeof value === "bigint") {
+    return value.toString();
   }
 
   if (Array.isArray(value)) {
-    return value.map(valueSerializer)
+    return value.map(valueSerializer);
   }
 
-  if (typeof value === 'object' && value !== null) {
+  if (typeof value === "object" && value !== null) {
     return Object.fromEntries(
       Object.entries(value).map(([k, v]) => [k, valueSerializer(v)]),
-    )
+    );
   }
 
-  return value
-}
+  return value;
+};
 
 const client = createClient({
   json: {
     parse: JSON.parse, // use default parsing
     stringify: (obj: unknown) => JSON.stringify(valueSerializer(obj)),
   },
-})
+});
 
 await client.command({
   query: `
@@ -75,20 +75,20 @@ await client.command({
     ENGINE MergeTree
     ORDER BY id
   `,
-})
+});
 
 await client.insert({
-  table: 'inserts_custom_json_handling',
-  format: 'JSONEachRow',
+  table: "inserts_custom_json_handling",
+  format: "JSONEachRow",
   values: [
     {
-      id: BigInt('250000000000000200'), // serialized as a string
+      id: BigInt("250000000000000200"), // serialized as a string
       dt: new Date(), // serialized as ms since epoch
     },
   ],
-})
+});
 
-await client.close()
+await client.close();
 ```
 
 > The custom `valueSerializer` runs **before** `JSON.stringify`, so values
@@ -102,10 +102,10 @@ or precision-lossy numbers), plug in a `BigInt`-aware parser such as
 [`json-bigint`](https://www.npmjs.com/package/json-bigint):
 
 ```ts
-import { createClient } from '@clickhouse/client'
-import JSONBig from 'json-bigint'
+import { createClient } from "@clickhouse/client";
+import JSONBig from "json-bigint";
 
-const bigJson = JSONBig({ useNativeBigInt: true })
+const bigJson = JSONBig({ useNativeBigInt: true });
 
 const client = createClient({
   json: {
@@ -115,7 +115,7 @@ const client = createClient({
   clickhouse_settings: {
     output_format_json_quote_64bit_integers: 0,
   },
-})
+});
 ```
 
 `output_format_json_quote_64bit_integers: 0` is the default since
@@ -134,15 +134,15 @@ hand-rolled reviver. This uses the `context.source` argument that
 numeric literal is available before it's coerced to a JS `number`:
 
 ```ts
-import { createClient } from '@clickhouse/client'
+import { createClient } from "@clickhouse/client";
 
 const parseBigInt = (text: string) =>
   JSON.parse(text, function (key, value, context) {
-    if (key.endsWith('__bigint')) {
-      return BigInt(context.source)
+    if (key.endsWith("__bigint")) {
+      return BigInt(context.source);
     }
-    return value
-  })
+    return value;
+  });
 
 const client = createClient({
   json: {
@@ -150,15 +150,15 @@ const client = createClient({
     stringify: JSON.stringify, // use default stringify
   },
   clickhouse_settings: { output_format_json_quote_64bit_integers: 0 },
-})
+});
 
 const rs = await client.query({
-  query: 'SELECT toUInt64(250000000000000200) AS id__bigint',
-})
-const { data } = await rs.json()
-console.log(data[0].id__bigint) // 250000000000000200
+  query: "SELECT toUInt64(250000000000000200) AS id__bigint",
+});
+const { data } = await rs.json();
+console.log(data[0].id__bigint); // 250000000000000200
 
-await client.close()
+await client.close();
 ```
 
 Trade-offs versus `json-bigint`:

package/skills/clickhouse-js-node-coding/reference/data-types.md

@@ -50,7 +50,7 @@ When answering about storing and reading JSON objects:
 ## `Dynamic`, `Variant(...)`, `JSON`
 
 ```ts
-import { createClient } from '@clickhouse/client'
+import { createClient } from "@clickhouse/client";
 
 const client = createClient({
   clickhouse_settings: {
@@ -61,7 +61,7 @@ const client = createClient({
     allow_experimental_dynamic_type: 1,
     allow_experimental_json_type: 1,
   },
-})
+});
 
 await client.command({
   query: `
@@ -75,16 +75,16 @@ await client.command({
     ENGINE MergeTree
     ORDER BY id
   `,
-})
+});
 
 await client.insert({
-  table: 'chjs_dynamic_variant_json',
-  format: 'JSONEachRow',
+  table: "chjs_dynamic_variant_json",
+  format: "JSONEachRow",
   values: [
-    { id: 1, var: 42, dynamic: 'foo', json: { foo: 'x' } },
-    { id: 2, var: 'str', dynamic: 144, json: { bar: 10 } },
+    { id: 1, var: 42, dynamic: "foo", json: { foo: "x" } },
+    { id: 2, var: "str", dynamic: 144, json: { bar: 10 } },
   ],
-})
+});
 
 const rs = await client.query({
   query: `
@@ -95,36 +95,36 @@ const rs = await client.query({
            dynamicType(json.bar)
     FROM chjs_dynamic_variant_json
   `,
-  format: 'JSONEachRow',
-})
-console.log(await rs.json())
+  format: "JSONEachRow",
+});
+console.log(await rs.json());
 ```
 
 Outputs:
 
 ```js
-;[
+[
   {
-    id: '1',
-    var: '42',
-    dynamic: 'foo',
-    json: { foo: 'x' },
-    'variantType(var)': 'Int64',
-    'dynamicType(dynamic)': 'String',
-    'dynamicType(json.foo)': 'String',
-    'dynamicType(json.bar)': 'None',
+    id: "1",
+    var: "42",
+    dynamic: "foo",
+    json: { foo: "x" },
+    "variantType(var)": "Int64",
+    "dynamicType(dynamic)": "String",
+    "dynamicType(json.foo)": "String",
+    "dynamicType(json.bar)": "None",
   },
   {
-    id: '2',
-    var: 'str',
-    dynamic: '144',
-    json: { bar: '10' },
-    'variantType(var)': 'String',
-    'dynamicType(dynamic)': 'Int64',
-    'dynamicType(json.foo)': 'None',
-    'dynamicType(json.bar)': 'Int64',
+    id: "2",
+    var: "str",
+    dynamic: "144",
+    json: { bar: "10" },
+    "variantType(var)": "String",
+    "dynamicType(dynamic)": "Int64",
+    "dynamicType(json.foo)": "None",
+    "dynamicType(json.bar)": "Int64",
   },
-]
+];
 ```
 
 ### Notes
@@ -149,7 +149,7 @@ sub-second precision (`p` digits, up to `9` for nanoseconds). Both require
 ```ts
 const client = createClient({
   clickhouse_settings: { enable_time_time64_type: 1 },
-})
+});
 
 await client.command({
   query: `
@@ -165,38 +165,38 @@ await client.command({
     ENGINE MergeTree
     ORDER BY id
   `,
-})
+});
 
 await client.insert({
-  table: 'chjs_time_time64',
-  format: 'JSONEachRow',
+  table: "chjs_time_time64",
+  format: "JSONEachRow",
   values: [
     {
       id: 1,
-      t: '12:34:56',
-      t64_0: '12:34:56',
-      t64_3: '12:34:56.123',
-      t64_6: '12:34:56.123456',
-      t64_9: '12:34:56.123456789',
+      t: "12:34:56",
+      t64_0: "12:34:56",
+      t64_3: "12:34:56.123",
+      t64_6: "12:34:56.123456",
+      t64_9: "12:34:56.123456789",
     },
     {
       id: 2,
-      t: '999:59:59',
-      t64_0: '999:59:59',
-      t64_3: '999:59:59.999',
-      t64_6: '999:59:59.999999',
-      t64_9: '999:59:59.999999999',
+      t: "999:59:59",
+      t64_0: "999:59:59",
+      t64_3: "999:59:59.999",
+      t64_6: "999:59:59.999999",
+      t64_9: "999:59:59.999999999",
     },
     {
       id: 3,
-      t: '-999:59:59',
-      t64_0: '-999:59:59',
-      t64_3: '-999:59:59.999',
-      t64_6: '-999:59:59.999999',
-      t64_9: '-999:59:59.999999999',
+      t: "-999:59:59",
+      t64_0: "-999:59:59",
+      t64_3: "-999:59:59.999",
+      t64_6: "-999:59:59.999999",
+      t64_9: "-999:59:59.999999999",
     },
   ],
-})
+});
 ```
 
 ### Notes
@@ -228,16 +228,16 @@ ClickHouse handle the bit-plane layout — don't feed raw `FixedString` bytes
 through JSON yourself.
 
 ```ts
-import { createClient } from '@clickhouse/client'
+import { createClient } from "@clickhouse/client";
 
-const tableName = `chjs_qbit`
+const tableName = `chjs_qbit`;
 const client = createClient({
   clickhouse_settings: {
     // QBit introduced in ClickHouse 25.10 (experimental), GA since 26.x.
     // This setting is required only on 25.10; harmless/no-op on >= 26.x.
     allow_experimental_qbit_type: 1,
   },
-})
+});
 
 await client.command({
   query: `
@@ -249,7 +249,7 @@ await client.command({
     ENGINE MergeTree
     ORDER BY id
   `,
-})
+});
 
 // Even though QBit is stored internally as a Tuple of FixedString bit planes,
 // JSON* formats accept (and return) the original Array(Float32) shape.
@@ -257,21 +257,21 @@ const values = [
   { id: 1, vec: [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0] },
   { id: 2, vec: [8.0, 7.0, 6.0, 5.0, 4.0, 3.0, 2.0, 1.0] },
   { id: 3, vec: [1.5, 2.5, 3.5, 4.5, 5.5, 6.5, 7.5, 8.5] },
-]
+];
 await client.insert({
   table: tableName,
-  format: 'JSONEachRow',
+  format: "JSONEachRow",
   values,
-})
+});
 
 // Round-trip via JSONEachRow: the vec column comes back as an array of numbers.
 const rs = await client.query({
   query: `SELECT id, vec FROM ${tableName} ORDER BY id`,
-  format: 'JSONEachRow',
-})
-const rows = await rs.json<{ id: number; vec: number[] }>()
+  format: "JSONEachRow",
+});
+const rows = await rs.json<{ id: number; vec: number[] }>();
 // vec comes back unchanged as the original Float32 array.
-console.log(rows)
+console.log(rows);
 
 // Approximate vector search via L2DistanceTransposed.
 // The third argument is the precision in bits: lower = less I/O, less accurate.
@@ -286,13 +286,13 @@ const search = await client.query({
     ref: [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0],
     bits: 16,
   },
-  format: 'JSONEachRow',
-})
-const nearest = await search.json<{ id: number; dist: number }>()
+  format: "JSONEachRow",
+});
+const nearest = await search.json<{ id: number; dist: number }>();
 // The reference vector is exactly row #1, so it's the closest match (dist 0).
-console.log(nearest)
+console.log(nearest);
 
-await client.close()
+await client.close();
 ```
 
 ### Notes

package/skills/clickhouse-js-node-coding/reference/insert-columns.md

@@ -22,11 +22,11 @@ get their declared default.
 
 ```ts
 await client.insert({
-  table: 'events',
-  columns: ['message'], // the rest of the events table columns get their DEFAULTs
-  format: 'JSONEachRow',
-  values: [{ message: 'foo' }],
-})
+  table: "events",
+  columns: ["message"], // the rest of the events table columns get their DEFAULTs
+  format: "JSONEachRow",
+  values: [{ message: "foo" }],
+});
 ```
 
 ## Insert excluding columns
@@ -36,11 +36,11 @@ should default but you want to name only the few to skip.
 
 ```ts
 await client.insert({
-  table: 'events',
-  format: 'JSONEachRow',
-  values: [{ message: 'bar' }],
-  columns: { except: ['id'] },
-})
+  table: "events",
+  format: "JSONEachRow",
+  values: [{ message: "bar" }],
+  columns: { except: ["id"] },
+});
 ```
 
 ## Tables with EPHEMERAL columns
@@ -62,18 +62,18 @@ await client.command({
     ENGINE MergeTree
     ORDER BY id
   `,
-})
+});
 
 await client.insert({
-  table: 'events',
-  format: 'JSONEachRow',
+  table: "events",
+  format: "JSONEachRow",
   values: [
-    { id: '42', message_default: 'foo' },
-    { id: '144', message_default: 'bar' },
+    { id: "42", message_default: "foo" },
+    { id: "144", message_default: "bar" },
   ],
   // Including the ephemeral column name triggers the DEFAULT expression
-  columns: ['id', 'message_default'],
-})
+  columns: ["id", "message_default"],
+});
 ```
 
 ## Insert into a different database
@@ -82,15 +82,15 @@ If the client's default `database` is not the target, qualify the table name
 with `db.table`:
 
 ```ts
-const client = createClient({ database: 'system' })
+const client = createClient({ database: "system" });
 
-await client.command({ query: 'CREATE DATABASE IF NOT EXISTS analytics' })
+await client.command({ query: "CREATE DATABASE IF NOT EXISTS analytics" });
 
 await client.insert({
-  table: 'analytics.events', // fully qualified
-  format: 'JSONEachRow',
-  values: [{ id: 42, message: 'foo' }],
-})
+  table: "analytics.events", // fully qualified
+  format: "JSONEachRow",
+  values: [{ id: 42, message: "foo" }],
+});
 ```
 
 There is no per-call `database` override on `insert()` / `query()` — qualify

package/skills/clickhouse-js-node-coding/reference/insert-formats.md

@@ -27,20 +27,20 @@ When answering "what format/call should I use for an array of JS objects?":
 This is the right answer for ~90% of inserts.
 
 ```ts
-import { createClient } from '@clickhouse/client'
+import { createClient } from "@clickhouse/client";
 
-const client = createClient()
+const client = createClient();
 
 await client.insert({
-  table: 'events',
-  format: 'JSONEachRow',
+  table: "events",
+  format: "JSONEachRow",
   values: [
-    { id: 42, name: 'foo' },
-    { id: 43, name: 'bar' },
+    { id: 42, name: "foo" },
+    { id: 43, name: "bar" },
   ],
-})
+});
 
-await client.close()
+await client.close();
 ```
 
 The shape of `values` must match the chosen format.
@@ -60,15 +60,15 @@ The shape of `values` must match the chosen format.
 
 ```ts
 await client.insert({
-  table: 'events',
-  format: 'JSONCompactEachRowWithNamesAndTypes',
+  table: "events",
+  format: "JSONCompactEachRowWithNamesAndTypes",
   values: [
-    ['id', 'name', 'sku'],
-    ['UInt32', 'String', 'Array(UInt32)'],
-    [11, 'foo', [1, 2, 3]],
-    [12, 'bar', [4, 5, 6]],
+    ["id", "name", "sku"],
+    ["UInt32", "String", "Array(UInt32)"],
+    [11, "foo", [1, 2, 3]],
+    [12, "bar", [4, 5, 6]],
   ],
-})
+});
 ```
 
 These formats can be **streamed** — pass a Node stream of rows instead of an
@@ -88,33 +88,33 @@ These cannot be streamed — the entire body is sent in one shot.
 | `JSONObjectEachRow`       | `Record<string, { col: value, ... }>` (the record key labels each row but is not stored)                                  |
 
 ```ts
-import type { InputJSON, InputJSONObjectEachRow } from '@clickhouse/client'
+import type { InputJSON, InputJSONObjectEachRow } from "@clickhouse/client";
 
-const meta: InputJSON['meta'] = [
-  { name: 'id', type: 'UInt32' },
-  { name: 'name', type: 'String' },
-]
+const meta: InputJSON["meta"] = [
+  { name: "id", type: "UInt32" },
+  { name: "name", type: "String" },
+];
 
 await client.insert({
-  table: 'events',
-  format: 'JSONCompact',
+  table: "events",
+  format: "JSONCompact",
   values: {
     meta,
     data: [
-      [19, 'foo'],
-      [20, 'bar'],
+      [19, "foo"],
+      [20, "bar"],
     ],
   },
-})
+});
 
 await client.insert({
-  table: 'events',
-  format: 'JSONObjectEachRow',
+  table: "events",
+  format: "JSONObjectEachRow",
   values: {
-    row_1: { id: 23, name: 'foo' },
-    row_2: { id: 24, name: 'bar' },
+    row_1: { id: 23, name: "foo" },
+    row_2: { id: 24, name: "bar" },
   } satisfies InputJSONObjectEachRow<{ id: number; name: string }>,
-})
+});
 ```
 
 ## Quick chooser