clickhouse-architecture-advisor

A design consultation for a ClickHouse database, shaped around the kind of data and traffic you actually have, where every suggestion is marked as either backed by the official documentation or drawn from field experience.

WHEN TO USE

SCOPE

USE FOR

Design a pipeline that takes data in as it arrives and totals it up on the way.
Decide how to split up time-stamped data and how long to keep each slice.
Decide how to attach extra details, like a customer's name, to rows at query time.
Cope with records that arrive late without rewriting data already stored.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (7)

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:

Identify the workload shape
- observability
- security / SIEM
- product analytics
- IoT / telemetry
- market data / financial services
- mixed OLAP with point-lookups
Read the relevant decision rule files in rules/
Use mappings/doc_links.yaml to attach official documentation
Classify every recommendation as:
- official
- derived
- field
Never present field guidance as official guidance
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

rules/decision-ingestion-strategy.md
rules/decision-real-time-preaggregation.md
Relevant best-practices insert rules

Time-series and retention design

rules/decision-partitioning-timeseries.md
Relevant best-practices schema partition rules

Enrichment and dimension lookups

rules/decision-join-enrichment.md
Relevant best-practices query join rules

Mutable state / late-arriving events

rules/decision-late-arriving-upserts.md
Relevant best-practices mutation avoidance rules

Output format

Structure responses like this:

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

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.

This skill ships inside the ClickHouse Agent Skills plugin.

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add clickhouse/agent-skills --skill "clickhouse-architecture-advisor" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

What's inside

Files included with this skill.

View on GitHub

Same repository

chdb-datastore
Use when the user has tabular data (pandas DataFrame, parquet, csv, Arrow, json) and wants to filter, group, aggregate, join, or speed up slow pandas. Provides chDB DataStore — same pandas API, ClickHouse engine underneath. Also handles reading from S3, MySQL, PostgreSQL, MongoDB, ClickHouse Cloud, Iceberg, Delta Lake as DataFrames and joining across sources. TRIGGER when: user mentions DataFrame, parquet, csv, "fast pandas", "speed up pandas", or cross-source DataFrame joins; user imports chdb.datastore or from datastore import DataStore. SKIP this skill for raw SQL syntax (use chdb-sql instead), ClickHouse server administration, or non-Python DataStore API work.Read full description
chdb-sql
Use when the user wants to run SQL — especially analytical SQL — on local files (parquet/csv/json), URLs, S3 paths, or remote databases (Postgres, MySQL, MongoDB, ClickHouse Cloud, Iceberg, Delta Lake) without setting up a server. Provides chDB — embedded ClickHouse SQL in Python with 1000+ functions, Session for stateful multi-step pipelines, parametrized queries, and cross-source joins via s3(), mysql(), postgresql(), iceberg(), deltaLake(), remoteSecure() table functions. TRIGGER when: user wants SQL on parquet/csv/files or across remote analytical sources; uses ClickHouse SQL features (window functions, windowFunnel, geoToH3, JSON path ops, Session, parametrized queries); imports chdb or calls chdb.query(). SKIP this skill for pandas-style DataFrame method-chaining (use chdb-datastore instead) or ClickHouse server administration.Read full description
clickhouse-best-practices
MUST USE when reviewing ClickHouse schemas, queries, or configurations. Contains 31 rules that MUST be checked before providing recommendations. Always read relevant rule files and cite specific rules in responses.Read full description
clickhouse-js-node-coding
Write idiomatic application code with the ClickHouse Node.js client (@clickhouse/client). Use this skill whenever a user is *building* against the Node.js client — configuring the client, pinging, inserting rows in JSON or raw formats, selecting and parsing results, binding query parameters, managing sessions and temporary tables, working with data types or customizing JSON parsing. Do NOT use for browser/Web client code.Read full description
clickhouse-js-node-rowbinary
Generate TypeScript/JavaScript code that reads/decodes AND writes/encodes ClickHouse RowBinary streams for the ClickHouse HTTP server. Use this skill whenever a user wants to parse or produce RowBinary, RowBinaryWithNames, or RowBinaryWithNamesAndTypes. Node.js only, doesn't cover browsers.Read full description
clickhouse-js-node-troubleshooting
Troubleshoot and resolve common issues with the ClickHouse Node.js client (@clickhouse/client). Use this skill whenever a user reports errors, unexpected behavior, or configuration questions involving the Node.js client specifically — including socket hang-up errors, Keep-Alive problems, stream handling issues, data type mismatches, read-only user restrictions, proxy/TLS setup problems, or long-running query timeouts. Trigger even when the user hasn't precisely named the issue; vague symptoms like "my inserts keep failing" or "connection drops randomly" in a Node.js context are strong signals to use this skill. Do NOT use for browser/Web client issues.Read full description