ClickHouse HOLs
GitHub

SharedMergeTree internals, measured

On ClickHouse Cloud, ENGINE = MergeTree becomes SharedMergeTree: parts live in object storage, part metadata lives in Keeper, and replicas share both instead of copying parts to each other. This lab measures what that means on a real service, from the system tables: what one INSERT writes and where, what the other replica does when a part appears, who runs a merge, how soon another replica sees a new row, what many small INSERTs cost with and without async_insert, and which OSS DDL forms Cloud accepts.

Verified on ClickHouse Cloud 26.8.1.608 (AWS ap-northeast-2, 2 replicas of 2 vCPU / 8 GiB), 2026-11-07, run.sh 99 then KEEP=1 run.sh (steps 01 → 06); 99 ran on its own the same day. Every number below comes from that run, whose masked output is in runs/2026-11-07/; a re-run will differ in the details.

Author: Ken Lee · MIT

What each step shows

Step Writes Shows
01-setup.sql smt_lab, smt_lab.big The Shared database engine; MergeTree stored as SharedMergeTree('/clickhouse/tables/{uuid}/{shard}', '{replica}'); the one-shard default cluster; system.replicas per replica; part-shaping MergeTree settings; insert consistency settings
02-write-path.sql 2M rows into big NewPart on the writer vs DownloadPart on the other replica, with object storage bytes; empty replication queue; Keeper requests of the INSERT, by Keeper node
03-visibility.sh smt_lab.vis 30 + 30 trials: INSERT one row, then ask both replicas at once; lag from part_log; cost of select_sequential_consistency = 1; SYSTEM SYNC REPLICA … LIGHTWEIGHT
04-merges.sh smt_lab.m 20 INSERTs, then every merge: on which replica it ran, and who only loaded the result
05-small-inserts.sh smt_lab.small_sync, small_async 200 one-row INSERTs from 20 clients, synchronous vs async_insert = 1: parts, object storage bytes, Keeper requests, latency
06-ddl-port.sh smt_lab.p* OSS DDL forms that fail (negative checks: the step fails if they succeed) and the forms that work; Distributed over default
99-cleanup.sql drops smt_lab —

Run

Needs the clickhouse binary (clickhouse client, and clickhouse local to redraw masked tables) and a Cloud service with at least two replicas. The data is small (about 165 MiB); the run takes a few minutes of compute and keeps the service awake while it runs.

cp .env.example .env && chmod 600 .env   # CH_HOST, CH_USER, CH_PASSWORD
./run.sh 99 && KEEP=1 ./run.sh           # clean start; every step but 99, objects kept for screenshots
./run.sh 99                              # drop the lab database when done
./run.sh 03                              # one step again (01 must have run)

Each shell step (03–05) reads only log rows written after it started, so it can be re-run on its own. 02 reads rows since 01, so re-run both together. Captures are masked unless MASK=0: pod names keep only their random suffix (2rdd723-0), and the endpoint, namespace, bucket and table UUIDs are replaced. system.zookeeper is not readable by the service's default user (ACCESS_DENIED), so Keeper is observed through system.aggregated_zookeeper_log and the ZooKeeper* profile events instead.

What the 2026-11-07 run returned

A plain CREATE TABLE. The database engine is Shared; ENGINE = MergeTree is stored as SharedMergeTree('/clickhouse/tables/{uuid}/{shard}', '{replica}'). The default cluster is one shard with two replicas. min_bytes_for_wide_part is 1 GiB on this service, so every part in this lab is Compact, even a 90 MiB one.

One INSERT (step 02). 2M rows became two parts (1,111,953 and 888,047 rows; 90 and 72 MiB). The writer wrote 161.84 MiB to object storage; the query took 3.3 s and made 18 Keeper requests (16 of them inside multi-requests). For each part the sink checks its replica node and that the deduplication hash does not exist, then creates the hash, a block number, a virtual_parts entry and an insert memo id, and sets the table and virtual_parts nodes. The other replica logged a DownloadPart for each part (36 and 45 ms long). It read 1.00 MiB in one GET for the 90 MiB part and wrote nothing. Both replicas then reported the same 2 active parts and 161.84 MiB. system.replication_queue and system.replicated_fetches were empty on both.

Event Replica Part Size Object storage
NewPart writer all_0_0_0 89.98 MiB 89.98 MiB written, 1,375 ms
DownloadPart other all_0_0_0 89.98 MiB 1.00 MiB read (1 GET), 36 ms
NewPart writer all_1_1_0 71.86 MiB 71.86 MiB written, 1,226 ms
DownloadPart other all_1_1_0 71.86 MiB 1.00 MiB read (1 GET), 45 ms

In step 04 the parts were small (about 170 KiB each), and each DownloadPart read about as many bytes as the part held. The lab does not show what the 1 MiB read contains; it shows only that the part data was not copied.

