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. 偏好使用 JSONEachRow 進行典型的資料列插入/選取，除非使用者已選擇其他格式或正在串流原始位元組（CSV / TSV / Parquet — 請參閱 examples/node/performance/）。
   關於 clickhouse_settings 的注意事項： 傳遞給 createClient 的設定是每個請求的預設值；可以透過直接將 clickhouse_settings 傳遞給 insert()、query() 或 command() 來覆蓋每個呼叫的設定。當使用者在用戶端層級設定設定時，請務必提及這一點。
4. 一律對使用者提供的值使用 query_params — 絕不要使用樣板字面量插值將它們插入 SQL。請參閱 reference/query-parameters.md。
   在回答參數繫結問題時，您的回應必須明確指出樣板字面量插值是「SQL 注入風險」 — 即使使用者只問了語法且未提及安全性。需要出現「SQL 注入」這個字詞；這是 PostgreSQL/MySQL 使用者最常見的錯誤，安全性框架是正確答案的一部分，而非可選的附帶說明。
5. 選擇正確的方法來完成工作：
   • client.insert() — 寫入資料列。
   • client.query() + resultSet.json() / .text() / .stream() — 讀取會回傳資料的資料列。
   • client.command() — DDL 和其他不回傳資料列的陳述式（CREATE、DROP、TRUNCATE、ALTER、session 中的 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 正式推出）。
   • 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 與原始格式、JSONEachRow 與 JSON 與 JSONObjectEachRow	reference/insert-formats.md
插入到部分欄位 / 不同資料庫	insert({ columns })、排除欄位、暫存欄位、跨資料庫插入	reference/insert-columns.md
插入值、表達式、日期、十進位數字	INSERT … VALUES 搭配 SQL 函式、從 JS 處理 Date/DateTime、Decimal 精確度、INSERT … SELECT；將 UUID 插入 UInt128 欄位較為棘手——當使用者撰寫將 UUID 儲存為 UInt128 的程式碼時使用	reference/insert-values.md
非同步插入（伺服器端批次處理）	async_insert=1、fire-and-forget 與等待確認	reference/async-insert.md
選取並解析結果	JSONEachRow 讀取、帶有元資料的 JSON、選擇選取格式	reference/select-formats.md
參數化查詢	繫結值、特殊字元 / 跳脫、「SQL 注入？」、{name: Type} 語法	reference/query-parameters.md
Session 與暫存資料表	session_id、CREATE TEMPORARY TABLE、每個 session 的 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）的日常程式碼撰寫。以下主題刻意不在此處涵蓋：

• 錯誤、掛起、型別不匹配、代理路徑名稱意外、日誌靜默、socket 掛起、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 資料型別