Skip to content

Commit e48666f

Browse files
authored
Merge pull request #3642 from ClickHouse/revert-3639-query-parallelism-runnable-queries
Revert "Made some of the queries runnable."
2 parents b11ab5d + 0622847 commit e48666f

File tree

1 file changed

+10
-12
lines changed

1 file changed

+10
-12
lines changed

Diff for: docs/guides/best-practices/query-parallelism.md

+10-12
Original file line numberDiff line numberDiff line change
@@ -83,11 +83,14 @@ SETTINGS send_logs_level='trace';
8383
```
8484

8585
We can see that
86+
87+
88+
8689
* ① ClickHouse needs to read 3,609 granules (indicated as marks in the trace logs) across 3 data ranges.
8790
* ② With 59 CPU cores, it distributes this work across 59 parallel processing streams—one per lane.
8891

8992
Alternatively, we can use the [EXPLAIN](/sql-reference/statements/explain#explain-pipeline) clause to inspect the [physical operator plan](/academic_overview#4-2-multi-core-parallelization)—also known as the "query pipeline"—for the aggregation query:
90-
```sql runnable
93+
```sql runnable=false
9194
EXPLAIN PIPELINE
9295
SELECT
9396
max(price)
@@ -96,7 +99,6 @@ FROM
9699
```
97100

98101
```txt
99-
Static result for the query above from April 2025
100102
┌─explain───────────────────────────────────────────────────────────────────────────┐
101103
1. │ (Expression) │
102104
2. │ ExpressionTransform × 59 │
@@ -128,19 +130,18 @@ Note that the `Resize` operators in the physical plan above [repartition and red
128130
## Why max_threads isn't always respected {#why-max-threads-isnt-always-respected}
129131

130132
As mentioned above, the number of `n` parallel processing lanes is controlled by the `max_threads` setting, which by default matches the number of CPU cores available to ClickHouse on the server:
131-
```sql runnable
133+
```sql runnable=false
132134
SELECT getSetting('max_threads');
133135
```
134136

135137
```txt
136-
Static result for the query above from April 2025
137138
┌─getSetting('max_threads')─┐
138139
1. │ 59 │
139140
└───────────────────────────┘
140141
```
141142

142-
However, the `max_threads` value may be ignored for some plan operators depending on the amount of data selected for processing:
143-
```sql runnable
143+
However, the `max_threads` value may be ignored depending on the amount of data selected for processing:
144+
```sql runnable=false
144145
EXPLAIN PIPELINE
145146
SELECT
146147
max(price)
@@ -150,7 +151,6 @@ WHERE town = 'LONDON';
150151
```
151152

152153
```txt
153-
Static result for the query above from April 2025
154154
...
155155
(ReadFromMergeTree)
156156
MergeTreeSelect(pool: PrefetchedReadPool, algorithm: Thread) × 30
@@ -159,7 +159,7 @@ MergeTreeSelect(pool: PrefetchedReadPool, algorithm: Thread) × 30
159159
As shown in the operator plan extract above, even though `max_threads` is set to `59`, ClickHouse uses only **30** concurrent streams to scan the data.
160160

161161
Now let’s run the query:
162-
```sql runnable
162+
```sql runnable=false
163163
SELECT
164164
max(price)
165165
FROM
@@ -168,7 +168,6 @@ WHERE town = 'LONDON';
168168
```
169169

170170
```txt
171-
Static result for the query above from April 2025
172171
┌─max(price)─┐
173172
1. │ 594300000 │ -- 594.30 million
174173
└────────────┘
@@ -179,7 +178,7 @@ Peak memory usage: 27.24 MiB.
179178

180179
As shown in the output above, the query processed 2.31 million rows and read 13.66MB of data. This is because, during the index analysis phase, ClickHouse selected **282 granules** for processing, each containing 8,192 rows, totaling approximately 2.31 million rows:
181180

182-
```sql runnable
181+
```sql runnable=false
183182
EXPLAIN indexes = 1
184183
SELECT
185184
max(price)
@@ -189,7 +188,6 @@ WHERE town = 'LONDON';
189188
```
190189

191190
```txt
192-
Static result for the query above from April 2025
193191
┌─explain───────────────────────────────────────────────┐
194192
1. │ Expression ((Project names + Projection)) │
195193
2. │ Aggregating │
@@ -206,7 +204,7 @@ Static result for the query above from April 2025
206204
└───────────────────────────────────────────────────────┘
207205
```
208206

209-
Regardless of the configured `max_threads` value, ClickHouse only allocates additional parallel processing lanes for operator plans scanning the data when there’s enough data to justify them. The "max" in `max_threads` refers to an upper limit, not a guaranteed number of threads used.
207+
Regardless of the configured `max_threads` value, ClickHouse only allocates additional parallel processing lanes when there’s enough data to justify them. The "max" in `max_threads` refers to an upper limit, not a guaranteed number of threads used.
210208

211209
What "enough data" means is primarily determined by two settings, which define the minimum number of rows (163,840 by default) and the minimum number of bytes (2,097,152 by default) that each processing lane should handle:
212210

0 commit comments

Comments
 (0)