ClickHouse HOLs
GitHub

SELECT … FINAL across ClickHouse versions


The same SELECT … FINAL SQL run on six builds (the LTS lines 24.8, 25.3, 25.8, 26.3, 26.8 and the latest stable 26.10). For each probe the runner records the answer (and whether it is the correct one), the time, the rows read and, where it matters, the bytes read. Every cell in RESULTS.md comes from a run; the raw per-probe data (including query_log rows) is in results/<version>.json.

What is probed: FINAL on ReplacingMergeTree (with and without is_deleted), CollapsingMergeTree, SummingMergeTree and AggregatingMergeTree; the setting final; FINAL on a view; keys that cross partitions; PREWHERE under FINAL; skip indexes under FINAL; FINAL in a JOIN; and the read cost of FINAL, argMax … GROUP BY and LIMIT 1 BY at 20M rows.

Run it

cd workload/final-across-versions
./run_matrix.py                      # all six versions, about 10 minutes; pulls nothing, images must exist
./run_matrix.py --versions 26.10     # one version (prefix of a line in versions.txt)
./run_matrix.py --only 03            # one file or probe-id prefix (a file's results replace that file in the JSON)
./run_matrix.py --report-only        # rebuild RESULTS.md from results/*.json
tools/hol run workload/final-across-versions   # from the repository root: the SQL on 26.10 only, must not raise

versions.txt pins the exact tags, oldest first. run_matrix.py is the same file as in workload/join-across-versions and workload/upsert-across-versions; it removes each container with docker rm -f -v, so the image's anonymous /var/lib/clickhouse volume goes with it (without -v every version left about 5 GB behind; #117). Containers are named fav-<tag>. A statement preceded by -- probe: <id> [repeat=N] [show] [value] is a probe, the others are setup; value puts the first result row in the table cell, show prints the newest version's rows. -- settings: a, b lists settings to look up in system.settings. Each statement runs in its own clickhouse-client call, so there is no bare SET. Each probe's comment states the correct answer computed from the data.

Probes

File What it does
01-replacing.sql ReplacingMergeTree(ver) and (ver, is_deleted), 1M keys, 1% re-written with a higher ver, 1,000 marked deleted: count() without and with FINAL, SETTINGS final = 1 (also through a subquery), a view with FINAL inside and FINAL on a view without it, FINAL vs argMax … GROUP BY vs LIMIT 1 BY, enable_vertical_final = 0, and the FINAL-related rows of system.settings_changes
02-engines.sql CollapsingMergeTree (state, then cancel + new state), SummingMergeTree((a, b)) with 100 keys whose sums are all zero and 100 where only a is zero, AggregatingMergeTree with SimpleAggregateFunction and AggregateFunction, before and after OPTIMIZE … FINAL
03-partitions.sql a partition key inside the sorting key vs a key that crosses partitions (January row, newer February row): FINAL, do_not_merge_across_partitions_select_final = 1, WHERE on the partition column, defer_partition_pruning_after_final = 0
04-prewhere.sql WHERE vs explicit PREWHERE on a non-key column under FINAL, apply_prewhere_after_final = 1; then 10M rows with a 100-character column and a sorting-key condition the primary key cannot use (toUInt32(ts) % 86400 < 3600): time and bytes read with optimize_move_to_prewhere_if_final default, 1 and 0, against a MergeTree control; whether the plan has a PREWHERE
05-skip-index.sql 20M rows, a bloom_filter index on a non-key column whose value changed for 1% of keys: looking up an old value under FINAL with use_skip_indexes_if_final 0 / 1 and exact mode 0 / 1 (correct answer 0), and a value that did not change
06-join.sql a fact table joined to a ReplacingMergeTree dimension without FINAL, with FINAL on the dimension, with SETTINGS final = 1; d1 FINAL JOIN d2 (FINAL on the left table only) and analyzer_compatibility_apply_final_to_all_joined_tables = 1
07-scale.sql 20M rows, every column CODEC(LZ4): MergeTree control, a one-part ReplacingMergeTree, 1% and 10% re-written keys, a 16-partition table: FINAL, enable_vertical_final = 0, max_final_threads = 1, argMax … GROUP BY, LIMIT 1 BY, a 100,000-row range, do_not_merge_across_partitions_select_final = 1, enable_automatic_decision_for_merging_across_partitions_for_final = 0 (5 repeats each)
errors/01-expected-failures.sql statements that fail on every build: FINAL on a plain MergeTree and on a Memory table (Code 181), FINAL SAMPLE without SAMPLE BY (Code 141), JOIN t FINAL AS d (Code 62; JOIN t AS d FINAL is the form that parses). tools/hol does not run this directory; the runner does

