ClickHouse 클러스터 구조 - Shard, Replica, Distributed 테이블

 ClickHouse를 처음 접했을 때 가장 혼란스러웠던 건 용어였다.

 

 MySQL이나 MariaDB에서는 그냥 테이블 만들고 쿼리 날리면 됐는데, ClickHouse는 처음부터 "Shard", "Replica", "Distributed 테이블", "ZooKeeper"가 튀어나온다. 심지어 테이블도 두 종류가 있다고 한다.

 

 이 글에서는 ClickHouse 클러스터가 어떤 구조로 이루어져 있는지, 각 개념이 무슨 역할을 하는지 한 눈에 이해할 수 있도록 정리해본다.

 

 

---

ClickHouse는 왜 클러스터 구조를 쓸까?

https://clickhouse.com/docs/faq/general/columnar-database

 

 ClickHouse는 대용량 분석 쿼리에 최적화된 컬럼형 DB다. 수억 건의 데이터를 빠르게 집계하는 게 주 목적이다 보니, 데이터를 여러 서버에 나눠 저장하고 병렬로 처리하는 구조가 기본이 된다.

 

 이때 등장하는 두 가지 핵심 개념이 Shard와 Replica다.

 

 

---

Shard - 데이터를 나눠 갖는다

 Shard는 데이터를 수평으로 분할하는 단위다.

https://clickhouse.com/docs/ko/assets/images/shards_04-2c51656ae086b256719302d6cf54039c.png

 

 예를 들어 1억 건의 데이터가 있을 때, Shard 1에 5천만 건, Shard 2에 5천만 건을 나눠 저장한다. 쿼리를 날리면 두 Shard가 동시에 각자의 데이터를 처리하고 결과를 합산한다. 서버가 2대면 처리 속도가 2배에 가까워진다.

전체 데이터 1억 건
├── Shard 1 (서버 A): 5천만 건
└── Shard 2 (서버 B): 5천만 건

 

 Shard는 "성능과 용량"을 위한 개념이다.

 

---

Replica - 똑같은 데이터를 복제한다

 Replica는 같은 Shard의 데이터를 다른 서버에 복제한 것이다. 서버 하나가 죽어도 데이터가 날아가지 않도록 한다.

https://clickhouse.com/docs/ko/assets/images/shards_replicas_01-5c3bbfd0e4c3e23e8df544d2ad3d83d8.png

 

Shard 1
├── 서버 A (Primary)  - 5천만 건
└── 서버 B (Replica)  - 5천만 건 (A의 복제본)

 

 Replica는 "가용성과 안정성"을 위한 개념이다.

 

 Shard가 데이터를 나누는 것이라면, Replica는 데이터를 복사하는 것이다. 둘은 독립적인 개념이지만 함께 쓰인다.

 

---

ZooKeeper는 무슨 역할을 하나?

https://clickhouse.com/docs/assets/ideal-img/both.ab6f28d.1024.png

 

Replica 간 동기화를 조율하는 코디네이터다. Primary에 데이터가 쓰이면 ZooKeeper를 통해 Replica에 복제 작업이 트리거된다.

클러스터 DDL을 실행할 때도 ZooKeeper가 각 노드에 작업을 배포한다.

 

 

 

 

---

로컬 테이블 vs Distributed 테이블

 여기서 헷갈리기 시작한다. ClickHouse에는 같은 이름처럼 보이는 테이블이 두 벌 존재할 수 있다.

https://clickhouse.com/docs/ko/assets/images/shards_03-c0314e996d7af8b2af4fa2ea1bb7baad.png

 

 

로컬 테이블 (ReplicatedMergeTree)

 각 서버(노드)에 실제로 데이터를 저장하는 테이블이다. ReplicatedMergeTree 엔진을 사용하며, ZooKeeper를 통해 같은 Shard 내 Replica끼리 자동으로 동기화된다.

-- local 스키마에 생성 (각 노드에 물리적으로 존재)
CREATE TABLE local.user_events_local (
    event_date  Date,
    user_id     UInt64,
    event_type  String,
    created_at  DateTime
) ENGINE = ReplicatedMergeTree('/clickhouse/tables/{shard}/user_events', '{replica}')
PARTITION BY toYYYYMMDD(event_date)
ORDER BY (event_date, user_id);

 

 

Distributed 테이블

 데이터를 직접 저장하지 않는다. 각 Shard의 로컬 테이블을 가리키는 라우터 역할만 한다. 애플리케이션은 이 테이블에만 쿼리를 날리면 되고, 내부적으로 알아서 각 Shard로 분산시켜 준다.

-- 스키마에 생성 (라우터 역할)
CREATE TABLE default.user_events
ENGINE = Distributed('my_cluster', 'local', 'user_events_local', rand());

rand()는 INSERT 시 데이터를 어느 Shard로 보낼지 결정하는 방식이다. rand()를 쓰면 무작위로 분산된다.

Distributed 테이블 = 빈 껍데기. 데이터는 로컬 테이블에만 있다.

 

 

---

전체 구조 한눈에 보기

애플리케이션
    │
    ▼
[default.user_events]  ← Distributed 테이블 (라우터)
    │                    │
    ▼                    ▼
[Shard 1]            [Shard 2]
서버 A (Primary)     서버 C
서버 B (Replica)          │
    │       │            │
    └───────┴────────────┘
              │
          [ZooKeeper]
        (레플리카 동기화)

개념	역할	키워드
Shard	데이터를 수평 분할	성능, 용량
Replica	동일 데이터를 복제	가용성, 안정성
로컬 테이블	실제 데이터 저장 (ReplicatedMergeTree)	물리 저장소
Distributed 테이블	쿼리 분산 라우터	빈 껍데기
ZooKeeper	레플리카 동기화 조율	코디네이터

 

 

 

---

마치며

 처음에 "테이블이 왜 두 개야?"라는 의문에서 출발했는데, 구조를 이해하고 나면 오히려 자연스럽다. Distributed 테이블이 라우터 역할을 분리해줌으로써 애플리케이션은 클러스터 구조를 몰라도 되는 설계다.

 

 다만 이 구조를 제대로 이해하지 않으면 실수하기 좋은 지점이 있다. 대표적인 것이 DROP PARTITION을 Distributed 테이블에서 실행하는 경우인데, 이건 다음 글에서 다뤄볼 예정이다.