clickhouse

ClickHouse（TypeScript）

当使用 TypeScript/Node 处理 ClickHouse OLAP 工作时，使用此技能：官方 JS 客户端、应用运行的 SQL、表设计、数据导入、Cloud 与自托管，以及应用可查询的运维信息。

工作流

1. 检查本地环境：
   • 软件包：@clickhouse/client（Node）和／或 @clickhouse/client-web（浏览器／Workers）。快照版本为 1.23.1（1.24.0 已合并，但尚未发布）。Node 版本需为 >=20。客户端支持 24.8+ 服务器版本；当前服务器版本系列为稳定版 26.9 和 26.8 / 26.3 LTS。
   • 连接：url（Cloud 使用 HTTPS :8443，本地使用 HTTP :8123）、身份验证（密码或 Cloud JWT access_token）、database、TLS。
   • 架构：引擎（MergeTree 系列）、ORDER BY、PARTITION BY、MV／投影。
   • 数据导入路径：insert() 批次与 async_insert、流、空数组无操作。
2. 日常操作指南请先参阅 usage-guide.md。
3. 版本不一致时请更新文档。从 source-map.md 开始。
4. 深入了解请参阅：
   • 客户端 API、格式、流、设置：client-ts.md。
   • 引擎、键、MV、投影、索引：sql-engines-modeling.md。
   • 插入／查询 SQL 模式、FINAL、JOIN、变更操作：ingest-query-patterns.md。
   • 类型、Cloud、系统表、错误：types-cloud-ops.md。
   • Testcontainers + SQL 迁移：testing-migrations.md。
5. 优先使用官方 @clickhouse/client，不要使用未限定作用域的／clickhouse 社区软件包。绝不要将用户输入插入 SQL；请使用 {name: Type} + query_params。
6. 通过有针对性的 query／insert 冒烟测试验证，留意数据导入时的分区数，并消费／关闭每个 ResultSet。

核心判断

• ClickHouse 是列式 OLAP，不是 OLTP。应针对批量分析进行优化，而非高 QPS 点查。
• JS 客户端仅使用 HTTP(S)（不支持原生 TCP 9000）。
• 默认使用 MergeTree + 强有力的 ORDER BY；分区用于数据管理（TTL／DROP），不能替代排序键。
• 优先使用批量 insert({ format: 'JSONEachRow' })；微小的同步插入会导致 TOO_MANY_PARTS。客户端无法批量处理时，使用 async_insert=1 + wait_for_async_insert=1。
• 特殊引擎（Replacing／Summing／Aggregating／Collapsing）需要确保正确性的 SQL（FINAL 或可处理合并的聚合），因为合并最终才会完成。
• 优先使用仅插入、RMT、MV，而不是频繁执行 ALTER UPDATE／DELETE 变更操作；删除行时使用轻量级 DELETE FROM；轻量级 UPDATE … SET（测试版，会修改分区）仅用于小规模（<~10%）批量修复。
• Server 26.9+：新分析器为强制启用（enable_analyzer 已弃用），默认压缩方式已改为 ZSTD——升级时请重新测试旧查询和固定的设置。
• 类型陷阱：JSON 中 UInt64 → 字符串；Decimal 作为字符串；Date 使用 'YYYY-MM-DD'；对象行始终设置 format: 'JSONEachRow'（插入默认格式为 JSONCompactEachRow）。
• 始终消费或调用 close() 关闭 ResultSet——未关闭的流会导致 ECONNRESET。
• 每个进程共享一个客户端；关闭时调用 close()／await using。使用会话时设置 max_open_connections: 1。
• Cloud：使用 HTTPS :8443、托管复制，应用层不要使用 Distributed(...)——需要时使用 remoteSecure。
• 命令示例优先使用 bun / bunx。

验证

优先使用仓库自带的命令。对于有实际意义的 ClickHouse 工作，覆盖相关子集：

• bun pm ls @clickhouse/client 和 Node ≥20。
• 冒烟测试：ping({ select: true })，通过 command 执行 DDL，使用 JSONEachRow 执行 insert + query。
• 数据摄取：批次大小 / async_insert 设置；留意错误 252（分区过多）。
• 流式处理：完整消费或调用 close()；对插入流实施背压。
• 云端：TLS URL、凭据 / JWT、keep-alive 空闲 TTL < 服务端超时（客户端默认约为 2500 ms）。
• 架构：ORDER BY 与筛选模式匹配；验证 RMT/MV 在 FINAL 或合并聚合下的正确性。
• 测试：存在集成测试时，使用 @testcontainers/clickhouse + getClientOptions()。

报告已运行和未运行的检查，以及仍未确定的版本 / 云端假设。