用途:覆盖 ClickHouse 核心工作流的读写部分,把数据高效写入 ClickHouse,再用聚合、漏斗、留存、窗口函数和物化视图回答分析问题。
前提:表已创建(否则先运行 clickhouse-core-workflow-a);已安装并连接 @clickhouse/client,环境变量含 CLICKHOUSE_HOST、CLICKHOUSE_USER、CLICKHOUSE_PASSWORD;有目标库表(示例用 analytics.events)。
主要能力与用法:
- 批量插入(快路径):用 client.insert({ table, values, format: 'JSONEachRow' }) 批量写入,客户端内部缓冲。最佳实践是每次 INSERT 约 1 万至 10 万行,避免逐行插入;ClickHouse 每次 INSERT 生成一个新 part,过多小插入会导致 too many parts;实时流可缓冲 1-5 秒再刷写。流式文件(CSV、Parquet 等)用同一调用配合读流和对应格式(如 CSVWithNames)。
- 分析查询:用 count()、uniqExact() 与时间过滤做聚合,典型形态为按 tenant_id、event_type 分组统计事件数与去重用户数,按事件数降序取前 100。漏斗、留存与安全参数化查询模式见 references/queries.md。
- 预聚合与窗口:仪表盘场景可在 INSERT 时用物化视图配合 AggregatingMergeTree 目标表预聚合,读取时合并状态;窗口函数(row_number()、OVER (PARTITION BY ...) 累计)与完整函数参考见 references/advanced.md。
输出:批量插入代码或文件流;通过 rs.json() 返回的聚合结果,可直接供仪表盘或 API 使用;物化视图与目标表 DDL,使小表随源表 INSERT 自动更新。
错误处理:too many parts(300)多因频繁小插入,应批量插入或调大 parts_to_throw_insert;内存超限因大 GROUP BY/JOIN,可加 WHERE 过滤或调大 max_memory_usage;UNKNOWN_FUNCTION 多为版本不符,用 SELECT version() 检查;日期解析失败需用 YYYY-MM-DD HH:MM:SS 格式。
限制:需先完成建表工作流;具体函数与高级引擎细节需查阅随附 references 文件;资料未提供收费、平台支持范围等信息。