clickhouse-best-practices

SKILL.md

28 ClickHouse best practices rules organized by schema design, query optimization, and data ingestion strategy.

Covers three critical areas: primary key and data type selection (immutable design decisions), JOIN and query optimization, and insert batching with mutation avoidance

Includes 28 rules prioritized by impact, with schema design and query optimization rules marked CRITICAL due to ClickHouse's columnar storage and sparse index mechanics

Provides structured review procedures for schemas, queries, and insert strategies, with checklists and rule citations for formal code reviews

Each rule file contains incorrect/correct examples and trade-off context; full compiled guide available in AGENTS.md for quick multi-rule reference

ClickHouse Best Practices

Comprehensive guidance for ClickHouse covering schema design, query optimization, data ingestion, and AI agent connectivity. Contains 31 rules across 4 main categories (schema, query, insert, agent), prioritized by impact.

Official docs: ClickHouse Best Practices

IMPORTANT: How to Apply This Skill

Before answering ClickHouse questions, follow this priority order:

Check for applicable rules in the rules/ directory

If rules exist: Apply them and cite them in your response using "Per rule-name..."

If no rule exists: Use the LLM's ClickHouse knowledge or search documentation

If uncertain: Use web search for current best practices

Always cite your source: rule name, "general ClickHouse guidance", or URL

Why rules take priority: ClickHouse has specific behaviors (columnar storage, sparse indexes, merge tree mechanics) where general database intuition can be misleading. The rules encode validated, ClickHouse-specific guidance.