Agent Native

clickhouse-js-node-rowbinary

This skill generates TypeScript/JavaScript code to decode and encode ClickHouse RowBinary wire format streams in Node.js.

by ClickHouseOfficial publisherNot reviewed

Identity proven by GitHub's verified organisation badge (ClickHouse)

Agents
Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode
License
Apache-2.0 (permissive)
Pin
f3d5c8fpinned Oct 9, 2026
Context cost
about 1,200 tokenswhen the skill loads
GitHub stars
332on clickhouse/clickhouse-js
Scripts
173 scripts

What it does

“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.”
The author's description, from SKILL.md

Generated summary from the skill's own text

This skill generates TypeScript/JavaScript code to decode and encode ClickHouse RowBinary wire format streams in Node.js. It handles RowBinary, RowBinaryWithNames, and RowBinaryWithNamesAndTypes variants, providing readers to parse bytes into values and writers to serialize values back into bytes.

When to use it

  • Processing wide numeric types like Int256, Decimal256 from ClickHouse
  • Handling binary fixed-width data like IPv4, IPv6, UUID, FixedString
  • High-volume columnar numeric data where throughput matters most
  • Needing bidirectional codec generation for RowBinary format

When not to

  • Data is mostly strings or JSON-like values consumed wholesale
  • Columnar analytics is the main goal, use Native format instead
  • Browser or Web Worker environments, use client-web instead

Install

These commands install from the publisher's repository and need no account.

skills CLI

npx skills add clickhouse/clickhouse-js --skill clickhouse-js-node-rowbinary

Installs from the repository's default branch, which may have changed since the commit we checked.

GitHub CLI 2.90 or later

gh skill install clickhouse/clickhouse-js clickhouse-js-node-rowbinary@f3d5c8f36790af1c7e2a89b1e29725bc4c39e7fa

Installs the commit we checked (f3d5c8f).

Copy by hand

Download the folder at f3d5c8f and put it in .claude/skills/clickhouse-js-node-rowbinary for Claude Code and in .agents/skills/clickhouse-js-node-rowbinary for Codex, Cursor, Gemini CLI, GitHub Copilot and OpenCode.

Skill folder on GitHub at f3d5c8f

Claude Code plugin

/plugin install clickhouse@claude-plugins-official

The publisher's plugin in Claude's official marketplace. It may hold more than this skill, and we have not pinned it.

Claude Code plugin

/plugin install clickhouse-best-practices@claude-plugins-official

The publisher's plugin in Claude's official marketplace. It may hold more than this skill, and we have not pinned it.

Copy for your agent

A prompt for any coding agent. It installs this skill from GitHub at the pinned commit, copies the files as they are, and runs nothing unless you ask.

Prompt

Install the agent skill "clickhouse-js-node-rowbinary" by ClickHouse.

Source, pinned to commit f3d5c8f36790af1c7e2a89b1e29725bc4c39e7fa:
https://github.com/clickhouse/clickhouse-js/tree/f3d5c8f36790af1c7e2a89b1e29725bc4c39e7fa/skills/clickhouse-js-node-rowbinary

1. Download that folder at exactly this commit. Do not use the default branch.
2. Copy every file unchanged, keeping the folder structure, into .claude/skills/clickhouse-js-node-rowbinary/ for Claude Code and .agents/skills/clickhouse-js-node-rowbinary/ for Codex, Cursor, Gemini CLI, GitHub Copilot and OpenCode. Create the folders if they do not exist.
3. Do not edit the files, and do not run any script in the folder unless I ask you to.
4. When you are done, list the files you copied and where you put them.

Listing and checks: https://www.agentnative.dev/skills/clickhouse/clickhouse-js-node-rowbinary-clickhouse-js

SKILL.md at the pin

---
name: clickhouse-js-node-rowbinary
description: >
  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.
---

