[ClickHouse] Distributed 테이블 - DROP PARTITION이 왜 일부 데이터만 지워질까?

 ClickHouse 클러스터를 처음 사용하다 보면 당황스럽다.

 

 분명히 특정 날짜 데이터를 삭제했는데, 조회해보면 데이터가 여전히 남아있다. 분명 DROP PARTITION을 실행했는데. 알고 보면 삭제된 건 클러스터 전체가 아니라 일부 Shard의 데이터뿐이다.

 

 이 글에서는 왜 이런 일이 생기는지, 그리고 어떻게 해야 클러스터 전체에 올바르게 적용할 수 있는지 정리한다.

 

 

 

---

배경: Distributed 테이블은 라우터다

앞선 글에서 다뤘지만 다시 짚고 넘어가자.

ClickHouse 클러스터에서 테이블은 두 벌이다.

default.user_events          ← Distributed 테이블 (라우터, 데이터 없음)
local.user_events_local      ← 로컬 테이블 (실제 데이터 저장)

 

 

https://clickhouse.com/docs/assets/ideal-img/shards_replicas_01.f8da341.2048.png

 

 애플리케이션은 보통 default.user_events (Distributed 테이블)만 바라본다. SELECT, INSERT 모두 여기로 날리면 내부적으로 각 Shard로 분산된다.

 

 문제는 DDL 동작이 SELECT/INSERT와 다르다는 점이다.

 

 

 

---

무슨 일이 일어나는가?

Distributed 테이블에서 DROP PARTITION을 실행하면 어떻게 될까?

-- Distributed 테이블에서 실행
ALTER TABLE default.user_events
DROP PARTITION '20260318';

 

 직관적으로는 클러스터 전체에서 해당 날짜 데이터가 삭제될 것 같다.

 하지만 실제로는 쿼리를 수신한 노드 하나의 로컬 데이터만 삭제된다.

 

 

클러스터 구성
├── Shard 1 (서버 A, B)
└── Shard 2 (서버 C)

ALTER TABLE default.user_events DROP PARTITION '20260318'
→ 쿼리가 서버 A로 접속된 경우: 서버 A의 로컬 데이터만 삭제
→ 서버 C의 데이터는 그대로 남음

 

조회해보면 데이터가 여전히 보인다. Distributed 테이블은 모든 Shard를 합쳐서 보여주기 때문에, Shard 2의 데이터가 남아있으면 삭제가 안 된 것처럼 보인다.

 

 

 

---

왜 이렇게 동작하나?

Distributed 테이블은 SELECT/INSERT는 각 Shard에 분산시키지만, DDL은 분산시키지 않는다.

ClickHouse 공식 문서에도 명시되어 있다.

Distributed table does not store any data itself. It only routes queries to remote servers.
DDL queries (like ALTER) are applied only to the current server.

 

 즉 Distributed 테이블에서 ALTER를 실행하면 해당 서버의 로컬 테이블에만 적용된다. 다른 Shard로 전파되지 않는다.

 

 

 

---

올바른 방법: 로컬 테이블 + ON CLUSTER

해결책은 두 가지다.

 

방법 1: ON CLUSTER 사용 (권장)

로컬 테이블을 직접 지정하되, ON CLUSTER 구문을 붙이면 ClickHouse가 ZooKeeper를 통해 클러스터 내 모든 노드에 자동으로 DDL을 배포한다.

 

-- 올바른 방법: 로컬 테이블 + ON CLUSTER
ALTER TABLE local.user_events_local ON CLUSTER my_cluster
DROP PARTITION '20260318';

 

 한 번의 쿼리로 서버 A, B, C 모두에서 해당 파티션이 삭제된다.

 

 

 

방법 2: 각 노드에 직접 접속해서 실행

ON CLUSTER 없이 각 Shard 서버에 직접 접속해서 로컬 테이블에 실행하는 방법도 있다.

-- 서버 A에 접속해서 실행
ALTER TABLE local.user_events_local DROP PARTITION '20260318';

-- 서버 C에 접속해서 실행
ALTER TABLE local.user_events_local DROP PARTITION '20260318';

 

 동일한 결과지만, 서버가 늘어날수록 번거롭고 실수할 여지가 생긴다. ON CLUSTER를 쓰는 게 훨씬 낫다.

 

 

 

---

 

정리

실행 대상	ON CLUSTER	결과
Distributed 테이블	X	쿼리 수신 노드 1개만 적용
로컬 테이블	X	해당 노드 1개만 적용
로컬 테이블	O	클러스터 전체 적용

 

Distributed 테이블은 SELECT/INSERT만 분산시킨다. DDL은 로컬 테이블 + ON CLUSTER로 실행해야 한다.

 

 

 

---

 

덧붙임: Replica 동기화는 자동이다

ON CLUSTER로 실행하면 각 Shard의 Primary 노드에 DDL이 전달된다. 그러면 Replica는 어떻게 되나?

 

 Replica 간 동기화는 ZooKeeper가 담당한다. Primary에 DDL이 적용되면 ZooKeeper를 통해 같은 Shard의 Replica에 자동으로 반영된다. 별도로 Replica 서버에 접속해서 실행할 필요가 없다.

 

ALTER TABLE local.user_events_local ON CLUSTER my_cluster DROP PARTITION '20260318'
    │
    ├── Shard 1 - 서버 A (Primary) → ZooKeeper → 서버 B (Replica) 자동 반영
    └── Shard 2 - 서버 C → (Replica 없으면 바로 완료)

 

 

 

---

 

마치며

 처음엔 "Distributed 테이블에 쿼리 날리면 다 되는 거 아니야?"라고 생각했는데, DDL만큼은 예외라는 걸 직접 겪어보고 나서야 제대로 이해했다.

 

 SELECT/INSERT와 DDL의 동작 방식이 다르다는 점, ON CLUSTER가 어떤 역할을 하는지를 이해하면 ClickHouse 클러스터 운영에서 의도치 않은 실수를 줄일 수 있다.

 

 

 

---

참고

• https://clickhouse.com/docs/sql-reference/distributed-ddl
• https://clickhouse.com/docs/sql-reference/statements/alter/partition#drop-partitionpart
• https://clickhouse.com/docs/en/engines/table-engines/mergetree-family/replication