learnNote

主题

从 0 到 1 学习 ClickHouse ​

一、项目目标 ​

打造一套适合零基础小白入门、同时覆盖底层原理与面试高频考点的 ClickHouse 学习教程。要求内容由浅入深、图文并茂、能动手实操，最终达到「看完会用、用了懂原理、面试能答上」的效果。

与 MySQL / PostgreSQL / Redis 教程的差异化定位：

  • 强调「OLAP 而非 OLTP」：ClickHouse 不是用来替代 MySQL 处理订单交易的，它是用来对亿级以上数据做秒级聚合分析的。讲解时要时刻提醒读者它的「能干什么、不能干什么」。
  • 强调「列式存储 + 向量化执行」：这是 ClickHouse 与 MySQL/PG 在物理存储与执行模型上的根本区别，必须用图解把「行存 vs 列存」「逐行 vs 向量化」讲透。
  • 强调「MergeTree 引擎家族」：MergeTree 是 ClickHouse 的灵魂，所有性能、去重、聚合、物化视图、TTL、副本都建立在它之上，必须作为重点章节展开。
  • 强调「数仓视角」：要把 ClickHouse 放到「实时数仓 / Lakehouse / OLAP 大家族（Doris / Druid / StarRocks / Pinot）」中比较，让读者理解它的生态位。

二、读者画像 ​

  • 主要受众：从未接触过 ClickHouse 的初学者，可能用过 MySQL / PostgreSQL，但对列存、向量化、Part / Mark / Granule、MergeTree 合并机制一无所知。
  • 次要受众：用过 ClickHouse 但停留在 select count(*) 层面，希望系统化补齐底层原理（存储格式、Merge 过程、副本与分片、物化视图、Projection）的开发者；以及准备数据 / 数仓 / 大数据方向面试的同学。
  • 风格要求：能用「Excel 按列复制」「图书馆按主题分书架」「快递分拣中心合并小包裹」「日记本每天追加一页」这类生活化的比喻讲清楚列式存储、Part 合并、稀疏索引、物化视图、分布式查询等晦涩概念。

三、环境约定 ​

  • 服务端无需读者自己安装：教程默认环境中已经有可用的 ClickHouse Server（本地 127.0.0.1:9000 TCP / 8123 HTTP，或容器化均可），文档不再花篇幅讲安装。
  • 默认账号 / 库：示例统一使用 default 用户连接，演示数据库统一命名为 learn_ck，由各章节按需建表，不污染默认库。
  • 统一客户端：所有交互式示例使用 clickhouse-client，编程示例统一使用 Python clickhouse-connect（HTTP）或 clickhouse-driver（TCP），全教程保持一致。
  • 聚焦点：
    1. ClickHouse 的正确使用姿势（SQL 方言、表引擎选择、数据类型、写入姿势、聚合 / 窗口函数、物化视图、字典）。
    2. ClickHouse 的底层实现逻辑（列式存储格式、稀疏主键索引、MergeTree 合并、副本与分片、向量化执行、查询计划）。

四、章节内容物（每个章节都必须包含以下 4 部分） ​

每个章节按照统一结构产出，缺一不可：

  1. 学习文档（.md）

    • 用「概念 → 生活类比 → SQL/代码示例 → 底层原理 → 与 MySQL/PG 对比 → 小结」六段式组织。
    • 大量使用 ASCII 图 / Mermaid 图 展示列式存储布局、Part 目录结构、Mark 与 Granule 关系、MergeTree 合并过程、分布式查询执行链路，避免纯文字堆砌。
    • 关键 SQL 必须给出 clickhouse-client 实操记录（输入 + 输出 + 耗时），并在性能相关章节配上 EXPLAIN PIPELINE / EXPLAIN PLAN / system.query_log 的真实分析。

  2. 实战案例（可运行代码）

    • 至少 1 个贴近真实业务的场景，例如：网站埋点 PV/UV 实时统计、广告点击漏斗分析、日志大宽表查询、用户行为路径分析、IoT 时序数据聚合、A/B 实验指标看板、实时大屏 Top-N 排行榜等。
    • 给出完整可运行的代码（推荐 Python clickhouse-connect 一以贯之），附带 docker-compose.yml（如需）、初始化 SQL 脚本 init.sql、批量造数脚本 seed.py、清理脚本 teardown.sql，方便反复练习。
    • 数据量级要符合 OLAP 场景（建议至少百万行起，关键章节给出千万 / 亿级造数脚本以体现性能差距）。

  3. HTML 演示页面（demo.html）

    • 单文件、零依赖（或仅引入 CDN），打开即可在浏览器中可视化演示该章节的核心概念。
    • 例如：用动画展示「行存 vs 列存的 IO 差异」「稀疏主键索引如何通过 Mark 跳过 Granule」「MergeTree Part 如何被后台合并」「ReplacingMergeTree 去重过程」「物化视图触发时机」「分布式查询的 fan-out / fan-in」「副本之间的 ZooKeeper/Keeper 协调」等。
    • 页面要有交互（按钮、输入框、步进控制、可调数据规模），让读者能「点一下看一步」，并能直观感受到列存压缩、稀疏索引带来的扫描量差异。

  4. 面试题清单

    • 收集大厂真实面经中该章节的高频题目（至少 5 题）。
    • 每题给出：题目 → 考察点 → 标准答案（分点作答）→ 加分项 / 易错点 → 与 MySQL/PG 或同类 OLAP（Doris / Druid / StarRocks）的对比要点（如适用）。

