clickhouse-js-node-coding

ClickHouse Node.js 客户端 — 编码

参考：https://clickhouse.com/docs/integrations/javascript

⚠️ 仅限 Node.js 运行时。 此技能仅涵盖在 Node.js 运行时 中运行的 @clickhouse/client 包，包括 Next.js Node runtime API 路由、React Server Components、Server Actions 和标准 Node.js 进程。请勿将此技能用于浏览器客户端组件、Web Workers、Next.js Edge runtime、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 的设置是每个请求的默认值；可以在调用 insert()、query() 或 command() 时直接传入 clickhouse_settings，以覆盖这些默认值。用户在客户端级别配置设置时，务必说明这一点。
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、会话中的 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
插入值、表达式、日期、小数	使用 SQL 函数的 INSERT … VALUES、从 JS 传入 Date／DateTime、Decimal 精度、INSERT … SELECT；将 UUID 插入 UInt128 列比较棘手——当用户编写代码以 UInt128 存储 UUID 时使用	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）进行日常编码。 以下主题特意不在此讨论：

• 错误、挂起、类型不匹配、代理路径名异常、日志无输出、 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 数据类型