Visibility across replicas (step 03). Each trial INSERTs one row and asks both replicas through clusterAllReplicas on the same connection; the check started 29–35 ms after the INSERT finished (p50 31.5 ms).

Check Other replica saw the row at once
select_sequential_consistency = 0 (default) 29 of 30
select_sequential_consistency = 1 30 of 30

Server-side lag from NewPart on the writer to DownloadPart on the other replica, over 60 inserted parts: min 18.8 ms, p50 29.6 ms, p90 37.1 ms, max 77.4 ms. The lag and the check gap are about the same size, which is why the default check missed a row now and then. (On two earlier runs that day the default check saw 21 and 25 of 30, with the lag max at 385 ms on one run.) On a plain SELECT count(), select_sequential_consistency = 1 cost 2 Keeper requests and took 12.2 ms on average against 1 ms without it (10 runs each). SYSTEM SYNC REPLICA smt_lab.vis LIGHTWEIGHT took 7–19 ms with 4 Keeper requests.

Merges (step 04). 20 INSERTs of 50,000 rows became 4 active parts after 3 merges. Each merge ran on one replica, and the other logged one DownloadPart for its result:

Merged part Rows From parts Merged on Loaded on the other replica
all_0_5_1 300,000 6 2rdd723-0 1
all_0_10_2 550,000 6 2rdd723-0 1
all_0_16_3 850,000 7 2rdd723-0 1

The merges wrote 5.70 MiB; the other replica wrote nothing for them. system.replicas named 6row3gp-0 as merge_coordinator_replica while the merges ran on 2rdd723-0, so the coordinator is not necessarily the replica that merges. queue_size and merges_in_queue were 0 on both.

Many small INSERTs (step 05). 200 one-row INSERTs from 20 concurrent clients:

Parts created Object storage written Keeper requests Client latency p50 / max
synchronous 200 209.38 KiB 1,210 85 / 118 ms
async_insert = 1, wait_for_async_insert = 1 29 31.21 KiB 194 (in the 29 flushes) 834 / 1,089 ms

With async_insert the server buffered 6.3–7.5 INSERTs per flush, and each flush is a query of its own in query_log. The client waited for the flush (async_insert_busy_timeout_max_ms is 1000 on this service), so each INSERT took longer, while the service created a seventh of the parts and made a sixth of the Keeper requests. The part-count limits (parts_to_delay_insert 1000, parts_to_throw_insert 3000, max_parts_in_total 10000) were not reached in this lab.

Porting OSS DDL (step 06).

DDL Result
ON CLUSTER '{cluster}' fails, code 139: no cluster macro
ReplicatedMergeTree('/clickhouse/tables/{shard}/t', '{replica}') fails, code 36: explicit Keeper path and replica name are not allowed in a Replicated database (unless database_replicated_allow_replicated_engine_arguments is set)
the same with ON CLUSTER default fails, code 36
ReplicatedMergeTree without arguments, with or without ON CLUSTER default works → SharedMergeTree
ReplicatedReplacingMergeTree(v), AggregatingMergeTree work → SharedReplacingMergeTree, SharedAggregatingMergeTree
Distributed(default, db, t, rand()) works; one shard, so it returns each row once (1000 = 1000)

Not covered


ClickHouse Cloud에서 ENGINE = MergeTree는 SharedMergeTree가 됩니다. 파트는 오브젝트 스토리지에, 파트 메타데이터는 Keeper에 있고, 레플리카는 파트를 서로 복사하지 않고 둘을 함께 씁니다. 이 실습은 실제 서비스의 system 테이블로 다음을 측정합니다. INSERT 하나가 무엇을 어디에 쓰는지, 파트가 생겼을 때 다른 레플리카가 무엇을 하는지, 병합은 누가 하는지, 다른 레플리카가 새 행을 얼마나 빨리 보는지, 작은 INSERT가 async_insert 유무에 따라 얼마나 드는지, OSS DDL 중 어떤 형태가 Cloud에서 통하는지.

ClickHouse Cloud 26.8.1.608에서 검증 (AWS ap-northeast-2, 2 vCPU / 8 GiB 레플리카 2개), 2026-11-07, run.sh 99 후 KEEP=1 run.sh(단계 01 → 06). 99는 같은 날 따로 실행했습니다. 아래 수치는 모두 이 실행에서 나온 값이며(마스킹한 출력은 runs/2026-11-07/), 다시 실행하면 세부 값은 달라집니다.

작성: Ken Lee · MIT

단계별 내용

