用途:这是 ClickHouse 的冒烟测试技能,用于新建项目时验证连接、学习 MergeTree 基础并跑通第一条分析查询。
前置条件:已安装并连接 @clickhouse/client(连接配置见 clickhouse-install-auth 技能);存在可访问的 ClickHouse 服务(本地 Docker、ClickHouse Cloud 或自托管),并设置环境变量 CLICKHOUSE_HOST、CLICKHOUSE_USER、CLICKHOUSE_PASSWORD。
主要步骤:
- 创建 MergeTree 表。用 createClient 建立连接,通过 client.command 执行 CREATE TABLE IF NOT EXISTS events,字段含 event_id UUID DEFAULT generateUUIDv4()、event_type LowCardinality(String)、user_id UInt64、payload String、created_at DateTime DEFAULT now(),引擎为 MergeTree(),ORDER BY (event_type, created_at),PARTITION BY toYYYYMM(created_at),TTL created_at + INTERVAL 90 DAY。
- 插入数据。用 client.insert 写入 5 条示例事件,format 为 JSONEachRow。
- 查询数据。用 client.query 按 event_type 分组,统计 count() 与 uniqExact(user_id),按总数降序,format 为 JSONEachRow。注意 ClickHouse 在 JSON 中把数值聚合返回为字符串,做算术前需转换。
- 可选:通过 system.parts 查看磁盘占用与分区数量,确认分区是否健康。
关键概念:MergeTree() 是分析场景的基础引擎;ORDER BY 定义主索引(排序键),应选常用于过滤/分组的列;PARTITION BY 按月切分数据以便裁剪;TTL 实现数据自动过期;LowCardinality(String) 适合基数低于约 1 万的字符串列。
输出示例:表创建成功(IF NOT EXISTS 保证幂等)、插入 5 条事件,查询得到 page_view 3 条 3 用户、click 1 条 1 用户、purchase 1 条 1 用户。
错误处理:表已存在用 IF NOT EXISTS;未知列用 DESCRIBE TABLE events 检查;类型不匹配需对齐 schema;内存超限则加 WHERE 或 LIMIT。
限制与后续:资料未提供收费、价格与平台支持细节;扩展内容(替换引擎、Decimal 列、system.parts 查询)见参考文件,下一步可进入 clickhouse-local-dev-loop 技能进行 Docker 本地开发与迭代式 schema 编辑。