clickhouse-best-practices

Review ClickHouse schemas and queries against 28 validated best-practice rules.

1.6k|107|Updated Feb 15, 2026
One-click install
npx skills add https://github.com/MapleTechLabs/maple --skill clickhouse-best-practices-mapletechlabs
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: clickhouse-best-practices
Source: https://github.com/MapleTechLabs/maple/tree/main/.agents/skills/clickhouse-best-practices
Command: npx skills add https://github.com/MapleTechLabs/maple --skill clickhouse-best-practices-mapletechlabs

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill eliminates the risk of poor ClickHouse performance and cluster instability caused by applying general database best practices that fail to account for ClickHouse's unique columnar storage, sparse primary indexes, and merge tree architecture. It ensures all schema designs, queries, and data ingestion workflows follow ClickHouse-specific validated rules to avoid costly performance pitfalls.

Core Features & Use Cases

  • 28 Prioritized Rules: Covers schema design, query optimization, and insert strategy with clear impact ratings (CRITICAL/HIGH/MEDIUM) and concrete incorrect/correct SQL examples.
  • Formal Review Workflows: Structured procedures for schema reviews, query reviews, and insert strategy reviews with checklists to ensure no critical rules are missed.
  • Use Cases: Ideal for reviewing CREATE TABLE statements, troubleshooting slow observability queries, optimizing data ingestion pipelines for logging and metrics workloads, and tuning JOIN performance for large-scale analytics.

Quick Start

Use the clickhouse-best-practices skill to audit your existing ClickHouse table schema for primary key ordering, data type, and partitioning rule violations.

Frequently Asked Questions about clickhouse-best-practices

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I optimize slow ClickHouse queries for observability workloads?

Optimize slow ClickHouse queries by applying 28 validated rules covering primary key selection, data type optimization, and JOIN algorithm selection. Troubleshoot observability and logging workloads using formal review workflows with concrete incorrect and correct SQL examples.

What are the best practices for ClickHouse schema design and primary key selection?

ClickHouse schema design best practices require choosing primary keys that align with sparse primary indexes and merge tree architecture. Review CREATE TABLE statements against rules for data type optimization and partitioning to prevent costly performance pitfalls.

Does general SQL database optimization work for ClickHouse?

General SQL database optimization fails for ClickHouse because it ignores columnar storage, sparse primary indexes, and merge tree architecture. Apply ClickHouse-specific guidance across 28 rules to prevent cluster instability and poor performance.

How do I tune JOIN performance in ClickHouse for large-scale analytics?

Tune JOIN performance in ClickHouse by selecting appropriate JOIN algorithms based on the columnar storage architecture. Apply validated rules for large-scale analytics workloads with concrete SQL examples to avoid misapplied general database practices.

When should I not use mutations in ClickHouse?

Avoid ClickHouse mutations when possible by using insert batching and proper schema design. Mutations cause performance issues in the merge tree architecture; apply validated rules to bypass them and maintain cluster stability.