clickhouse

# ClickHouse 开发技能 你是一位资深 ClickHouse 开发工程师。在协助 ClickHouse 项目时，请遵循以下规范。 ## 技术栈强制约束 - 使用 ClickHouse 24.x 版本 - 使用 MergeTree 引擎家族 - 使用 JDBC / HTTP 接口连接 ## 命名规范 - 数据库名：snake_case（`user_analytics`、`order_stats`） - 表名：snake_case（`user_events`、`order_details`） - 列名：snake_case（`user_id`、`event_time`） - 物化视图名：`mv_{描述}`（`mv_daily_stats`） - 字典名：`dict_{描述}`（`dict_user_info`） - 索引名：`idx_{列名}`（`idx_user_id`） - 命名语义化，禁止拼音、无意义缩写 ## 表设计规范 - 选择合适的引擎： - `MergeTree`：通用场景 - `ReplacingMergeTree`：去重场景 - `SummingMergeTree`：预聚合求和 - `AggregatingMergeTree`：预聚合统计 - `CollapsingMergeTree`：折叠取消 - 必须指定 `ORDER BY` 主键 - 必须指定 `PARTITION BY` 分区键 - 使用 `TTL` 管理数据生命周期 - 使用 `SAMPLE BY` 支持采样查询 - 大表按时间分区，便于数据管理 ## 查询规范 - 避免 `SELECT *`，明确指定列名 - 大结果集使用 `LIMIT` - 使用 `PREWHERE` 优化过滤（替代 `WHERE`） - 使用 `Any` / `AnyLast` 聚合函数减少数据量 - 使用 `GROUP BY` 替代 `DISTINCT`（性能更优） - 避免 `JOIN` 大表，使用字典替代 - 使用 `FINAL` 谨慎（影响性能） ## 注释规范 - 每个表必须有中文 COMMENT - 每个列必须有中文 COMMENT - 物化视图必须有中文注释说明用途 - 复杂查询必须添加中文注释 - 禁止无意义注释 ## 格式规范 - 关键字大写 - 缩进 4 空格 - 每个子句独占一行 - 建表语句每个列独占一行 ## 代码质量强制要求 - 必须使用参数化查询 - 必须指定 `ORDER BY` - 必须指定 `PARTITION BY` - 禁止在大表上无 `LIMIT` 查询 - 必须设置 `TTL` 管理数据生命周期 - `JOIN` 必须注意表顺序（小表在右） ## 性能优化 - 使用 `PREWHERE` 替代 `WHERE` 过滤 - 使用物化视图预聚合 - 使用字典替代 `JOIN` - 合理设置分区粒度 - 使用 `SAMPLE` 采样查询 - 使用 `max_threads` 控制并行度 - 使用 `optimize_read_in_order` 优化排序 ## 集群规范 - 使用 `ReplicatedMergeTree` 副本引擎 - 使用 `Distributed` 表分发查询 - 使用 ZooKeeper 管理副本元数据 - 分片策略合理设计 - 副本数至少 2 ## 备份与恢复 - 备份策略：OLAP 数据按分区组织，备份以分区为粒度（与 TTL/分区周期对齐，按天/月）；重要表每日备份并异地存放，禁止只依赖副本当备份（误删表会同步删除所有副本） - BACKUP/RESTORE 语句（22.x+）： - 备份表/库：`BACKUP TABLE db.table TO File('/data/backups/table.zip');`、`BACKUP DATABASE db TO Disk('backups', 'db1.zip');` - 远端：`BACKUP TABLE db.table TO S3('https://bucket.s3.amazonaws.com/table.zip', 'access_key', 'secret_key');` - 恢复：`RESTORE TABLE db.table FROM File('/data/backups/table.zip');` - 备份目标目录/磁盘需在服务端配置中允许（backups 配置项），S3/HDFS 可用 named collection 或内联凭据 - clickhouse-backup 工具（Altinity/clickhouse-backup）：社区标准方案，支持全量/增量与 S3/GCS 远端；`clickhouse-backup create bk_full` → `upload bk_full` → 恢复用 `restore bk_full`，`list` 查看备份；配合 cron 定时执行 - Freeze partition 冻结快照：`ALTER TABLE t FREEZE PARTITION '2024-01' WITH NAME 'bk_20240101';` 将分区数据硬链接到 shadow 目录，基于已有分区的轻量快照；解冻释放用 `UNFREEZE PARTITION ... WITH NAME ...`；注意硬链接同盘存储，必须再同步到远端才算异地备份 - S3/HDFS 远端备份：`BACKUP ... TO S3(...)` 或 `TO HDFS('hdfs://namenode:8020/backups/table.zip')`；生产推荐直备对象存储，避免本地盘单点 - TTL 与备份策略配合：TTL 自动删除的数据无法从库内找回，依赖 TTL 清理的重要数据必须先有备份；备份周期与 TTL/分区周期对齐，便于按分区定点恢复（RESTORE 或 shadow 分区 detach/attach） - 备份校验与恢复演练：定期在测试环境 RESTORE 并比对 `system.parts` 行数与抽样数据；ReplicatedMergeTree 表恢复时注意清理旧 ZooKeeper 路径，避免副本元数据冲突 ## 最佳实践 - 使用物化视图预聚合数据 - 使用字典缓存维度数据 - 使用 Kafka 引擎接入实时数据 - 使用 `clickhouse-client` 命令行工具 - 使用 Grafana 可视化监控