Clickhouse Js Node Rowbinary Agent Skill

> Generate TypeScript/JavaScript code that reads/decodes AND writes/encodes ClickHouse RowBinary streams for the ClickHouse HTTP server. Use this skill whenever a user wants to parse or produce `RowBinary`, `RowBinaryWithNames`, or `RowBinaryWithNamesAndTypes`. Node.js only, doesn't cover browsers.

174k tokens

context cost

the whole folder, loaded on every use

193

files

ships runnable scripts

copies elsewhere

how many repositories repackaged it

81 d ago

last touched

this folder, not the whole repository

Install

one command, takes just this skill from the repository

npx skills add https://github.com/ClickHouse/agent-skills --skill clickhouse-js-node-rowbinary

What comes with it

236 369 bytes besides the instruction

.gitignore

AGENTS.md

CHANGELOG.md

EXAMPLES.md

README.md

case-studies/iot-rowbinary-vs-json.md

case-studies/ledger-rowbinary-vs-json.md

case-studies/logs-json-wins.md

case-studies/wasm-vs-js.md

eval_result.md

eval_result_composer.md

eval_result_haiku.md

eval_result_sonnet.md

package-lock.json

package.json

reader.md

src/examples/carts.ts

src/examples/events.ts

src/examples/iot.ts

src/examples/ledger.ts

src/examples/logs.ts

src/examples/observability.ts

src/examples/orders.ts

src/examples/profiles.ts

src/examples/telemetry.ts

src/readers/aggregateFunction.ts

src/readers/bool.ts

src/readers/columnar.ts

src/readers/compile.ts

src/readers/composite.ts

src/readers/core.ts

src/readers/datetime.ts

src/readers/decimals.ts

src/readers/dynamic.ts

src/readers/enums.ts

src/readers/floats.ts

src/readers/geo.ts

src/readers/header.ts

src/readers/integers.ts

src/readers/interval.ts

The instruction itself

6 sections, as written by the author

ClickHouse JS RowBinary Codec Generator for Node.js

This skill generates both directions of the wire format: readers (decode

bytes → values) and writers (encode values → bytes, the mirror). A given

task normally needs only one side. This file is the shared entry point — the

format gate plus the principles common to both directions; the per-direction

decisions, guidance, and the per-type reference tables live in two sibling files.

Pick your side — read only the one you need:

Decoding a RowBinary* response from ClickHouse into JS values →

reader.md. Streaming vs whole-buffer, row-objects vs columnar,

fixed vs runtime schema, and the per-type reader reference.

Encoding JS values into a RowBinary payload to send to ClickHouse →

writer.md. The Sink/writeX building blocks, writeRows

streaming, and the per-type writer reference.

The per-type code is real, split by direction under src/readers/ and

src/writers/.

First: is RowBinary even the right format?

RowBinary exists for throughput, but it is **not automatically the fastest

path** — match the format to the shape of the data before committing to a

bespoke parser.

Prefer a JSON* format (e.g. JSONEachRow) when the result is mostly

strings / JSON-like values that you consume wholesale — randomly accessing

essentially every field, running string/regexp methods on them, treating values

as text. V8's native JSON.parse is heavily optimized C++ and builds JS strings

and objects faster than a JS-level RowBinary decoder can; pair it with HTTP

response compression (gzip / zstd, which crushes JSON's repetitive keys) and

the wire cost shrinks too.

RowBinary clearly wins when the result is dominated by:

Wide numerics — Int128/Int256/UInt128/UInt256,

Decimal128/Decimal256.

Binary / fixed-width blobs — IPv4, IPv6, UUID, FixedString.
High-volume fixed-width numeric columns generally, where each value is a

single DataView read.

Prefer the Native format when columnar load and client-side analytics are

the main goal (fold/scan/filter columns, feed typed arrays to a Worker or WASM).

Native is column-major, so it loads straight into one typed array per column

with no transpose.

For help choosing and consuming a JSON* format (or CSV / TSV) instead, use the

clickhouse-js-node-coding skill.

Core guidance (both directions)

These principles apply whether you are generating a reader or a writer; the

side-specific operational guidance is in reader.md /

writer.md.

Little-endian only. RowBinary is little-endian; target x86/ARM. Read and

write every multi-byte number with DataView accessors passing a literal

true for the littleEndian flag.

Correct first, then optimize. First emit a correct codec built from the

plain per-type API. Only after it's correct (and tested) specialize it. Don't

bake performance assumptions in before correctness.

Monomorphize generic/composite types. Emit specialized, inlined code per

type combination instead of passing functions as arguments where the type is

known ahead of time.

Inline the leaf ops. The per-type readX/writeX functions are the

correct, composable reference; the generated codec should INLINE their bodies,

not call them, so the row loop is straight-line with no per-field indirection

(and so the fixed-width coalescing can fold the offset arithmetic together).

Annotate the type per column. Inlining erases the type structure, so put a

short comment above each column's encode/decode block naming the ClickHouse

type it handles.

Shared scratch is not reentrant. Some hot methods reuse a module-level

scratch buffer as a write-then-read pair — correct only because the access is

fully synchronous. An async/yield boundary between populating and reading

it corrupts the value.

TypeScript by default. Generate TypeScript code and helpers unless the user

explicitly asks for plain JavaScript.

Worked examples

Six end-to-end examples with real speedup are catalogued in EXAMPLES.md.

Out of scope

JSON / CSV / TSV / Parquet parsing → use clickhouse-js-node-coding.
Connection errors, hangs, type mismatches → use

clickhouse-js-node-troubleshooting.

Browser / Web Worker / Edge → @clickhouse/client-web.

Still Stuck?

Other skills for the same job

different authors, same section of the catalogue

Biorxiv Database

by christophacham

×4

Efficient database search tool for bioRxiv preprint server. Use this skill when searching for life sciences preprints by keywords, authors, date ranges, or categories, retrieving paper metadata, downloading PDFs, or conducting literature reviews.

Access BRENDA enzyme database via SOAP API. Retrieve kinetic parameters (Km, kcat), reaction equations, organism data, and substrate-specific enzyme information for biochemical research and metabolic pathway analysis.

Access ClinPGx pharmacogenomics data (successor to PharmGKB). Query gene-drug interactions, CPIC guidelines, allele functions, for precision medicine and genotype-guided dosing decisions.

Query NCBI ClinVar for variant clinical significance. Search by gene/position, interpret pathogenicity classifications, access via E-utilities API or FTP, annotate VCFs, for genomic medicine.

Access COSMIC cancer mutation database. Query somatic mutations, Cancer Gene Census, mutational signatures, gene fusions, for cancer research and precision oncology. Requires authentication.

Query Ensembl genome database REST API for 250+ species. Gene lookups, sequence retrieval, variant analysis, comparative genomics, orthologs, VEP predictions, for genomic research.

Query openFDA API for drugs, devices, adverse events, recalls, regulatory submissions (510k, PMA), substance identification (UNII), for FDA regulatory data analysis and safety research.

Query NCBI Gene via E-utilities/Datasets API. Search by symbol/ID, retrieve gene info (RefSeqs, GO, locations, phenotypes), batch lookups, for gene annotation and functional analysis.

13k tokens scripts

How to use it

Copy the folder

Take clickhouse/clickhouse-js-node-rowbinary from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.