mcpField
C
clickhouse-js-node-rowbinary

clickhouse-js-node-rowbinary

github.com/clickhouse開発5626.4k 回インストール1 週間前に更新
リポジトリ

clickhouse-js-node-rowbinary について

ClickHouse RowBinary を扱う Node.js 開発者向けに、バイト列から値へのデコード、値からバイト列へのエンコードを行う JavaScript／TypeScript コーデックの生成を案内するスキルです。形式の選択、リーダーとライターの設計、型ごとの処理を扱い、JSON や Native が適する場面も示します。

主な機能

  1. 01RowBinary リーダーとライターの生成
  2. 02JSON と Native の用途比較
  3. 03リトルエンディアンの読み書き指針
  4. 04型別コード生成の原則
  5. 05ストリーミングと型別リファレンス

活用シーン

  1. 01ClickHouse RowBinary レスポンスのデコード
  2. 02ClickHouse へ送るデータのエンコード
  3. 03固定幅数値カラム向けコーデックの作成

インストール

コマンドをコピーしてターミナルで実行します。

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

インストール後、Claude Code で/clickhouse-js-node-rowbinaryを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

.gitignore
AGENTS.md
CHANGELOG.md
eval_result_composer.md
eval_result_haiku.md
eval_result_sonnet.md
eval_result.md
EXAMPLES.md
package-lock.json
package.json
reader.md
README.md
case-studies/
iot-rowbinary-vs-json.md
ledger-rowbinary-vs-json.md
logs-json-wins.md
wasm-vs-js.md
src/examples/
carts.ts
events.ts
iot.ts
ledger.ts
logs.ts
observability.ts
orders.ts
profiles.ts
telemetry.ts
src/readers/
aggregateFunction.ts
bool.ts
columnar.ts
compile.ts
composite.ts

詳細

Node.js 用 ClickHouse RowBinary コーデックジェネレーター

このスキルは、ワイヤーフォーマットの両方向、つまりリーダー（バイト列 → 値へのデコード）とライター（値 → バイト列へのエンコード、その逆方向）を生成します。通常、1つのタスクで必要なのは片方だけです。このファイルは共通のエントリーポイントであり、フォーマットの判定と両方向に共通する原則を扱います。方向ごとの判断とガイダンス、型ごとのリファレンステーブルは、2つの関連ファイルにあります。

必要な方向を選び、必要な方だけを読んでください。

  • ClickHouse からの RowBinary* レスポンスを JS の値にデコードする場合 → reader.md。ストリーミングかバッファー全体か、行オブジェクトか列指向か、固定スキーマか実行時スキーマか、型ごとのリーダーリファレンスを扱います。
  • JS の値を ClickHouse に送る RowBinary ペイロードにエンコードする場合 → writer.md。Sink／writeX の基本構成要素、writeRows によるストリーミング、型ごとのライターリファレンスを扱います。

型ごとのコードは実装済みで、方向別に src/readers/ と src/writers/ に分かれています。

まず、RowBinary は本当に適切なフォーマットですか？

RowBinary はスループットを目的としていますが、必ずしも最速の方法とは限りません。専用パーサーを作る前に、データの形状に合わせてフォーマットを選んでください。

結果の大部分が文字列や JSON に似た値で、それらを一括して読み込み、ほぼすべてのフィールドにランダムアクセスしたり、文字列メソッドや正規表現メソッドを実行したり、テキストとして扱ったりする場合は、JSON* フォーマット（例：JSONEachRow）を優先してください。 V8 ネイティブの JSON.parse は最適化された C++ で実装されており、JS レベルの RowBinary デコーダーよりも高速に JS の文字列やオブジェクトを構築できます。これに HTTP レスポンス圧縮（JSON の繰り返しキーを大幅に圧縮できる gzip／zstd）を組み合わせれば、ワイヤーコストも小さくなります。

結果の大部分が次のような場合は、RowBinary が明らかに優れています。

  • 幅広い数値型 — Int128／Int256／UInt128／UInt256、 Decimal128／Decimal256。
  • バイナリ／固定幅のデータ — IPv4、IPv6、UUID、FixedString。
  • 一般に、大量の固定幅数値列。各値を単一の DataView 読み取りで処理できます。

列指向の読み込みとクライアント側の分析が主な目的（列の集計／スキャン／フィルタリング、型付き配列の Worker または WASM への受け渡し）の場合は、Native フォーマットを優先してください。 Native は列優先形式なので、転置せずに列ごとに1つの型付き配列へ直接読み込めます。

JSON* フォーマット（または CSV／TSV）の選び方や利用方法については、clickhouse-js-node-coding スキルを参照してください。

コアガイダンス（読み取りと書き込みの両方）

これらの原則は、リーダーとライターのどちらを生成する場合にも適用されます。方向ごとの運用ガイダンスについては、reader.md / writer.md を参照してください。

  • リトルエンディアンのみ。 RowBinary はリトルエンディアンです。対象は x86/ARM です。複数バイトの数値はすべて、DataView のアクセサーで littleEndian フラグにリテラルの true を渡して読み書きしてください。

  • まず正しく、その後に最適化。 まず、型ごとのプレーンな API から正しいコーデックを生成します。正しく動作することを確認してテストした後にのみ、特化させてください。正しさを確認する前に、パフォーマンスに関する前提を組み込まないでください。

  • ジェネリック型／複合型を単相化する。 型が事前に判明している場合は、関数を引数として渡すのではなく、型の組み合わせごとに特化したインラインコードを生成してください。

  • 末端の処理をインライン化する。 型ごとの readX／writeX 関数は、正しく組み合わせて使える参照実装です。生成するコーデックでは、それらを呼び出すのではなく、関数本体をインライン化してください。これにより、行ループをフィールドごとの間接呼び出しのない直線的なコードにできます（また、固定幅データのまとめ処理でオフセット計算を統合できます）。

  • 各カラムに型を注釈する。 インライン化すると型構造が失われるため、各カラムのエンコード／デコードブロックの上に、処理対象の ClickHouse 型を示す短いコメントを付けてください。

  • 共有スクラッチ領域は再入可能ではありません。 ホットメソッドの一部では、モジュールレベルのスクラッチバッファーを、書き込み後に読み取る形で再利用します。アクセスが完全に同期的な場合に限り、正しく動作します。値の設定と読み取りの間に async／yield 境界があると、値が破損します。

  • デフォルトは TypeScript。 ユーザーがプレーンな JavaScript を明示的に要求しない限り、TypeScript のコードとヘルパーを生成してください。

実例

実際に高速化を実現したエンドツーエンドの例を6つ、EXAMPLES.md にまとめています。

対象外

  • JSON／CSV／TSV／Parquet の解析 → clickhouse-js-node-coding を使用してください。
  • 接続エラー、ハング、型の不一致 → clickhouse-js-node-troubleshooting を使用してください。
  • ブラウザー／Web Worker／Edge → @clickhouse/client-web を使用してください。

まだ解決しませんか？

コメント

Markdown 対応