# Clickhouse Architecture Advisor

MUST USE when designing ClickHouse architectures, selecting between ingestion or...

- Repository: https://github.com/ClickHouse/agent-skills (565 stars)
- Category: Design
- License: Apache-2.0
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add ClickHouse/agent-skills --skill clickhouse-architecture-advisor -g -a claude-code -y`
Codex: `npx skills add ClickHouse/agent-skills --skill clickhouse-architecture-advisor -g -a codex -y`
Cursor: `npx skills add ClickHouse/agent-skills --skill clickhouse-architecture-advisor -g -a cursor -y`
Gemini CLI: `npx skills add ClickHouse/agent-skills --skill clickhouse-architecture-advisor -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add ClickHouse/agent-skills`

## Description

MUST USE when designing ClickHouse architectures, selecting between ingestion or modeling patterns, or translating best practices into workload-specific system designs. Complements clickhouse-best-practices with decision frameworks and explicit provenance labels.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# ClickHouse Architecture Advisor

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.

## 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

## Provenance rules

### `official`
Use this when the recommendation is directly backed by official docs.

### `derived`
Use this when the recommendation is not stated verbatim in docs but follows logically from documented ClickHouse behavior.

### `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

### Time-series and retention design
1. `rules/decision-partitioning-timeseries.md`
2. Relevant best-practices schema partition rules

### Enrichment and dimension lookups
1. `rules/decision-join-enrichment.md`
2. Relevant best-practices query join rules

### Mutable state / late-arriving events
1. `rules/decision-late-arriving-upserts.md`
2. Relevant best-practices mutation avoidance rules

## Output format

Structure responses like this:

The rest: https://github.com/ClickHouse/agent-skills/blob/HEAD/skills/clickhouse-architecture-advisor/SKILL.md