ClickHouse RowBinary、クエリ専用パーサーをAgent Skillで生成

ClickHouseは、Node.js向けの読み書きライブラリ@clickhouse/rowbinaryを公開しました。通常の汎用パーサーとして使えるだけでなく、同梱のSKILL.mdをコーディングエージェントへ読ませ、クエリの列型に特化したパーサーを生成できる点が特徴です。

要点

• RowBinary、RowBinaryWithNames、RowBinaryWithNamesAndTypesの読み書きとストリーミングに対応します。
• Agent Skillは、検証済みの読み取り部品を組み合わせ、実行時の型判定を減らしたクエリ専用パーサーを生成します。
• ClickHouseの検証では汎用パーサー比1.5〜3.4倍ですが、文字列中心のデータではRowBinaryが常に最速とは限りません。
• 生成コードは人がレビュー、テスト、ベンチマークしてリポジトリへ取り込む前提です。

今回のブログ記事で語られていること

RowBinaryは、リトルエンディアンの基本型とLEB128による可変長整数を使い、行ごとの余分な情報を持たない形式です。そのためClickHouseから大量データを取り出す用途には効率的ですが、JavaScript側の復号処理は単純ではありません。Nullable、Array、Map、Tuple、LowCardinalityは入れ子になり、DateTime64では精度とタイムゾーンを扱います。Variant、Dynamic、JSONは値ごとの型情報を読みながら再帰的に処理します。JSONへ変換すれば実装は容易になりますが、CPU負荷が増えるうえ、UInt64がNumber.MAX_SAFE_INTEGERを超えた場合に値を気づかず丸める危険があります。

@clickhouse/rowbinaryの第1層は、ClickHouseの各型を読む小さな関数と、それらを組み合わせるラッパーです。全体をメモリへ読み込む処理と分割ストリームの両方があり、書き込み処理や@clickhouse/datatype-parserを使う動的なRowBinaryWithNamesAndTypes処理も提供します。この層だけを通常のライブラリとして使い、parseRowBinary(...)で既知の経路を選ぶこともできます。

第2層がSKILL.mdです。APIの呼び方を説明するだけではなく、対象クエリの列型に合わせて読み取り関数をどう組み立てるかをエージェントへ教えます。バッファーの所有、64ビット整数をBigIntとnumberのどちらへ写すか、日付変換、Decimalのスケール、配列の具体化方法など、生成時に判断できる余地もコメントで示します。注文データの例では、26バイト固定の行に対して境界確認を一度だけ行い、固定オフセットで読み、DecimalのスケールとUUID変換を埋め込むことで、汎用実装と同じ結果を3.41倍の速度で得たとしています。

5万行を使った比較では、金融台帳が1.55倍、IoTテレメトリーが2.46倍、注文データが3.41倍でした。正確な大整数処理を行うJSON経路に対してもRowBinaryは2.5〜3.3倍でした。一方、文字列中心のログではJSONCompactEachRowの方が速い結果も示しています。生成費用はキャッシュ利用時に1パーサー約0.20ドルという試算ですが、これは特定モデルと評価条件による値です。重要なのは速度だけではなく、公式にテストされた部品を再利用し、UUIDのバイト順や大整数の丸めといった静かにデータを壊す不具合を避ける設計にあります。

今回のブログ記事が関係する人

ClickHouseからNode.jsへ高頻度でデータを取り出す開発者、バイナリー形式の性能を担当する人、コーディングエージェントによるコード生成を本番開発へ取り入れる基盤チームに関係します。

結局、今回のブログ記事をどう読むべきか

Agent Skillをコンパイラーの代替候補として使う提案ですが、生成物をそのまま信頼する仕組みではありません。汎用パーサーを基準として残し、バイト単位の一致、大整数、UUID、タイムゾーン、入れ子型、ストリーミングをテストし、実データで速度を測れるチーム向けの方法です。