altinity-expert-clickhouse-ingestion

INSERT 与摄取性能

通过 system.query_log、system.part_log、system.query_views_log、system.kafka_consumers、system.processes 和 system.text_log，回答“为什么插入速度慢、失败或创建了过多分区”。 如果尚未确定连接模式、集群和时间范围，请先运行 altinity-expert-clickhouse-connection。

查询包

• checks.sql — 14 项检查：Kafka 消费者健康状况和调度容量、正在运行和近期的插入活动、每个表的分区创建速率、插入与合并的平衡、慢速插入、物化视图对插入的开销、失败的插入、批次大小分布、Kafka 引擎摄取、日志中的 Kafka 消息、Buffer 表刷新模式，以及当前与插入相关的设置。其中 2 项需要 system.part_log，1 项需要 system.query_views_log，1 项需要 system.text_log。

如何运行查询包

1. 从此技能的目录读取每个包文件（技能加载器会打印目录路径）。
2. 一次运行一条语句，绝不要运行整个文件。语句以 ; 结尾，并以 -- @check <id> <title> 标头开头；将 id 与结果一并保留。
3. 遵循 -- @requires：当指定的表缺失、需要 keeper 但服务器没有 Keeper/ZooKeeper，或不满足版本条件时，跳过该语句。列出跳过的 id 及原因。
4. 如果存在集群宏，按原样保留 {cluster}；否则应用连接技能中的改写规则。其他任何 {placeholder} 都是模板变量：先替换为实际值，否则跳过该语句。
5. 出错时，记录检查 id 和错误的第一行，然后继续。仅当错误为 UNKNOWN_IDENTIFIER 时，运行 DESCRIBE TABLE system.<table> 并移除缺失的列。
6. severity 列是该行的判定结果。照录即可；不要重新评级。

深入分析语句

当已知慢速插入的 query_id 时，按物化视图拆解其耗时。将 {query_id} 替换为从检查 ingestion-07 或 ingestion-08 中获取的 id。

SELECT
    view_name,
    view_duration_ms,
    read_rows,
    written_rows,
    status,
    exception
FROM system.query_views_log
WHERE query_id = '{query_id}'
ORDER BY view_duration_ms DESC;

解读规则

• 每次插入的平均 written_rows 低于 1000，表示批次过小：客户端为每一行承担分区创建成本。建议每条 INSERT 批量插入 10k-1M 行；若客户端无法批量插入，则启用 async_insert。检查 ingestion-10 返回的是 batch_status，而非 severity；将 “Seriously under-batched” 视为 Major，将 “Could improve” 视为 Moderate。
• 同一时间窗口内 NewPart 事件很多而 MergeParts 事件很少（ingestion-06），意味着合并跟不上摄取速度，并非插入太慢。插入侧运行正常；问题在合并侧。
• 当 system.query_views_log 显示视图耗时占插入耗时的主要部分（ingestion-08）时，应修复物化视图查询，而非插入。指出最慢的视图及其占插入耗时的比例。
• Buffer 表会增加自身的刷新延迟：只有刷新后才能看到行；较大的 Buffer 会占用更多内存，并在重启时带来数据丢失窗口。ingestion-13 中的刷新模式可以解释仅靠 query_log 无法显示的插入到可见延迟。
• 当 part_log 被禁用时，跳过标记为 @requires table:system.part_log 的检查。请明确说明这一点，不要据此断定分区创建正常；没有 part_log，就无法确定分区创建速率以及插入与合并的平衡情况。
• 失败的插入（ingestion-09）若出现 TOO_MANY_PARTS 或文本 “Too many parts”，是合并积压的症状，而非插入错误。插入时出现 MEMORY_LIMIT_EXCEEDED，通常是由物化视图或单个批次过大导致。
• 这里仅汇总 Kafka 检查（ingestion-01、-02、-11、-12）。若轮询或提交时间持续增长，或异常数组非空，就应转到 Kafka 技能，而不是在本技能中继续深入排查。

报告格式

1. 标题：连接模式、集群或“单节点”、ClickHouse 版本、时间范围。
2. 发现：包含 check、severity、object、evidence、recommendation 列的表格；每项发现占一行，按严重程度从高到低排列。证据引用结果行中的数字。
3. 正常检查：用一行列出未返回问题行的检查 ID。
4. 跳过和失败的检查：列出 ID 和原因或第一条错误信息。此部分不得省略。
5. 后续步骤：接下来要加载的技能和立即采取的措施。

后续技能

• Kafka 消费者延迟、消费者异常、重新均衡或消费者数量超过池大小 → 加载技能 altinity-expert-clickhouse-kafka
• 分区创建速度超过合并速度、TOO_MANY_PARTS、每个分区包含许多分区片段 → 加载技能 altinity-expert-clickhouse-merges
• 物化视图查询本身很慢或读取数据过多 → 加载技能 altinity-expert-clickhouse-reporting
• 插入失败并出现 MEMORY_LIMIT_EXCEEDED 或峰值内存过高 → 加载技能 altinity-expert-clickhouse-memory
• 分区键过于细化、宽表或物化视图设计问题 → 加载技能 altinity-expert-clickhouse-schema
• 插入延迟与磁盘或写入吞吐量相关 → 加载技能 altinity-expert-clickhouse-storage
• 插入操作被复制表阻塞或等待 insert_quorum → 加载技能 altinity-expert-clickhouse-replication