단계 쓰는 것 보여 주는 것
01-setup.sql smt_lab, smt_lab.big Shared 데이터베이스 엔진, SharedMergeTree('/clickhouse/tables/{uuid}/{shard}', '{replica}')로 저장되는 MergeTree, 샤드 1개인 default 클러스터, 레플리카별 system.replicas, 파트 모양을 정하는 MergeTree 설정, INSERT 일관성 설정
02-write-path.sql big에 2M 행 쓴 레플리카의 NewPart와 다른 레플리카의 DownloadPart, 오브젝트 스토리지 바이트, 비어 있는 복제 큐, Keeper 노드별 INSERT 요청
03-visibility.sh smt_lab.vis 30 + 30회: 한 행 INSERT 직후 두 레플리카에 동시에 묻기, part_log 기준 지연, select_sequential_consistency = 1의 비용, SYSTEM SYNC REPLICA … LIGHTWEIGHT
04-merges.sh smt_lab.m INSERT 20회 후 모든 병합: 어느 레플리카가 했고 누가 결과만 읽었는지
05-small-inserts.sh smt_lab.small_sync, small_async 클라이언트 20개가 한 행 INSERT 200회, 동기 vs async_insert = 1: 파트 수, 오브젝트 스토리지 바이트, Keeper 요청, 지연
06-ddl-port.sh smt_lab.p* 실패하는 OSS DDL(음성 검사: 성공하면 단계가 실패)과 통하는 형태, default 위의 Distributed
99-cleanup.sql smt_lab 삭제 —

실행

clickhouse 바이너리(clickhouse client, 마스킹한 표를 다시 그리는 clickhouse local)와 레플리카가 2개 이상인 Cloud 서비스가 필요합니다. 데이터는 약 165 MiB로 작고, 몇 분의 컴퓨트를 쓰며, 실행 중에는 서비스가 아이들 상태로 들어가지 않습니다.

cp .env.example .env && chmod 600 .env   # CH_HOST, CH_USER, CH_PASSWORD
./run.sh 99 && KEEP=1 ./run.sh           # 깨끗하게 시작, 99를 뺀 모든 단계, 캡처용으로 객체 유지
./run.sh 99                              # 끝나면 실습 데이터베이스 삭제
./run.sh 03                              # 한 단계만 다시(01이 먼저 실행돼 있어야 함)

셸 단계(03–05)는 자기가 시작한 뒤의 로그 행만 읽으므로 따로 다시 실행해도 됩니다. 02는 01 이후 행을 읽으니 둘을 함께 다시 실행합니다. 캡처는 MASK=0이 아니면 마스킹됩니다. 파드 이름은 끝의 무작위 부분(2rdd723-0)만 남기고, 엔드포인트·네임스페이스·버킷·테이블 UUID는 바꿉니다. 서비스의 default 사용자는 system.zookeeper를 읽을 수 없어서(ACCESS_DENIED), Keeper는 system.aggregated_zookeeper_log와 ZooKeeper* 프로파일 이벤트로 봅니다.

2026-11-07 실행 결과

평범한 CREATE TABLE. 데이터베이스 엔진은 Shared이고, ENGINE = MergeTree는 SharedMergeTree('/clickhouse/tables/{uuid}/{shard}', '{replica}')로 저장됩니다. default 클러스터는 샤드 1개, 레플리카 2개입니다. 이 서비스의 min_bytes_for_wide_part는 1 GiB여서, 90 MiB 파트까지 이 실습의 파트는 모두 Compact입니다.

INSERT 하나(02단계). 2M 행이 파트 2개(1,111,953행·888,047행, 90 MiB·72 MiB)가 되었습니다. 쓴 레플리카가 오브젝트 스토리지에 161.84 MiB를 썼고, 쿼리는 3.3초 걸렸으며 Keeper 요청은 18개(그중 16개는 multi 요청 안)였습니다. 파트마다 싱크는 자기 레플리카 노드와 중복 제거 해시가 없음을 확인하고, 해시· 블록 번호·virtual_parts 항목·insert memo id를 만들고, 테이블 노드와 virtual_parts 노드를 갱신합니다. 다른 레플리카는 파트마다 DownloadPart(36 ms, 45 ms)를 남겼습니다. 90 MiB 파트에 대해 GET 한 번으로 1.00 MiB를 읽었고 쓴 것은 없습니다. 이후 두 레플리카 모두 활성 파트 2개, 161.84 MiB로 같게 보고했습니다. system.replication_queue와 system.replicated_fetches는 둘 다 비어 있었습니다.

이벤트 레플리카 파트 크기 오브젝트 스토리지
NewPart 쓴 쪽 all_0_0_0 89.98 MiB 89.98 MiB 쓰기, 1,375 ms
DownloadPart 다른 쪽 all_0_0_0 89.98 MiB 1.00 MiB 읽기(GET 1회), 36 ms
NewPart 쓴 쪽 all_1_1_0 71.86 MiB 71.86 MiB 쓰기, 1,226 ms
DownloadPart 다른 쪽 all_1_1_0 71.86 MiB 1.00 MiB 읽기(GET 1회), 45 ms

