ClickHouse HOLs
GitHub

ClickHouse Cloud system tables in depth

A ClickHouse Cloud service is several replicas behind one endpoint, and most of the system database describes only the replica that answers. This lab shows which tables are per replica and which are shared, where the log tables are stored, how log history survives a replica being replaced, and the query patterns that read all of it: clusterAllReplicas, merge(), KILL QUERY ON CLUSTER. A small workload of its own (5M rows, a materialized view, a mutation, a failing query, a long query that gets killed) gives every log table something to show.

Verified on ClickHouse Cloud 26.8.1.608 (AWS ap-northeast-2, 2 replicas of 2 vCPU / 8 GiB, fast release channel), 2026-11-04, full run 01 → 99 in 58 s. oss-diff.sh compared it with clickhouse/clickhouse-server:26.8 (26.8.36.3).

Author: Ken Lee · MIT

What each step shows

Step Writes Shows
01-inventory.sql — Kinds of system table (in-memory, log, older log generations); log tables with size and TTL; the object-storage policy and disks they live on; Cloud-only tables; logging settings
02-replicas.sql, 02-routing.sh — The replicas behind the endpoint, the default and all_groups.default clusters, query_log counted per replica, ten connections spread across replicas
03-log-history.sql — query_log_N: logs of replaced replicas mounted read-only; the system_tables_tracking_* registry; full history with clusterAllReplicas(default, merge(system, ^query_log)); three ways of counting a week of queries
04-workload.sql systables_lab Tables, an MV, five 1M-row inserts, four reads (cache on/off, key hit/miss), a mutation — all tagged with log_comment
05-expected-error.sql — A query that must fail (CANNOT_PARSE_DATE); run.sh fails if it does not
06-query-log.sql — The workload in query_log; cache vs S3 bytes from ProfileEvents; marks selected by the key; failures; query_views_log; who fills query_log on Cloud; top query shapes
07-parts-merges.sql — system.parts the same on every replica, part_log events only on the replica that did the work, part ↔ insert through query_id, the mutation, outdated parts
08-metrics-errors.sql — cgroup vs host size, current metrics, metric_log per minute, system.errors vs error_log, session_log, the SQL behind the built-in dashboards
09-kill.sh — A plain KILL QUERY that lands on the wrong replica does nothing; KILL QUERY ON CLUSTER 'default' stops it
99-cleanup.sql drops systables_lab —

oss-diff.sh starts an OSS server of the same release in Docker and lists the system tables only one side has.

Run

Needs the clickhouse binary (for clickhouse client and clickhouse local, which redraws the masked tables) and a Cloud service. The workload adds a few minutes of compute; 99 drops its database. Querying system tables keeps a service awake, so an idling service will not idle while you run this.

cp .env.example .env && chmod 600 .env   # CH_HOST, CH_USER, CH_PASSWORD
./run.sh               # every step; output also goes to out/ (gitignored)
./run.sh 06 07         # only some steps (04 must have run first)
./oss-diff.sh 26.8     # optional: Cloud-only system tables, needs Docker

Each statement opens its own connection, as most HTTP clients and pools do, so consecutive statements can land on different replicas. Steps 06–08 read only log rows written after 04 started (the systables_lab.run table), so a re-run on the same day does not mix runs. system.errors is a counter since the replica started, so it keeps counting across runs.

Captures are masked unless MASK=0: pod names keep only their random suffix (2rdd723-0), and the bucket, the service namespace, the endpoint and e-mail addresses are replaced.

What the 2026-11-04 run returned

The article that walks through these results is on the notes site (Korean).


ClickHouse Cloud 서비스는 엔드포인트 하나 뒤에 레플리카가 여러 대 있고, system 데이터베이스의 대부분은 응답한 레플리카 한 대만 보여 줍니다. 이 실습은 어떤 테이블이 레플리카별이고 어떤 테이블이 공유되는지, 로그 테이블이 어디에 저장되는지, 레플리카가 교체돼도 로그 이력이 어떻게 남는지, 그리고 그것을 모두 읽는 쿼리 패턴(clusterAllReplicas, merge(), KILL QUERY ON CLUSTER)을 보여 줍니다. 직접 만든 작은 워크로드(500만 행, Materialized View, 뮤테이션, 실패하는 쿼리, 중간에 죽이는 긴 쿼리)가 로그 테이블마다 보여 줄 거리를 만듭니다.