# 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](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](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](reader.md) /
[writer.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](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?

- [ClickHouse RowBinary format](https://clickhouse.com/docs/interfaces/formats#rowbinary)
- [ClickHouse data types](https://clickhouse.com/docs/sql-reference/data-types)
- [ClickHouse JS client docs](https://clickhouse.com/docs/integrations/javascript)

From clickhouse/clickhouse-js at f3d5c8f, shown as plain text under its license: Apache-2.0 (permissive). The license text is in LICENSE.

View SKILL.md on GitHub at f3d5c8f

Files

193 files, 695 KB in total. Each file has a sha256 in the pin's manifest; the first 12 characters are shown.

Skill folder on GitHub at f3d5c8f
All 15 skills from ClickHouse

More from ClickHouse

  • chdb-datastore

    This skill enables working with tabular data using a pandas-compatible API backed by ClickHouse for faster execution.

    Contains scripts

    Claude Code, Codex, Cursor +3 · about 1.2K tokens · pinned 6 days ago

  • chdb-sql

    The skill enables running ClickHouse SQL queries on local files (parquet, csv, json), remote databases (Postgres, MySQL, MongoDB, ClickHouse Cloud), and cloud…

    Contains scripts

    Claude Code, Codex, Cursor +3 · about 960 tokens · pinned 6 days ago

  • clickhouse-architecture-advisor

    This skill guides agents through ClickHouse architecture decisions for specific workloads like observability, SIEM, and financial services.

    Claude Code, Codex, Cursor +4 · about 690 tokens · pinned 6 days ago

  • clickhouse-best-practices

    This skill provides 31 ClickHouse best practices rules covering schema design, query optimization, data ingestion, and agent connectivity.

    Claude Code, Codex, Cursor +4 · about 2.5K tokens · pinned 6 days ago

  • clickhouse-js-node-rowbinary

    This skill generates TypeScript/JavaScript code to read and write ClickHouse RowBinary format streams in Node.js.

    Contains scripts

    Claude Code, Codex, Cursor +3 · about 1.2K tokens · pinned 6 days ago

  • clickhouse-js-node-troubleshooting

    Diagnose and fix issues with the ClickHouse Node.js client (@clickhouse/client) running in Node.js environments.

    Claude Code, Codex, Cursor +4 · about 1.1K tokens · pinned 6 days ago

All Data and databases skills

Related in Data and databases

  • clickhouse-js-node-coding

    Write Node.js application code using the ClickHouse JavaScript client (@clickhouse/client).

    by ClickHouseOfficial publisher

    Claude Code, Codex, Cursor +4 · about 2.7K tokens · pinned 6 days ago

  • clickhouse-js-node-troubleshooting

    Diagnoses and resolves issues with the ClickHouse Node.js client (@clickhouse/client) in Node.js environments.

    by ClickHouseOfficial publisher

    Claude Code, Codex, Cursor +4 · about 1.1K tokens · pinned 6 days ago

  • infra-clickhouse

    Sets up and manages ClickHouse databases using clickhousectl CLI for local development or production deployment on ClickHouse Cloud.

    by ClickHouseOfficial publisher

    Contains scripts

    Claude Code, Codex, Cursor +3 · about 510 tokens · pinned 6 days ago

  • infra-postgres

    This skill sets up and manages Postgres databases using the clickhousectl CLI.

    by ClickHouseOfficial publisher

    Contains scripts

    Claude Code, Codex, Cursor +3 · about 570 tokens · pinned 6 days ago

  • prisma-next-quickstart

    This skill guides developers through setting up Prisma Next in three scenarios: starting a fresh project, adopting it into an existing codebase, or connecting…

    by PrismaOfficial publisher

    Claude Code, Codex, Cursor +4 · about 7.4K tokens · pinned 6 days ago

  • databricks-zerobus-ingest

    This skill enables agents to build gRPC-based data ingestion clients that write records directly into Databricks Delta tables using the Zerobus Ingest SDK.

    by DatabricksOfficial publisher

    Claude Code, Codex, Cursor +4 · about 2.9K tokens · pinned 6 days ago

The skills listed here are third-party software, collected from public GitHub repositories as a catalog of recent skills and provided as is. Agent Native does not write or control them and is not responsible for any harm, loss or damage caused by installing or using them. Labels and checks describe what we saw at one commit and are not a guarantee. Read a skill's files before you run it. Terms of use