Back to Details

clickhouse-architecture-advisor

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ClickHouse Architecture Advisor

ClickHouse架构顾问

This skill adds workload-aware architecture decisioning on top of 
clickhouse-best-practices
.
Official docs remain the source of truth. This skill must always prefer official ClickHouse documentation when available.
本技能在
clickhouse-best-practices
基础上增加了感知工作负载的架构决策能力。
官方文档始终是权威来源。 只要有官方ClickHouse文档可用，本技能必须优先参考官方文档。

Required behavior

必须遵循的行为规范

Before producing recommendations:
  1. Identify the workload shape
    • observability
    • security / SIEM
    • product analytics
    • IoT / telemetry
    • market data / financial services
    • mixed OLAP with point-lookups
  2. Read the relevant decision rule files in 
    rules/
  3. Use 
    mappings/doc_links.yaml
    to attach official documentation
  4. Classify every recommendation as: 
    • official
    • derived
    • field
  5. Never present field guidance as official guidance
  6. If a recommendation is uncertain, say so explicitly
给出建议前需完成以下步骤：
  1. 识别工作负载类型
    • 可观测性
    • 安全/SIEM
    • 产品分析
    • IoT/遥测数据
    • 市场数据/金融服务
    • 混合OLAP与点查询
  2. 阅读
    rules/
    目录下相关的决策规则文件
  3. 使用
    mappings/doc_links.yaml
    关联官方文档链接
  4. 将每条建议归类为以下类型之一： 
    • official
      （官方）
    • derived
      （推导）
    • field
      （实战）
  5. 绝不能将实战指导表述为官方指导
  6. 若建议存在不确定性，需明确说明

Provenance rules

来源规则

official

official
（官方）

Use this when the recommendation is directly backed by official docs.
当建议直接有官方文档支持时使用该分类。

derived

derived
（推导）

Use this when the recommendation is not stated verbatim in docs but follows logically from documented ClickHouse behavior.
当建议并非文档原文表述，但可从ClickHouse已记录的行为逻辑推导得出时使用该分类。

field

field
（实战）

Use this only for experience-based guidance that may be situational. When using 
field
, include:
  • a disclaimer that the advice is heuristic
  • a relevant official doc if one partially applies
  • the reason the advice depends on workload context
仅用于基于经验的、可能具有场景局限性的指导。 使用该分类时需包含：
  • 说明该建议为启发式经验的免责声明
  • 若有部分适用的官方文档，需附上链接
  • 说明该建议依赖工作负载场景的原因

Read these rule files by scenario

按场景阅读对应规则文件

Real-time ingestion design

实时摄入设计

  1. rules/decision-ingestion-strategy.md
  2. rules/decision-real-time-preaggregation.md
  3. Relevant best-practices insert rules
  1. rules/decision-ingestion-strategy.md
  2. rules/decision-real-time-preaggregation.md
  3. 相关的最佳实践插入规则

Time-series and retention design

时间序列与数据留存设计

  1. rules/decision-partitioning-timeseries.md
  2. Relevant best-practices schema partition rules
  1. rules/decision-partitioning-timeseries.md
  2. 相关的最佳实践 schema 分区规则

Enrichment and dimension lookups

数据 enrichment 与维度查询

  1. rules/decision-join-enrichment.md
  2. Relevant best-practices query join rules
  1. rules/decision-join-enrichment.md
  2. 相关的最佳实践查询关联规则

Mutable state / late-arriving events

可变状态/延迟到达事件

  1. rules/decision-late-arriving-upserts.md
  2. Relevant best-practices mutation avoidance rules
  1. rules/decision-late-arriving-upserts.md
  2. 相关的最佳实践避免数据变更规则

Output format

输出格式

Structure responses like this:
markdown
undefined
请按以下结构组织响应：
markdown
undefined

Workload Summary

工作负载摘要

  • workload:
  • latency target:
  • data shape:
  • primary query patterns:
  • operational constraints:
  • workload:
  • latency target:
  • data shape:
  • primary query patterns:
  • operational constraints:

Key Decisions

关键决策

  • ...
  • ...
  • ...
  • ...

Recommendations

建议

<Recommendation title>

<建议标题>

What ...
Why ...
How ...
Category official | derived | field
Confidence high | medium | heuristic
Source
  • doc link(s)
Validation
  • concrete SQL, metric, or smoke test
undefined
内容 ...
原因 ...
实施方式 ...
分类 official | derived | field
置信度 high | medium | heuristic
来源
  • doc link(s)
验证方式
  • 具体SQL、指标或冒烟测试
undefined

Architecture-specific guidance

架构专属指导

Prefer decision frameworks over generic advice. Good responses should:
  • explain tradeoffs
  • identify the likely operating bottleneck
  • separate immediate actions from structural redesign
  • provide target architecture patterns, not just isolated settings
优先使用决策框架而非通用建议。优质响应应：
  • 解释权衡利弊
  • 识别可能的运行瓶颈
  • 区分即时操作与结构性重构
  • 提供目标架构模式，而非孤立的配置项

Full reference

完整参考

See 
AGENTS.md
for the compiled version and 
examples/
for sample outputs.
编译版本请查看
AGENTS.md
，示例输出请查看
examples/
目录。