五、内容深度与表达要求 ​

  • 从 0 到 1：第一次出现的术语必须解释，不能默认读者知道（比如第一次提到 OLAP / OLTP、列式存储、向量化执行、Part、Granule、Mark、MergeTree、ReplacingMergeTree、Materialized View、Projection、Distributed Table、Keeper 都要先讲它是什么）。
  • 生活化类比优先：晦涩点（列式存储、稀疏主键索引、MergeTree 合并、ReplacingMergeTree 的「最终一致去重」、SummingMergeTree 的「自动汇总」、物化视图、分布式表 fan-out、副本一致性、TTL 过期、Projection）必须先用生活例子打比方，再讲技术细节。
  • 能动手：所有 SQL、代码、演示页面读者都能复制即用，不要出现伪代码或「此处省略」。所有性能结论必须给出可复现的对比实验（同一台机器、同一份数据、同一条 SQL，开 / 关某项优化的耗时对比）。
  • 由浅入深：先讲「怎么用」，再讲「为什么这么设计」，最后引申「源码思想 / 性能调优 / 踩坑」。
  • 横向对比：在合适位置加「📌 与 MySQL/PG 的区别」小框，例如：
    • 存储模型：InnoDB 行存聚簇 vs ClickHouse 列存 + 稀疏主键
    • 主键含义：MySQL 主键唯一约束 vs ClickHouse 主键仅用于排序与稀疏索引（不保证唯一）
    • 事务：MySQL/PG 完整 ACID vs ClickHouse 仅有限事务（单分区写入原子）
    • 更新 / 删除：MySQL UPDATE/DELETE 实时生效 vs ClickHouse ALTER TABLE … UPDATE/DELETE（Mutation，异步重写）
    • JOIN：MySQL/PG 优化器全场景 vs ClickHouse 大表 JOIN 弱、推荐宽表 / 字典 / 物化视图

六、建议的章节大纲（可在执行时微调） ​

  1. ClickHouse 是什么 & 为什么快（OLAP vs OLTP、列式存储、向量化执行、压缩、ClickHouse 的诞生背景与典型场景、与 Doris/Druid/StarRocks 的定位差异）
  2. 客户端与基础 SQL（clickhouse-client / HTTP / JDBC、库 / 表 / 视图三级结构、DDL/DML/DQL、SHOW、DESCRIBE、SYSTEM 命令、ClickHouse SQL 方言与标准 SQL 的差异）
  3. 数据类型详解（数值、String / FixedString、LowCardinality、Date / DateTime / DateTime64、Decimal、UUID、Enum、Array、Tuple、Map、Nested、Nullable 的代价、AggregateFunction）
  4. 表引擎全景图（MergeTree 家族 / Log 家族 / Memory / File / URL / MySQL / PostgreSQL / Kafka / S3 / Distributed / Materialized*，以及如何根据场景选择）
  5. MergeTree 核心原理（Part 目录结构、primary.idx 稀疏索引、Mark 与 Granule、index_granularity、Skip Index 跳数索引：minmax/set/bloom_filter/ngrambf_v1 等、PARTITION BY / ORDER BY / PRIMARY KEY 关系）
  6. MergeTree 家族进阶（ReplacingMergeTree 去重、SummingMergeTree 预聚合、AggregatingMergeTree 聚合状态、CollapsingMergeTree / VersionedCollapsingMergeTree 行折叠、GraphiteMergeTree，以及 FINAL 关键字的代价）
  7. 写入与读取最佳实践（批量写入、避免小批次、async_insert、Buffer 引擎、INSERT ... SELECT、FORMAT 全家桶、查询并发与 max_threads）
  8. 聚合、窗口函数与数组（GROUP BY / WITH ROLLUP / CUBE / TOTALS、HAVING、丰富的聚合函数 uniq* / quantile* / topK / argMax、窗口函数、ARRAY JOIN、Lambda 与高阶数组函数）
  9. JOIN 与字典（INNER/LEFT/RIGHT/FULL/CROSS/ANY/ASOF JOIN、JOIN 的内存代价、GLOBAL JOIN、Dictionary 字典作为「右表」加速、字典源 mysql / postgresql / http / file）
  10. 物化视图与 Projection（普通视图 vs 物化视图、POPULATE 的坑、链式物化视图、AggregatingMergeTree + MaterializedView 实时聚合、Projection 与物化视图的取舍）
  11. TTL、分区与数据生命周期（PARTITION BY 设计原则、TTL ... DELETE / TO VOLUME / TO DISK、冷热分层存储、分区裁剪、OPTIMIZE TABLE ... FINAL 的代价）
  12. Mutation：UPDATE / DELETE 的真相（ALTER TABLE … UPDATE/DELETE 异步重写机制、system.mutations、轻量级 lightweight DELETE、REPLACE PARTITION，以及为何 ClickHouse「不适合频繁改」）
  13. 副本与分布式（ReplicatedMergeTree + ZooKeeper/ClickHouse Keeper、副本同步流程、Distributed 引擎与本地表的关系、分片键、internal_replication、读写路径全景图）
  14. 集成生态（Kafka 引擎做实时摄入、MaterializedPostgreSQL 实时同步、S3 / HDFS 读写、MySQL / PostgreSQL 表函数、remote() 跨集群查询、Airbyte / Debezium 入仓）
  15. 权限、配额与多租户（用户与 Profile、GRANT/REVOKE、行级 / 列级权限、Quota 配额、max_memory_usage 等关键限制、SQL 防御性配置）
  16. 性能调优与查询分析（EXPLAIN PLAN / PIPELINE / ESTIMATE、system.query_log / system.parts / system.metrics 必看视图、trace_log 与火焰图、常见慢查询模式与优化手段）
  17. 运维与可观测（关键配置 config.xml / users.xml、SYSTEM 命令族、备份与恢复（BACKUP / RESTORE、clickhouse-backup）、升级与版本兼容、Prometheus/Grafana 监控）
  18. 生态与扩展（UDF：SQL UDF / Executable UDF、clickhouse-local 单机分析、chdb 嵌入式、与 Spark / Flink / Superset / Metabase 的集成）
  19. 综合实战项目（任选其一并贯穿：实时埋点分析平台 / 广告归因漏斗 / IoT 时序大屏 / 日志检索与告警 / 用户行为路径与留存分析）

