Interpreters

src/Interpreters/ is the largest directory in the codebase. It owns the per-query Context, the legacy interpreter pipeline, the join and aggregation engines, and a long list of cross-cutting services. This page walks the major modules.

Per-query Context

src/Interpreters/Context.h (88 KB) and Context.cpp (310 KB) — the Context carries everything a query needs:

• The connected user, profile, settings, current database, query id, client info.
• Pointers to global subsystems: storage policies, dictionaries, named collections, access control, ZooKeeper, the merge scheduler, the various caches.
• Per-query state: progress, throttlers, memory tracker, kill signal, dependent contexts.

Context::createGlobal() runs at server startup; Context::createCopy() produces a per-query child with overridden settings.

InterpreterFactory

src/Interpreters/InterpreterFactory.cpp maps an AST top-level node to an IInterpreter subclass. Major interpreters:

Interpreter	Handles
InterpreterSelectQuery	The legacy SELECT interpreter (still used as a fallback).
InterpreterSelectQueryAnalyzer	Wrapper over the analyzer + planner pipeline.
InterpreterSelectWithUnionQuery	UNION trees.
InterpreterInsertQuery	INSERT (in many flavors: VALUES, SELECT, FORMAT).
InterpreterCreateQuery	CREATE TABLE/VIEW/DICTIONARY/....
InterpreterAlterQuery	ALTER.
InterpreterDropQuery	DROP.
InterpreterRenameQuery	RENAME.
InterpreterShowTablesQuery, InterpreterShowCreateQuery, InterpreterDescribeQuery	Introspection.
InterpreterSystemQuery	The whole SYSTEM ... family.
InterpreterExplainQuery	EXPLAIN.
InterpreterTransactionControlQuery	Experimental MV-CC transactions.
InterpreterBackupQuery / InterpreterRestoreQuery	BACKUP/RESTORE.
InterpreterCheckQuery, InterpreterOptimizeQuery, InterpreterKillQueryQuery, InterpreterWatchQuery	Operational.
InterpreterAccessQuery, InterpreterCreateUserQuery, InterpreterCreateRoleQuery, InterpreterGrantQuery, …	RBAC DDL.
InterpreterCreateDictionaryQuery	Dictionaries.

Joins

src/Interpreters/HashJoin/, MergeJoin.cpp, DirectJoin.cpp, JoinSwitcher.cpp, GraceHashJoin.cpp, FullSortingMergeJoin.h. The IJoin abstraction is instantiated by the planner; here is where the heavy code lives.

The hash join uses templated specializations per key column type and supports parallel build. The direct join targets dictionary storages. The grace-hash join spills to disk when memory is tight.

src/Interpreters/JoinedTables.cpp and src/Interpreters/JoinUtils.cpp carry shared helpers (key extraction, types alignment, anti/semi join handling).

Aggregation

src/Interpreters/Aggregator.cpp (~162 KB) and Aggregator.h are the heart of GROUP BY. Highlights:

• Many specialized hash-table layouts depending on key type (AggregationMethod*, AggregatedDataVariants.h).
• Two-level hashing for high cardinality with parallel merge.
• Spill-to-disk via TemporaryDataOnDisk.
• Special paths for low-cardinality and string keys.
• Parallel aggregation across worker threads with a final merge step.

MergingAggregatedTransform.cpp handles the second phase when partial states arrive from shards or worker threads.

ActionsDAG and ExpressionActions

Expressions are compiled to a DAG and then executed:

• Interpreters/ActionsDAG.h (~30 KB) — the DAG of computations.
• Interpreters/ActionsDAG.cpp (~150 KB) — construction, optimization, splitting, materialization.
• Interpreters/ExpressionActions.cpp (~45 KB) — the execution engine.
• Interpreters/ExpressionAnalyzer.cpp (~103 KB) — the legacy expression analyzer (still used for some legacy paths).
• Interpreters/ExpressionJIT.cpp — LLVM JIT of inner expression loops when compile_expressions=1.

The ActionsDAG is the canonical IR for filters, projections, and aggregation expressions across both analyzer and legacy paths.

DDL coordination

• Interpreters/DDLWorker.cpp (~65 KB) — runs distributed ON CLUSTER DDL by reading /clickhouse/task_queue/ddl/ from Keeper.
• Interpreters/DDLTask.cpp — task representation.
• Interpreters/DDLOnClusterQueryStatusSource.cpp — streaming the status back.

System-level services

Interpreters/ also hosts a long tail of services attached to the global Context:

Module	Purpose
Cache/	The unified file cache (FileCache.cpp, FileSegment.cpp, query result cache).
FileCache/	Same cache used by remote disks.
EmbeddedDictionaries.cpp, ExternalDictionariesLoader.cpp, ExternalLoader.cpp	Dictionary loading.
Cluster.cpp, ClusterDiscovery.cpp, ClusterProxy/	Cluster topology.
BackgroundSchedulePool (in src/Common/) plus Interpreters/BackgroundProcessList.h	Thread pools.
MutationsInterpreter.cpp	Plans the part rewrite for ALTER UPDATE/DELETE.
TransactionLog.cpp, MergeTreeTransaction.cpp	Experimental transactions.
DatabaseCatalog.cpp	Tracks every database/table; resolves db.table lookups.
Crash*Log.cpp, TextLog.cpp, QueryLog.cpp, PartLog.cpp, ZooKeeperLog.cpp, MetricLog.cpp, AsynchronousMetricLog.cpp, BlobStorageLog.cpp, OpenTelemetrySpanLog.cpp, ProcessorsProfileLog.cpp, …	The system tables that capture observability data.
OpenTelemetrySpanLog.cpp, ClientInfo.cpp	Distributed tracing context.
executeQuery.cpp	The main executeQuery() entry point for any SQL string.
loadMetadata.cpp	Server startup table loader.

The legacy SELECT interpreter

InterpreterSelectQuery.cpp and InterpreterSelectWithUnionQuery.cpp predate the analyzer. They are still wired up as a fallback when enable_analyzer=0, when running certain views, and during early test setup. New optimizations should land in the analyzer/planner instead.

Entry points for modification

• New SYSTEM command → add a kind to Parsers/ASTSystemQuery.cpp, handle it in InterpreterSystemQuery.cpp.
• New top-level statement → add a parser, a IAST subclass, and an interpreter; register the interpreter in InterpreterFactory.cpp.
• New aggregation hash-table strategy → extend AggregationMethod and AggregatedDataVariants.
• New join algorithm → implement IJoin, then add a planner branch (see Planner).

Related pages

• Analyzer, Planner, Processors
• Functions, Aggregate functions
• Coordination
• Access control