clickhouse/clickhouse

ClickHouse

ClickHouse is an open-source column-oriented database management system (DBMS) for online analytical processing (OLAP). It is written in C++ and designed to run analytical queries over very large datasets at high speed by combining vectorized execution, sparse primary indexes, and a merge-tree storage layout that compresses data into immutable columnar parts.

What this wiki covers

This wiki is a guided tour of the source tree at the root of the ClickHouse repository. It maps the C++ subsystems under src/ to the user-facing concepts (MergeTree, replication, distributed queries, materialized views, etc.) and to the binaries shipped from programs/ (clickhouse-server, clickhouse-client, clickhouse-local, clickhouse-keeper). It is oriented at engineers who want to read or change ClickHouse internals — not at SQL users, who should refer to the official documentation instead.

High-level structure

ClickHouse ships as a single multi-call binary. The dispatch table for subcommands lives in programs/main.cpp:

clickhouse server — long-running database server
clickhouse client — interactive TCP/native client
clickhouse local — single-process query engine over local files
clickhouse keeper — Raft-based metadata coordination service (a ZooKeeper replacement)
A long tail of operator tools: compressor, format, obfuscator, disks, keeper-utils, static-files-disk-uploader, extract-from-config, git-import, benchmark, etc.

The source tree under src/ is organized by responsibility, not by feature. The most important roots are:

Directory	Responsibility
`src/Storages/`	Table engines (`MergeTree`, `Distributed`, `Kafka`, object storage, MySQL, etc.)
`src/Storages/MergeTree/`	The columnar storage engine that powers analytics
`src/Interpreters/`	Query context, expression analysis, joins, aggregation, DDL coordination
`src/Analyzer/` and `src/Planner/`	The new query analyzer and planner pipeline
`src/Parsers/`	SQL parsers and AST nodes
`src/Processors/`	The pull/push physical operator graph (the execution engine)
`src/QueryPipeline/`	Wiring between processors and the rest of the engine
`src/Functions/` and `src/AggregateFunctions/`	The thousands of built-in scalar and aggregate functions
`src/DataTypes/`, `src/Columns/`, `src/Core/`	Type system, columnar containers, `Block`/`Field`
`src/IO/` and `src/Disks/`	Buffered I/O abstractions and disk plugins (S3, Azure, HDFS, web, …)
`src/Coordination/`	The native Raft-based Keeper service (NuRaft + RocksDB)
`src/Backups/`	`BACKUP`/`RESTORE` orchestration and storage backends
`src/Access/`	Users, roles, grants, row policies, quotas, settings profiles
`src/Server/`	HTTP, native TCP, MySQL/PostgreSQL/gRPC/ArrowFlight wire protocols
`src/Client/`	Code shared between the various clients
`src/Compression/`	Column codecs (LZ4, ZSTD, Delta, T64, Gorilla, FPC, …)
`src/Common/`	Hash tables, allocators, logging, profiling, ZooKeeper client, etc.

External dependencies live in contrib/ as git submodules — 250+ of them. ClickHouse vendors everything: Boost, Poco, Arrow, Parquet, RocksDB, NuRaft, LZ4, ZSTD, re2, OpenSSL, Avro, Iceberg, Delta-Kernel, Hive metastore, protobuf, gRPC, cppkafka, etc. The build itself uses CMake and ninja with clang (see Getting started).

Where to read next

Architecture — the request lifecycle, from SQL string to columnar response.
Glossary — Block, Part, Granule, Mark, Replicated*, etc.
How to contribute — workflow, testing, debugging, conventions.
Apps — the binaries shipped from programs/.
Systems — the major C++ subsystems under src/.
Features — cross-cutting capabilities (replication, distributed queries, materialized views, vector search, …).

What this wiki covers

High-level structure

Where to read next

See also