검증: ClickHouse Cloud 26.8.1.608 (AWS ap-northeast-2, 2 vCPU / 8 GiB 레플리카 2대, fast 릴리스 채널), 2026-11-04, 01 → 99 전체 실행 58초. oss-diff.sh로 clickhouse/clickhouse-server:26.8(26.8.36.3)과 비교했습니다.

작성: Ken Lee · MIT

단계별 내용

단계 쓰기 보여 주는 것
01-inventory.sql — system 테이블의 종류(인메모리, 로그, 이전 세대 로그), 로그 테이블의 크기와 TTL, 저장되는 오브젝트 스토리지 정책과 디스크, Cloud 전용 테이블, 로깅 설정
02-replicas.sql, 02-routing.sh — 엔드포인트 뒤의 레플리카, default·all_groups.default 클러스터, 레플리카별 query_log 건수, 새 연결 10개가 레플리카에 나뉘는 모습
03-log-history.sql — query_log_N: 교체된 레플리카의 로그를 읽기 전용으로 붙인 것, system_tables_tracking_* 레지스트리, clusterAllReplicas(default, merge(system, ^query_log))로 읽는 전체 이력, 일주일 쿼리 수를 세는 세 가지 방법
04-workload.sql systables_lab 테이블, MV, 100만 행 INSERT 다섯 번, 읽기 네 번(캐시 켬/끔, 키 적중/미적중), 뮤테이션. 모두 log_comment 태그
05-expected-error.sql — 반드시 실패해야 하는 쿼리(CANNOT_PARSE_DATE). 실패하지 않으면 run.sh가 실패
06-query-log.sql — query_log 속 워크로드, ProfileEvents로 본 캐시 대 S3 바이트, 키가 고른 마크, 실패, query_views_log, Cloud에서 query_log를 채우는 주체, 상위 쿼리 형태
07-parts-merges.sql — 모든 레플리카에서 같은 system.parts, 일한 레플리카에만 남는 part_log, query_id로 잇는 파트 ↔ INSERT, 뮤테이션, outdated 파트
08-metrics-errors.sql — cgroup 대 호스트 크기, 현재 메트릭, 분 단위 metric_log, system.errors 대 error_log, session_log, 내장 대시보드의 SQL
09-kill.sh — 다른 레플리카에 떨어진 일반 KILL QUERY는 아무것도 하지 않고, KILL QUERY ON CLUSTER 'default'가 멈춤
99-cleanup.sql systables_lab 삭제 —

oss-diff.sh는 같은 릴리스의 OSS 서버를 Docker로 띄워 한쪽에만 있는 system 테이블을 보여 줍니다.

실행

clickhouse 바이너리(clickhouse client, 그리고 마스킹한 표를 다시 그리는 clickhouse local)와 Cloud 서비스가 필요합니다. 워크로드가 몇 분 분량의 컴퓨트를 더 쓰고, 99가 데이터베이스를 지웁니다. system 테이블을 조회하면 서비스가 깨어 있으므로, 실행하는 동안 idling 서비스는 쉬지 않습니다.

cp .env.example .env && chmod 600 .env   # CH_HOST, CH_USER, CH_PASSWORD
./run.sh               # 전체 단계. 출력은 out/에도 저장(gitignore)
./run.sh 06 07         # 일부 단계만(04가 먼저 실행돼 있어야 함)
./oss-diff.sh 26.8     # 선택: Cloud 전용 system 테이블, Docker 필요

대부분의 HTTP 클라이언트·커넥션 풀처럼 문장마다 연결을 새로 열기 때문에, 연속한 문장이 서로 다른 레플리카에 떨어질 수 있습니다. 06–08단계는 04가 시작된 뒤 기록된 로그만 읽으므로(systables_lab.run 테이블), 같은 날 다시 돌려도 실행이 섞이지 않습니다. system.errors는 레플리카가 시작된 뒤의 누적 카운터라 실행을 거듭하면 계속 늘어납니다.

캡처는 MASK=0이 아니면 마스킹합니다. 파드 이름은 무작위 접미사(2rdd723-0)만 남기고, 버킷·서비스 네임스페이스·엔드포인트·이메일 주소는 바꿉니다.

2026-11-04 실행 결과

이 결과를 하나씩 풀어 쓴 글은 노트 사이트에 있습니다(한국어).

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