---
title: "@clickhouse/rowbinary: when your library is also a parser compiler"
description: "ClickHouse's @clickhouse/rowbinary is a Node.js reader and writer for the RowBinary, RowBinaryWithNames, and RowBinaryWithNamesAndTypes formats, offering both a generic parser and an accompanying Agent Skill. RowBinary avoids per-row overhead but is difficult to consume in JavaScript because nested types, LEB128 varints, precision-sensitive DateTime64 values, and recursive self-describing types require extensive runtime dispatch; JSON alternatives can also round large UInt64 values. The package provides small, composable, monomorphizable reading primitives, while SKILL.md instructs a coding agent to assemble query-specific parsers with inlined operations and selected policies such as BigInt handling and array materialization. Generated parsers run 1.5–3.4x faster than composing library functions in loops, with a fixed-width benchmark parser reaching 3.41x faster, and produce reviewable source that can be tested and benchmarked like ordinary application code."
---

# @clickhouse/rowbinary: when your library is also a parser compiler

[Clickhouse](https://yomu.fyi/company/clickhouse) · Jul 14, 2026

**Type:** Explainer

## Summary

ClickHouse's @clickhouse/rowbinary is a Node.js reader and writer for the RowBinary, RowBinaryWithNames, and RowBinaryWithNamesAndTypes formats, offering both a generic parser and an accompanying Agent Skill. RowBinary avoids per-row overhead but is difficult to consume in JavaScript because nested types, LEB128 varints, precision-sensitive DateTime64 values, and recursive self-describing types require extensive runtime dispatch; JSON alternatives can also round large UInt64 values. The package provides small, composable, monomorphizable reading primitives, while SKILL.md instructs a coding agent to assemble query-specific parsers with inlined operations and selected policies such as BigInt handling and array materialization. Generated parsers run 1.5–3.4x faster than composing library functions in loops, with a fixed-width benchmark parser reaching 3.41x faster, and produce reviewable source that can be tested and benchmarked like ordinary application code.

## Context

RowBinary is efficient for retrieving ClickHouse data, but consuming it from JavaScript is difficult because each leaf type has a distinct read pattern, complex types can nest arbitrarily, and generic type-dispatched readers incur runtime dispatch costs. The source also states that JSON formats can silently round UInt64 values beyond Number.MAX\_SAFE\_INTEGER unless a slower stringify-and-reparse path is used.

## Approach / What changed

The package combines type-specific, composable reading primitives with an Agent Skill in SKILL.md. A coding agent reads the library and its comments, then generates a parser specialized to a query's exact column types, including inlined fixed-width reads, baked-in Decimal scale handling, UUID lookup-table formatting, and configurable choices such as BigInt versus number and array materialization. The generic parser, writers, and streaming variants remain available.

## Takeaways

- The library supports RowBinary, RowBinaryWithNames, and RowBinaryWithNamesAndTypes, with full-buffer and chunked-stream reading variants plus writers.
- For a fixed-width orders schema, the generated parser performs one bounds check for a 26-byte row and reads columns at constant offsets.
- The generated parser is regular source code intended for human review, testing, and benchmarking; Haiku's reported pass rate improved from 52% to 86% with focused sub-agents.

**Tags:** [Architecture](https://yomu.fyi/topic/architecture), [Open Source](https://yomu.fyi/topic/open-source), [Performance](https://yomu.fyi/topic/performance), [TypeScript](https://yomu.fyi/topic/typescript)

- Source: [Clickhouse](https://clickhouse.com/blog/clickhouse-rowbinary-library-parser-compiler)
- Source URL: https://clickhouse.com/blog/clickhouse-rowbinary-library-parser-compiler
- Ingested by Yomu: 2026-08-29T01:38:32.208Z

[Read original post](https://clickhouse.com/blog/clickhouse-rowbinary-library-parser-compiler)