clickhouse-js-node-coding

ClickHouse Node.js クライアント — コーディング

リファレンス：https://clickhouse.com/docs/integrations/javascript

⚠️ Node.js ランタイム専用です。 このスキルの対象は、Node.js ランタイムで動作する @clickhouse/client パッケージに限られます。これには、Next.js Node ランタイムの API ルート、React Server Components、Server Actions、標準的な Node.js プロセスが含まれます。このスキルをブラウザのクライアントコンポーネント、Web Workers、Next.js Edge ランタイム、Cloudflare Workers、または @clickhouse/client-web の使用に適用しないでください。ブラウザ／エッジ環境で使用する正しいパッケージは @clickhouse/client-web です。

---

このスキルの使い方

1. ユーザーの意図を以下のタスクインデックスの該当行に照らし合わせ、コードを書く前に対応するリファレンスファイルを読んでください。読み終えたら、そのリファレンスにある回答チェックリストを確認し、最終回答に該当する項目がすべて含まれていることを確認してください。チェックリストには、ユーザーが通常必要とするものの、短い回答では省略しやすい詳細が記載されています。
2. 常に @clickhouse/client からインポートし（@clickhouse/client-web は使用しないでください）、createClient({ url }) でクライアントを作成するか、適切な場合はサポートされているデフォルト値を利用してください。不要になったとき、またはグローバルリソースの正常なシャットダウン時に、できるだけ await client.close() でクライアントを閉じてください。
3. ユーザーが別の形式を選択している場合、または生バイトをストリーミングする場合（CSV／TSV／Parquet — examples/node/performance/ を参照）を除き、通常の行の挿入／選択には JSONEachRow を優先してください。 clickhouse_settings に関する注意： createClient に渡す設定はすべてのリクエストに適用されるデフォルトです。insert()、query()、または command() に clickhouse_settings を直接渡すと、呼び出し単位で上書きできます。クライアントレベルで設定する場合は、この点を必ず伝えてください。
4. ユーザー指定の値には常に query_params を使ってください。値をテンプレートリテラルで SQL に埋め込まないでください。reference/query-parameters.md を参照してください。 パラメーターのバインドに関する質問に回答する場合、テンプレートリテラルによる埋め込みが「SQL injection のリスク」であることを明示してください。ユーザーが構文についてのみ質問し、セキュリティに触れていない場合も同様です。「SQL injection」という表記を必ず含めてください。これは PostgreSQL／MySQL のユーザーが最もよく犯す間違いであり、セキュリティ上の説明は正しい回答の一部であって、任意の補足ではありません。
5. 目的に合ったメソッドを選んでください：
   • client.insert() — 行を書き込みます。
   • client.query() + resultSet.json() / .text() / .stream() — データを返す行を読み取ります。
   • client.command() — 行を返さない DDL およびその他のステートメント（CREATE、DROP、TRUNCATE、ALTER、セッション内の SET など）を実行します。
   • client.exec() — 任意のステートメントの生のレスポンスストリームが必要な場合に使用します（コーディングではまれです）。
   • client.ping() — ヘルスチェックに使用します。{ success, error? } を返し、接続に失敗しても例外をスローしません。
6. 該当する場合は、バージョン要件に注意してください。例：
   • pathname 設定オプション：クライアント >= 1.0.0。
   • query_params 内の BigInt 値：クライアント >= 1.15.0。
   • query_params 内の TupleParam と JS Map：クライアント >= 1.9.0。
   • 設定可能な json.parse / json.stringify：クライアント >= 1.14.0。
   • Time / Time64 データ型：ClickHouse サーバー >= 25.6。
   • QBit データ型：ClickHouse サーバー >= 25.10（26.x で GA）。
   • Dynamic / Variant / 新しい JSON 型：ClickHouse サーバー >= 24.1 / 24.5 / 24.8（25.3 以降は実験的ではありません）。

---

タスクインデックス

ユーザーのタスクを特定し、該当するリファレンスファイルを読んでください。

