CREATE DICTIONARY ... LAYOUT 개요

딕셔너리를 메모리에 저장하는 여러 가지 방법이 있으며, 각각 CPU와 RAM 사용량 간의 트레이드오프가 있어요.

출처: 문서

본문

Dictionary layout types

딕셔너리를 메모리에 저장하는 여러 가지 방법이 있으며, 각각 CPU와 RAM 사용량 간의 트레이드오프가 있어요.

Layout	Description
flat	키로 인덱싱된 플랫 배열에 데이터를 저장해요. 가장 빠른 레이아웃이지만, 키는 `UInt64`이어야 하고 `max_array_size`로 제한돼요.
hashed	해시 테이블에 데이터를 저장해요. 키 크기 제한이 없고, 원하는 만큼 요소를 지원해요.
sparse_hashed	`hashed`와 같지만, 더 낮은 메모리 사용을 위해 CPU를 희생해요.
complex_key_hashed	복합 키를 위한 `hashed`예요.
complex_key_sparse_hashed	복합 키를 위한 `sparse_hashed`예요.
hashed_array	속성을 배열에 저장하고 해시 테이블이 키를 배열 인덱스에 매핑해요. 속성이 많을 때 메모리 효율적이에요.
complex_key_hashed_array	복합 키를 위한 `hashed_array`예요.
range_hashed	정렬된 범위가 있는 해시 테이블이에요. 키 + 날짜/시간 범위로 조회를 지원해요.
complex_key_range_hashed	복합 키를 위한 `range_hashed`예요.
cache	고정 크기 인메모리 캐시예요. 자주 접근하는 키만 저장돼요.
complex_key_cache	복합 키를 위한 `cache`예요.
ssd_cache	`cache`와 같지만 인메모리 인덱스와 함께 데이터를 SSD에 저장해요.
complex_key_ssd_cache	복합 키를 위한 `ssd_cache`예요.
direct	인메모리 저장 없음 — 각 요청에 대해 소스를 직접 쿼리해요.
complex_key_direct	복합 키를 위한 `direct`예요.
ip_trie	빠른 IP 접두사 조회(CIDR 기반)를 위한 트라이(trie) 구조예요.
hierarchical	부모-자식 관계를 설명하는 숫자 키로 계층을 지원해요.
polygon	효율적인 point-in-polygon 조회(역방향 지오코딩)예요.
regexp_tree	키를 정규 표현식 트리와 매칭해요.

Recommended layouts

flat, hashed, complex_key_hashed가 최상의 쿼리 성능을 제공해요. 캐싱 레이아웃은 잠재적으로 성능이 낮고 파라미터 튜닝이 어려워 권장되지 않아요 — 자세한 내용은 cache를 참고하세요.

Specify dictionary layout

ClickHouse Cloud에서 딕셔너리를 사용한다면 DDL 쿼리 방식으로 딕셔너리를 만들고, default 사용자로 딕셔너리를 생성하세요. 또한 지원되는 딕셔너리 소스 목록은 Cloud Compatibility guide에서 확인하세요.

LAYOUT 절(DDL) 또는 구성 파일 정의의 layout 설정으로 딕셔너리 레이아웃을 구성할 수 있어요.

DDL
Configuration file

CREATE DICTIONARY (...)
...
LAYOUT(LAYOUT_TYPE(param value)) -- layout settings
...

<clickhouse>
    <dictionary>
        ...
        <layout>
            <layout_type>
                <!-- layout settings -->
            </layout_type>
        </layout>
        ...
    </dictionary>
</clickhouse>

전체 DDL 문법은 CREATE DICTIONARY도 참고하세요.

레이아웃 이름에 complex-key*가 없는 딕셔너리는 UInt64 타입의 키를 가지며, complex-key* 딕셔너리는 복합 키(임의 타입의 복잡한 키)를 가져요.

숫자 키 예시(key_column 컬럼이 UInt64 타입):

DDL
Configuration file

CREATE DICTIONARY dict_name (
    key_column UInt64,
    ...
)
PRIMARY KEY key_column

<structure>
    <id>
        <name>key_column</name>
    </id>
    ...
</structure>

복합 키 예시(키가 String 타입의 한 요소를 가짐):

DDL
Configuration file

CREATE DICTIONARY dict_name (
    country_code String,
    ...
)
PRIMARY KEY country_code

<structure>
    <key>
        <attribute>
            <name>country_code</name>
            <type>String</type>
        </attribute>
    </key>
    ...
</structure>

Improve dictionary performance

딕셔너리 성능을 개선하는 몇 가지 방법이 있어요.

GROUP BY 뒤에 딕셔너리 작업용 함수를 호출한다.
추출할 속성을 injective로 표시한다. 다른 키가 다른 속성 값에 대응하면 속성은 injective라고 불러요. 따라서 GROUP BY가 키로 속성 값을 가져오는 함수를 사용하면, 이 함수는 자동으로 GROUP BY에서 빠집니다.

ClickHouse는 딕셔너리 오류에 대해 예외를 생성해요. 오류의 예로는 다음이 있을 수 있어요.

접근한 딕셔너리를 로드할 수 없음.
cached 딕셔너리 쿼리 오류.

딕셔너리 목록과 상태는 system.dictionaries 테이블에서 볼 수 있어요.

CREATE DICTIONARY ... LAYOUT 개요