# ClickHouse 架构师 ClickHouse (v24.4+) 的规范性架构设计、压缩选择和性能优化。涵盖 ClickHouse Cloud (SharedMergeTree) 和自托管 (ReplicatedMergeTree) 部署。 ## 何时使用此技能在以下情况下使用此技能： * 使用 ORDER BY 键选择设计 ClickHouse 表模式 * 为列类型选择压缩编解码器 * 配置分区键以进行数据生命周期管理 * 添加性能加速器（投影、索引、字典） * 审核和优化现有的 ClickHouse 架构 ## 核心方法论 ### 架构设计工作流程设计或审查 ClickHouse 模式时请遵循以下顺序： 1. **定义 ORDER BY 键**（3-5 列，基数最低的在前） 2. **为每个列类型选择压缩编解码器** 3. **配置PARTITION BY**进行数据生命周期管理 4. **添加性能加速器**（预测、索引） 5. **使用审核查询进行验证**（请参阅脚本/） 6. **带有 COMMENT 语句的文档**（请参阅 [`references/schema-documentation.md`]()） ### ORDER BY 键选择 ORDER BY 子句是 ClickHouse 架构设计中最关键的决策。 **规则**： * 最多限制 3-5 列（每增加一列收益递减） * 首先放置基数最低的列（例如，将 `tenant_id` 放在 `timestamp` 之前） * 包括用于范围查询的 WHERE 子句中使用的所有列 * PRIMARY KEY 必须是 ORDER BY 的前缀（或省略使用完整的 ORDER BY） **示例**： -- 正确：低基数优先，4 列创建表交易（交换低基数（字符串），符号低基数（字符串），时间戳 DateTime64(3), trade_id UInt64, 价格浮动64，数量 Float64 ) 引擎 = MergeTree() ORDER BY（交易所、交易品种、时间戳、trade_id）； -- 错误：高基数优先（查询速度慢 10 倍） ORDER BY (trade_id, 时间戳, 交易品种, 交易所); ### 压缩编解码器快速参考列类型|默认编解码器 |大量阅读的替代方案 |示例 ---|---|---|--- 日期时间/日期时间64 | `编解码器（DoubleDelta，ZSTD）` | `编解码器（DoubleDelta，LZ4）` | `时间戳 DateTime64(3) 编解码器（DoubleDelta，ZSTD）` 浮动价格/指标 | `编解码器（大猩猩，ZSTD）` | `编解码器（大猩猩，LZ4）` | `价格 Float64 编解码器（Gorilla、ZSTD）` 整数计数器 | `编解码器（T64，ZSTD）` | — | `计数 UInt64 CODEC(T64, ZSTD)` 缓慢变化的整数 | `编解码器（Delta，ZSTD）` | `编解码器（Delta，LZ4）` | `版本 UInt32 编解码器（Delta，ZSTD）` 字符串（低基数）| `低基数（字符串）` | — | `状态低基数（字符串）` 一般数据| `编解码器（ZSTD（3））` | `编解码器（LZ4）` |默认压缩级别 3 **何时使用 LZ4 而不是 ZSTD**：LZ4 的解压速度快 1.76 倍。使用 LZ4 处理具有单调序列（时间戳、计数器）的读取繁重工作负载。当压缩比很重要或数据模式未知时，使用 ZSTD（默认）。 **关于编解码器组合的注意事项**： Delta/DoubleDelta + Gorilla 组合默认被阻止（allow_suspicious_codecs），因为 Gorilla 已经在内部执行隐式增量压缩——组合它们是**冗余**，并不危险。历史上的腐败错误（PR #45615，2023 年 1 月）已修复，但阻止仍然是最佳实践护栏。独立地将每个编解码器系列用于其预期的数据类型： -- 正确使用价格 Float64 CODEC(Gorilla, ZSTD) -- 浮点数：使用 Gorilla timestamp DateTime64 CODEC(DoubleDelta, ZSTD) -- 时间戳：使用 DoubleDelta timestamp DateTime64 CODEC(DoubleDelta, LZ4) -- 重读：使用 LZ4 ### 按准则分区 PARTITION BY 用于**数据生命周期管理**，而不是查询优化。 **规则**： * 按时间单位（月、周）划分，用于 TTL 和数据管理 * 将所有表的分区总数保持在 1000 以下 * 每个分区最多包含 1-300 个零件 * 切勿按高基数列分区 **示例**： -- 正确：按月分区进行 TTL 管理按 toYYYYMM（时间戳）分区 -- 错误：每日分区（部分太多）按 toYYYYMMDD（时间戳）分区 -- 错误：高基数分区键按 user_id 分区 ### 反模式清单 (v24.4+) 图案|严重性 |现代状态|修复 ---|---|---|--- 零件太多（>300/分区）|关键|仍然很关键|降低分区粒度小批量插入 (<1000) |关键|仍然很关键|批量处理 10k-100k 行高基数优先 ORDER BY |关键|仍然很关键|重新排序：基数最低的优先无内存限制 |高|仍然很关键|设置“最大内存使用量” 非规范化过度使用 |高|仍然很关键|使用字典+物化视图大型连接 |中等| **改进 180 倍** |仍然避免超低延迟突变（更新/删除）|中等| **改进 1700 倍** |使用轻量级更新 (v24.4+) ### 表引擎选择部署|发动机|使用案例 ---|---|--- ClickHouse云 | `共享合并树` |云部署的默认设置自托管集群| `ReplicatedMergeTree` |多节点复制自主办单| `合并树` |单节点开发/测试 **云（SharedMergeTree）**：创建表交易 (...) ENGINE = SharedMergeTree('/clickhouse/tables/{shard}/trades', '{replica}') ORDER BY（交易所、符号、时间戳）； **自托管（ReplicatedMergeTree）**：创建表交易 (...) ENGINE = ReplicatedMergeTree('/clickhouse/tables/{shard}/trades', '{replica}') ORDER BY（交易所、符号、时间戳）； ## 技能委托指南此技能是 ClickHouse 相关任务的**中心**。当用户的需求超出架构设计范围时，请调用以下相关技能。 ### 授权决策矩阵用户需求|召唤技能|触发短语 ---|---|--- 创建数据库用户，管理权限| `devops-tools：clickhouse-云管理` | “创建用户”、“授予”、“权限”、“凭据” 配置DBeaver，生成连接JSON | `devops-tools:clickhouse-pydantic-config` | “DBeaver”、“客户端配置”、“连接设置” 根据实时数据库验证架构合同 | `质量工具：schema-e2e-validation` | “验证模式”、“地球 E2E”、“模式契约” ### 典型工作流程顺序 1. **模式设计**（本技能）→设计ORDER BY、压缩、分区 2. **用户设置** → `clickhouse-cloud-management`（如果需要云凭据） 3. **客户端配置** → `clickhouse-pydantic-config`（生成 DBeaver JSON） 4. **验证** → `schema-e2e-validation`（CI/CD 模式合约） ### 示例：全栈请求 **用户**：“我需要为 ClickHouse Cloud 设计一个交易表并设置 DBeaver 来查询它。” **预期行为**： 1. 使用此技能进行模式设计 2.调用`clickhouse-cloud-management`创建数据库用户 3. 调用 `clickhouse-pydantic-config` 进行 DBeaver 配置 ## 性能加速器 ### 预测创建 ClickHouse 自动选择的替代排序顺序：更改表交易添加投影 trades_by_symbol ( SELECT * ORDER BY 符号、时间戳）；更改表交易具体化投影 trades_by_symbol; ### 物化视图仪表板查询的预计算聚合：创建物化视图 trades_hourly_mv 引擎 = SummingMergeTree() ORDER BY（交易所、代码、小时）作为选择交换，符号, toStartOfHour(时间戳) AS 小时， sum(数量) AS 总体积， count() 作为 trade_count 来自交易 GROUP BY 交易所、交易品种、时间； ### 字典将 JOIN 替换为 **大规模星型模式** 的 O(1) 字典查找： **何时使用字典 (v24.4+)** : * 具有 100M+ 行连接维度表的事实表 * 具有单调键的维度表 1k-500k 行 * 需要 LEFT ANY JOIN 语义 **当 JOIN 足够时 (v24.4+)** ： * 维度表 <500 行（JOIN 开销可以忽略不计） * v24.4+ 谓词下推提供 8-180 倍的改进 * 复杂 JOIN 类型（FULL、RIGHT、多条件） **基准上下文**：在星型模式基准（1.4B 行）上测量得到 6.6 倍加速。创建字典symbol_info ( 符号字符串，名称字符串，扇区字符串）主键符号源（ClickHouse（表'符号'）） LAYOUT(FLAT()) -- 最适合使用单调键的 <500k 条目寿命（3600）； -- 在查询中使用（O(1) 查找）选择符号, dictGet('符号信息', '名称', 符号) AS 符号名称来自交易； ## 脚本执行全面的架构审核： clickhouse-client --multiquery <脚本/schema-audit.sql 审核脚本检查： * 每个分区的部件数（阈值：300） * 按列的压缩率 * 查询性能模式 * 复制延迟（如果适用） * 内存使用模式 ## 其他资源 ### 参考文件参考|内容 ---|--- [`references/schema-design-workflow.md`]() |完整的工作流程和示例 [`references/compression-codec-selection.md`]() |决策树+基准 [`references/anti-patterns-and-fixes.md`]() | 13 罪 + v24.4+ 状态 [`references/audit-and-diagnostics.md`]() |查询解释指南 [`references/idiomatic-architecture.md`]() |参数化视图、字典、重复数据删除 [`references/schema-documentation.md`]() | AI 理解的 COMMENT 模式 + 命名 [`references/cache-schema-evolution.md`]() |缓存失效+模式演化模式 ### 外部文档 * [ClickHouse 最佳实践]() * [Altinity知识库]() * [ClickHouse 博客]() ## Python 驱动程序策略 **使用`clickhouse-connect`（官方）进行所有Python集成。** # ✅ 推荐：clickhouse-connect（官方，HTTP）导入clickhouse_connect 客户端 = clickhouse_connect.get_client( 主机='本地主机', port=8123, # HTTP 端口用户名='默认', 密码='' ） result = client.query("SELECT * FROM 交易 LIMIT 1000") df = client.query_df("SELECT * FROM trades") # Pandas 集成 ### 为什么不`clickhouse-driver` 因素 | clickhouse-连接 | clickhouse-驱动程序 ---|---|--- 维护者 | ClickHouse 公司 |独立开发者每周提交 |是（主动）|稀疏（月）未解决的问题 | 41（已解决）| 76（累计中）每周下载次数 | 270 万 | 1.5M 总线因素风险|低（公司）| **高（1人）** **不要使用`clickhouse-driver`**，尽管它对于大型导出有约 26% 的速度优势。维护风险超过性能收益： * 单一维护者 (mymarilyn)，没有继任计划 * 问题累积而无响应 * 废弃的风险会破坏生产代码 **例外**：仅当您有极端的性能要求（导出数百万行）并接受维护风险时才考虑“clickhouse-driver”。 ## 相关技能技能|目的 ---|--- `devops-tools：clickhouse-云管理` |用户/权限管理 `devops-tools:clickhouse-pydantic-config` | DBeaver 连接生成 `质量工具：schema-e2e-validation` | YAML 架构合约 `质量工具：多代理 e2e 验证` |数据库迁移验证 ** ** ## 故障排除问题 |原因 |解决方案 ---|---|--- 零件太多 |过度分区|减少分区粒度（每月而不是每天）慢查询 | ORDER BY 顺序错误 |将基数最低的列放在前面内存使用率高 |未设置内存限制 |配置 max_memory_usage 设置 Delta+Gorilla 上的编解码器错误 |可疑的编解码器组合 |独立使用每个编解码器系列未使用投影|优化器选择了不同的计划 |检查 EXPLAIN 以验证投影选择字典陈旧 |生命周期已过 |增加 LIFETIME 或触发刷新复制滞后 |部分合并落后|检查merge_tree设置，添加资源插入太慢|小批量 |每个 INSERT 批量处理 10k-100k 行

Clickhouse建筑师

包含技能