ClickHouse Developer Guide

A practical collection of English-language notes for understanding, building, testing, debugging, and profiling ClickHouse. The guides focus on source-code paths, storage internals, query execution, and reproducible operational workflows.

This is a community-maintained learning resource and is not official ClickHouse documentation. Details may vary by ClickHouse version.

Contents

Build, test, and CI

• Build ClickHouse
• Troubleshoot compilation
• Run unit tests
• Run integration tests
• Read CI results

Core query engine and analyzer (Query Pipeline 2.0)

• New Analyzer, QueryTreeNode AST, and Processor Execution Graph

TimeSeries storage engine and PromQL

• ENGINE = TimeSeries, PromQL-to-SQL Translation, Welford/Chan Variance & Stale Markers

MergeTree, Object Storage, and Zero-Copy

• MergeTree interfaces
• MergeTree read path
• MergeTree read modes
• MergeTree Granules, Object Storage (S3/Azure), and Zero-Copy Replication
• Broken parts
• Merge implementation notes
• Disk abstractions
• MinIO setup

Replication, ClickHouse Keeper, and Parallel Replicas

• ReplicatedMergeTree Replication Log, Keeper Concurrency & Parallel Replicas

SIMD vectorization, memory architecture, and profiling

• SIMD Vectorization (AVX2/AVX-512/ARM Neon), Memory Infrastructure (PODArray/Arena) & FlameGraphs
• CPU and memory flame graphs
• Profiling release builds with perf

Data types, expressions, and functions

• Dynamic and JSON storage models
• Map column design and storage
• Expression trees and actions
• Function return types
• Utility classes

Query execution and indexes

• Distributed query send/receive path
• Hash join internals
• Text skip index internals
• apply_mutations_on_fly internals
• Python client and concurrent insert example

Using this guide

Start with the topic closest to the subsystem you are investigating. Most pages assume familiarity with Linux, C++, SQL, and the ClickHouse source tree. Commands and source paths should be checked against the ClickHouse version you are using.

Contributing

Corrections, clearer explanations, and version-specific updates are welcome. Keep examples reproducible, identify the ClickHouse version when behavior is version-dependent, and link to relevant source files where possible.