用途:指导在 Node.js 运行时使用 @clickhouse/client 编写符合惯例的 ClickHouse 应用代码,包括 Next.js Node 运行时 API 路由、React Server Components、Server Actions 及标准 Node.js 进程。不适用于浏览器组件、Web Worker、Next.js Edge 运行时、Cloudflare Workers 或 @clickhouse/client-web。
主要能力:按任务索引提供参考文件,涵盖客户端配置与连接、请求/响应压缩、ping 健康检查、插入格式选择、指定列或跨库插入、插入值与表达式、异步插入、查询结果解析、查询参数绑定、会话与临时表、现代数据类型(Dynamic、Variant、JSON、Time、Time64、QBit)、自定义 JSON 解析/序列化。
使用方式:始终从 @clickhouse/client 导入并用 createClient({ url }) 创建客户端,不再需要时或优雅关闭时 await client.close()。插入/查询默认优先 JSONEachRow。按用途选择方法:client.insert() 写行,client.query() 配合 resultSet.json()/.text()/.stream() 读数据,client.command() 执行 DDL 等不返回行的语句,client.exec() 获取原始响应流,client.ping() 做健康检查。用户提供的值必须用 query_params 绑定,禁止模板字符串拼接 SQL。参数绑定使用 ClickHouse 原生 {name: Type} 语法,而非 $1、? 或 :name。集群或负载均衡后执行 DDL 时,在 command() 上设置 clickhouse_settings: { wait_end_of_query: 1 }。
限制:仅限 Node.js 运行时;浏览器/边缘环境应改用 @clickhouse/client-web。错误排查、流式与性能调优、TLS 与 RBAC、建表与部署、浏览器示例均不在本技能范围内,分别由其他技能或示例目录覆盖。部分功能有版本要求,如 pathname 需客户端 >= 1.0.0,query_params 中 BigInt 需 >= 1.15.0,TupleParam 与 JS Map 需 >= 1.9.0,可配置 json.parse/stringify 需 >= 1.14.0,Time/Time64 需服务端 >= 25.6,QBit 需服务端 >= 25.10。