Every probe in the top-level files succeeds on 26.10 (tools/hol run stops at the first exception). Failures on older versions are the result, shown as ✗ Code N; all of them are Code 115 (UNKNOWN_SETTING), a setting that build does not have yet.

What changed between versions

Written only from RESULTS.md (run on 2026-11-05, 12 CPUs, 15.6 GiB Docker VM, no other container running). The correct answer is in brackets.

Read cost at 20M rows (07-scale.sql)

Every column is CODEC(LZ4): from 26.9 a part of 100 MB or more defaults to ZSTD(3) (the 07-codec probe shows ['LZ4','ZSTD(3)'] as part defaults on 26.10.3.7 and CODEC(LZ4) as the column codec), so without the pin the times would compare codecs as well as builds. Median (fastest) of 5 repeats in ms (durations_ms in results/*.json); no other container was running.

Query 24.8 25.3 25.8 26.3 26.8 26.10
MergeTree, no FINAL 21 (20) 38 (29) 29 (26) 22 (19) 38 (24) 18 (18)
one part, FINAL 19 (18) 24 (23) 27 (25) 20 (18) 21 (18) 19 (18)
1% re-written, no FINAL (wrong answer) 22 (20) 27 (24) 26 (24) 24 (21) 24 (23) 23 (18)
1% re-written, FINAL 82 (73) 134 (108) 98 (90) 101 (90) 107 (94) 124 (95)
1%, FINAL, enable_vertical_final = 0 113 (98) 126 (113) 114 (104) 92 (85) 94 (88) 115 (106)
1%, FINAL, max_final_threads = 1 319 (293) 358 (305) 305 (298) 283 (281) 283 (279) 391 (350)
1%, argMax … GROUP BY 750 (627) 861 (376) 347 (182) 383 (311) 203 (163) 187 (159)
1%, LIMIT 1 BY 4,827 (4,023) 4,623 (4,279) 4,321 (4,109) 514 (454) 284 (280) 213 (199)
10% re-written, FINAL 125 (101) 238 (128) 114 (97) 86 (79) 107 (88) 88 (85)
10%, argMax … GROUP BY 1,041 (727) 796 (685) 349 (309) 300 (232) 203 (159) 167 (159)
1%, 100,000-row range, FINAL 6 (4) 10 (6) 5 (4) 4 (4) 4 (4) 4 (4)
16 partitions, FINAL 64 (60) 84 (68) 65 (53) 41 (38) 40 (38) 44 (36)
same, automatic decision off ✗ 115 ✗ 115 ✗ 115 189 (180) 192 (179) 198 (185)

Peak memory: argMax at 20M keys 3,970 MiB on 24.8, 2,529 MiB on 25.8, 785 MiB on 26.8, 745 MiB on 26.10; LIMIT 1 BY 2,339 MiB on 24.8 to 25.8 and about 210 MiB from 26.3; FINAL 71 to 79 MiB everywhere.

Reading the table: on this data (keys in insert order, two parts) FINAL costs about 4x to 5x a plain scan of the same table on every build and did not get faster between 24.8 and 26.10; it is the cheapest of the three ways to get the newest row per key on every build. argMax … GROUP BY became about 4x faster and 5x leaner, LIMIT 1 BY about 22x faster (the drop is between 25.8 and 26.3). With the partition key a function of the sorting key, FINAL handles partitions separately by default (from 23.12 automatically, from 26.2 through enable_automatic_decision_for_merging_across_partitions_for_final); switching that off made it about 4.5x slower. A 100,000-row range read on the sorting key takes 10 ms or less with or without FINAL on every build. max_final_threads = 1 is about 2.6x to 3.9x slower than the default (12 threads).

Screens

Captured 2026-11-05 from ClickHouse's /play UI on local throwaway containers loaded with this lab's files, for the notes article core-architecture/clickhouse-final:

Not verified here

Verified on 24.8.14.39, 25.3.14.14, 25.8.33.6, 26.3.62.3, 26.8.36.3 and 26.10.3.7, 2026-11-05 (./run_matrix.py, all six; tools/hol run on 26.10.3.7).


같은 SELECT … FINAL SQL을 여섯 빌드(LTS 24.8, 25.3, 25.8, 26.3, 26.8과 최신 stable 26.10)에서 실행합니다. probe마다 결과(정답인지), 시간, 읽은 행, 필요한 곳에서는 읽은 바이트를 기록합니다. RESULTS.md의 모든 셀은 실행 결과이고, 원시 데이터(query_log 행 포함)는 results/<버전>.json에 있습니다.

대상: ReplacingMergeTree(is_deleted 유무), CollapsingMergeTree, SummingMergeTree, AggregatingMergeTree의 FINAL, 설정 final, 뷰에 붙인 FINAL, 파티션을 넘는 키, FINAL 아래의 PREWHERE, FINAL 아래의 skip index, JOIN 속 FINAL, 2,000만 행에서 FINAL · argMax … GROUP BY · LIMIT 1 BY의 읽기 비용.

실행

cd workload/final-across-versions
./run_matrix.py                      # 여섯 버전 전부, 약 10분. 이미지는 미리 받아 둬야 함
./run_matrix.py --versions 26.10     # 한 버전(versions.txt 줄의 접두사)
./run_matrix.py --only 03            # 파일 또는 probe id 접두사(그 파일의 결과가 JSON에서 통째로 바뀜)
./run_matrix.py --report-only        # results/*.json으로 RESULTS.md 재생성
tools/hol run workload/final-across-versions   # 저장소 루트에서: 26.10에서만 실행, 예외가 없어야 함

versions.txt는 정확한 태그를 오래된 순으로 고정합니다. run_matrix.py는 workload/join-across-versions · workload/upsert-across-versions와 같은 파일입니다. 컨테이너를 docker rm -f -v로 지워 이미지의 익명 볼륨 /var/lib/clickhouse도 함께 지웁니다(-v가 없으면 버전마다 약 5 GB가 남았습니다, #117). 컨테이너 이름은 fav-<태그>입니다. -- probe: <id> [repeat=N] [show] [value]가 앞에 붙은 문장이 probe이고 나머지는 준비 문장입니다. value는 첫 결과 행을 표 셀에, show는 최신 버전의 결과 행을 그대로 넣습니다. -- settings: a, b는 system.settings에서 찾을 설정입니다. 문장마다 clickhouse-client를 따로 호출하므로 단독 SET은 쓰지 않습니다. probe마다 주석에 데이터로 계산한 정답을 적었습니다.

Probe

파일 내용
01-replacing.sql ReplacingMergeTree(ver), (ver, is_deleted). 키 100만 개, 1%를 더 높은 ver로 다시 쓰고 1,000개를 삭제 표시: FINAL 유무의 count(), SETTINGS final = 1(서브쿼리 포함), 안에 FINAL이 있는 뷰와 없는 뷰에 붙인 FINAL, FINAL 대 argMax … GROUP BY 대 LIMIT 1 BY, enable_vertical_final = 0, system.settings_changes의 FINAL 관련 행
02-engines.sql CollapsingMergeTree(상태 행 뒤 취소 행 + 새 상태 행), 합이 모두 0인 키 100개와 a만 0인 키 100개를 둔 SummingMergeTree((a, b)), SimpleAggregateFunction · AggregateFunction의 AggregatingMergeTree. OPTIMIZE … FINAL 전후
03-partitions.sql 파티션 키가 정렬 키의 함수인 테이블과, 같은 키가 두 파티션에 있는 테이블(1월 행, 더 새로운 2월 행): FINAL, do_not_merge_across_partitions_select_final = 1, 파티션 컬럼 WHERE, defer_partition_pruning_after_final = 0
04-prewhere.sql FINAL 아래에서 키가 아닌 컬럼의 WHERE 대 명시적 PREWHERE, apply_prewhere_after_final = 1. 이어서 100자 컬럼이 있는 1,000만 행에 primary key가 쓰지 못하는 정렬 키 조건(toUInt32(ts) % 86400 < 3600): optimize_move_to_prewhere_if_final 기본 · 1 · 0의 시간과 읽은 바이트, MergeTree 대조군, 계획에 PREWHERE가 있는지
05-skip-index.sql 2,000만 행, 키의 1%에서 값이 바뀐 키 아닌 컬럼에 bloom_filter 인덱스: FINAL로 옛 값을 찾기(정답 0)를 use_skip_indexes_if_final 0 / 1, exact mode 0 / 1로, 바뀌지 않은 값도
06-join.sql fact 테이블과 ReplacingMergeTree 차원 테이블의 조인: FINAL 없이, 차원 테이블에 FINAL, SETTINGS final = 1. 왼쪽에만 FINAL을 붙인 d1 FINAL JOIN d2, analyzer_compatibility_apply_final_to_all_joined_tables = 1
07-scale.sql 2,000만 행, 모든 컬럼 CODEC(LZ4): MergeTree 대조군, 파트 하나인 ReplacingMergeTree, 키 1% · 10% 재기록, 16파티션 테이블: FINAL, enable_vertical_final = 0, max_final_threads = 1, argMax … GROUP BY, LIMIT 1 BY, 10만 행 범위, do_not_merge_across_partitions_select_final = 1, enable_automatic_decision_for_merging_across_partitions_for_final = 0(각 5회)
errors/01-expected-failures.sql 모든 빌드에서 실패하는 문장: 일반 MergeTree와 Memory의 FINAL(Code 181), SAMPLE BY 없는 FINAL SAMPLE(Code 141), JOIN t FINAL AS d(Code 62, 파싱되는 형태는 JOIN t AS d FINAL). tools/hol은 이 디렉터리를 실행하지 않고 러너는 실행합니다

최상위 파일의 probe는 26.10에서 모두 성공합니다(tools/hol run은 첫 예외에서 멈춥니다). 옛 버전의 실패도 결과이며 ✗ Code N으로 표시합니다. 모두 Code 115(UNKNOWN_SETTING), 그 빌드에 아직 없는 설정입니다.

버전 사이에 바뀐 것

RESULTS.md만 보고 썼습니다(2026-11-05 실행, 12 CPU, 15.6 GiB Docker VM, 다른 컨테이너 없음). 대괄호 안이 정답입니다.

2,000만 행 읽기 비용(07-scale.sql)

모든 컬럼이 CODEC(LZ4)입니다. 26.9부터 100 MB 이상 파트의 기본 코덱이 ZSTD(3)라(26.10.3.7에서 07-codec probe가 파트 기본값 ['LZ4','ZSTD(3)'], 컬럼 코덱 CODEC(LZ4)를 보여 줌), 고정하지 않으면 빌드와 함께 코덱도 비교하게 됩니다. 셀은 5회 중앙값(최솟값) ms(results/*.json의 durations_ms)이고, 다른 컨테이너는 없었습니다.

쿼리 24.8 25.3 25.8 26.3 26.8 26.10
MergeTree, FINAL 없음 21 (20) 38 (29) 29 (26) 22 (19) 38 (24) 18 (18)
파트 하나, FINAL 19 (18) 24 (23) 27 (25) 20 (18) 21 (18) 19 (18)
1% 재기록, FINAL 없음(틀린 답) 22 (20) 27 (24) 26 (24) 24 (21) 24 (23) 23 (18)
1% 재기록, FINAL 82 (73) 134 (108) 98 (90) 101 (90) 107 (94) 124 (95)
1%, FINAL, enable_vertical_final = 0 113 (98) 126 (113) 114 (104) 92 (85) 94 (88) 115 (106)
1%, FINAL, max_final_threads = 1 319 (293) 358 (305) 305 (298) 283 (281) 283 (279) 391 (350)
1%, argMax … GROUP BY 750 (627) 861 (376) 347 (182) 383 (311) 203 (163) 187 (159)
1%, LIMIT 1 BY 4,827 (4,023) 4,623 (4,279) 4,321 (4,109) 514 (454) 284 (280) 213 (199)
10% 재기록, FINAL 125 (101) 238 (128) 114 (97) 86 (79) 107 (88) 88 (85)
10%, argMax … GROUP BY 1,041 (727) 796 (685) 349 (309) 300 (232) 203 (159) 167 (159)
1%, 10만 행 범위, FINAL 6 (4) 10 (6) 5 (4) 4 (4) 4 (4) 4 (4)
16파티션, FINAL 64 (60) 84 (68) 65 (53) 41 (38) 40 (38) 44 (36)
같은 테이블, 자동 판단 끔 ✗ 115 ✗ 115 ✗ 115 189 (180) 192 (179) 198 (185)

최대 메모리: 키 2,000만 개의 argMax가 24.8 3,970 MiB, 25.8 2,529 MiB, 26.8 785 MiB, 26.10 745 MiB. LIMIT 1 BY는 24.8–25.8 2,339 MiB, 26.3부터 약 210 MiB. FINAL은 모든 빌드에서 71–79 MiB.

읽는 법: 이 데이터(키가 입력 순서, 파트 두 개)에서 FINAL은 모든 빌드에서 같은 테이블 일반 스캔의 약 4–5배였고 24.8과 26.10 사이에 빨라지지 않았습니다. 그래도 키마다 최신 행을 얻는 세 방법 중 모든 빌드에서 가장 쌌습니다. argMax … GROUP BY는 약 4배 빨라지고 메모리가 5분의 1이 됐고, LIMIT 1 BY는 약 22배 빨라졌습니다(25.8과 26.3 사이). 파티션 키가 정렬 키의 함수이면 FINAL은 기본으로 파티션을 따로 처리하고(23.12부터 자동, 26.2부터 enable_automatic_decision_for_merging_across_partitions_for_final), 이를 끄면 약 4.5배 느렸습니다. 정렬 키 10만 행 범위 읽기는 FINAL 유무와 관계없이 모든 빌드에서 10 ms 이하입니다. max_final_threads = 1은 기본값(12 스레드)보다 약 2.6–3.9배 느립니다.

화면

2026-11-05에 이 실습의 파일을 넣은 로컬 일회용 컨테이너의 ClickHouse /play UI에서 노트 글 core-architecture/clickhouse-final용으로 찍었습니다.

여기서 확인하지 않은 것

Verified on 24.8.14.39, 25.3.14.14, 25.8.33.6, 26.3.62.3, 26.8.36.3 and 26.10.3.7, 2026-11-05 (./run_matrix.py, all six; tools/hol run on 26.10.3.7).

Open this lab on GitHub →GitHub에서 이 실습 열기 →