clickhouse

ClickHouse（TypeScript）

TypeScript／Node から ClickHouse の OLAP 作業を行う場合にこのスキルを使用します。対象には、公式 JS クライアント、アプリが実行する SQL、テーブル設計、データ取り込み、Cloud とセルフホストの比較、アプリからクエリできる運用情報が含まれます。

ワークフロー

1. ローカル環境を確認します。
   • パッケージ：@clickhouse/client（Node）および／または @clickhouse/client-web（ブラウザー／Workers）。スナップショットは 1.23.1 です（1.24.0 はマージ済みですが未リリースです）。Node は >=20 です。クライアントはサーバー 24.8+ に対応します。現在のサーバー系列は 26.9（安定版）と 26.8 / 26.3 LTS です。
   • 接続：url（Cloud は HTTPS :8443、ローカルは HTTP :8123）、認証（パスワードまたは Cloud JWT access_token）、database、TLS。
   • スキーマ：エンジン（MergeTree ファミリー）、ORDER BY、PARTITION BY、MV／プロジェクション。
   • データ取り込み経路：insert() によるバッチ処理と async_insert、ストリーム、空配列の場合は何もしないこと。
2. 日常的な使い方については、まず usage-guide.md に従います。
3. バージョンに差がある場合はドキュメントを更新します。source-map.md から始めてください。
4. 詳細は以下を参照してください。
   • クライアント API、フォーマット、ストリーム、設定：client-ts.md。
   • エンジン、キー、MV、プロジェクション、インデックス：sql-engines-modeling.md。
   • INSERT／SELECT の SQL パターン、FINAL、JOIN、ミューテーション：ingest-query-patterns.md。
   • 型、Cloud、システムテーブル、エラー：types-cloud-ops.md。
   • Testcontainers と SQL マイグレーション：testing-migrations.md。
5. スコープが未指定の clickhouse コミュニティパッケージより、公式の @clickhouse/client を優先します。ユーザー入力を SQL に直接埋め込んではいけません。{name: Type} と query_params を使用してください。
6. query／insert の対象を絞ったスモークテスト、データ取り込み時のパーツ数への配慮、すべての ResultSet の消費／クローズによって検証します。

基本的な判断基準

• ClickHouse は 列指向 OLAP であり、OLTP ではありません。高 QPS のポイント検索ではなく、バッチ分析向けに最適化します。
• JS クライアントは HTTP(S) のみ（ネイティブ TCP 9000 ではありません）で通信します。
• デフォルトでは MergeTree と強力な ORDER BY を使用します。パーティションはデータ管理（TTL／DROP）のためのものであり、ソートキーの代わりにはなりません。
• insert({ format: 'JSONEachRow' }) によるバッチ取り込みを優先します。小さな同期 INSERT は TOO_MANY_PARTS の原因になります。クライアント側でバッチ処理できない場合は、async_insert=1 と wait_for_async_insert=1 を使用します。
• 特殊なエンジン（Replacing／Summing／Aggregating／Collapsing）では、正確性を保つ SQL（FINAL またはマージを考慮した集計）が必要です。マージは最終的に反映されます。
• 何度も実行する ALTER UPDATE／DELETE ミューテーションより、挿入専用の設計、RMT、MV を優先します。行の削除には軽量な DELETE FROM を使用します。軽量な UPDATE … SET（ベータ版、パーツを修正）は、小規模（約 10% 未満）のバッチ修正に限って使用します。
• サーバー 26.9 以降では、新しいアナライザーが必須です（enable_analyzer は廃止済み）。デフォルトの圧縮方式は ZSTD に変更されています。アップグレード時には、以前のクエリと固定している設定を再テストしてください。
• 型に関する注意点：JSON では UInt64 → string、Decimal は文字列、Date は 'YYYY-MM-DD' です。オブジェクト行では必ず format: 'JSONEachRow' を設定します（INSERT のデフォルトは JSONCompactEachRow です）。
• ResultSet は必ず 消費するか close() してください。ストリームを閉じずに残すと ECONNRESET が発生します。
• プロセスごとに共有クライアントを 1 つ使用し、シャットダウン時に close()／await using を使用します。セッションを使用する場合は max_open_connections: 1 を設定します。
• Cloud：HTTPS :8443、レプリケーションはマネージドです。アプリケーションレベルで Distributed(...) を使用せず、必要に応じて remoteSecure を使用します。
• コマンド例では bun／bunx を優先します。

検証

意味のある ClickHouse の作業では、リポジトリで管理されているコマンドを優先し、関連する項目を確認してください。

• bun pm ls @clickhouse/client と Node ≥20。
• スモークテスト：ping({ select: true })、command による DDL、JSONEachRow を使った insert と query。
• 取り込み：バッチサイズ／async_insert の設定。パーツが多すぎることを示すエラー 252 に注意してください。
• ストリーミング：最後まで読み取るか close() を呼び出してください。挿入ストリームではバックプレッシャーに注意してください。
• Cloud：TLS URL、認証情報／JWT、キープアライブのアイドル TTL をサーバーのタイムアウトより短く設定します（クライアントのデフォルトは約 2500 ms）。
• スキーマ：ORDER BY がフィルターパターンと一致していること。FINAL またはマージ集約を使った RMT/MV の正確性。
• テスト：インテグレーションテストがある場合は、@testcontainers/clickhouse と getClientOptions() を使用してください。

実行した確認項目と実行しなかった項目、残っているバージョン／Cloud に関する前提を報告してください。