Glossary

ClickHouse uses a large number of project-specific terms. This page lists the ones you will hit while reading the source.

Storage

• Part — an immutable, sorted, columnar directory on disk. The atomic unit of MergeTree. Each part has its own primary key, marks, and column files. See IMergeTreeDataPart.h.
• Active part — a part visible to queries. Inactive parts are kept on disk for a grace period for snapshot/recovery and then cleaned up.
• Granule — a contiguous range of rows inside a part. The granularity is configured by index_granularity (rows) or index_granularity_bytes. Marks index points at granule boundaries.
• Mark — an offset into a column file. There is one mark per granule per column substream. Stored in *.mrk2 / *.mrk3 files. See MergeTreeMarksLoader.cpp.
• Primary index — a sparse, sorted list of the primary key values at granule boundaries. Held in memory, used to skip granules. See MergeTreeIndexGranularity.cpp.
• Skip index (data skipping index) — a secondary index attached to a column or expression that summarizes ranges of granules (minmax, set, bloom_filter, tokenbf, text, vector_similarity, …). See MergeTreeIndices.h.
• Projection — an alternative materialized view of a table stored alongside the main parts. The optimizer rewrites queries to use them when cheaper. See ProjectionsDescription.cpp.
• TTL — time-to-live expression on a column or table that drops or moves rows during merges. See TTLDescription.cpp.
• Mutation — an asynchronous ALTER UPDATE/ALTER DELETE. Implemented as a merge that rewrites the affected ranges. See MergeTreeMutationEntry.cpp.
• Lightweight delete — a quick DELETE that writes a _row_exists mask without rewriting data. Combined with mutations and merges over time.
• Compact part / Wide part — two on-disk layouts. Compact stores all columns in a single file; wide gives each column its own file. Choice is driven by part size.
• Quorum insert — a write that is acknowledged only after replication to a configured quorum of replicas.

Query path

• AST — output of src/Parsers/. See ASTSelectQuery, ASTFunction, etc.
• QueryTree — typed, semantically-resolved query representation produced by the analyzer (src/Analyzer/). Replaces the legacy ASTSelectQuery interpretation path.
• Analyzer — the new query analyzer (src/Analyzer/). Toggleable via enable_analyzer.
• Planner — src/Planner/. Walks the QueryTree and emits a QueryPlan.
• QueryPlan — a tree of logical steps (src/Processors/QueryPlan/).
• Pipeline — the physical processor graph built from a QueryPlan. Lives in src/QueryPipeline/ and src/Processors/.
• Processor — a node in the execution graph. Has input/output ports and a work() method. See IProcessor.h.
• Chunk — a unit of column data flowing between processors. Wraps a Columns array plus row count.
• Block — a named collection of columns plus types. Used in static analysis and the legacy interpreter path. See Core/Block.h.
• Column — a typed contiguous container holding many values. See Columns/IColumn.h. Concrete subclasses include ColumnVector<T>, ColumnString, ColumnArray, ColumnNullable, ColumnLowCardinality, ColumnTuple.
• Field — a boxed scalar (variant). Used in interpretation, parameter binding, and formatting.
• DataType — the static description of a column's type (DataTypeUInt32, DataTypeArray, DataTypeNullable, …). Holds serialization logic.
• ActionsDAG — the compiled expression DAG used for filters, projections, and aggregations. See Interpreters/ActionsDAG.cpp.
• ExpressionActions — a lower-level executable form of an ActionsDAG. Some inner-loop expressions are JIT-compiled (ExpressionJIT.cpp).

Distribution

• Distributed table — a stateless query router. Holds no data; forwards SELECT/INSERT to shards listed in a cluster config. See StorageDistributed.cpp.
• Shard — a logical partition of a distributed table.
• Replica — one of multiple copies of a shard.
• Cluster — the named set of shards/replicas declared in <remote_servers> of config.xml. See Interpreters/Cluster.cpp.
• Cluster discovery — auto-population of clusters from Keeper. See ClusterDiscovery.cpp.
• Parallel replicas — a feature where one query is split across replicas of the same shard for more parallelism.
• Initial query / sub-query — the parent query and its children on remote shards.

Coordination

• Keeper / clickhouse-keeper — ClickHouse's native Raft-based coordination service. Speaks the ZooKeeper wire protocol. Lives in src/Coordination/.
• NuRaft — the Raft consensus library vendored under contrib/NuRaft.
• ZooKeeper path — replication metadata is stored at /clickhouse/tables/{shard}/{table}/.... See TableZnodeInfo.cpp.

Storage backends

• IDisk — abstract disk handle. Implementations include local filesystem, S3, Azure, HDFS, web, encrypted, cached, in-memory. See Disks/IDisk.h.
• ObjectStorage — disk implementations that wrap object stores (S3, Azure, HDFS, local fake). See Disks/ObjectStorages/.
• Cache disk — a local, on-disk cache layered in front of an object-storage disk. See Interpreters/Cache/.
• MergeTree storage policy — a named ladder of volumes/disks driving where new parts land and where TTL moves them. See MergeTreeSettings.cpp.

Engines

• MergeTree family — MergeTree, ReplicatedMergeTree, SummingMergeTree, AggregatingMergeTree, ReplacingMergeTree, CollapsingMergeTree, VersionedCollapsingMergeTree, GraphiteMergeTree. The columnar workhorse.
• ReplicatedMergeTree — MergeTree with replication coordinated through Keeper.
• Buffer / Memory / Set / Join / Null / View — small in-memory or pseudo engines used as building blocks.
• Distributed / Merge / Dictionary — virtual engines that proxy to other tables or sources.
• External engines — MySQL, PostgreSQL, MongoDB, Redis, SQLite, S3, Azure, HDFS, URL, Iceberg, DeltaLake, Hudi, Hive.
• Streaming engines — Kafka, NATS, RabbitMQ, FileLog. Pull-based ingestion.
• MaterializedView — a table that is automatically refreshed from another table. Two variants: incremental (the classic) and refreshable (cron-style).
• WindowView — streaming windowed aggregation.

Operations

• Background pool — thread pool for merges, mutations, fetches, moves. Limits in merge_tree_settings.
• Move TTL — TTL action that relocates data between disks/volumes.
• Compaction / Merge — the process that combines parts into bigger ones. Driven by MergeTreeDataMergerMutator.cpp.
• Fetch — replication operation that copies a part from a peer over HTTP. See DataPartsExchange.cpp.
• Quorum — minimum number of replicas that must acknowledge an insert.
• Backup / Restore — declarative BACKUP/RESTORE statements that snapshot tables, databases, or the whole instance to local/S3/Azure. See src/Backups/.

Quirks worth knowing

• Nested(...) — a column type that maps to a tuple of arrays of the same length.
• LowCardinality(T) — a dictionary-encoded wrapper for low-cardinality columns. Decoded only at the edges of the pipeline.
• Variant(...) / Dynamic — typed-union and dynamic columns supporting heterogeneous values.
• JSON — native JSON column type with lazily-discovered subcolumns and skip indexes.
• Projection vs Materialized View — projections are stored inside parts; materialized views are separate tables.
• SYSTEM queries — a large family of admin commands (SYSTEM SYNC REPLICA, SYSTEM FLUSH LOGS, SYSTEM RESTART DISK, …) handled by InterpreterSystemQuery.cpp.

For settings, see Reference → configuration. For the data-type catalog, see Reference → data models.