Day 72 - ClickHouse® Internals: How the Query Analyzer Works

When you execute a SQL query in ClickHouse®, it doesn't immediately start scanning data or reading storage files. Instead, the query passes through several stages that transform it from a raw SQL string into an executable pipeline.

One of the most critical stages in this system is the Query Analyzer. It bridges the gap between parsing a SQL statement and generating an execution plan by understanding what the query actually means.

In this article, we'll explore where the Query Analyzer fits into the query execution pipeline, what problems it solves, and why it's a critical component of the ClickHouse® query engine.

The Query Execution Pipeline

A simplified view of the ClickHouse® query execution pipeline flows as follows:

       SQL Query

           │

           ▼

        Parser

           │

           ▼

  Abstract Syntax Tree (AST)

           │

           ▼

     Query Analyzer

           │

           ▼

       Query Tree

           │

           ▼

     Query Planner

           │

           ▼

   Execution Pipeline

           │

           ▼

    Data Processing

Each stage has a highly specific responsibility:

• 
  The Parser: Verifies that the SQL syntax is valid.


• 
  The Query Analyzer: Resolves the semantic meaning of the query.


• 
  The Query Planner: Determines how to execute the resolved query efficiently.


• 
  The Execution Pipeline: Performs the actual work of reading, filtering, aggregating, and returning data.

Understanding this separation helps explain why parsing and analysis are treated as independent architectural layers.

Parsing: Understanding Query Structure

The parser is responsible only for recognizing SQL syntax. Consider the following query:

SELECT

    customer_id,

    SUM(amount) AS total

FROM sales

GROUP BY customer_id;

The parser checks strictly grammatical constraints:

• Are SELECT, FROM, and GROUP BY keywords used correctly?


• Are parentheses balanced in SUM(amount)?


• Do punctuation marks (like commas) appear in valid positions?

After successful parsing, ClickHouse® creates an Abstract Syntax Tree (AST). The AST represents the purely syntactic structure of the query; every clause, expression, function call, and identifier becomes a node in this tree.

⚠️ What the Parser Ignores: At this stage, ClickHouse® still hasn't answered basic semantic questions: Does the sales table exist? Is customer_id a valid column? Is SUM() a known function? Are the data types compatible? Those questions are deferred to the Analyzer.

What Is the Query Analyzer?

The Query Analyzer gives semantic meaning to the parsed query. While the parser understands how the query is written, the analyzer determines what data and operations the query actually references.

Instead of passing raw syntax further down the chain, the analyzer builds a richer internal representation called the Query Tree that encapsulates the validated logic, type systems, and database metadata.

7 Major Responsibilities of the Query Analyzer

1. Resolving Tables

The parser sees only the identifier sales. The analyzer queries the system catalog to verify that the sales table exists, identifies its underlying storage engine (e.g., MergeTree), and fetches its physical schema definition.

2. Resolving Columns

The analyzer checks if the requested columns actually exist within the resolved table. It also checks for ambiguity—if a query joins multiple tables that share identical column names without explicit qualifiers, the analyzer throws an error before resources are spent on planning.

3. Resolving Aliases

Aliases simplify complex SQL text, but they must be mapped back to concrete expressions. If you write price * quantity AS revenue, the analyzer ensures that any later references to revenue point directly to the underlying arithmetic expression (price * quantity).

4. Function Resolution

ClickHouse® features a massive library of built-in functions. The analyzer maps a string like lower(name) to its actual C++ execution kernel implementation, verifies that the function exists, checks that the argument count is correct, and ensures the argument types are valid.

5. Type Inference

If a query evaluates price * quantity, where price is a Decimal32 and quantity is a UInt32, the analyzer computes the exact output data type. This precise type signature is mandatory for the Query Planner and the vectorized execution engine.

6. Expression Validation

The analyzer catches logical SQL violations early. For instance, executing a aggregate function (SUM(amount)) alongside an unaggregated column (customer_id) without a matching GROUP BY clause is syntactically valid but semantically illegal. The analyzer halts this query immediately.

7. Building the Query Tree

The final and most crucial output of the analyzer is the Query Tree. Unlike the AST, which mimics the user's literal text, the Query Tree contains nodes bound to actual metadata objects, verified functions, and concrete data types.

Deep Dive: AST vs. Query Tree

Why Doesn't the Planner Work Directly on the AST?

The planner's sole job is optimization—determining the fastest way to read and process data.

If the planner operated directly on the AST, its code would be heavily bogged down. It would have to repeatedly look up metadata tables, perform type checks, and resolve aliases for every single optimization pass. By offloading these tasks to the Query Analyzer, the planner receives a clean, uniform, and fully validated Query Tree, allowing it to focus entirely on performance optimization strategies.

Inspecting the Analyzer

ClickHouse® exposes its internal analyzer mechanics via diagnostic commands. If you want to see exactly how ClickHouse® translates your query semantics, you can run:

EXPLAIN QUERY TREE

SELECT

    customer_id,

    SUM(amount)

FROM sales

GROUP BY customer_id;

Rather than printing a physical execution plan (which shows read steps and thread allocations), this command outputs the structured Query Tree. It is incredibly useful for debugging complex queries, checking unexpected alias behavior, or validating nested subquery behavior.

Conclusion

The Query Analyzer is the unsung hero of the ClickHouse® query engine. By cleanly separating syntactic validation from semantic resolution, ClickHouse® keeps its pipeline modular, predictable, and highly performant.

The next time you execute a query, remember that long before a single byte of data is read from disk, the Query Analyzer has already mapped out the exact DNA of your SQL statement.

References

• ClickHouse® Documentation: Understanding Query Execution with the Analyzer