Point Query 를 위한 Index Granularity 조정

ClickHouse는 대용량 분석 쿼리에 최적화된 컬럼 스토어 데이터베이스입니다. 하지만 적절한 설정을 통해 Point Query(단일 행 조회) 성능도 크게 향상시킬 수 있습니다. 이 글에서는 index_granularity 설정의 원리와 ClickHouse Cloud에서의 실제 성능 테스트 결과를 공유합니다.

• 1. Index Granularity란?
• 1.1 기본 개념
• 1.2 MergeTree 데이터 구조
• 1.3 Sparse Index의 특징
• 2. Granularity가 쿼리 성능에 미치는 영향
• 2.1 Point Query 동작 원리
• 2.2 Granularity별 비교
• 2.3 Trade-off 분석
• 3. ClickHouse Cloud 실제 테스트
• 3.1 테스트 환경
• 3.2 테이블 메타데이터 비교
• 3.3 Point Query 성능 테스트 결과
• 3.4 IN Query 성능 테스트
• 4. 워크로드별 권장 설정
• 4.1 의사결정 플로우
• 4.2 권장 Granularity 가이드
• 4.3 최적화 구성 예시
• 5. 결론
• 핵심 요약
• 실무 적용 가이드

1. Index Granularity란?

1.1 기본 개념

ClickHouse의 MergeTree 엔진은 데이터를 **Granule(그래뉼)**이라는 단위로 관리합니다. index_granularity는 하나의 Granule에 포함되는 행(row)의 수를 정의하며, 기본값은 8,192입니다.

💡 핵심 포인트: Granule은 ClickHouse가 데이터를 읽는 최소 단위입니다. 단 1행만 필요하더라도 해당 행이 속한 Granule 전체를 읽어야 합니다.

1.2 MergeTree 데이터 구조

각 Granule의 첫 번째 Primary Key 값만 인덱스에 저장됩니다. 이것이 **Sparse Index(희소 인덱스)**입니다.

1.3 Sparse Index의 특징

장점:

• 인덱스 크기가 매우 작음 (메모리에 전체 로드 가능)
• 대용량 데이터에서도 빠른 범위 검색
• 쓰기 성능에 미치는 영향 최소화

특성:

• 정확한 행 위치가 아닌 Granule 위치를 찾음
• 최종 필터링은 Granule 내에서 수행
• Granule 크기 = 최소 I/O 단위

2. Granularity가 쿼리 성능에 미치는 영향

2.1 Point Query 동작 원리

200만 행 테이블에서 WHERE player_id = 500000 쿼리 실행 시:

2.2 Granularity별 비교

2.3 Trade-off 분석

3. ClickHouse Cloud 실제 테스트

3.1 테스트 환경

• 플랫폼: ClickHouse Cloud (AWS ap-northeast-2)
• Engine: SharedMergeTree
• 데이터: 게임 플레이어 정보 200만 행
• 테이블: 동일 스키마, 다른 Granularity (256, 1024, 4096, 8192)

3.2 테이블 메타데이터 비교

3.3 Point Query 성능 테스트 결과

테스트 쿼리: SELECT * FROM player_g{N} WHERE player_id = 500000

✅ 결과: Granularity=256 설정에서 Point Query가 정확히 256행만 읽었습니다. 이론적 예상과 정확히 일치!

3.4 IN Query 성능 테스트

테스트 쿼리: WHERE player_id IN (100000, 300000, 700000, 1000000, 1500000)

4. 워크로드별 권장 설정

4.1 의사결정 플로우

4.2 권장 Granularity 가이드

4.3 최적화 구성 예시

CREATE TABLE optimized_player_lookup (
    player_id UInt64,
    player_name String,
    character_level UInt16,
    last_login_at DateTime64(3),
    -- ... 기타 컬럼

    -- Bloom Filter Index 추가 (선택적)
    INDEX idx_player_bloom player_id TYPE bloom_filter(0.01) GRANULARITY 1
)
ENGINE = MergeTree()
ORDER BY player_id
SETTINGS index_granularity = 256;

5. 결론

핵심 요약

실무 적용 가이드

1. 워크로드 분석: Point Query 비율 확인
2. 테스트 우선: 프로덕션 전 벤치마크 수행
3. 모니터링: system.query_log의 read_rows 확인
4. 점진적 적용: 새 테이블부터 적용 후 확대

🎯 결론: ClickHouse는 분석 DB이지만, index_granularity 튜닝으로 Point Query 성능도 충분히 확보할 수 있습니다.

활용 코드:

clickhouse-hols/workload/index-granularity-point-query at main · litkhai/clickhouse-hols

ClickHouse Hands-on Labs . Contribute to litkhai/clickhouse-hols development by creating an account on GitHub.

github.com

테스트 일자: 2025년 12월 25일

환경: ClickHouse Cloud (AWS ap-northeast-2, SharedMergeTree)