04단계의 파트는 작아서(각 약 170 KiB) DownloadPart가 파트 크기만큼을 읽었습니다. 이 실습은 1 MiB 읽기에 무엇이 들었는지는 보여 주지 않습니다. 파트 데이터가 복사되지 않았다는 것만 보여 줍니다.

레플리카 간 가시성(03단계). 매 시도는 한 행을 INSERT하고 같은 연결에서 clusterAllReplicas로 두 레플리카에 묻습니다. 확인 쿼리는 INSERT가 끝나고 29–35 ms 뒤에 시작했습니다(p50 31.5 ms).

확인 다른 레플리카가 바로 본 횟수
select_sequential_consistency = 0(기본) 30회 중 29회
select_sequential_consistency = 1 30회 중 30회

쓴 레플리카의 NewPart부터 다른 레플리카의 DownloadPart까지 서버 측 지연(INSERT 파트 60개): 최소 18.8 ms, p50 29.6 ms, p90 37.1 ms, 최대 77.4 ms. 지연과 확인 간격이 비슷한 크기라서 기본 설정의 확인이 가끔 행을 놓쳤습니다. (같은 날 앞선 두 번의 실행에서는 기본 확인이 30회 중 21회와 25회를 보았고, 한 번은 지연 최대가 385 ms였습니다.) 평범한 SELECT count()에서 select_sequential_consistency = 1은 Keeper 요청 2개가 더 들고 평균 12.2 ms 걸렸습니다(끄면 1 ms, 각 10회). SYSTEM SYNC REPLICA smt_lab.vis LIGHTWEIGHT는 Keeper 요청 4개로 7–19 ms 걸렸습니다.

병합(04단계). 50,000행 INSERT 20회가 병합 3번 뒤 활성 파트 4개가 되었습니다. 병합은 모두 한 레플리카에서만 돌았고, 다른 레플리카는 결과마다 DownloadPart를 하나씩 남겼습니다.

병합된 파트 행 원본 파트 수 병합한 레플리카 다른 레플리카의 읽기
all_0_5_1 300,000 6 2rdd723-0 1
all_0_10_2 550,000 6 2rdd723-0 1
all_0_16_3 850,000 7 2rdd723-0 1

병합은 5.70 MiB를 썼고, 다른 레플리카는 이 병합으로 아무것도 쓰지 않았습니다. system.replicas의 merge_coordinator_replica는 6row3gp-0였지만 병합은 2rdd723-0에서 돌았습니다. 코디네이터가 곧 병합하는 레플리카는 아닙니다. 두 레플리카 모두 queue_size와 merges_in_queue는 0이었습니다.

작은 INSERT 여러 개(05단계). 동시 클라이언트 20개가 한 행 INSERT 200회:

생긴 파트 오브젝트 스토리지 쓰기 Keeper 요청 클라이언트 지연 p50 / 최대
동기 200 209.38 KiB 1,210 85 / 118 ms
async_insert = 1, wait_for_async_insert = 1 29 31.21 KiB 194(플러시 29회 안) 834 / 1,089 ms

async_insert에서는 서버가 플러시 한 번에 INSERT 6.3–7.5개를 모았고, 플러시는 query_log에 별도 쿼리로 남습니다. 클라이언트는 플러시를 기다렸으므로(이 서비스의 async_insert_busy_timeout_max_ms는 1000) INSERT 하나하나는 느려졌지만, 서비스가 만든 파트는 약 7분의 1, Keeper 요청은 약 6분의 1이었습니다. 파트 수 한도 (parts_to_delay_insert 1000, parts_to_throw_insert 3000, max_parts_in_total 10000)에는 이 실습에서 닿지 않았습니다.

OSS DDL 옮기기(06단계).

DDL 결과
ON CLUSTER '{cluster}' 실패, 코드 139: cluster 매크로가 없음
ReplicatedMergeTree('/clickhouse/tables/{shard}/t', '{replica}') 실패, 코드 36: Replicated 데이터베이스에서는 Keeper 경로와 레플리카 이름을 명시할 수 없음(database_replicated_allow_replicated_engine_arguments를 켜지 않는 한)
같은 문장에 ON CLUSTER default 실패, 코드 36
인자 없는 ReplicatedMergeTree, ON CLUSTER default 유무와 무관 통함 → SharedMergeTree
ReplicatedReplacingMergeTree(v), AggregatingMergeTree 통함 → SharedReplacingMergeTree, SharedAggregatingMergeTree
Distributed(default, db, t, rand()) 통함. 샤드가 1개라 각 행을 한 번만 돌려줌(1000 = 1000)

다루지 않은 것

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