タスク	トリガー／症状	参照ファイル
クライアントの設定／接続	createClient の呼び出し、URL パラメーター、clickhouse_settings、デフォルトのフォーマット、カスタム HTTP ヘッダーを構築する	reference/client-configuration.md
リクエスト／レスポンスの圧縮	compression、gzip と zstd の比較、{ codec } オプションの形式、Node のバージョン要件、Web の制限事項	reference/compression.md
サーバーへの ping	ヘルスチェック、レディネスプローブ、「ClickHouse は稼働していますか？」	reference/ping.md
挿入フォーマットの選択	「挿入にはどのフォーマットを使えばよいですか？」、JSON と raw の比較、JSONEachRow と JSON と JSONObjectEachRow の比較	reference/insert-formats.md
一部のカラム／別のデータベースへの挿入	insert({ columns })、カラムの除外、一時的なカラム、データベースをまたぐ挿入	reference/insert-columns.md
値、式、日付、10進数の挿入	SQL 関数を使った INSERT … VALUES、JS からの Date／DateTime、Decimal の精度、INSERT … SELECT。UUID を UInt128 カラムに挿入するのは難しいため、UUID を UInt128 として保存するコードをユーザーが作成している場合に使用します	reference/insert-values.md
非同期挿入（サーバー側のバッチ処理）	async_insert=1、応答を待たない場合と確認応答を待つ場合の比較	reference/async-insert.md
結果の選択と解析	JSONEachRow の読み取り、メタデータ付きの JSON、選択フォーマットの指定	reference/select-formats.md
クエリのパラメーター化	値のバインド、特殊文字／エスケープ、「SQL インジェクション？」、{name: Type} 構文	reference/query-parameters.md
セッションと一時テーブル	session_id、CREATE TEMPORARY TABLE、セッションごとの SET コマンド	reference/sessions.md
最新のデータ型	Dynamic、Variant、JSON（オブジェクト）、Time、Time64、QBit（ベクトル検索）	reference/data-types.md
カスタム JSON の解析／文字列化	JSONBig／safe-stable-stringify／BigInt 対応のシリアライザーを組み込む	reference/custom-json.md

---

回答で使用する規約

• 常に import { createClient } from '@clickhouse/client' を表示します（Node 用です。Web 用ではありません）。
• 自己完結したスニペットでは、最後に必ず await client.close() を実行します。長時間稼働するサービスでは、正常なシャットダウン時にクローズします。
• 挿入では、ユーザーのシナリオで別の方法が必要な場合を除き、format: 'JSONEachRow' と values: [...] を優先します。
• 選択では、小規模から中規模の結果セットには await (await client.query({...})).json<RowType>() を優先し、大規模な結果にはストリーミングを提案します。
• パラメーターのバインドを示す場合は、ClickHouse のネイティブな {name: Type} 構文を使用します。$1、?、:name は使用しません。
• クラスター内またはロードバランサーの背後で DDL を実行する場合は、変更が適用された後にのみサーバーが応答するよう、command() 呼び出しに clickhouse_settings: { wait_end_of_query: 1 } を設定します。https://clickhouse.com/docs/en/interfaces/http/#response-buffering を参照してください。

---

対象外

このスキルでは、@clickhouse/client（Node）を使った日常的なコーディングを扱います。次のトピックは意図的に対象外としています。

• エラー、ハング、型の不一致、プロキシのパス名に関する予期しない動作、ログが出力されない問題、ソケットの切断、ECONNRESET → clickhouse-js-node-troubleshooting スキルを使用してください。
• ストリーミング、Parquet、ファイルストリーム、サーバーサイドの一括移動、進捗のストリーミング、非同期挿入のスループット調整 — examples/node/performance/ を参照してください。
• TLS、RBAC／読み取り専用ユーザー、より詳細な SQL インジェクション対策のガイダンス — examples/node/security/ を参照してください。
• CREATE TABLE のパターン、デプロイ環境に応じた接続文字列、レプリケーション／シャーディングの選択 — examples/node/schema-and-deployments/ を参照してください。
• ブラウザー、Web Worker、Next.js Edge、Cloudflare Workers — @clickhouse/client-web を使用し、examples/web/ を参照してください。

---

まだ解決しませんか？

• examples/node/coding/ — このスキルの基になっている、実行可能なサンプル集です。
• ClickHouse JS クライアントのドキュメント
• ClickHouse の対応フォーマット
• ClickHouse のデータ型