@clickhouse/client 1.22.0 → 1.23.0-head.c8dc8d8.1

package/skills/clickhouse-js-node-rowbinary-parser/case-studies/iot-rowbinary-vs-json.md

@@ -0,0 +1,83 @@
+# Case study: RowBinary vs JSON on a table of IoT readings
+
+**TL;DR** — On a dense fixed-width numeric row, the skill's optimized RowBinary
+reader decodes **3.5x faster than the best JSON format** (`JSONCompactEachRow`)
+and **5.4x faster than `JSONEachRow`**, over a wire that is **1.6–3.3x smaller**.
+This is the workload shape the [SKILL's format-choice
+guidance](../SKILL.md#first-is-rowbinary-even-the-right-format) points at
+RowBinary for — and the numbers below are _measured_, not assumed.
+
+Reproduce: `npx vitest bench --run tests/iot.bench.ts` (against a live
+ClickHouse server). Source: [`tests/iot.bench.ts`](../tests/iot.bench.ts),
+reader: [`src/examples/iot.ts`](../src/examples/iot.ts).
+
+## The data
+
+A table of IoT sensor readings — every column fixed-width, not a string in the
+row, so the whole record is a flat 41-byte run:
+
+```sql
+sensor_id   UInt32         -- 4 bytes
+ts          DateTime64(3)  -- 8 bytes
+temperature Float64        -- 8 bytes
+humidity    Float64        -- 8 bytes
+pressure    Float64        -- 8 bytes
+battery     Float32        -- 4 bytes
+status      UInt8          -- 1 byte
+```
+
+50,000 rows, fetched from a live server in three formats and decoded into
+equivalent JS objects. A cross-format check asserts the RowBinary (binary
+float) and JSON (decimal-text → float) decodes agree on every numeric column
+before any timing is taken — so this measures the same work three ways, not
+three different results.
+
+## What was compared
+
+- **RowBinary — optimized.** The skill's monomorphized reader: the seven column
+  bounds checks coalesce into one `advance(s, 41)`, every field read at a
+  constant offset off that base.
+- **RowBinary — API combinators.** The same logic written with the plain
+  per-type readers (`readUInt32`, `readFloat64`, …) — the clear default.
+- **JSONCompactEachRow — `JSON.parse`.** Newline-delimited _arrays_ (no repeated
+  keys). The strongest JSON contender a knowledgeable user would pick.
+- **JSONEachRow — `JSON.parse`.** Newline-delimited _objects_ (keys repeated
+  every row) — the naive idiomatic choice.
+
+Both JSON paths use the fastest idiomatic decode: splice the rows into one
+`[...]` document and hand it to V8's native `JSON.parse` in a single call.
+
+## Wire size (HTTP response bytes)
+
+| Format             | Size    | B/row | vs RowBinary |
+| ------------------ | ------- | ----- | ------------ |
+| RowBinary          | 2.05 MB | 41.0  | 1.0x         |
+| JSONCompactEachRow | 3.38 MB | 67.6  | 1.6x         |
+| JSONEachRow        | 6.68 MB | 133.6 | 3.3x         |
+
+## Decode throughput (full 50k-row decode; higher = faster)
+
+| Decoder                           | ops/s | ms/decode | ≈ rows/s | speedup  |
+| --------------------------------- | ----- | --------- | -------- | -------- |
+| **RowBinary — optimized**         | 399   | 2.50      | ~20.0 M  | **1.0x** |
+| RowBinary — API combinators       | 159   | 6.31      | ~7.9 M   | 0.40x    |
+| JSONCompactEachRow — `JSON.parse` | 114   | 8.76      | ~5.7 M   | 0.29x    |
+| JSONEachRow — `JSON.parse`        | 74    | 13.47     | ~3.7 M   | 0.19x    |
+
+_Node 24 / V8. Your numbers will vary; run `npm run bench` on your own hardware._
+
+## Takeaways
+
+- **This is the textbook RowBinary win.** High-volume fixed-width numerics where
+  each field is one `DataView` read and there is no text to tokenize or numbers
+  to parse from decimal strings. The monomorphization win (2.5x over the
+  combinator API) is unusually large here because the whole row coalesces into a
+  _single_ bounds check with constant-offset reads.
+- **Format choice matters more than the optimization.** Even the plain
+  combinator-API RowBinary reader (~7.9 M rows/s) beats the best JSON option —
+  before any monomorphization.
+- **The flip side still holds.** Had this been a string-heavy result (logs, JSON
+  blobs, text consumed wholesale), `JSON.parse`'s optimized C++ would likely
+  _win_, and the skill would steer you to `JSONEachRow` + compression instead.
+  For IoT telemetry, RowBinary is clearly right — match the format to the shape
+  of the data.

package/skills/clickhouse-js-node-rowbinary-parser/case-studies/ledger-rowbinary-vs-json.md

@@ -0,0 +1,103 @@
+# Case study: RowBinary vs JSON on a financial ledger (wide ints & decimals)
+
+**TL;DR** — When every column is wider than a JS `number` can hold (`UInt128`,
+`Int64`, `Decimal128(18)`, `UInt256`), RowBinary wins _twice over_. Stock
+`JSON.parse` is not merely slow here — it is **silently wrong**, rounding every
+value to a float64. The only correct JSON path quotes the values server-side and
+re-parses each string into a `bigint`/decimal pair by hand, which is **~5x
+slower** than the optimized RowBinary reader over a **2.1–2.6x larger** wire.
+RowBinary reads each value exactly, straight off the wire.
+
+This is the workload the [SKILL's format-choice
+guidance](../SKILL.md#first-is-rowbinary-even-the-right-format) calls out
+explicitly: "RowBinary clearly wins when the result is dominated by **wide
+numerics** — `Int128`/`Int256`/`UInt128`/`UInt256`, `Decimal128`/`Decimal256`."
+
+Reproduce: `npx vitest bench --run tests/ledger.bench.ts` (against a live
+ClickHouse server). Source: [`tests/ledger.bench.ts`](../tests/ledger.bench.ts),
+reader: [`src/examples/ledger.ts`](../src/examples/ledger.ts).
+
+## The data
+
+A financial ledger — every column exceeds IEEE-754 double's 53-bit exact range:
+
+```sql
+txn_id   UInt128         -- 16 bytes
+account  Int64           --  8 bytes  (values past 2^53)
+amount   Decimal128(18)  -- 16 bytes  (~32 significant digits)
+balance  Decimal128(18)  -- 16 bytes
+fee      Decimal64(4)    --  8 bytes
+volume   UInt256         -- 32 bytes
+```
+
+50,000 rows, fixed-width (96 bytes/row), fetched from a live server.
+
+## The correctness trap
+
+ClickHouse emits these types as **bare, unquoted JSON numbers**. So stock
+`JSON.parse` parses them as float64 and silently corrupts every one — measured
+on row 0 of the live result:
+
+| Column    | Exact value (RowBinary)                   | `JSON.parse` of bare JSON                 |                  |
+| --------- | ----------------------------------------- | ----------------------------------------- | ---------------- |
+| `txn_id`  | `340282366920938463463374607431768200000` | `340282366920938463463374607431768211456` | ✗ off by 11 456  |
+| `account` | `9007199254740993`                        | `9007199254740992`                        | ✗ off by 1       |
+| `amount`  | `98765432109876.123456789012345678`       | `98765432109876.12`                       | ✗ lost 16 digits |
+
+No exception, no warning — just wrong numbers. For money and IDs, that is a
+correctness bug, not a performance footnote.
+
+### Making JSON correct costs extra work
+
+The only way to get exact values through JSON is to **quote them server-side** so
+they arrive as strings, then re-parse each one:
+
+```sql
+... SETTINGS output_format_json_quote_64bit_integers = 1,
+             output_format_json_quote_decimals = 1
+```
+
+```ts
+txn_id:  BigInt(r.txn_id),                 // string -> bigint
+amount:  parseDecimal(r.amount, 18),       // string -> [unscaled, scale]
+```
+
+That per-field `BigInt(...)` / decimal parse is work RowBinary doesn't do — it
+reads the exact `bigint` directly with two `DataView` reads — and it lands on
+top of a larger wire (strings are longer than the binary words).
+
+## Wire size (correct paths quote wide values as strings)
+
+| Format                      | Size     | vs RowBinary |
+| --------------------------- | -------- | ------------ |
+| RowBinary                   | 4.80 MB  | 1.0x         |
+| JSONCompactEachRow (quoted) | 9.88 MB  | 2.1x         |
+| JSONEachRow (quoted)        | 12.28 MB | 2.6x         |
+
+## Decode throughput (full 50k-row decode; higher = faster)
+
+| Decoder                                            | ops/s | ms/decode | ≈ rows/s | speedup  | correct?       |
+| -------------------------------------------------- | ----- | --------- | -------- | -------- | -------------- |
+| **RowBinary — optimized**                          | 130   | 7.71      | ~6.5 M   | **1.0x** | ✅             |
+| RowBinary — API combinators                        | 80    | 12.50     | ~4.0 M   | 0.62x    | ✅             |
+| JSONEachRow bare — `JSON.parse` only               | 44    | 22.74     | ~2.2 M   | 0.34x    | ❌ **corrupt** |
+| JSONCompactEachRow quoted — parse + BigInt/decimal | 26    | 37.78     | ~1.3 M   | 0.20x    | ✅             |
+| JSONEachRow quoted — parse + BigInt/decimal        | 25    | 40.70     | ~1.2 M   | 0.19x    | ✅             |
+
+_Node 24 / V8. Your numbers will vary; run `npm run bench` on your own hardware._
+
+## Takeaways
+
+- **The fast JSON path is the wrong one.** Bare `JSON.parse` is JSON's quickest
+  option and it is still 2.95x slower than RowBinary — _and_ it silently
+  corrupts every wide value. There is no "fast and correct" JSON here.
+- **The correct JSON path is ~5x slower.** Quote + per-field `BigInt`/decimal
+  parsing is the price of correctness, on top of a 2.1–2.6x larger wire.
+- **RowBinary is correct by construction.** Each value is composed from 64-bit
+  words read at constant offsets (high word signed for the signed types),
+  yielding an exact `bigint` or `[unscaled, scale]` pair — no rounding, no
+  string re-parsing.
+- **Contrast with the [IoT case study](iot-rowbinary-vs-json.md):** there the
+  numbers fit a float64 and the win was purely throughput (3.5x). Here the values
+  don't fit, so the win is _correctness first_, throughput second. Match the
+  format to the shape of the data.

package/skills/clickhouse-js-node-rowbinary-parser/case-studies/logs-json-wins.md

@@ -0,0 +1,86 @@
+# Case study: JSON beats RowBinary on a string-heavy log table
+
+**TL;DR** — This is the honest counter-case. When the result is mostly **text
+consumed wholesale** (an application log table), `JSONCompactEachRow` +
+`JSON.parse` decodes **1.4x faster** than the optimized RowBinary reader — and
+once you turn on HTTP compression, RowBinary's raw-wire size advantage
+**disappears**: gzip ties the two, and with **zstd the JSON response is actually
+slightly smaller**. For this shape the skill steers you _away_ from RowBinary —
+and proving that is what makes its "use RowBinary here" advice (see the
+[IoT](iot-rowbinary-vs-json.md) and [ledger](ledger-rowbinary-vs-json.md)
+studies) trustworthy.
+
+This is exactly what the [SKILL's format-choice
+guidance](../SKILL.md#first-is-rowbinary-even-the-right-format) says: prefer a
+`JSON*` format when the result is "mostly strings / JSON-like values that you
+consume wholesale," because V8's native `JSON.parse` is heavily optimized C++
+and "pair it with HTTP response compression (`gzip` / `zstd`, which crushes
+JSON's repetitive keys)."
+
+Reproduce: `npx vitest bench --run tests/logs.bench.ts` (against a live
+ClickHouse server). Source: [`tests/logs.bench.ts`](../tests/logs.bench.ts),
+reader: [`src/examples/logs.ts`](../src/examples/logs.ts).
+
+## The data
+
+An application log table — four of five columns are text consumed as text:
+
+```sql
+ts        DateTime
+level     LowCardinality(String)   -- transparent in RowBinary -> plain String
+service   LowCardinality(String)
+message   String                   -- templated log line, varying values
+trace_id  String                   -- high-cardinality 32-char hex
+```
+
+50,000 rows, fetched from a live server. The two `LowCardinality` columns carry
+no dictionary on the RowBinary wire — they decode as plain `String`.
+
+## Decode throughput (full 50k-row decode; higher = faster)
+
+| Decoder                               | ops/s | ms/decode | ≈ rows/s | speedup  |
+| ------------------------------------- | ----- | --------- | -------- | -------- |
+| **JSONCompactEachRow — `JSON.parse`** | 93    | 10.73     | ~4.7 M   | **1.0x** |
+| JSONEachRow — `JSON.parse`            | 72    | 13.89     | ~3.6 M   | 0.77x    |
+| RowBinary — optimized (monomorphized) | 66    | 15.07     | ~3.3 M   | 0.71x    |
+| RowBinary — API combinators           | 54    | 18.68     | ~2.7 M   | 0.57x    |
+
+`JSONCompactEachRow` (arrays, no repeated keys) is the fastest JSON option and
+beats even the optimized RowBinary reader by ~1.4x. A RowBinary string is a
+varint length + `buf.toString("utf8", …)` decoded one field at a time in JS;
+`JSON.parse` builds the same JS strings in one optimized C++ pass.
+
+## Wire size — raw, and compressed (gzip / zstd)
+
+| Format             | raw     | gzip    | zstd    |
+| ------------------ | ------- | ------- | ------- |
+| RowBinary          | 5.04 MB | 1.46 MB | 1.35 MB |
+| JSONCompactEachRow | 6.84 MB | 1.51 MB | 1.32 MB |
+| JSONEachRow        | 8.84 MB | 1.52 MB | 1.33 MB |
+
+RowBinary is 1.4–1.8x smaller **raw**, which is the usual argument for it. But
+that edge is mostly JSON's repeated structure (keys, punctuation) — exactly what
+a compressor removes. With `gzip` the three are within ~4% of each other, and
+with `zstd` the JSON responses are _slightly smaller_ than RowBinary. Any
+production HTTP path should have compression on, so the wire-size case for
+RowBinary on this data effectively vanishes.
+
+_Node 24 / V8. Your numbers will vary; run `npm run bench` on your own hardware._
+
+## Takeaways
+
+- **JSON wins both axes here.** Faster to decode (~1.4x) _and_, once compressed,
+  no larger on the wire. There is no reason to hand-write a RowBinary parser for
+  this shape.
+- **`JSONCompactEachRow` is the one to reach for** — it drops the per-row
+  repeated keys, so it parses faster than `JSONEachRow` and compresses about the
+  same.
+- **Compression erases RowBinary's raw-size advantage on text.** RowBinary's
+  smaller raw wire comes largely from not repeating keys; a compressor already
+  does that for JSON. Always compare _compressed_ sizes when the data is
+  string-heavy.
+- **This is the boundary of the skill.** RowBinary earns its keep on
+  numeric/wide/binary data ([IoT](iot-rowbinary-vs-json.md),
+  [ledger](ledger-rowbinary-vs-json.md)); on string-heavy results read as text,
+  the right answer is `JSONCompactEachRow` + compression. Match the format to the
+  shape of the data — and measure.

package/skills/clickhouse-js-node-rowbinary-parser/case-studies/wasm-vs-js.md

@@ -0,0 +1,172 @@
+# Case study: why JS, not WASM, for RowBinary parsing (and the one place WASM wins)
+
+**TL;DR** — A JIT-compiled JS RowBinary reader already streams bytes at **memory
+bandwidth** (~16 GB/s), and the dominant cost of decoding is allocating the JS
+values themselves (objects, `Date`, strings, `BigInt`) — which **WASM cannot do
+and therefore cannot remove**. So for the skill's actual job, turning a RowBinary
+response into usable JS data, WASM buys ~nothing (a wash, or a loss after the
+copy-in tax). WASM wins decisively in exactly **one** different problem:
+**in-place aggregation of wide integers / decimals** (and hash group-by), where
+JS is forced onto heap `BigInt`/`Map`. There we measured a hand-written WASM
+kernel at **27–38x** over JS. But that is _compute_, not parsing — and it is
+usually pushable to ClickHouse anyway. And if you genuinely need heavier
+**client-side analytics**, the lever isn't WASM-over-RowBinary at all — it's a
+**columnar wire format (`Native`)**, coming soon to the JS client out of the
+Python-client collaboration; RowBinary is row-major and fights every analytical
+pass.
+
+Reproduce:
+
+- `npx vitest bench --run tests/iot.wasm-headroom.bench.ts` (the parsing headroom)
+- `node tests/wasm-int128.experiment.mjs` (the hand-emitted WASM kernel)
+
+All numbers Node 24 / V8; yours will vary.
+
+## The idea under test
+
+A tempting architecture: a _dynamic WASM JIT inside the JS runtime_. A type
+builder (`t.Int32()`, `t.Map(t.FixedString, t.Int32())`) plus a query DSL
+(`q.sum(q.column(1))`) compile **on the fly** to a WASM module that parses the
+raw network chunk sitting at address 0 in linear memory, computes the answer,
+writes it to a result region, and returns the offset where the incomplete
+trailing row begins (streaming resume). Elegant. The question is _what it would
+win_ — and the honest answer needs three measurements.
+
+## Proof 1 — JIT-compiled JS reads at memory speed
+
+V8 compiles `DataView` accessors to native loads. Folding a 32 MB column of
+native-width values (`Float64`) in a plain JS loop:
+
+| Read                   | ms / 32 MB | throughput    |
+| ---------------------- | ---------- | ------------- |
+| JS `DataView` f64 fold | 1.94 ms    | **16.5 GB/s** |
+
+That is essentially RAM bandwidth. **There is no headroom for a "faster
+language" to read these bytes** — JS is already at the metal. A WASM parser
+reading the same bytes lands in the same place (see Proof 3, where the WASM
+kernel reads at 28 GB/s doing _integer_ loads — same order, also bandwidth-bound,
+not 10x).
+
+## Proof 2 — the parsing bottleneck is allocation, which WASM can't touch
+
+On the best case for RowBinary (IoT, every column fixed-width numeric), three
+decoders over the same buffer (`tests/iot.wasm-headroom.bench.ts`):
+
+| Decode                                               | ms   | vs current | what it isolates     |
+| ---------------------------------------------------- | ---- | ---------- | -------------------- |
+| **rows** — current fast reader (objects + `Date`)    | 3.48 | 1.0x       | full materialization |
+| **columnar** — into typed arrays, no per-row objects | 0.86 | 4.0x       | drop the objects     |
+| **parseOnly** — reads only, zero allocation          | 0.61 | 5.8x       | the pure-read floor  |
+
+**~83% of decode time is JS-side object/`Date` allocation**, not byte reading.
+A WASM parser still has to produce those JS values across the boundary, so it
+_cannot_ remove that 83%. Even if WASM made the parse slice instantaneous and the
+copy-in free, the row-object decode would drop only `3.48 → 2.88 ms` — a **max
+~1.2x**, and realistically a wash once you add the copy into linear memory.
+
+The 4.0x that _is_ on the table comes from the **output contract** (columnar
+typed arrays), and it's available in **plain JS** — no WASM. (That columnar path
+is worth shipping; it's the real win this whole investigation surfaced.)
+
+## Proof 3 — the one place WASM wins: wide-int / decimal aggregation
+
+Summing an `Int128` column forces JS onto heap `BigInt` (one allocation per
+row). A hand-emitted WASM kernel (94 bytes; native `i64` add-with-carry) does it
+in registers. Same 32 MB buffer, result verified equal to the BigInt sum
+(`tests/wasm-int128.experiment.mjs`):
+
+| Sum of an `Int128` column               | ms / 32 MB | throughput |                |
+| --------------------------------------- | ---------- | ---------- | -------------- |
+| **JS BigInt-128 sum** (what JS must do) | 42.93 ms   | 0.7 GB/s   | correct        |
+| WASM `i64` add-carry — kernel only      | 1.14 ms    | 28.2 GB/s  | correct        |
+| WASM + copy-in boundary tax             | 1.62 ms    | 19.7 GB/s  | (copy 0.49 ms) |
+
+**WASM is 37.8x faster than JS (26.5x including the copy into linear memory).**
+Note _why_: the win is escaping `BigInt`, not reading bytes faster — the WASM
+kernel (28 GB/s) is the same order as the JS f64 floor (16.5 GB/s). JS pays a
+**22x `BigInt` tax** purely to add 128-bit integers; WASM's native `i64` reclaims
+it. The same logic applies to `Decimal128/256` accumulation and to hash group-by
+(WASM open-addressing table in linear memory vs JS `Map` + GC).
+
+## Verdict on the dynamic-WASM-JIT
+
+The architecture is **sound for the aggregation regime and only that regime**.
+It targets the one quadrant where WASM beats well-written JS: _parse and compute
+in place, return a small result, never cross the boundary per value._ The design
+answers its own open questions well:
+
+- **Where does the answer go?** Scalars return directly (`i128` via multi-value
+  or two `i64`s); group-by results go to a reserved linear-memory region that JS
+  reads as a typed-array view — only the small final result crosses.
+- **Streaming.** Returning the resume offset (vs throwing across the FFI) is
+  clean, and accumulator state lives in linear memory across chunks — the module
+  _is_ the streaming aggregation state.
+
+But three caveats bound where it's worth building:
+
+1. **For parsing → JS values, use generated JS, not WASM.** Proofs 1–2: JS is
+   already at memory speed and the cost is materialization WASM can't remove. A
+   `DSL → new Function(generatedJS)` backend captures the parse + native-numeric
+   aggregation case with **zero toolchain**, debuggable. This is the skill's
+   existing monomorphization thesis.
+2. **Reserve a WASM backend for the wide-int/decimal + group-by kernels only** —
+   gate it on the presence of `Int128/256`, `Decimal128/256`, or a `GROUP BY`,
+   where Proof 3's 27–38x is real. For `Float64` sums it would tie JS.
+3. **SIMD won't help much** — RowBinary is row-major (AoS); strided columns
+   defeat Wasm SIMD (no gather) without a transpose pass. The WASM win here is
+   native `i64` + no GC, not vectorization.
+4. **The elephant: push it down.** `q.sum(col)` is `SELECT sum(col)` — ClickHouse
+   will beat any client. Client-side aggregation only justifies itself when you
+   _can't_ push down: folding a stream you already receive for another reason,
+   combining across queries/sources, or compute SQL can't express.
+
+## If you need more client-side analytical strength: reach for Native columnar
+
+Step back from WASM and look at _why_ the wins above are so narrow. RowBinary is
+**row-major (AoS)**: every row interleaves all columns, so any analytical pass —
+fold a column, vectorize, build a column-at-a-time accumulator — has to stride
+over the bytes it doesn't want and re-materialize a value at a time. That is the
+same row-major tax that defeats SIMD (caveat 3) and that makes the free **4x in
+Proof 2 cost a transpose** today (you decode rows, _then_ pack into typed
+arrays).
+
+So the honest answer to _"I need real client-side analytical strength"_ is **not
+a smarter parser over RowBinary, and not WASM** — it is a **columnar wire
+format**. ClickHouse's **`Native`** format is **column-major (SoA)**: each block
+arrives as contiguous per-column runs. That flips every constraint in this study:
+
+- The Proof-2 columnar typed-array path stops needing a transpose — the wire
+  _is_ already `Float64Array`-shaped, so you `subarray`/`set` a column in one
+  move instead of decoding rows first.
+- Vectorization becomes real: a contiguous column is exactly what `v128.load` /
+  SIMD (and even auto-vectorized JS) want — the gather problem disappears.
+- The wide-int/decimal aggregation win (Proof 3) keeps applying, now over
+  contiguous input, which is the friendliest possible layout for it.
+
+A columnar reader is **coming to the JS client soon**, out of the **collaboration
+with the Python client** (which already ships a mature `Native`/columnar path —
+the format and lessons port directly). When it lands, the order of preference for
+client-side analytics becomes: **push down to ClickHouse → if you can't, decode
+`Native` columnar → reserve WASM for the wide-int/decimal/group-by kernel on top
+of those columns.** RowBinary stays the right tool for what this skill targets —
+turning a result into JS _rows/values_ — not for analytics over them.
+
+## Takeaways
+
+- **Generated JS is the right engine for the parser.** It reads at memory
+  bandwidth; the remaining cost is JS-value materialization that no language
+  swap removes. WASM for parsing is a wash-to-loss.
+- **The free 4x is a columnar (typed-array) output contract — in pure JS.** Worth
+  capturing as a first-class option for numeric results.
+- **WASM earns its complexity in one place: in-place wide-int/decimal/group-by
+  aggregation** (27–38x measured), where JS is trapped in `BigInt`/`Map`. And
+  even then, prefer pushing the aggregation to ClickHouse unless you genuinely
+  can't.
+- **For real client-side analytical strength, the answer is columnar, not WASM.**
+  RowBinary is row-major and taxes every analytical pass; a `Native` (SoA)
+  columnar reader — coming to the JS client soon via the Python-client
+  collaboration — removes the transpose, unlocks SIMD, and is the natural
+  substrate for the aggregation kernels above.
+- Matches the rest of the studies' through-line: pick the tool for the shape of
+  the work, and **measure** — the 94-byte WASM kernel exists precisely so this
+  claim isn't hand-waved.

package/skills/clickhouse-js-node-rowbinary-parser/src/aggregateFunction.ts

@@ -0,0 +1,34 @@
+import { type Reader } from "./core.js";
+
+/**
+ * `AggregateFunction(func, T…)` holds an OPAQUE serialized aggregation STATE
+ * (what `-State` combinators produce). In RowBinary this state is written RAW,
+ * with **NO length prefix** and a layout entirely specific to `func` (and to the
+ * ClickHouse version): `sumState(UInt64)` is 8 bytes, `uniqState(...)` is a
+ * variable-length hash-set blob, etc.
+ *
+ * So it cannot be decoded generically (there is no schema in the bytes) and
+ * cannot even be SKIPPED generically (there is no length to skip past) — without
+ * knowing `func`'s exact byte layout you cannot find where it ends, and every
+ * later column in the row misaligns. There is therefore NO generic reader.
+ *
+ * Fix it server-side (RECOMMENDED): finalize with the `-Merge` combinator or
+ * `finalizeAggregation()` in SQL so the column becomes a normal value
+ * (`sum` -> `UInt64`, `uniq` -> `UInt64`, `avg` -> `Float64`, …) and use the
+ * matching reader. Never ship raw `-State` columns to the client unless you
+ * intend to merge them later.
+ *
+ * ESCAPE HATCH: a few functions' state IS just a value of a known type (e.g.
+ * `sumState(UInt64)` is literally that `UInt64`), so you may decode it as that
+ * type — fragile and version-specific; only when you truly know the layout. See
+ * `tests/aggregateFunction.test.ts`.
+ *
+ * This reader throws to stop a generic parser from silently misaligning the row.
+ */
+export const readAggregateFunction: Reader<never> = () => {
+  throw new Error(
+    "RowBinary: AggregateFunction is opaque, unframed aggregation state with no " +
+      "length prefix — not generically decodable or skippable. Finalize server-side " +
+      "(-Merge / finalizeAggregation()) and decode the concrete result type instead.",
+  );
+};

package/skills/clickhouse-js-node-rowbinary-parser/src/bool.ts

@@ -0,0 +1,10 @@
+import { Cursor } from "./core.js";
+import { readUInt8 } from "./integers.js";
+
+/**
+ * Read a `Bool`: 1 byte, stored as `UInt8` (`0` = false, `1` = true). Treats any
+ * non-zero byte as true.
+ */
+export function readBool(state: Cursor): boolean {
+  return readUInt8(state) !== 0;
+}

package/skills/clickhouse-js-node-rowbinary-parser/src/columnar.ts

@@ -0,0 +1,125 @@
+/**
+ * Streaming COLUMNAR decode for an all-numeric, fixed-width RowBinary result —
+ * one concrete example reader that ties together the three wins this skill keeps
+ * pointing at. The schema is hard-coded on purpose: a real columnar reader is
+ * MONOMORPHIZED to its result, so the row loop is straight-line constant-offset
+ * reads with no per-field dispatch. Generate one shaped like this per schema.
+ *
+ * The example schema (`sensor_id UInt32, ts DateTime64(3), value Float64,
+ * quality Float32, status UInt8`) — every column fixed-width, stride 25 bytes:
+ *
+ *   sensor_id  UInt32         @ o+0   getUint32     -> Uint32Array
+ *   ts         DateTime64(3)  @ o+4   2x getUint32  -> BigInt64Array (raw ms ticks)
+ *   value      Float64        @ o+12  getFloat64    -> Float64Array
+ *   quality    Float32        @ o+20  getFloat32    -> Float32Array
+ *   status     UInt8          @ o+24  buf[o+24]     -> Uint8Array
+ *
+ * The three wins:
+ *
+ *  1. COLUMNAR (struct-of-arrays). One typed array per column, not one object
+ *     per row — removes the per-row object / `Date` / number-boxing allocation
+ *     that dominates a numeric decode (~4x in plain JS; see `src/examples/iot.ts`
+ *     and `tests/iot.columnar.bench.ts`). Keep `ts` as raw `BigInt64Array` ticks
+ *     and make a `Date` lazily, per displayed row — never allocate 50k `Date`s.
+ *     The `Int64` column is itself filled WITHOUT allocating a bigint per row:
+ *     copy the two little-endian 32-bit words straight into a `Uint32Array` view
+ *     over its buffer (`getBigInt64` would box a bigint each row); the bigint is
+ *     materialized lazily, only when the consumer reads `ts[i]`.
+ *
+ *  2. TRANSFERABLE. Each column is a fresh, exactly-sized typed array that OWNS
+ *     its `ArrayBuffer` at offset 0, so a batch ships to a Worker / WASM kernel
+ *     zero-copy: `postMessage(batch, columns.map(c => c.buffer))`.
+ *
+ *  3. RESPECTS INCOMPLETE BUFFERS (streaming). Because the stride is constant,
+ *     honoring a partial trailing row is pure ARITHMETIC: the number of complete
+ *     rows in the buffer is `(work.length / STRIDE) | 0`. No `advance()`, no
+ *     `NeedMoreData`, no throw/restart — the leftover `work.length % STRIDE` bytes
+ *     just carry to the next chunk. Strictly cheaper than the row-oriented
+ *     `streamRowBatches`, which re-decodes the partial row on every boundary.
+ *
+ * SCOPE: fixed-width numeric columns only — the ClickHouse types with a 1:1
+ * native TypedArray (`Int8/16/32/64`, `UInt8/16/32/64`, `Float32/64`). Anything
+ * whose value isn't one native-typed number has no constant stride to divide by
+ * (`String`/`Array`/`Map`/`Tuple`) or no 1:1 array (`Int128`+, `Decimal*`,
+ * `BFloat16`); decode those row-wise. `Bool`/`Enum`/`Date*`/`DateTime*` ride
+ * their underlying int here for the RAW value.
+ */
+
+/** One decoded batch of the example schema: `rows` complete rows, one typed array per column. */
+export interface SensorColumnBatch {
+  /** Number of complete rows decoded in this batch. */
+  rows: number;
+  columns: {
+    sensor_id: Uint32Array;
+    ts: BigInt64Array; // raw DateTime64(3) ms ticks
+    value: Float64Array;
+    quality: Float32Array;
+    status: Uint8Array;
+  };
+}
+
+/** Byte stride of one fixed-width row: 4 + 8 + 8 + 4 + 1. */
+const STRIDE = 25;
+
+const EMPTY_CHUNK = Buffer.alloc(0);
+
+/**
+ * Stream a chunked RowBinary response of the example schema into columnar
+ * batches: one `{ rows, columns }` per incoming chunk, holding exactly the rows
+ * that completed within it.
+ *
+ * BACKPRESSURE: a pull stream — the next chunk is requested only when the
+ * consumer asks for the next batch. SMALL CHUNKS: tiny chunks mean tiny batches
+ * (more allocations, worse Worker amortization); compose `coalesceChunks` (from
+ * `./stream.js`) in front to merge them up to a target size first.
+ */
+export async function* streamSensorColumns(
+  chunks: AsyncIterable<Uint8Array>,
+): AsyncGenerator<SensorColumnBatch, void, undefined> {
+  let carry: Buffer = EMPTY_CHUNK;
+  for await (const chunk of chunks) {
+    // Wrap as a Buffer VIEW over the chunk's bytes — no copy (a Buffer made from
+    // an ArrayBuffer slice shares it). We own the chunk for the life of this
+    // generator, so holding a view into it is safe.
+    const incoming = Buffer.from(
+      chunk.buffer,
+      chunk.byteOffset,
+      chunk.byteLength,
+    );
+    const work =
+      carry.length === 0 ? incoming : Buffer.concat([carry, incoming]);
+
+    // Complete rows available right now — pure arithmetic, since STRIDE is fixed.
+    const n = (work.length / STRIDE) | 0;
+    if (n > 0) {
+      const view = new DataView(work.buffer, work.byteOffset, work.byteLength);
+      const sensor_id = new Uint32Array(n);
+      const ts = new BigInt64Array(n);
+      // Uint32 view over ts's OWN bytes: 2 little-endian words per Int64,
+      // [lo, hi, lo, hi, ...]. Filling ts through this view copies the raw bytes
+      // and skips the per-row bigint allocation `getBigInt64` would force; the
+      // bigint is materialized lazily, only for rows the consumer indexes.
+      const tsWords = new Uint32Array(ts.buffer);
+      const value = new Float64Array(n);
+      const quality = new Float32Array(n);
+      const status = new Uint8Array(n);
+      for (let i = 0, o = 0; i < n; i++, o += STRIDE) {
+        sensor_id[i] = view.getUint32(o, true); // UInt32        @ o+0
+        // DateTime64(3) Int64 @ o+4: two LE 32-bit words, no bigint allocated.
+        tsWords[i * 2] = view.getUint32(o + 4, true); // low word
+        tsWords[i * 2 + 1] = view.getUint32(o + 8, true); // high word
+        value[i] = view.getFloat64(o + 12, true); // Float64       @ o+12
+        quality[i] = view.getFloat32(o + 20, true); // Float32       @ o+20
+        status[i] = work[o + 24]!; // UInt8         @ o+24
+      }
+      yield { rows: n, columns: { sensor_id, ts, value, quality, status } };
+    }
+    // Carry the partial trailing row (if any) to the next chunk.
+    carry = work.subarray(n * STRIDE);
+  }
+  if (carry.length > 0) {
+    throw new Error(
+      `RowBinary stream ended mid-row: ${carry.length} trailing byte(s) left undecoded`,
+    );
+  }
+}