Dictionary — 조인 대신 쓰는 인메모리 조회 테이블
ClickHouse Dictionary 및 QUALIFY 절 공식 문서 종합 (웹 리서치, 2026) — ClickHouse 공식 문서(sql-reference/dictionaries, sql-reference/statements/select/qualify) ClickHouse 공식 문서 Dictionaries
이 모듈을 다 읽으면
- Dictionary가 일반 JOIN과 근본적으로 다른 방식(인메모리 조회 vs 테이블 스캔)으로 동작한다는 것을 설명할 수 있다
- LIFETIME 설정이 Dictionary와 원본 데이터 간의 동기화를 어떻게 제어하는지 설명할 수 있다
clickhouse-learn-06에서 다룬 Distributed 테이블처럼 여러 노드에 걸친 데이터를 다루는 것과 달리, 자주 참조되지만 자주 안 바뀌는 작은 참조 데이터(국가코드→국가명, 사용자ID→속성 등)를 매 쿼리마다 JOIN으로 스캔하지 않고 미리 메모리에 올려두고 함수 호출로 즉시 조회하는 Dictionary 기능을 정리한다.
JOIN이 아니라 '함수 호출'로 조회한다
Dictionary는 키-값 매핑을 위한 참조 데이터를 담는 객체로, 일반 테이블처럼 매 쿼리마다 디스크에서 스캔하는 대신 정의된 레이아웃(FLAT/HASHED/CACHE 등)에 따라 메모리 구조로 미리 적재해둔다. 조회는 JOIN 구문이 아니라 dictGet 계열 함수(dictGet, dictGetOrDefault 등)를 SELECT의 컬럼 표현식 안에서 직접 호출하는 방식으로 이뤄진다 — 공식 문서도 참조 테이블과의 결합에는 JOIN보다 Dictionary+dictGet 조합이 더 쉽고 효율적이라고 명시한다. 이런 이유로 국가코드→국가명, 상품ID→카테고리처럼 자주 참조되지만 큰 테이블은 아닌 참조 데이터에 전형적으로 쓰인다.
핵심 포인트
- Dictionary는 참조 데이터를 메모리 구조(FLAT/HASHED/CACHE 등 레이아웃)로 미리 적재해두고, dictGet 계열 함수로 조회한다
- 매 쿼리 스캔이 필요한 JOIN보다 참조 데이터 결합에 더 쉽고 효율적이라고 공식 문서가 명시
레이아웃 선택 — FLAT/HASHED/CACHE
FLAT은 키가 작은 정수 범위에 몰려 있을 때 배열 기반으로 저장해 가장 빠르지만 메모리 낭비가 클 수 있고, HASHED는 해시 테이블 기반이라 임의의 키 분포에도 적용 가능한 범용 선택지다. CACHE는 원본 데이터 전체를 메모리에 올리지 않고 최근 조회된 항목만 제한된 크기로 캐싱하며 캐시 미스 시 원본에서 채워 넣는 방식이라, 원본 자체가 너무 커서 전체를 메모리에 올릴 수 없는 경우에 쓴다 — 다만 이 경우 캐시에 없는 키를 조회하면 그 시점에 원본을 조회하는 추가 지연이 발생할 수 있다.
핵심 포인트
- FLAT: 작은 정수 키 범위에 최적(배열 기반, 빠르지만 메모리 낭비 가능), HASHED: 임의 키 분포에 쓰는 범용 선택지
- CACHE: 원본이 너무 커서 전체 적재가 부담될 때 최근 조회 항목만 캐싱, 캐시 미스 시 원본 조회로 추가 지연 발생 가능
LIFETIME — 원본과의 동기화는 '주기적 리로드'
Dictionary는 원본 데이터가 바뀌어도 실시간으로 즉각 반영되지 않는다 — LIFETIME 설정(최소/최대 갱신 주기)에 따라 주기적으로 원본에서 전체를 다시 읽어와 갱신하는 방식이다. 즉 Dictionary는 '항상 최신'이 아니라 '최대 LIFETIME 간격만큼 지연될 수 있는 최신'이라는 트레이드오프를 감수하는 구조이며, 실시간성이 중요한 데이터에는 부적합할 수 있다는 점을 실무에서 고려해야 한다.
핵심 포인트
- LIFETIME(최소/최대 갱신 주기)에 따라 원본에서 주기적으로 전체 리로드 — 실시간 반영이 아니라는 트레이드오프
- 실시간성이 중요한 데이터는 Dictionary의 갱신 지연을 감안해 적합성을 판단해야 함