@clickhouse/client 1.18.4 → 1.18.5-head.09b78f0.1

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

@@ -0,0 +1,145 @@
+# Insert Data Formats
+
+> **Applies to:** all versions. The `JSON` type column / new JSON family is a
+> ClickHouse feature; the JSON _formats_ listed here are universally supported
+> by the client.
+
+Backing examples:
+[`examples/node/coding/array_json_each_row.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/array_json_each_row.ts),
+[`examples/node/coding/insert_data_formats_overview.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/insert_data_formats_overview.ts).
+
+> **Raw / binary formats (CSV, TSV, CustomSeparated, Parquet) require a Node
+> stream as input.** See
+> [`examples/node/performance/`](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/node/performance)
+> — defer if the user wants to insert from a file or `Readable`.
+
+## Answer checklist
+
+When answering "what format/call should I use for an array of JS objects?":
+
+- Use `client.insert({ table, values, format: 'JSONEachRow' })`.
+- Say the array of plain objects can be passed directly as `values` for
+  ordinary in-memory batches such as a few thousand or tens of thousands of
+  rows.
+- Do not steer the user to streaming, Parquet, or file APIs unless their input
+  is already a stream/file or the task is explicitly about throughput.
+- Warn not to wrap `JSONEachRow` rows in a `{ data: [...] }` envelope; that
+  shape belongs to single-document formats.
+- Mention `JSONCompactEachRow*` as a denser alternative for larger payloads
+  when the caller can provide positional arrays or explicit names/types.
+
+## Default choice: `JSONEachRow` with an array of objects
+
+This is the right answer for ~90% of inserts.
+
+```ts
+import { createClient } from '@clickhouse/client'
+
+const client = createClient()
+
+await client.insert({
+  table: 'events',
+  format: 'JSONEachRow',
+  values: [
+    { id: 42, name: 'foo' },
+    { id: 43, name: 'bar' },
+  ],
+})
+
+await client.close()
+```
+
+The shape of `values` must match the chosen format.
+
+## Streamable JSON formats (pass an array)
+
+| Format                                       | `values` shape                                      |
+| -------------------------------------------- | --------------------------------------------------- |
+| `JSONEachRow`                                | `Array<{ col: value, ... }>`                        |
+| `JSONStringsEachRow`                         | `Array<{ col: stringifiedValue, ... }>`             |
+| `JSONCompactEachRow`                         | `Array<[v1, v2, ...]>`                              |
+| `JSONCompactStringsEachRow`                  | `Array<[stringV1, stringV2, ...]>`                  |
+| `JSONCompactEachRowWithNames`                | First row = column names, then data rows            |
+| `JSONCompactEachRowWithNamesAndTypes`        | Row 1 = names, row 2 = types, then data             |
+| `JSONCompactStringsEachRowWithNames`         | First row = names, then stringified data rows       |
+| `JSONCompactStringsEachRowWithNamesAndTypes` | Row 1 = names, row 2 = types, then stringified data |
+
+```ts
+await client.insert({
+  table: 'events',
+  format: 'JSONCompactEachRowWithNamesAndTypes',
+  values: [
+    ['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
+array. See
+[`examples/node/performance/`](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/node/performance)
+for streaming guidance.
+
+## Single-document JSON formats (pass an object)
+
+These cannot be streamed — the entire body is sent in one shot.
+
+| Format                    | `values` shape (typed via `InputJSON<T>` / `InputJSONObjectEachRow<T>`)                                                   |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `JSON`                    | `{ meta: [], data: Array<{ col: value, ... }> }` — for TypeScript/client usage, pass `meta: []` if metadata is not needed |
+| `JSONCompact`             | `{ meta: [{ name, type }, ...], data: Array<[v1, v2, ...]> }`                                                             |
+| `JSONColumnsWithMetadata` | `{ meta: [...], data: { col1: [v, ...], col2: [v, ...] } }`                                                               |
+| `JSONObjectEachRow`       | `Record<string, { col: value, ... }>` (the record key labels each row but is not stored)                                  |
+
+```ts
+import type { InputJSON, InputJSONObjectEachRow } from '@clickhouse/client'
+
+const meta: InputJSON['meta'] = [
+  { name: 'id', type: 'UInt32' },
+  { name: 'name', type: 'String' },
+]
+
+await client.insert({
+  table: 'events',
+  format: 'JSONCompact',
+  values: {
+    meta,
+    data: [
+      [19, 'foo'],
+      [20, 'bar'],
+    ],
+  },
+})
+
+await client.insert({
+  table: 'events',
+  format: 'JSONObjectEachRow',
+  values: {
+    row_1: { id: 23, name: 'foo' },
+    row_2: { id: 24, name: 'bar' },
+  } satisfies InputJSONObjectEachRow<{ id: number; name: string }>,
+})
+```
+
+## Quick chooser
+
+| Use case                                     | Format                                            |
+| -------------------------------------------- | ------------------------------------------------- |
+| Insert plain JS objects                      | `JSONEachRow` _(default)_                         |
+| Insert tuples / column-positional rows       | `JSONCompactEachRow`                              |
+| Insert with explicit column ordering / types | `JSONCompactEachRow*WithNames…`                   |
+| Insert a single document with metadata       | `JSON`, `JSONCompact`                             |
+| Insert from a CSV / TSV / Parquet file       | Raw format + Node stream → `examples/node/performance/` |
+
+## Common pitfalls
+
+- **Wrong shape for the format.** The most common cause of insert failures —
+  e.g., passing `Array<{...}>` to `JSONCompact` (which expects
+  `{ meta, data }`).
+- **Don't wrap a `JSONEachRow` array in a `{ data: [...] }` envelope.** That
+  envelope only belongs to single-document formats (`JSON` / `JSONCompact` /
+  `JSONColumnsWithMetadata`).
+- For type guidance (`Decimal` strings, `Date` objects, `BigInt`), see
+  `insert-values.md` and `custom-json.md`.

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

@@ -0,0 +1,141 @@
+# Insert Values, SQL Expressions, Dates, Decimals
+
+> **Applies to:** all versions. `wait_end_of_query: 1` is a server-side
+> setting available on every supported ClickHouse version.
+
+Backing examples:
+[`examples/node/coding/insert_from_select.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/insert_from_select.ts),
+[`examples/node/coding/insert_values_and_functions.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/insert_values_and_functions.ts),
+[`examples/node/coding/insert_js_dates.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/insert_js_dates.ts),
+[`examples/node/coding/insert_decimals.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/insert_decimals.ts).
+
+## `INSERT … SELECT` (no values payload)
+
+When the data already lives in ClickHouse, use `client.command()` with a raw
+`INSERT … SELECT`:
+
+```ts
+await client.command({
+  query: `
+    INSERT INTO target
+    SELECT '42', quantilesBFloat16State(0.5)(arrayJoin([toFloat32(10), toFloat32(20)]))
+  `,
+})
+```
+
+Use `command()` (not `insert()`) — there is no row payload to send.
+
+## `INSERT … VALUES` with SQL functions
+
+When you need `unhex(...)`, `toUUID(...)`, `now()`, or any other SQL
+function around a value, keep the SQL shape static and pass values with
+ClickHouse `{name: Type}` parameters. Run it via `command()` and set
+`wait_end_of_query: 1` for safety in clustered setups.
+
+```ts
+await client.command({
+  query: `
+    INSERT INTO events (id, timestamp, email, name)
+    VALUES (
+      unhex({id: String}),
+      {timestamp: DateTime},
+      {email: String},
+      {name: Nullable(String)}
+    )
+  `,
+  query_params: {
+    id: '00112233445566778899aabbccddeeff',
+    timestamp: '2026-05-06 12:34:56',
+    email: 'alice@example.com',
+    name: 'Alice',
+  },
+  clickhouse_settings: { wait_end_of_query: 1 },
+})
+```
+
+Do not build `VALUES` rows with string interpolation or manual escaping. If
+you need to insert many ordinary JS rows, prefer `client.insert()` with
+`format: 'JSONEachRow'`; use this `command()` pattern when the SQL itself needs
+functions or expressions around the values.
+
+## Inserting JS `Date` objects
+
+JS `Date` objects work for `DateTime` and `DateTime64` columns once the
+server is set to accept ISO-8601 strings. Either set
+`date_time_input_format: 'best_effort'` per request, on the client, or
+session-wide.
+
+```ts
+await client.insert({
+  table: 'events',
+  format: 'JSONEachRow',
+  values: [{ id: '42', dt: new Date() }],
+  clickhouse_settings: {
+    date_time_input_format: 'best_effort',
+  },
+})
+```
+
+> JS `Date` objects do **not** work for the `Date` type (date-only) — pass
+> `'YYYY-MM-DD'` strings for that.
+
+## Inserting `Decimal*` values
+
+Decimals must be passed as **strings** in JSON formats to avoid precision
+loss in JavaScript:
+
+```ts
+await client.command({
+  query: `
+    CREATE OR REPLACE TABLE prices (
+      id     UInt32,
+      dec32  Decimal(9, 2),
+      dec64  Decimal(18, 3),
+      dec128 Decimal(38, 10),
+      dec256 Decimal(76, 20)
+    )
+    ENGINE MergeTree ORDER BY id
+  `,
+})
+
+await client.insert({
+  table: 'prices',
+  format: 'JSONEachRow',
+  values: [
+    {
+      id: 1,
+      dec32: '1234567.89',
+      dec64: '123456789123456.789',
+      dec128: '1234567891234567891234567891.1234567891',
+      dec256:
+        '12345678912345678912345678911234567891234567891234567891.12345678911234567891',
+    },
+  ],
+})
+```
+
+When reading them back, cast to string in the SELECT to avoid the same
+precision loss:
+
+```ts
+const rs = await client.query({
+  query: `
+    SELECT toString(dec64)  AS decimal64,
+           toString(dec128) AS decimal128
+    FROM prices
+  `,
+  format: 'JSONEachRow',
+})
+```
+
+## Common pitfalls
+
+- **Passing decimals as JS `number`s.** Anything beyond `Number.MAX_SAFE_INTEGER`
+  silently loses precision before it ever reaches the server.
+- **Using `client.insert()` for `INSERT … SELECT`.** There's nothing to
+  upload — use `client.command()` with the full SQL.
+- **Forgetting `date_time_input_format: 'best_effort'`** when inserting
+  `Date` objects (or ISO strings). The default input format does not accept
+  ISO-8601 with the `T`/`Z` separators.
+- **Hand-building `VALUES` with user input.** Always parameterize user data;
+  see `reference/query-parameters.md`.

package/skills/clickhouse-js-node-coding/reference/ping.md

@@ -0,0 +1,120 @@
+# Ping the Server
+
+> **Applies to:** all versions. `ping()` returns a discriminated
+> `PingResult = { success: true } | { success: false, error: Error }` —
+> it does **not** throw on connection failures.
+
+Backing examples:
+[`examples/node/coding/ping_existing_host.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/ping_existing_host.ts),
+[`examples/node/coding/ping_non_existing_host.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/ping_non_existing_host.ts).
+
+## Successful ping
+
+```ts
+import { createClient } from '@clickhouse/client'
+
+const client = createClient({
+  url: process.env.CLICKHOUSE_URL,
+  password: process.env.CLICKHOUSE_PASSWORD,
+})
+
+const pingResult = await client.ping()
+if (pingResult.success) {
+  console.info('ClickHouse is reachable')
+} else {
+  console.error('Ping failed:', pingResult.error)
+}
+await client.close()
+```
+
+Use `ping()` to:
+
+- Probe ClickHouse at application startup.
+- Wake up a ClickHouse Cloud instance that may be idling (a ping is enough to
+  bring it out of sleep).
+- Implement a `/healthz` / readiness endpoint.
+
+## Failure: host unreachable
+
+`ping()` does **not** throw — it resolves with
+`{ success: false, error: Error }`, so you can branch without `try/catch`:
+
+```ts
+import type { PingResult } from '@clickhouse/client'
+import { createClient } from '@clickhouse/client'
+
+const client = createClient({
+  url: 'http://localhost:8100', // non-existing host
+  request_timeout: 50, // keep failure fast
+})
+
+const pingResult = await client.ping()
+if (hasConnectionRefusedError(pingResult)) {
+  console.info('Connection refused, as expected')
+} else {
+  console.error('Ping expected ECONNREFUSED, got:', pingResult)
+}
+await client.close()
+
+function hasConnectionRefusedError(
+  pingResult: PingResult,
+): pingResult is PingResult & { error: { code: 'ECONNREFUSED' } } {
+  return (
+    !pingResult.success &&
+    'code' in pingResult.error &&
+    pingResult.error.code === 'ECONNREFUSED'
+  )
+}
+```
+
+## Mapping to an HTTP health endpoint
+
+```ts
+app.get('/healthz', async (_req, res) => {
+  const r = await client.ping()
+  if (r.success) {
+    res.status(200).json({ ok: true })
+  } else {
+    res.status(503).json({ ok: false, error: String(r.error) })
+  }
+})
+```
+
+## `ping()` vs `ping({ select: true })`
+
+The default `ping()` hits ClickHouse's `/ping` HTTP endpoint — it verifies
+network connectivity but **does not check credentials or query processing**.
+A server that is reachable but has a bad password (or a broken query
+pipeline) will still return `{ success: true }` from a plain `ping()`.
+
+Pass `{ select: true }` to run a lightweight `SELECT 1` instead:
+
+```ts
+const r = await client.ping({ select: true })
+// success only if the server is reachable AND auth is correct AND it can run queries
+```
+
+|                         | `client.ping()` | `client.ping({ select: true })` |
+| ----------------------- | --------------- | ------------------------------- |
+| Endpoint                | `/ping` (HTTP)  | `SELECT 1` query                |
+| Checks auth             | **No**          | Yes                             |
+| Checks query processing | No              | **Yes**                         |
+| Overhead                | Minimal         | Slightly higher                 |
+
+**When to use which:**
+
+- **Liveness probe** (is the process alive?) — plain `ping()` is fine.
+- **Readiness probe** (can it serve traffic?) — use `ping({ select: true })`
+  so the probe fails if credentials are wrong or the query layer is broken.
+- **Waking a ClickHouse Cloud idle instance** — plain `ping()` is enough.
+
+## Common pitfalls
+
+- **Do not wrap `ping()` in `try/catch` as your only check.** It resolves on
+  failure; the `success` boolean is the source of truth.
+- **Lower `request_timeout` if you want pings to fail fast** (the example
+  above uses `50` ms). The default is high enough to be unsuitable for
+  liveness probes.
+- **Plain `ping()` does not check credentials.** If auth is part of what you
+  want to verify, use `ping({ select: true })`.
+- For ping that times out specifically, see the troubleshooting skill.

package/skills/clickhouse-js-node-coding/reference/query-parameters.md

@@ -0,0 +1,152 @@
+# Query Parameter Binding
+
+> **Applies to:** all versions. NULL parameter binding fixed in `0.0.16`.
+> Special-character (tab/newline/quote/backslash) binding `>= 0.3.1`.
+> `TupleParam` and JS `Map` parameters `>= 1.9.0`. Boolean formatting in
+> `Array`/`Tuple`/`Map` parameters fixed in `>= 1.13.0`. `BigInt` query
+> parameters `>= 1.15.0`.
+
+Backing examples:
+[`examples/node/coding/query_with_parameter_binding.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/query_with_parameter_binding.ts),
+[`examples/node/coding/query_with_parameter_binding_special_chars.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/query_with_parameter_binding_special_chars.ts).
+
+## Answer checklist
+
+When the user passes user-controlled values into SQL:
+
+- Use ClickHouse `{name: Type}` placeholders and a `query_params` object.
+- Explicitly call template-literal/string interpolation of user input a
+  **SQL injection risk**.
+- Do not suggest PostgreSQL/MySQL-style `$1`, `?`, or `:name` placeholders.
+- Pick the placeholder type to match the ClickHouse column type (`String`,
+  `Date`, `DateTime`, `Nullable(T)`, etc.).
+
+## Syntax: `{name: Type}`
+
+ClickHouse uses `{name: Type}` placeholders — **not** `$1`, `?`, or `:name`.
+
+```ts
+await client.query({
+  query: 'SELECT plus({a: Int32}, {b: Int32})',
+  format: 'JSONEachRow',
+  query_params: { a: 10, b: 20 },
+})
+```
+
+The `Type` must be a valid ClickHouse type (`Int32`, `String`, `Date`,
+`Array(UInt32)`, `Tuple(Int32, String)`, `Map(K, V)`, `Nullable(T)`, etc.).
+
+## ⚠️ Never use template literals for user values
+
+Interpolating user input into the SQL string bypasses server-side escaping
+and opens the door to SQL injection:
+
+```ts
+// ❌ Dangerous — never do this with user-controlled values
+const userId = req.params.id
+await client.query({ query: `SELECT * FROM users WHERE id = ${userId}` })
+
+// ✓ Safe — parameterized
+await client.query({
+  query: 'SELECT * FROM users WHERE id = {id: UInt32}',
+  query_params: { id: userId },
+})
+```
+
+This is the most common mistake for users coming from PostgreSQL/MySQL. Call
+it out explicitly when the user shows template-literal interpolation.
+
+## Common types
+
+```ts
+import { TupleParam } from '@clickhouse/client'
+
+await client.query({
+  query: `
+    SELECT
+      {var_int: Int32}                     AS var_int,
+      {var_float: Float32}                 AS var_float,
+      {var_str: String}                    AS var_str,
+      {var_array: Array(Int32)}            AS var_array,
+      {var_tuple: Tuple(Int32, String)}    AS var_tuple,
+      {var_map: Map(Int, Array(String))}   AS var_map,
+      {var_date: Date}                     AS var_date,
+      {var_datetime: DateTime}             AS var_datetime,
+      {var_datetime64_3: DateTime64(3)}    AS var_datetime64_3,
+      {var_datetime64_9: DateTime64(9)}    AS var_datetime64_9,
+      {var_decimal: Decimal(9, 2)}         AS var_decimal,
+      {var_uuid: UUID}                     AS var_uuid,
+      {var_ipv4: IPv4}                     AS var_ipv4,
+      {var_null: Nullable(String)}         AS var_null
+  `,
+  format: 'JSONEachRow',
+  query_params: {
+    var_int: 10,
+    var_float: '10.557',
+    var_str: 'hello',
+    var_array: [42, 144],
+    var_tuple: new TupleParam([42, 'foo']), // >= 1.9.0
+    var_map: new Map([
+      [42, ['a', 'b']],
+      [144, ['c', 'd']],
+    ]), // >= 1.9.0
+    var_date: '2022-01-01',
+    var_datetime: '2022-01-01 12:34:56', // or a Date
+    var_datetime64_3: '2022-01-01 12:34:56.789', // or a Date
+    var_datetime64_9: '2022-01-01 12:34:56.123456789', // string for ns precision
+    var_decimal: '123.45', // string to avoid precision loss
+    var_uuid: '01234567-89ab-cdef-0123-456789abcdef',
+    var_ipv4: '192.168.0.1',
+    var_null: null, // fixed in 0.0.16
+  },
+})
+```
+
+### Type-by-type tips
+
+- **Decimals** — pass as strings to avoid JS number precision loss.
+- **`DateTime64(>3)`** — pass as a string; JS `Date` only has millisecond
+  precision and will lose sub-millisecond digits.
+- **`DateTime64`** — strings can also be UNIX timestamps, including
+  fractional ones (e.g., `'1651490755.123456789'`).
+- **`BigInt`** — supported in `query_params` since `>= 1.15.0`. On older
+  clients, pass as a string.
+- **`Tuple(...)`** — wrap in `new TupleParam([...])` (`>= 1.9.0`); on older
+  clients, build the literal manually as a string.
+- **`Map(K, V)`** — pass a JS `Map` (`>= 1.9.0`); on older clients, build
+  it manually.
+- **`Nullable(T)`** — pass `null` directly (`>= 0.0.16`).
+
+## Special characters in string parameters (`>= 0.3.1`)
+
+Tabs, newlines, carriage returns, single quotes, and backslashes are
+escaped automatically by the client — just pass the JS string as-is:
+
+```ts
+await client.query({
+  query: `
+    SELECT
+      'foo_\t_bar'  = {tab: String}             AS has_tab,
+      'foo_\n_bar'  = {newline: String}         AS has_newline,
+      'foo_\\'_bar' = {single_quote: String}    AS has_single_quote,
+      'foo_\\_bar'  = {backslash: String}       AS has_backslash
+  `,
+  format: 'JSONEachRow',
+  query_params: {
+    tab: 'foo_\t_bar',
+    newline: 'foo_\n_bar',
+    single_quote: "foo_'_bar",
+    backslash: 'foo_\\_bar',
+  },
+})
+```
+
+## Common pitfalls
+
+- **`$1` / `?` / `:name` placeholders.** None work — use `{name: Type}`.
+- **Forgetting the type in the placeholder.** `{id}` is a syntax error;
+  it must be `{id: UInt32}`.
+- **Stringifying tuples/maps manually on `>= 1.9.0`.** Use `TupleParam`
+  and `Map` — both serialize correctly and respect special characters.
+- **Boolean array/tuple/map elements before `1.13.0`.** Boolean formatting
+  was fixed in 1.13.0 — earlier versions may misformat them.

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

@@ -0,0 +1,111 @@
+# Select Data Formats
+
+> **Applies to:** all versions. `JSONEachRowWithProgress` requires client
+> `>= 1.7.0`; see the in-repo performance examples under
+> `examples/node/performance/`.
+
+Backing examples:
+[`examples/node/coding/select_json_each_row.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/select_json_each_row.ts),
+[`examples/node/coding/select_data_formats_overview.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/select_data_formats_overview.ts),
+[`examples/node/coding/select_json_with_metadata.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/select_json_with_metadata.ts).
+
+## Default choice: `JSONEachRow` → `.json<T>()`
+
+Right answer for ~90% of selects when the result fits in memory.
+
+```ts
+import { createClient } from '@clickhouse/client'
+
+interface Row {
+  number: string
+}
+
+const client = createClient()
+const rows = await client.query({
+  query: 'SELECT number FROM system.numbers LIMIT 5',
+  format: 'JSONEachRow',
+})
+const result = await rows.json<Row>() // Row[]
+result.forEach((r) => console.log(r))
+await client.close()
+```
+
+`UInt64`/`Int64` and other 64-bit integers are returned as **strings**
+when `output_format_json_quote_64bit_integers=1`, to avoid JS precision
+loss. If that setting is `0`, they may be returned as unquoted JSON
+numbers instead. Note that in ClickHouse `>= 25.8`, this setting can
+default to `0`; see the troubleshooting skill for ways to control that.
+
+## Single-document `JSON` format with metadata
+
+Use `JSON` (or `JSONCompact`) when you need ClickHouse's response envelope
+(rows + meta + statistics + row count). Type the result with
+`ResponseJSON<T>`:
+
+```ts
+import { createClient, type ResponseJSON } from '@clickhouse/client'
+
+const client = createClient()
+const rows = await client.query({
+  query: 'SELECT number FROM system.numbers LIMIT 2',
+  format: 'JSON',
+})
+const result = await rows.json<ResponseJSON<{ number: string }>>()
+console.info(result.meta, result.data, result.rows, result.statistics)
+await client.close()
+```
+
+> `JSON`, `JSONCompact`, `JSONStrings`, `JSONCompactStrings`,
+> `JSONColumnsWithMetadata`, `JSONObjectEachRow` are **single-document**
+> formats — they cannot be streamed. Use a `*EachRow` variant if you want
+> to stream.
+
+## Selecting raw text (CSV / TSV / CustomSeparated)
+
+Use `.text()` (not `.json()`) for raw textual formats:
+
+```ts
+const rs = await client.query({
+  query: 'SELECT number, number * 2 AS doubled FROM system.numbers LIMIT 3',
+  format: 'CSVWithNames',
+})
+console.log(await rs.text())
+```
+
+Streaming raw text/Parquet line-by-line belongs in
+[`examples/node/performance/`](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/node/performance)
+— in particular, Parquet exports use `client.exec()` and pipe the raw
+response stream rather than `ResultSet.stream()` (see
+[`select_parquet_as_file.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/performance/select_parquet_as_file.ts)).
+
+## Format chooser
+
+| Use case                                                 | Format                                                                                                                                                     |
+| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Read rows as JS objects                                  | `JSONEachRow` _(default)_                                                                                                                                  |
+| Read rows as positional tuples (smaller payload)         | `JSONCompactEachRow`                                                                                                                                       |
+| Need `meta` / `statistics` / `rows` envelope             | `JSON` or `JSONCompact` + `ResponseJSON<T>`                                                                                                                |
+| Read all values as strings (avoid number-precision loss) | `JSONStringsEachRow` / `JSONCompactStringsEachRow`                                                                                                         |
+| Stream very large result                                 | `JSONEachRow` / `JSONCompactEachRow` (see [`examples/node/performance/`](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/node/performance)) |
+| Export to CSV/TSV/Parquet                                | `CSV*`, `TabSeparated*`, `Parquet` (see [`examples/node/performance/`](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/node/performance))   |
+
+## ResultSet methods
+
+| Method               | Returns                                          | Notes                                                                                                                                                                                                                                                                                                                                |
+| -------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `await rs.json<T>()` | `T[]` for `*EachRow`, single-doc shape otherwise | Buffers the full response                                                                                                                                                                                                                                                                                                            |
+| `await rs.text()`    | `string`                                         | Buffers the full response — for textual formats only (CSV/TSV/etc.)                                                                                                                                                                                                                                                                  |
+| `rs.stream()`        | Node `Readable` of `Row[]` chunks                | Use for large newline-delimited results (`JSONEachRow`/`JSONCompactEachRow`/`CSV`/`TSV`); **not** suitable for binary formats like `Parquet` — for those, use `client.exec()` and pipe the raw response stream (see [`examples/node/performance/`](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/node/performance)) |
+| `rs.close()`         | `void` (synchronous)                             | Always call if you obtained `stream()` and stop reading early                                                                                                                                                                                                                                                                        |
+
+## Common pitfalls
+
+- **Calling `.json()` on a `JSON` (single-doc) result and expecting an
+  array.** You get a `ResponseJSON<T>` object; the rows are under
+  `.data`. Use `JSONEachRow` if you want a flat array.
+- **Leaving a `stream()` half-consumed.** This is a top cause of
+  `ECONNRESET` on the _next_ request — fully iterate the stream or call
+  `resultSet.close()` (synchronous — no `await`). (Diagnosis details live in the
+  troubleshooting skill.)
+- **Reaching for `.json()` on a CSV/TSV result.** Use `.text()` (or
+  `.stream()` for large results).