七、产出格式约束 ​

  • 所有文档放在 learnNote/clickhouse/ 下，按 序号_主题.md 命名（如 01_intro.md、02_client_basic.md）。

  • 每章节配套的演示页面与代码放在同名子目录中，例如：

    learnNote/clickhouse/
├── 0_learn_plan.md          # 总学习路线（由本文档拆出来的精简版）
├── 01_intro.md
├── 01_intro/
│   ├── demo.html
│   └── code/
│       └── hello_ck.py
├── 02_client_basic.md
├── 02_client_basic/
│   ├── demo.html
│   ├── init.sql
│   └── code/
│       └── basic_query.py
├── 05_mergetree_core/
│   ├── demo.html            # 可视化演示 Part / Mark / Granule
│   ├── init.sql
│   ├── seed.py              # 千万级造数脚本
│   └── code/
│       └── explain_demo.py
├── ...
├── docker-compose.yml       # 可选：一键起 ClickHouse + Keeper
├── requirements.txt         # Python 依赖（clickhouse-connect 等）
├── interview.md             # 各章面试题总索引
├── appendix_cheatsheet.md   # 常用命令 / 函数速查表
├── appendix_ck_vs_mysql.md  # ClickHouse vs MySQL/PG 对比速查
└── appendix_pitfalls.md     # 踩坑案例集（FINAL、JOIN、Mutation 等）

  • 文档中的代码块必须标注语言（```sql、```bash、```python、```mermaid 等），方便高亮。

  • SQL 示例统一使用大写关键字 + 小写标识符（与官方文档一致），并在 01_intro.md 开篇明确这一约定。

  • 涉及性能的章节必须给出可复现的对比数据：

    • 表结构 / 数据量 / 机器规格写在小节开头；
    • 用 EXPLAIN PIPELINE 或 system.query_log 中的 read_rows / read_bytes / memory_usage / query_duration_ms 作为客观指标；
    • 给出「优化前 / 优化后」对照表。

  • 面试题统一汇总到每章末尾的「面试高频题」小节，并在 learnNote/clickhouse/interview.md 做总索引（按主题分类，例如「存储与索引」「MergeTree 家族」「副本与分片」「物化视图」「调优」「踩坑」）。

八、写作执行顺序（建议） ​

  1. 先产出 0_learn_plan.md：把第六节的大纲展开成「每章预计字数 / 核心知识点 / 配套实战 / 演示页要点 / 面试题数量」的表格，作为后续章节的施工图。
  2. 再按章节顺序逐个产出 0X_xxx.md + 同名目录下的 demo.html + init.sql + code/。
  3. 重点章节优先打磨：第 1、5、6、10、13 章是 ClickHouse 的「灵魂章节」，可以多投入篇幅与演示动画，其它章节保持节奏即可。
  4. 每完成 3 ~ 5 章，回顾一次 interview.md，把已完成章节的面试题归集进去。
  5. 全部章节产出后，再做一次总复盘：补充三个附录文档——
    • appendix_cheatsheet.md：常用 SQL / 函数 / SYSTEM 命令 / 关键 system.* 视图速查表；
    • appendix_ck_vs_mysql.md：ClickHouse vs MySQL / PostgreSQL / Doris / StarRocks 对比速查表；
    • appendix_pitfalls.md：典型踩坑集（小批量写入、滥用 FINAL、大表 JOIN、Nullable 滥用、Mutation 阻塞、OPTIMIZE FINAL 误用、分区粒度过细等）。