Processors Profile

What It Does

The Processors Profile page shows you exactly how ClickHouse® ran a specific query, as a visual pipeline diagram.

When you run a query, ClickHouse® does not run it as a single operation. It breaks the work into a chain of small steps called "processors." For example, a query like SELECT count() FROM table WHERE x > 10 might flow through these steps:

Read data from disk
    |
Filter rows where x > 10
    |
Count the matching rows
    |
Send the result to you

In reality, ClickHouse® runs many of these steps in parallel across several threads. This makes a tree-shaped pipeline with branches that fork and merge. The Processors Profile page renders the full pipeline as an interactive diagram, where you can see how long each step took and where the bottleneck is.

How to Use It

Step 1: Open the page

Go to Query Tools > Processors Profile in the sidebar.

Step 2: Load queries

At the top is a filter row with three controls: a time range, a Query Kind dropdown, and a Type dropdown. CHOps builds the Query Kind and Type options from what actually appears in your query log for the selected time range, so you choose from real values. By default the filter is the last hour, query kind Select, and type QueryFinish.

Click Apply to load the matching queries into the dropdown below the filter. To reach an older query, widen the time range. To look at a different kind of statement, change the query kind.

Step 3: Select a query

Pick a query from the dropdown. Each entry shows the timestamp, user, duration, query ID, and a preview of the SQL.

The pipeline diagram renders automatically. CHOps auto-selects the most recent query when you click Apply.

Step 4: Read the diagram

The diagram shows the execution pipeline, top to bottom:

• Each box is one processor (a step in the pipeline).
• Lines between boxes show data flow from one step to the next.
• Box color shows how long that step took:
  • White is fast.
  • Light orange is moderate.
  • Deep orange is slow (the bottleneck).
• The legend bar in the top-left corner shows the color scale with real time values.

Step 5: Inspect a processor

Click any box to open the detail panel on the right. It shows:

Step 6: Navigate large pipelines

For complex queries with many processors:

• Scroll wheel to zoom in and out.
• Click and drag the canvas to pan.
• MiniMap (bottom-right corner) shows an overview of the full pipeline with heatmap colors. Click anywhere on it to jump to that area.
• Controls (bottom-left corner) have zoom in, zoom out, and fit-to-view buttons.

What the Colors Tell You

The heatmap makes bottlenecks visible at a glance. Here are common patterns.

One deep orange node, everything else white. A single processor is the bottleneck. Look at its name:

• ReadFromMergeTree means slow disk reads. Consider an index or a more selective WHERE clause.
• AggregatingTransform means expensive aggregation. Consider a pre-aggregation with a materialized view.
• SortingTransform means a heavy sort. Consider an ORDER BY key that matches your query.

Several orange nodes in a chain. The pipeline has a sequential bottleneck. Data flows slowly through several stages. Check whether the upstream processor passes too many rows (look at Output rows in the detail panel).

Orange "wait" values, low "elapsed." A processor is fast but starved for input. The bottleneck is upstream. Look at the processor that feeds data into this one.

Everything is roughly the same color. The workload is spread evenly. There is no single bottleneck. To improve performance, reduce the overall data volume with better filtering, sampling, or fewer columns.

When the Diagram is Empty

If the diagram renders but all nodes are white with no heatmap:

• The query may have run with log_processors_profiles = 0, the server setting that enables profiling. Ask your DBA to enable it.
• The profile log entries may have aged out. ClickHouse® rotates system.processors_profile_log on its configured retention. Recent queries are more likely to have data.

Prerequisite: ClickHouse® Settings

For the Processors Profile to show data, the ClickHouse® server needs:

<profiles>
    <default>
        <log_processors_profiles>1</log_processors_profiles>
    </default>
</profiles>

This is on by default in ClickHouse® 22.3 and later. On an older version, ask your DBA to add it to the server configuration.

How It Differs from Query Profiler

CHOps has two profiling tools. They answer different questions.

Use the Processors Profile first. If it points to a specific processor but you need deeper detail on why that processor is slow, switch to the Query Profiler for a function-level breakdown.