SuperAPI AI 工具集

clickhouse-js-node-coding

编程与开发

查看项目

更新于 10-15 20:12

技能介绍

用途:帮助在 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 健康检查、插入格式选择、指定列或跨库插入、VALUES 与表达式插入、异步插入、查询结果解析、查询参数绑定、会话与临时表、现代数据类型(Dynamic、Variant、JSON、Time、Time64、QBit)、自定义 JSON 解析/序列化。

使用方式:始终从 @clickhouse/client 导入并用 createClient({ url }) 创建客户端,不再需要时或优雅关闭时 await client.close()。写入用 client.insert(),读取用 client.query() 配合 resultSet.json()/.text()/.stream(),DDL 等不返回行的语句用 client.command(),需要原始响应流时用 client.exec(),健康检查用 client.ping()。插入默认推荐 format: 'JSONEachRow' 与 values: [...];中小结果集用 await (await client.query({...})).json<RowType>(),更大结果建议流式。用户提供的值必须用 query_params 绑定,采用 ClickHouse 原生 {name: Type} 语法,禁止模板字符串拼接,否则存在 SQL injection 风险。createClient 传入的 clickhouse_settings 是每个请求的默认值,可在 insert()、query()、command() 中按调用覆盖。集群或负载均衡后执行 DDL 时,可在 command() 上设置 clickhouse_settings: { wait_end_of_query: 1 }。

版本约束:pathname 需客户端 >= 1.0.0;query_params 中的 BigInt 需 >= 1.15.0;TupleParam 与 JS Map 需 >= 1.9.0;可配置 json.parse/json.stringify 需 >= 1.14.0;Time/Time64 需服务端 >= 25.6;QBit 需服务端 >= 25.10(26.x GA);Dynamic/Variant/新 JSON 类型需服务端 >= 24.1/24.5/24.8(25.3 起不再实验)。

限制:本技能不覆盖错误与挂起排查、流式与 Parquet 性能调优、TLS 与 RBAC 安全、建表与部署拓扑,这些分别属于其他技能或示例目录;浏览器与边缘环境应改用 @clickhouse/client-web。具体示例代码与完整清单未在资料中提供。