기타 서버 설정

기타 서버 설정 (Other Server Settings)

이 문서는 ClickHouse 서버 설정 중 별도 페이지가 없는 나머지 설정들을 모아 놓은 종합(catch-all) 참조예요. 로그, 암호화, LDAP, OpenSSL, 압축, 캐시, 시스템 로그 테이블 등 다양한 설정을 포함해요. ClickHouse 소스 코드에서 자동으로 생성된 참조 문서예요.

출처: 문서

본문

이 설정들은 ClickHouse 서버를 구성하며 ClickHouse 소스 코드에서 자동으로 생성돼요.

abort_on_logical_error

LOGICAL_ERROR 예외 시 서버를 크래시시켜요. 전문가 전용이에요.

allowed_disks_for_table_engines

Iceberg와 함께 사용할 수 있는 디스크 목록이에요.

auth_use_forwarded_address

프록시를 통해 연결된 클라이언트의 인증에 원래 주소(originating address)를 사용해요.

• 기본값: false

전달된 주소는 쉽게 위조될 수 있으므로 이 설정은 특히 주의해서 사용해야 해요. 그런 인증을 허용하는 서버는 직접 접근하면 안 되고 오직 신뢰할 수 있는 프록시를 통해서만 접근해야 해요.

bcrypt_workfactor

Bcrypt 알고리즘을 사용하는 bcrypt_password 인증 타입의 작업 인자(work factor)예요. 작업 인자는 해시를 계산하고 비밀번호를 검증하는 데 필요한 계산량과 시간을 정의해요.

• 기본값: 12

<bcrypt_workfactor>12</bcrypt_workfactor>

높은 작업 인자에서 bcrypt의 계산 오버헤드 때문에 고빈도 인증 애플리케이션에서는 대체 인증 방법을 고려해요.

blob_storage_log

blob_storage_log 시스템 테이블의 설정이에요.

다음 설정은 하위 태그로 구성할 수 있어요:

설정	설명	기본값	참고
database	데이터베이스 이름.
table	시스템 테이블 이름.
engine	시스템 테이블의 MergeTree 엔진 정의.		partition_by 또는 order_by가 정의되어 있으면 사용할 수 없어요. 지정하지 않으면 기본으로 MergeTree가 선택돼요
partition_by	시스템 테이블의 사용자 지정 파티셔닝 키.		시스템 테이블에 engine이 지정되어 있으면 partition_by 파라미터를 'engine' 안에 직접 지정해야 해요
ttl	테이블 TTL 지정.		시스템 테이블에 engine이 지정되어 있으면 ttl 파라미터를 'engine' 안에 직접 지정해야 해요
order_by	시스템 테이블의 사용자 지정 정렬 키. engine이 정의되어 있으면 사용할 수 없어요.		시스템 테이블에 engine이 지정되어 있으면 order_by 파라미터를 'engine' 안에 직접 지정해야 해요
storage_policy	테이블에 사용할 스토리지 정책 이름(선택).		시스템 테이블에 engine이 지정되어 있으면 storage_policy 파라미터를 'engine' 안에 직접 지정해야 해요
settings	MergeTree 동작을 제어하는 추가 파라미터(선택).		시스템 테이블에 engine이 지정되어 있으면 settings 파라미터를 'engine' 안에 직접 지정해야 해요
flush_interval_milliseconds	메모리 버퍼에서 테이블로 데이터를 플러시하는 주기.	7500
max_size_rows	로그의 최대 라인 수. 플러시되지 않은 로그가 max_size에 도달하면 로그가 디스크로 덤프돼요.	1048576
reserved_size_rows	로그를 위해 미리 할당하는 메모리 크기(라인 수).	8192
buffer_size_rows_flush_threshold	라인 수 임계값. 이 임계값에 도달하면 로그를 디스크로 플러시하는 작업이 백그라운드에서 시작돼요.	max_size_rows / 2
flush_on_crash	크래시 발생 시 로그를 디스크로 덤프할지 여부.	false

또한 모든 시스템 로그 테이블의 기본 플러시 정책을 제어하는 서버 수준 설정이 있어요:

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>

설정	설명	기본값
skip_alias_columns	true이면 ALIAS 열이 시스템 로그 테이블 스키마에서 제외돼요. S3 기반 시스템 로그에 필요해요.	false

예:

<blob_storage_log>
    <database>system</database>
    <table>blob_storage_log</table>
    <partition_by>toYYYYMM(event_date)</partition_by>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    <ttl>event_date + INTERVAL 30 DAY</ttl>
</blob_storage_log>

builtin_dictionaries_reload_interval

내장 사전(built-in dictionaries)을 다시 로드하기 전의 간격(초)이에요.

ClickHouse는 내장 사전을 매 x초마다 다시 로드해요. 서버를 재시작하지 않고 사전을 "즉시(on the fly)" 편집할 수 있게 해줘요.

예시

<builtin_dictionaries_reload_interval>3600</builtin_dictionaries_reload_interval>

cache_size_to_ram_max_ratio

캐시 크기 대비 RAM 최대 비율을 설정해요. 저용량 메모리 시스템에서 캐시 크기를 낮출 수 있게 해줘요.

cannot_allocate_thread_fault_injection_probability

테스트용이에요.

cgroups_memory_usage_observer_wait_time

서버의 최대 허용 메모리 소비가 cgroups의 해당 임계값에 의해 조정되는 간격(초)이에요.

cgroup 관찰자를 비활성화하려면 이 값을 0으로 설정해요.

compression

MergeTree 엔진 테이블의 데이터 압축 설정이에요.

ClickHouse를 사용하기 시작한 지 얼마 안 되었다면 변경하지 않는 것을 권장해요.

구성 템플릿:

<compression>
    <case>
      <min_part_size>...</min_part_size>
      <min_part_size_ratio>...</min_part_size_ratio>
      <method>...</method>
      <level>...</level>
    </case>
    ...
</compression>

<case> 필드:

• min_part_size – 데이터 파트의 최소 크기.
• min_part_size_ratio – 데이터 파트 크기 대비 테이블 크기의 비율.
• method – 압축 방법. 허용되는 값: lz4, lz4hc, zstd, deflate_qpl.
• level – 압축 수준. Codecs 참고.

여러 <case> 섹션을 구성할 수 있어요.

조건이 충족될 때의 동작:

• 데이터 파트가 조건 집합과 일치하면 ClickHouse는 지정된 압축 방법을 사용해요.
• 데이터 파트가 여러 조건 집합과 일치하면 ClickHouse는 마지막으로 일치한 조건 집합을 사용해요(<case> 섹션은 순서대로 검사되며, 일치하는 각각이 이전 선택을 재정의해요).

데이터 파트에 대해 어떤 조건도 충족되지 않으면 ClickHouse는 크기 인식 내장 기본값을 사용해요. 100 MB 미만은 LZ4, 그 이상은 ZSTD(3)이에요. 위의 min_part_size 조건처럼, 크기는 코덱을 선택해야 할 때 데이터가 기록되기 전에 알려진 크기예요. 새로 삽입된 파트는 0이고, merge나 mutation의 경우 소스 파트의 크기예요. 따라서 입력을 줄이는 재작성(예: TTL DELETE나 collapsing merge)은 입력 크기로 분류되어 임계값 아래의 파트를 만들 수 있는데 그 파트는 여전히 ZSTD(3)일 수 있어요.

예시

<compression incl="clickhouse_compression">
    <case>
        <min_part_size>10000000000</min_part_size>
        <min_part_size_ratio>0.01</min_part_size_ratio>
        <method>zstd</method>
        <level>10</level>
    </case>
</compression>

config-file

서버 구성 파일을 가리켜요.

config_reload_interval_ms

clickhouse가 구성 파일을 다시 로드하고 새 변경 사항을 확인하는 주기예요.

core_dump

코어 덤프 파일 크기의 소프트 제한을 구성해요.

하드 제한은 시스템 도구로 구성돼요.

예시

<core_dump>
     <size_limit>1073741824</size_limit>
</core_dump>

crash_log

crash_log 시스템 테이블 작업의 설정이에요.

다음 설정은 하위 태그로 구성할 수 있어요:

설정	설명	기본값	참고
buffer_size_rows_flush_threshold	라인 수 임계값. 이 임계값에 도달하면 로그를 디스크로 플러시하는 작업이 백그라운드에서 시작돼요.	max_size_rows / 2
database	데이터베이스 이름.
engine	시스템 테이블의 MergeTree 엔진 정의.		partition_by 또는 order_by가 정의되어 있으면 사용할 수 없어요. 지정하지 않으면 기본으로 MergeTree가 선택돼요
flush_interval_milliseconds	메모리 버퍼에서 테이블로 데이터를 플러시하는 주기.	7500
flush_on_crash	크래시 발생 시 로그를 디스크로 덤프할지 여부.	false
max_size_rows	로그의 최대 라인 수. 플러시되지 않은 로그가 max_size에 도달하면 로그가 디스크로 덤프돼요.	1024
order_by	시스템 테이블의 사용자 지정 정렬 키. engine이 정의되어 있으면 사용할 수 없어요.		시스템 테이블에 engine이 지정되어 있으면 order_by 파라미터를 'engine' 안에 직접 지정해야 해요
partition_by	시스템 테이블의 사용자 지정 파티셔닝 키.		시스템 테이블에 engine이 지정되어 있으면 partition_by 파라미터를 'engine' 안에 직접 지정해야 해요
reserved_size_rows	로그를 위해 미리 할당하는 메모리 크기(라인 수).	1024
settings	MergeTree 동작을 제어하는 추가 파라미터(선택).		시스템 테이블에 engine이 지정되어 있으면 settings 파라미터를 'engine' 안에 직접 지정해야 해요
storage_policy	테이블에 사용할 스토리지 정책 이름(선택).		시스템 테이블에 engine이 지정되어 있으면 storage_policy 파라미터를 'engine' 안에 직접 지정해야 해요
table	시스템 테이블 이름.
ttl	테이블 TTL 지정.		시스템 테이블에 engine이 지정되어 있으면 ttl 파라미터를 'engine' 안에 직접 지정해야 해요

기본 서버 구성 파일 config.xml에는 다음 설정 섹션이 포함돼요:

<crash_log>
    <database>system</database>
    <table>crash_log</table>
    <partition_by>toYYYYMM(event_date)</partition_by>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    <max_size_rows>1024</max_size_rows>
    <reserved_size_rows>1024</reserved_size_rows>
    <buffer_size_rows_flush_threshold>512</buffer_size_rows_flush_threshold>
    <flush_on_crash>false</flush_on_crash>
</crash_log>

create_union_system_log_tables

시스템 로그 테이블 옆에 all_... 테이블 생성을 요청해요(system.query_log에 대한 system.all_query_log, system.text_log에 대한 system.all_text_log 등). 그런 테이블은 해당 로그 테이블, 그것의 회전된 버전(query_log_0, query_log_1, …) 및/또는 클러스터의 모든 복제본에 있는 같은 테이블들의 합집합이며, clusterAllReplicas(default, merge(system, '^query_log')) 같은 구문을 기억하지 않고도 모두를 한 번에 조회할 수 있게 해요.

이 섹션은 선택 사항이에요. 있으면 다음 설정 중 적어도 하나를 지정해야 해요:

설정	설명
merge_rotated_tables	true이면 all_... 테이블이 merge 테이블 함수로 로그 테이블과 그 회전된 버전에서 선택해요.
cluster	지정하면 all_... 테이블이 clusterAllReplicas 테이블 함수로 이 클러스터의 모든 복제본에서 선택해요(SETTINGS skip_unavailable_shards = 1을 사용해 사용할 수 없는 복제본이 쿼리를 실패시키지 않게 해요).

두 설정을 모두 지정하면 테이블은 클러스터의 모든 복제본에 걸친 회전된 테이블들의 합집합이에요.

이 옵션은 모든 시스템 로그 테이블에 적용되며, 시스템 로그별로 다른 구성을 허용하지 않아요. 테이블은 각 로그의 첫 플러시 시 시스템 로그 테이블과 같은 데이터베이스에 생성되고, 로그 테이블의 구조가 변경되면(회전 시) 자동으로 재생성돼요. 상태가 없으므로 언제든 삭제해도 안전해요. 생성은 Atomic, Replicated, Shared 데이터베이스 엔진에서만 지원돼요.

cluster 설정을 사용하면 테이블 정의가 클러스터를 참조하며, 테이블이 로드되려면 클러스터가 존재해야 해요. 구성에서 클러스터를 제거하면 all_... 테이블도 삭제해요(다음 플러시 시 새 구성에 따라 재생성될 거예요).

예시

<create_union_system_log_tables>
    <merge_rotated_tables>true</merge_rotated_tables>
    <cluster>default</cluster>
</create_union_system_log_tables>

database_atomic_delay_before_drop_table_sec

삭제된 테이블을 UNDROP 문으로 복원할 수 있는 지연 시간이에요. DROP TABLE이 SYNC 수식어로 실행된 경우 이 설정은 무시돼요. 이 설정의 기본값은 480(8분)이에요.

dead_letter_queue

'dead_letter_queue' 시스템 테이블의 설정이에요.

다음 설정은 하위 태그로 구성할 수 있어요:

설정	설명	기본값	참고
database	데이터베이스 이름.
table	시스템 테이블 이름.
engine	시스템 테이블의 MergeTree 엔진 정의.		partition_by 또는 order_by가 정의되어 있으면 사용할 수 없어요. 지정하지 않으면 기본으로 MergeTree가 선택돼요
partition_by	시스템 테이블의 사용자 지정 파티셔닝 키.		시스템 테이블에 engine이 지정되어 있으면 partition_by 파라미터를 'engine' 안에 직접 지정해야 해요
ttl	테이블 TTL 지정.		시스템 테이블에 engine이 지정되어 있으면 ttl 파라미터를 'engine' 안에 직접 지정해야 해요
order_by	시스템 테이블의 사용자 지정 정렬 키. engine이 정의되어 있으면 사용할 수 없어요.		시스템 테이블에 engine이 지정되어 있으면 order_by 파라미터를 'engine' 안에 직접 지정해야 해요
storage_policy	테이블에 사용할 스토리지 정책 이름(선택).		시스템 테이블에 engine이 지정되어 있으면 storage_policy 파라미터를 'engine' 안에 직접 지정해야 해요
settings	MergeTree 동작을 제어하는 추가 파라미터(선택).		시스템 테이블에 engine이 지정되어 있으면 settings 파라미터를 'engine' 안에 직접 지정해야 해요
flush_interval_milliseconds	메모리 버퍼에서 테이블로 데이터를 플러시하는 주기.	7500
max_size_rows	로그의 최대 라인 수. 플러시되지 않은 로그가 max_size에 도달하면 로그가 디스크로 덤프돼요.	1048576
reserved_size_rows	로그를 위해 미리 할당하는 메모리 크기(라인 수).	8192
buffer_size_rows_flush_threshold	라인 수 임계값. 이 임계값에 도달하면 로그를 디스크로 플러시하는 작업이 백그라운드에서 시작돼요.	max_size_rows / 2
flush_on_crash	크래시 발생 시 로그를 디스크로 덤프할지 여부.	false

또한 모든 시스템 로그 테이블의 기본 플러시 정책을 제어하는 서버 수준 설정이 있어요:

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>

설정	설명	기본값
skip_alias_columns	true이면 ALIAS 열이 시스템 로그 테이블 스키마에서 제외돼요. S3 기반 시스템 로그에 필요해요.	false

기본 설정은 다음과 같아요:

<dead_letter_queue>
    <database>system</database>
    <table>dead_letter</table>
    <partition_by>toYYYYMM(event_date)</partition_by>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
</dead_letter_queue>

dictionary_background_reconnect_interval

background_reconnect가 활성화된 실패한 MySQL 및 Postgres 사전의 재연결 시도 간격(밀리초)이에요.

disk_transaction_wait_for_blob_removal

디스크별 wait_for_blob_removal 설정의 기본값이에요. 활성화하면 서버는 백그라운드 blob 제거가 완료될 때까지 기다린 후 작업을 확인해요.

display_secrets_in_show_and_select

테이블, 데이터베이스, 테이블 함수, 사전에 대한 SHOW와 SELECT 쿼리에서 비밀(secrets)을 표시할지 여부를 활성화하거나 비활성화해요.

비밀을 보려는 사용자는 또한 format_display_secrets_in_show_and_select 포맷 설정을 켜고 displaySecretsInShowAndSelect 권한을 가져야 해요.

가능한 값:

• 0 — 비활성화.
• 1 — 활성화.

dns_max_consecutive_failures

이 횟수만큼 연속 실패하면 호스트네임의 DNS 캐시를 갱신하려는 추가 시도를 중단해요. 정보는 여전히 DNS 캐시에 남아요. 0은 무제한을 의미해요.

참고

• SYSTEM DROP DNS CACHE

dynamic_user_defined_executable_functions_path

드라이버가 동적으로 만든 실행 가능 UDF(CREATE FUNCTION ... ENGINE = DriverName(...) 참고)의 구성 파일을 보관하는 디렉터리예요. 서버 재시작 시 디렉터리를 스캔해 구성 파일을 찾고, 드라이버를 다시 호출하지 않고 해당 UDF를 로드해요.

예시

<dynamic_user_defined_executable_functions_path>/var/lib/clickhouse/dynamic_user_defined_executable_functions/</dynamic_user_defined_executable_functions_path>

encryption

encryption 코덱이 사용하는 키를 얻기 위한 명령을 구성해요. 키(들)는 환경 변수에 쓰거나 구성 파일에 설정해야 해요.

키는 16바이트 길이의 hex 또는 문자열이 될 수 있어요.

예시

구성에서 로드:

<encryption_codecs>
    <aes_128_gcm_siv>
        <key>1234567812345678</key>
    </aes_128_gcm_siv>
</encryption_codecs>

구성 파일에 키를 저장하는 것은 권장하지 않아요. 안전하지 않아요. 키를 보안 디스크의 별도 구성 파일로 옮기고 그 구성 파일에 대한 심볼릭 링크를 config.d/ 폴더에 넣을 수 있어요.

키가 hex일 때 구성에서 로드:

<encryption_codecs>
    <aes_128_gcm_siv>
        <key_hex>00112233445566778899aabbccddeeff</key_hex>
    </aes_128_gcm_siv>
</encryption_codecs>

환경 변수에서 키 로드:

<encryption_codecs>
    <aes_128_gcm_siv>
        <key_hex from_env="ENVVAR"></key_hex>
    </aes_128_gcm_siv>
</encryption_codecs>

여기서 current_key_id는 암호화의 현재 키를 설정하며, 지정된 모든 키는 복호화에 사용할 수 있어요.

이 방법은 각각 여러 키에 적용할 수 있어요:

<encryption_codecs>
    <aes_128_gcm_siv>
        <key_hex id="0">00112233445566778899aabbccddeeff</key_hex>
        <key_hex id="1" from_env="ENVVAR"></key_hex>
        <current_key_id>1</current_key_id>
    </aes_128_gcm_siv>
</encryption_codecs>

여기서 current_key_id는 암호화의 현재 키를 보여줘요.

또한 사용자는 12바이트 길이여야 하는 nonce를 추가할 수 있어요(기본적으로 암호화·복호화 과정은 0바이트로 구성된 nonce를 사용해요):

<encryption_codecs>
    <aes_128_gcm_siv>
        <nonce>012345678910</nonce>
    </aes_128_gcm_siv>
</encryption_codecs>

또는 hex로 설정할 수 있어요:

<encryption_codecs>
    <aes_128_gcm_siv>
        <nonce_hex>abcdefabcdef</nonce_hex>
    </aes_128_gcm_siv>
</encryption_codecs>

위에서 언급한 모든 것은 aes_256_gcm_siv에도 적용할 수 있어요(단, 키는 32바이트 길이여야 해요).

enforce_keeper_component_tracking

활성화하면 모든 ZooKeeper 요청이 Coordination::setCurrentComponent로 설정된 컴포넌트 이름을 가져야 해요. 컴포넌트가 없으면 LOGICAL_ERROR 예외를 발생해요.

error_log

기본적으로 비활성화돼요.

활성화

오류 기록 수집을 수동으로 켜려면 system.error_log에 대해 다음 내용으로 /etc/clickhouse-server/config.d/error_log.xml을 만들어요:

<clickhouse>
    <error_log>
        <database>system</database>
        <table>error_log</table>
        <flush_interval_milliseconds>7500</flush_interval_milliseconds>
        <collect_interval_milliseconds>1000</collect_interval_milliseconds>
        <max_size_rows>1048576</max_size_rows>
        <reserved_size_rows>8192</reserved_size_rows>
        <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
        <flush_on_crash>false</flush_on_crash>
    </error_log>
</clickhouse>

비활성화

error_log 설정을 비활성화하려면 다음 내용으로 /etc/clickhouse-server/config.d/disable_error_log.xml 파일을 만들어야 해요:

<clickhouse>
    <error_log remove="1" />
</clickhouse>

다음 설정은 하위 태그로 구성할 수 있어요:

설정	설명	기본값	참고
database	데이터베이스 이름.
table	시스템 테이블 이름.
engine	시스템 테이블의 MergeTree 엔진 정의.		partition_by 또는 order_by가 정의되어 있으면 사용할 수 없어요. 지정하지 않으면 기본으로 MergeTree가 선택돼요
partition_by	시스템 테이블의 사용자 지정 파티셔닝 키.		시스템 테이블에 engine이 지정되어 있으면 partition_by 파라미터를 'engine' 안에 직접 지정해야 해요
ttl	테이블 TTL 지정.		시스템 테이블에 engine이 지정되어 있으면 ttl 파라미터를 'engine' 안에 직접 지정해야 해요
order_by	시스템 테이블의 사용자 지정 정렬 키. engine이 정의되어 있으면 사용할 수 없어요.		시스템 테이블에 engine이 지정되어 있으면 order_by 파라미터를 'engine' 안에 직접 지정해야 해요
storage_policy	테이블에 사용할 스토리지 정책 이름(선택).		시스템 테이블에 engine이 지정되어 있으면 storage_policy 파라미터를 'engine' 안에 직접 지정해야 해요
settings	MergeTree 동작을 제어하는 추가 파라미터(선택).		시스템 테이블에 engine이 지정되어 있으면 settings 파라미터를 'engine' 안에 직접 지정해야 해요
flush_interval_milliseconds	메모리 버퍼에서 테이블로 데이터를 플러시하는 주기.	7500
max_size_rows	로그의 최대 라인 수. 플러시되지 않은 로그가 max_size에 도달하면 로그가 디스크로 덤프돼요.	1048576
reserved_size_rows	로그를 위해 미리 할당하는 메모리 크기(라인 수).	8192
buffer_size_rows_flush_threshold	라인 수 임계값. 이 임계값에 도달하면 로그를 디스크로 플러시하는 작업이 백그라운드에서 시작돼요.	max_size_rows / 2
flush_on_crash	크래시 발생 시 로그를 디스크로 덤프할지 여부.	false

또한 모든 시스템 로그 테이블의 기본 플러시 정책을 제어하는 서버 수준 설정이 있어요:

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>

설정	설명	기본값
skip_alias_columns	true이면 ALIAS 열이 시스템 로그 테이블 스키마에서 제외돼요. S3 기반 시스템 로그에 필요해요.	false

filesystem_caches_path

이 설정은 캐시 경로를 지정해요.

예시

<filesystem_caches_path>/var/lib/clickhouse/filesystem_caches/</filesystem_caches_path>

google_protos_path

Protobuf 타입용 proto 파일들이 있는 디렉터리를 정의해요.

예시

<google_protos_path>/usr/share/clickhouse/protos/</google_protos_path>

handshake_timeout_milliseconds

전체 TCP 핸드셰이크 단계(Hello + Addendum)의 벽시계 타임아웃(밀리초)이에요. 인증되지 않은 연결이 스레드를 붙잡을 수 있는 시간을 제한해요. 0으로 설정하면 비활성화돼요.

hdfs.libhdfs3_conf

libhdfs3이 자신의 구성을 올바른 위치로 가리키게 해요.

hsts_max_age

HSTS의 만료 시간(초)이에요.

값 0은 ClickHouse가 HSTS를 비활성화한다는 뜻이에요. 양수를 설정하면 HSTS가 활성화되고 max-age는 설정한 숫자가 돼요.

예시

<hsts_max_age>600000</hsts_max_age>

iceberg_background_schedule_pool_size

원격 iceberg 카탈로그에서 최신 메타데이터를 비동기로 가져오는 스레드 풀 크기예요. 이 풀은 모든 활성 테이블이 공유해요.

iceberg_manifest_decode_thread_pool_queue_size

Iceberg 데이터 매니페스트 파일 디코딩을 위해 스레드 풀에 예약(schedule)할 수 있는 작업의 최대 수예요.

ignore_empty_sql_security_in_create_view_query

true이면 DEFINER도 SQL SECURITY도 지정하지 않는 CREATE VIEW 또는 CREATE MATERIALIZED VIEW 쿼리가 작성된 그대로 저장되고, 뷰는 빈 SQL 보안 타입을 갖게 돼요. DEFINER만 지정하면 SQL SECURITY DEFINER로 간주되므로 그런 쿼리는 이 설정의 영향을 받지 않아요. 빈 SQL 보안 타입의 일반 뷰는 호출자(invoker)의 권한으로 실행돼요. 명시적으로 지정된 대상 테이블이 있는 materialized view의 경우 대상 테이블에 대한 접근 검사를 건너뛰어요. 소스 테이블에 삽입하는 데 대상 테이블에 대한 INSERT 권한이 필요하지 않고, 뷰에서 읽는 데 SELECT 권한이 필요하지 않아요.

false이면 default_normal_view_sql_security, default_materialized_view_sql_security, default_view_definer 설정의 기본값이 생성 시점에 뷰 정의에 기록돼요. 그 설정들의 기본값으로, 두 절 중 어느 것도 지정하지 않고 만든 materialized view는 생성 사용자를 definer로 기록하고 그 사용자의 권한으로 실행돼요.

갱신 가능한(refreshable) materialized view는 이 설정과 관계없이 항상 기본값을 받아요.

이 설정을 변경하면 이후에 생성되는 뷰에만 영향을 주며, 기존 뷰의 저장된 정의는 바뀌지 않아요.

include_from

치환(substitutions) 파일의 경로예요. XML과 YAML 포맷이 모두 지원돼요.

자세한 내용은 Configuration files 섹션을 참고해요. 기본적으로 비어 있어서 치환 파일을 사용하지 않아요. 26.8 버전 이전에는 /etc/metrika.xml 파일이 존재할 때마다 암시적으로 사용되었어요. 그 파일에 의존한다면 경로를 명시적으로 지정해요.

메인 서버 구성과 별개로 로드되는 구성 파일 — 사용자 구성(예: 메인 파일에 포함되지 않은 users.xml)과 XML 사전 구성 — 은 서버 구성이 아니라 자신의 내용에서 include_from 요소를 읽는다는 점을 참고해요. 치환에 의존하는 각 그런 파일은 자신의 include_from 요소가 필요해요.

예시

<include_from>/etc/clickhouse-server/substitutions.xml</include_from>

insert_deduplication_version

Deprecated 마이그레이션 가드예요. ClickHouse 26.7 이상 버전은 통합 삽입 중복 제거 해시(new_unified_hash)만 지원해요. 이 설정이 다른 값(예: old_separate_hashes 또는 compatible_double_hashes)으로 존재하면 서버가 시작을 거부해요. 업그레이드 전에 이전 버전에서 compatible_double_hashes(레거시 및 통합 해시를 모두 기록)를 실행해 중복 제거 마이그레이션을 완료해요. 복제 테이블의 경우 replicated_deduplication_window_seconds(기본값 1시간) 이상 실행해요. 기본 창은 그 창 동안 모든 삽입의 통합 해시를 보존하며, 이는 삽입 재시도 루프를 덮기에 충분한 것으로 간주돼요. non_replicated_deduplication_window > 0인 비복제 테이블의 경우 창은 시간 기반이 아니라 개수 기반이므로, 업그레이드 전에 그만큼의 삽입 횟수만큼 compatible_double_hashes를 실행해요.

io_thread_pool_queue_size

IO 스레드 풀에 예약(schedule)할 수 있는 작업의 최대 수예요.

0 값은 무제한을 의미해요.

keep_alive_timeout

ClickHouse가 HTTP 프로토콜로 연결을 닫기 전에 들어오는 요청을 기다리는 시간(초)이에요.

예시

<keep_alive_timeout>30</keep_alive_timeout>

ldap_servers

다음과 같은 목적으로 LDAP 서버와 해당 연결 파라미터를 나열해요:

• 'password' 대신 'ldap' 인증 메커니즘이 지정된 전용 로컬 사용자를 위한 인증기(authenticator)로 사용
• 원격 사용자 디렉터리로 사용.

다음 설정은 하위 태그로 구성할 수 있어요:

설정	설명
bind_dn	바인딩할 DN을 구성하는 데 사용하는 템플릿. 각 인증 시도 중 템플릿의 모든 \{user_name\} 부분 문자열을 실제 사용자 이름으로 바꿔 결과 DN을 구성해요.
enable_tls	LDAP 서버에 보안 연결 사용을 켜는 플래그. 평문(ldap://) 프로토콜에는 no 지정(권장하지 않음). SSL/TLS 상의 LDAP(ldaps://) 프로토콜에는 yes 지정(권장, 기본값). 레거시 StartTLS 프로토콜에는 starttls 지정(평문(ldap://) 프로토콜을 TLS로 업그레이드).
host	LDAP 서버 호스트네임 또는 IP. 필수이며 비어 있을 수 없어요.
port	LDAP 서버 포트. enable_tls가 true이면 기본 636, 그 외에는 389.
tls_ca_cert_dir	CA 인증서가 포함된 디렉터리 경로.
tls_ca_cert_file	CA 인증서 파일 경로.
tls_cert_file	인증서 파일 경로.
tls_cipher_suite	허용되는 암호 스위트(OpenSSL 표기).
tls_key_file	인증서 키 파일 경로.
tls_minimum_protocol_version	SSL/TLS의 최소 프로토콜 버전. 허용 값: ssl2, ssl3, tls1.0, tls1.1, tls1.2(기본값).
tls_require_cert	SSL/TLS 피어 인증서 검증 동작. 허용 값: never, allow, try, demand(기본값).
user_dn_detection	바인딩된 사용자의 실제 사용자 DN을 감지하기 위한 LDAP 검색 파라미터가 있는 섹션. 서버가 Active Directory일 때 추가 역할 매핑을 위한 검색 필터에 주로 사용돼요. 결과 사용자 DN은 \{user_dn\} 부분 문자열이 허용되는 모든 곳에서 치환할 때 사용돼요. 기본적으로 사용자 DN은 bind DN과 같게 설정되지만, 검색이 수행되면 실제 감지된 사용자 DN 값으로 갱신돼요.
verification_cooldown	성공적인 bind 시도 후의 시간(초)으로, 이 동안 사용자는 LDAP 서버에 연락하지 않고 모든 연속 요청에 대해 성공적으로 인증된 것으로 간주돼요. 0(기본값)을 지정하면 캐싱을 비활성화해 각 인증 요청마다 LDAP 서버에 연락하도록 강제해요.

user_dn_detection 설정은 하위 태그로 구성할 수 있어요:

설정	설명
base_dn	LDAP 검색의 base DN을 구성하는 데 사용하는 템플릿. LDAP 검색 중 템플릿의 모든 \{user_name\} 및 '{bind_dn}' 부분 문자열을 실제 사용자 이름과 bind DN으로 바꿔 결과 DN을 구성해요.
scope	LDAP 검색의 범위. 허용 값: base, one_level, children, subtree(기본값).
search_filter	LDAP 검색의 검색 필터를 구성하는 데 사용하는 템플릿. LDAP 검색 중 템플릿의 모든 \{user_name\}, \{bind_dn\}, \{base_dn\} 부분 문자열을 실제 사용자 이름, bind DN, base DN으로 바꿔 결과 필터를 구성해요. 특수 문자는 XML에서 제대로 이스케이프되어야 해요.

예:

<my_ldap_server>
    <host>localhost</host>
    <port>636</port>
    <bind_dn>uid={user_name},ou=users,dc=example,dc=com</bind_dn>
    <verification_cooldown>300</verification_cooldown>
    <enable_tls>yes</enable_tls>
    <tls_minimum_protocol_version>tls1.2</tls_minimum_protocol_version>
    <tls_require_cert>demand</tls_require_cert>
    <tls_cert_file>/path/to/tls_cert_file</tls_cert_file>
    <tls_key_file>/path/to/tls_key_file</tls_key_file>
    <tls_ca_cert_file>/path/to/tls_ca_cert_file</tls_ca_cert_file>
    <tls_ca_cert_dir>/path/to/tls_ca_cert_dir</tls_ca_cert_dir>
    <tls_cipher_suite>ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:AES256-GCM-SHA384</tls_cipher_suite>
</my_ldap_server>

예(추가 역할 매핑을 위한 사용자 DN 감지가 구성된 전형적인 Active Directory):

<my_ad_server>
    <host>localhost</host>
    <port>389</port>
    <bind_dn>EXAMPLE\{user_name}</bind_dn>
    <user_dn_detection>
        <base_dn>CN=Users,DC=example,DC=com</base_dn>
        <search_filter>(&amp;(objectClass=user)(sAMAccountName={user_name}))</search_filter>
    </user_dn_detection>
    <enable_tls>no</enable_tls>
</my_ad_server>

logger

로그 메시지의 위치와 형식이에요.

키:

키	설명
async	true(기본값)이면 로깅이 비동기로 이루어져요(출력 채널당 백그라운드 스레드 하나). 그렇지 않으면 LOG를 호출하는 스레드 안에서 로깅돼요.
async_queue_max_size	비동기 로깅 사용 시 플러시를 기다리는 큐에 보관되는 최대 메시지 수. 추가 메시지는 버려져요.
console	콘솔 로깅 활성화. 1 또는 true로 설정해 활성화. ClickHouse가 데몬 모드로 실행되지 않으면 기본 1, 그 외에는 0.
console_log_level	콘솔 출력의 로그 레벨. 기본값은 level.
console_shutdown_log_level	종료 레벨은 서버 종료 시 콘솔 로그 레벨을 설정하는 데 사용돼요.
console_startup_log_level	시작 레벨은 서버 시작 시 콘솔 로그 레벨을 설정하는 데 사용돼요. 시작 후 로그 레벨은 console_log_level 설정으로 되돌아가요.
count	회전 정책: ClickHouse가 보관하는 과거 로그 파일의 최대 개수.
errorlog	오류 로그 파일 경로.
formatting.type	콘솔 출력의 로그 형식. 현재 json만 지원돼요.
level	로그 레벨. 허용 값: none(로깅 끔), fatal, critical, error, warning, notice, information, debug, trace, test.
log	로그 파일 경로.
rotation	회전 정책: 로그 파일이 회전되는 시점을 제어. 회전은 크기, 시간, 또는 둘의 조합을 기반으로 할 수 있어요. 예: 100M, daily, 100M,daily. 로그 파일이 지정된 크기를 초과하거나 지정된 시간 간격에 도달하면 이름이 바뀌고 보관되며 새 로그 파일이 생성돼요.
shutdown_level	종료 레벨은 서버 종료 시 루트 로거 레벨을 설정하는 데 사용돼요.
size	회전 정책: 로그 파일의 최대 크기(바이트). 로그 파일 크기가 이 임계값을 초과하면 이름이 바뀌고 보관되며 새 로그 파일이 생성돼요.
startup_level	시작 레벨은 서버 시작 시 루트 로거 레벨을 설정하는 데 사용돼요. 시작 후 로그 레벨은 level 설정으로 되돌아가요.
stream_compress	LZ4로 로그 메시지를 압축. 1 또는 true로 설정해 활성화.
syslog_level	syslog로 로깅할 때의 로그 레벨.
use_syslog	로그 출력을 syslog로도 전달.

로그 형식 지정자

log와 errorLog 경로의 파일 이름은 결과 파일 이름에 대해 아래 형식 지정자를 지원해요(디렉터리 부분은 지원하지 않아요).

"Example" 열은 2023-07-06 18:32:07에서의 출력을 보여줘요.

지정자	설명	예시
%%	리터럴 %	%
%n	줄바꿈 문자
%t	가로 탭 문자
%Y	소수로 표시한 연도, 예: 2017	2023
%y	소수로 표시한 연도의 마지막 2자리(범위 [00,99])	23
%C	소수로 표시한 연도의 첫 2자리(범위 [00,99])	20
%G	4자리 ISO 8601 주 기반 연도, 즉 지정된 주를 포함하는 연도. 보통 %V와 함께만 유용	2023
%g	ISO 8601 주 기반 연도의 마지막 2자리, 즉 지정된 주를 포함하는 연도.	23
%b	약식 월 이름, 예: Oct(로케일 의존)	Jul
%h	%b의 동의어	Jul
%B	전체 월 이름, 예: October(로케일 의존)	July
%m	소수로 표시한 월(범위 [01,12])	07
%U	소수로 표시한 연중 주(일요일이 주의 첫날)(범위 [00,53])	27
%W	소수로 표시한 연중 주(월요일이 주의 첫날)(범위 [00,53])	27
%V	ISO 8601 주 번호(범위 [01,53])	27
%j	소수로 표시한 연중 일(범위 [001,366])	187
%d	0으로 채워진 소수로 표시한 월중 일(범위 [01,31]). 한 자리는 0이 앞에 붙어요.	06
%e	공백으로 채워진 소수로 표시한 월중 일(범위 [1,31]). 한 자리는 공백이 앞에 붙어요.	  6
%a	약식 요일 이름, 예: Fri(로케일 의존)	Thu
%A	전체 요일 이름, 예: Friday(로케일 의존)	Thursday
%w	일요일을 0으로 하는 정수 요일(범위 [0-6])	4
%u	월요일을 1로 하는 소수 요일(ISO 8601 형식)(범위 [1-7])	4
%H	24시간 시계의 소수 시(범위 [00-23])	18
%I	12시간 시계의 소수 시(범위 [01,12])	06
%M	소수 분(범위 [00,59])	32
%S	소수 초(범위 [00,60])	07
%c	표준 날짜·시간 문자열, 예: Sun Oct 17 04:41:13 2010(로케일 의존)	Thu Jul 6 18:32:07 2023
%x	지역화된 날짜 표현(로케일 의존)	07/06/23
%X	지역화된 시간 표현, 예: 18:40:20 또는 6:40:20 PM(로케일 의존)	18:32:07
%D	짧은 MM/DD/YY 날짜, %m/%d/%y와 동일	07/06/23
%F	짧은 YYYY-MM-DD 날짜, %Y-%m-%d와 동일	2023-07-06
%r	지역화된 12시간 시계 시간(로케일 의존)	06:32:07 PM
%R	"%H:%M"과 동일	18:32
%T	"%H:%M:%S"(ISO 8601 시간 형식)와 동일	18:32:07
%p	지역화된 a.m. 또는 p.m. 지정(로케일 의존)	PM
%z	ISO 8601 형식의 UTC 오프셋(예: -0430), 또는 시간대 정보가 없으면 문자 없음	+0800
%Z	로케일 의존 시간대 이름 또는 약어, 또는 시간대 정보가 없으면 문자 없음	Z AWST

예시

<logger>
    <level>trace</level>
    <log>/var/log/clickhouse-server/clickhouse-server-%F-%T.log</log>
    <errorlog>/var/log/clickhouse-server/clickhouse-server-%F-%T.err.log</errorlog>
    <size>1000M</size>
    <count>10</count>
    <stream_compress>true</stream_compress>
</logger>

로그 메시지를 콘솔에만 출력하려면:

<logger>
    <level>information</level>
    <console>true</console>
</logger>

레벨별 재정의

개별 로그 이름의 로그 레벨을 재정의할 수 있어요. 예를 들어 "Backup"과 "RBAC" 로거의 모든 메시지를 음소거하려면:

<logger>
    <levels>
        <logger>
            <name>Backup</name>
            <level>none</level>
        </logger>
        <logger>
            <name>RBAC</name>
            <level>none</level>
        </logger>
    </levels>
</logger>

syslog

로그 메시지를 syslog에 추가로 기록하려면:

<logger>
    <use_syslog>1</use_syslog>
    <syslog>
        <address>syslog.remote:10514</address>
        <hostname>myhost.local</hostname>
        <facility>LOG_LOCAL6</facility>
        <format>syslog</format>
    </syslog>
</logger>

<syslog>의 키:

키	설명
address	host\[:port\] 형식의 syslog 주소. 생략하면 로컬 데몬이 사용돼요.
hostname	로그를 보내는 호스트의 이름(선택).
facility	syslog facility 키워드. "LOG_" 접두사와 함께 대문자로 지정해야 해요, 예: LOG_USER, LOG_DAEMON, LOG_LOCAL3 등. 기본값: address가 지정되면 LOG_USER, 그 외에는 LOG_DAEMON.
format	로그 메시지 형식. 가능한 값: bsd와 syslog.

로그 형식

콘솔 로그에 출력될 로그 형식을 지정할 수 있어요. 현재 JSON만 지원돼요.

예시

여기 출력 JSON 로그의 예가 있어요:

{
  "date_time_utc": "2024-11-06T09:06:09Z",
  "date_time": "1650918987.180175",
  "thread_name": "#1",
  "thread_id": "254545",
  "level": "Trace",
  "query_id": "",
  "logger_name": "BaseDaemon",
  "message": "Received signal 2",
  "source_file": "../base/daemon/BaseDaemon.cpp; virtual void SignalListener::run()",
  "source_line": "192"
}

JSON 로깅 지원을 활성화하려면 다음 스니펫을 사용해요:

<logger>
    <formatting>
        <type>json</type>
        <!-- Can be configured on a per-channel basis (log, errorlog, console, syslog), or globally for all channels (then just omit it). -->
        <!-- <channel></channel> -->
        <names>
            <date_time>date_time</date_time>
            <thread_name>thread_name</thread_name>
            <thread_id>thread_id</thread_id>
            <level>level</level>
            <query_id>query_id</query_id>
            <logger_name>logger_name</logger_name>
            <message>message</message>
            <source_file>source_file</source_file>
            <source_line>source_line</source_line>
        </names>
    </formatting>
</logger>

JSON 로그 키 이름 바꾸기

<names> 태그 안의 태그 값을 변경해 키 이름을 수정할 수 있어요. 예를 들어 DATE_TIME을 MY_DATE_TIME으로 바꾸려면 <date_time>MY_DATE_TIME</date_time>을 사용할 수 있어요.

JSON 로그 키 생략

속성을 주석 처리해 로그 속성을 생략할 수 있어요. 예를 들어 로그가 query_id를 출력하지 않게 하려면 <query_id> 태그를 주석 처리하면 돼요.

logger.count

회전 정책: ClickHouse가 보관하는 과거 로그 파일의 최대 개수예요.

logger.errorlog

오류 로그 파일의 경로예요.

logger.formatting.type

콘솔 출력의 로그 형식이에요. 현재 <json>만 지원돼요.

logger.level

로그 레벨이에요. 허용 값: <none>(로깅 끔), <fatal>, <critical>, <error>, <warning>, <notice>, <information>, <debug>, <trace>, <test>.

logger.log

로그 파일의 경로예요.

logger.rotation

회전 정책: 로그 파일이 회전되는 시점을 제어해요. 회전은 크기, 시간, 또는 둘의 조합을 기반으로 할 수 있어요. 예: 100M, daily, 100M,daily. 로그 파일이 지정된 크기를 초과하거나 지정된 시간 간격에 도달하면 이름이 바뀌고 보관되며 새 로그 파일이 생성돼요.

logger.shutdown_level

종료 레벨은 서버 종료 시 루트 로거 레벨을 설정하는 데 사용돼요.

logger.size

회전 정책: 로그 파일의 최대 크기(바이트)예요. 로그 파일 크기가 이 임계값을 초과하면 이름이 바뀌고 보관되며 새 로그 파일이 생성돼요.

logger.startup_level

시작 레벨은 서버 시작 시 루트 로거 레벨을 설정하는 데 사용돼요. 시작 후 로그 레벨은 <level> 설정으로 되돌아가요.

logger.stream_compress

LZ4로 로그 메시지를 압축해요. <1> 또는 <true>로 설정해 활성화해요.

logger.syslog_level

syslog로 로깅할 때의 로그 레벨이에요.

logger.use_syslog

로그 출력을 syslog로도 전달해요.

macros

복제 테이블의 파라미터 치환이에요.

복제 테이블을 사용하지 않으면 생략할 수 있어요.

자세한 내용은 복제 테이블 만들기 섹션을 참고해요.

예시

<macros incl="macros" optional="true" />

message_queue_disable_insertion

메시지 큐 엔진(Kafka, RabbitMQ, NATS)에서 연결된 materialized view로의 삽입을 비활성화해요.

metric_log

기본적으로 비활성화돼요.

활성화

메트릭 기록 수집을 수동으로 켜려면 system.metric_log에 대해 다음 내용으로 /etc/clickhouse-server/config.d/metric_log.xml을 만들어요:

<clickhouse>
    <metric_log>
        <database>system</database>
        <table>metric_log</table>
        <flush_interval_milliseconds>7500</flush_interval_milliseconds>
        <collect_interval_milliseconds>1000</collect_interval_milliseconds>
        <max_size_rows>1048576</max_size_rows>
        <reserved_size_rows>8192</reserved_size_rows>
        <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
        <flush_on_crash>false</flush_on_crash>
    </metric_log>
</clickhouse>

비활성화

metric_log 설정을 비활성화하려면 다음 내용으로 /etc/clickhouse-server/config.d/disable_metric_log.xml 파일을 만들어야 해요:

<clickhouse>
    <metric_log remove="1" />
</clickhouse>

다음 설정은 하위 태그로 구성할 수 있어요:

설정	설명	기본값	참고
database	데이터베이스 이름.
table	시스템 테이블 이름.
engine	시스템 테이블의 MergeTree 엔진 정의.		partition_by 또는 order_by가 정의되어 있으면 사용할 수 없어요. 지정하지 않으면 기본으로 MergeTree가 선택돼요
partition_by	시스템 테이블의 사용자 지정 파티셔닝 키.		시스템 테이블에 engine이 지정되어 있으면 partition_by 파라미터를 'engine' 안에 직접 지정해야 해요
ttl	테이블 TTL 지정.		시스템 테이블에 engine이 지정되어 있으면 ttl 파라미터를 'engine' 안에 직접 지정해야 해요
order_by	시스템 테이블의 사용자 지정 정렬 키. engine이 정의되어 있으면 사용할 수 없어요.		시스템 테이블에 engine이 지정되어 있으면 order_by 파라미터를 'engine' 안에 직접 지정해야 해요
storage_policy	테이블에 사용할 스토리지 정책 이름(선택).		시스템 테이블에 engine이 지정되어 있으면 storage_policy 파라미터를 'engine' 안에 직접 지정해야 해요
settings	MergeTree 동작을 제어하는 추가 파라미터(선택).		시스템 테이블에 engine이 지정되어 있으면 settings 파라미터를 'engine' 안에 직접 지정해야 해요
flush_interval_milliseconds	메모리 버퍼에서 테이블로 데이터를 플러시하는 주기.	7500
max_size_rows	로그의 최대 라인 수. 플러시되지 않은 로그가 max_size에 도달하면 로그가 디스크로 덤프돼요.	1048576
reserved_size_rows	로그를 위해 미리 할당하는 메모리 크기(라인 수).	8192
buffer_size_rows_flush_threshold	라인 수 임계값. 이 임계값에 도달하면 로그를 디스크로 플러시하는 작업이 백그라운드에서 시작돼요.	max_size_rows / 2
flush_on_crash	크래시 발생 시 로그를 디스크로 덤프할지 여부.	false

또한 모든 시스템 로그 테이블의 기본 플러시 정책을 제어하는 서버 수준 설정이 있어요:

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>

설정	설명	기본값
skip_alias_columns	true이면 ALIAS 열이 시스템 로그 테이블 스키마에서 제외돼요. S3 기반 시스템 로그에 필요해요.	false

mmap_cache_size

이 설정은 (결과적인 페이지 폴트로 매우 비싼) 빈번한 open/close 호출을 피하고 여러 스레드와 쿼리에서 매핑을 재사용할 수 있게 해요. 설정 값은 매핑된 영역의 수예요(보통 매핑된 파일 수와 같음).

매핑된 파일의 데이터량은 다음 시스템 테이블과 메트릭으로 모니터링할 수 있어요:

• system.metrics, system.metric_log의 MMappedFiles/MMappedFileBytes/MMapCacheCells
• system.events, system.processes, system.query_log, system.query_thread_log, system.query_views_log의 CreatedReadBufferMMap/CreatedReadBufferMMapFailed/MMappedFileCacheHits/MMappedFileCacheMisses

매핑된 파일의 데이터량은 메모리를 직접 소비하지 않고 쿼리나 서버 메모리 사용량에 계산되지 않아요. OS 페이지 캐시처럼 이 메모리는 버릴 수 있기 때문이에요. 캐시는 MergeTree 계열 테이블의 오래된 파트 제거 시 자동으로 버려지고(파일이 닫힘), SYSTEM DROP MMAP CACHE 쿼리로 수동으로 버릴 수도 있어요.

이 설정은 런타임에 수정할 수 있고 즉시 적용돼요.

mutation_workload

리소스가 mutation과 다른 워크로드 사이에 어떻게 활용되고 공유되는지 조절하는 데 사용돼요. 지정된 값은 모든 백그라운드 mutation의 workload 설정 값으로 사용돼요. merge tree 설정으로 재정의할 수 있어요.

참고

• Workload Scheduling

named_collections_storage.type

named collections의 스토리지 타입이에요. 가능한 값은 local, local_encrypted, keeper, keeper_encrypted, zookeeper, zookeeper_encrypted예요. named_collections_storage.type으로 구성돼요(XML에서 <named_collections_storage><type>).

oom_score

Linux 시스템에서 OOM 킬러의 동작을 제어할 수 있어요.

openSSL

SSL 클라이언트/서버 구성이에요.

SSL 지원은 libpoco 라이브러리가 제공해요. 사용 가능한 구성 옵션은 SSLManager.h에 설명되어 있어요. 기본값은 SSLManager.cpp에서 찾을 수 있어요.

certificateFile, privateKeyFile, caConfig가 참조하는 파일은 변경되거나 SYSTEM RELOAD CONFIG 시 재시작 없이 다시 로드돼요. 새 연결은 다시 로드된 인증서를 사용하며, 수립된 연결은 영향을 받지 않아요.

서버/클라이언트 설정의 키:

옵션	설명	기본값
cacheSessions	세션 캐싱을 활성화하거나 비활성화해요. sessionIdContext와 함께 사용해야 해요. 허용 값: true, false.	false
caConfig	신뢰할 수 있는 CA 인증서가 포함된 파일 또는 디렉터리 경로. 파일을 가리키면 PEM 형식이어야 하며 여러 CA 인증서를 포함할 수 있어요. 디렉터리를 가리키면 CA 인증서당 하나의 .pem 파일을 포함해야 해요. 파일 이름은 CA 주체 이름 해시 값으로 조회돼요. 자세한 내용은 SSL_CTX_load_verify_locations 매뉴얼 페이지에서 찾을 수 있어요. certificateFile과 privateKeyFile처럼, CA 인증서는 파일이 변경되거나 SYSTEM RELOAD CONFIG 시 재시작 없이 다시 로드돼요.
certificateFile	PEM 형식의 클라이언트/서버 인증서 파일 경로. privateKeyFile이 인증서를 포함하면 생략할 수 있어요.
cipherList	지원되는 OpenSSL 암호화.	ALL:!ADH:!LOW:!EXP:!MD5:!3DES:@STRENGTH
disableProtocols	사용이 허용되지 않는 프로토콜.
extendedVerification	활성화하면 인증서 CN 또는 SAN이 피어 호스트네임과 일치하는지 검증해요.	openSSL.client는 true, openSSL.server는 false
fips	OpenSSL FIPS 모드를 활성화해요. 라이브러리의 OpenSSL 버전이 FIPS를 지원하면 지원돼요.	false
invalidCertificateHandler	유효하지 않은 인증서를 검증하는 클래스(CertificateHandler의 하위 클래스). 예: <invalidCertificateHandler> <name>RejectCertificateHandler</name> </invalidCertificateHandler>.	RejectCertificateHandler
loadDefaultCAFile	OpenSSL의 내장 CA 인증서를 사용할지 여부. ClickHouse는 내장 CA 인증서가 /etc/ssl/cert.pem(또는 /etc/ssl/certs 디렉터리) 또는 환경 변수 SSL_CERT_FILE(또는 SSL_CERT_DIR)이 지정하는 파일(또는 디렉터리)에 있다고 가정해요.	true
preferServerCiphers	클라이언트 선호 서버 암호화.	false
privateKeyFile	PEM 인증서의 비밀 키가 있는 파일 경로. 파일은 키와 인증서를 동시에 포함할 수 있어요.
privateKeyPassphraseHandler	비밀 키에 접근하기 위한 암호 문구를 요청하는 클래스(PrivateKeyPassphraseHandler 하위 클래스). 예: <privateKeyPassphraseHandler>, <name>KeyFileHandler</name>, <options><password>test</password></options>, </privateKeyPassphraseHandler>.	KeyConsoleHandler
requireTLSv1	TLSv1 연결을 요구해요. 허용 값: true, false.	false
requireTLSv1_1	TLSv1.1 연결을 요구해요. 허용 값: true, false.	false
requireTLSv1_2	TLSv1.2 연결을 요구해요. 허용 값: true, false.	false
sessionCacheSize	서버가 캐시하는 세션의 최대 수. 0 값은 무제한 세션을 의미해요.	1024*20
sessionIdContext	서버가 생성된 각 식별자에 추가하는 고유한 무작위 문자 집합. 문자열 길이는 SSL_MAX_SSL_SESSION_ID_LENGTH를 초과해선 안 돼요. 이 파라미터는 서버가 세션을 캐시하든 클라이언트가 캐싱을 요청하든 문제를 피하는 데 도움이 되므로 항상 권장돼요.	${application.name}
sessionTimeout	서버에서 세션을 캐시하는 시간(시간).	2
verificationDepth	검증 체인의 최대 길이. 인증서 체인 길이가 설정 값을 초과하면 검증이 실패해요.	9
verificationMode	노드의 인증서를 확인하는 방법. 세부 사항은 Context 클래스 설명에 있어요. 가능한 값: none, relaxed, strict, once.	relaxed

설정 예시:

<openSSL>
    <server>
        <!-- openssl req -subj "/CN=localhost" -new -newkey rsa:2048 -days 365 -nodes -x509 -keyout /etc/clickhouse-server/server.key -out /etc/clickhouse-server/server.crt -->
        <certificateFile>/etc/clickhouse-server/server.crt</certificateFile>
        <privateKeyFile>/etc/clickhouse-server/server.key</privateKeyFile>
        <!-- openssl dhparam -out /etc/clickhouse-server/dhparam.pem 4096 -->
        <dhParamsFile>/etc/clickhouse-server/dhparam.pem</dhParamsFile>
        <verificationMode>none</verificationMode>
        <loadDefaultCAFile>true</loadDefaultCAFile>
        <cacheSessions>true</cacheSessions>
        <disableProtocols>sslv2,sslv3</disableProtocols>
        <preferServerCiphers>true</preferServerCiphers>
    </server>
    <client>
        <loadDefaultCAFile>true</loadDefaultCAFile>
        <cacheSessions>true</cacheSessions>
        <disableProtocols>sslv2,sslv3</disableProtocols>
        <preferServerCiphers>true</preferServerCiphers>
        <!-- Use for self-signed: <verificationMode>none</verificationMode> -->
        <invalidCertificateHandler>
            <!-- Use for self-signed: <name>AcceptCertificateHandler</name> -->
            <name>RejectCertificateHandler</name>
        </invalidCertificateHandler>
    </client>
</openSSL>

openSSL.client.caConfig

신뢰할 수 있는 CA 인증서가 포함된 파일 또는 디렉터리 경로예요. 파일을 가리키면 PEM 형식이어야 하며 여러 CA 인증서를 포함할 수 있어요. 디렉터리를 가리키면 CA 인증서당 하나의 .pem 파일을 포함해야 해요. 파일 이름은 CA 주체 이름 해시 값으로 조회돼요. 자세한 내용은 SSL_CTX_load_verify_locations 매뉴얼 페이지에서 찾을 수 있어요. CA 인증서는 파일이 변경되거나 SYSTEM RELOAD CONFIG 시 재시작 없이 다시 로드되며, 새 연결은 다시 로드된 인증서로 검증돼요.

openSSL.client.cacheSessions

세션 캐싱을 활성화하거나 비활성화해요. <sessionIdContext>와 함께 사용해야 해요. 허용 값: <true>, <false>.

openSSL.client.certificateFile

PEM 형식의 클라이언트/서버 인증서 파일 경로예요. <privateKeyFile>이 인증서를 포함하면 생략할 수 있어요.

openSSL.client.cipherList

지원되는 OpenSSL 암호화예요.

openSSL.client.disableProtocols

사용이 허용되지 않는 프로토콜이에요.

openSSL.client.extendedVerification

활성화하면 인증서 CN 또는 SAN이 피어 호스트네임과 일치하는지 검증해요.

openSSL.client.fips

OpenSSL FIPS 모드를 활성화해요. 라이브러리의 OpenSSL 버전이 FIPS를 지원하면 지원돼요.

openSSL.client.invalidCertificateHandler.name

유효하지 않은 인증서를 검증하는 클래스(CertificateHandler의 하위 클래스)예요. 예: <<invalidCertificateHandler> <name>RejectCertificateHandler</name> </invalidCertificateHandler>>.

openSSL.client.loadDefaultCAFile

기본 CA 인증서를 사용할지 여부를 결정해요. ClickHouse는 /etc/ssl/cert.pem 파일(또는 /etc/ssl/certs 디렉터리), 환경 변수 SSL_CERT_FILE(또는 SSL_CERT_DIR)이 지정하는 파일(또는 디렉터리), 그리고 각 배포판의 다른 잘 알려진 위치에서 그것들을 찾아요. 파일 시스템에서 CA 인증서가 발견되지 않고 명시적 caConfig가 구성되지 않았으며 바이너리가 임베디드 CA 인증서로 빌드된 경우(기본값, ENABLE_EMBEDDED_CA_CERTIFICATES 빌드 옵션이 제어), 임베디드 인증서를 대신 사용해요. 따라서 파일이 하나도 없는 최소 환경, 예를 들어 "from scratch"로 빌드된 컨테이너에서도 TLS가 작동해요. 임베디드 CA 인증서 없이 빌드된 경우에는 이 상황에서 오류가 발생해요.

openSSL.client.preferServerCiphers

클라이언트 선호 서버 암호화예요.

openSSL.client.privateKeyFile

PEM 인증서의 비밀 키가 있는 파일 경로예요. 파일은 키와 인증서를 동시에 포함할 수 있어요.

openSSL.client.privateKeyPassphraseHandler.name

비밀 키에 접근하기 위한 암호 문구를 요청하는 클래스(PrivateKeyPassphraseHandler 하위 클래스)예요. 예: <<privateKeyPassphraseHandler>>, <<name>KeyFileHandler</name>>, <<options><password>test</password></options>>, <</privateKeyPassphraseHandler>>.

openSSL.client.verificationDepth

검증 체인의 최대 길이예요. 인증서 체인 길이가 설정 값을 초과하면 검증이 실패해요.

openSSL.client.verificationMode

노드의 인증서를 확인하는 방법이에요. 세부 사항은 Context 클래스 설명에 있어요. 가능한 값: <none>, <relaxed>, <strict>, <once>.

openSSL.server.caConfig

신뢰할 수 있는 CA 인증서가 포함된 파일 또는 디렉터리 경로예요. 파일을 가리키면 PEM 형식이어야 하며 여러 CA 인증서를 포함할 수 있어요. 디렉터리를 가리키면 CA 인증서당 하나의 .pem 파일을 포함해야 해요. 파일 이름은 CA 주체 이름 해시 값으로 조회돼요. 자세한 내용은 SSL_CTX_load_verify_locations 매뉴얼 페이지에서 찾을 수 있어요. CA 인증서는 파일이 변경되거나 SYSTEM RELOAD CONFIG 시 재시작 없이 다시 로드되며, 새 연결은 다시 로드된 인증서로 검증돼요.

openSSL.server.cacheSessions

세션 캐싱을 활성화하거나 비활성화해요. <sessionIdContext>와 함께 사용해야 해요. 허용 값: <true>, <false>.

openSSL.server.certificateFile

PEM 형식의 클라이언트/서버 인증서 파일 경로예요. <privateKeyFile>이 인증서를 포함하면 생략할 수 있어요.

openSSL.server.cipherList

지원되는 OpenSSL 암호화예요.

openSSL.server.disableProtocols

사용이 허용되지 않는 프로토콜이에요.

openSSL.server.extendedVerification

활성화하면 인증서 CN 또는 SAN이 피어 호스트네임과 일치하는지 검증해요.

openSSL.server.fips

OpenSSL FIPS 모드를 활성화해요. 라이브러리의 OpenSSL 버전이 FIPS를 지원하면 지원돼요.

openSSL.server.invalidCertificateHandler.name

유효하지 않은 인증서를 검증하는 클래스(CertificateHandler의 하위 클래스)예요. 예: <<invalidCertificateHandler> <name>RejectCertificateHandler</name> </invalidCertificateHandler>>.

openSSL.server.loadDefaultCAFile

기본 CA 인증서를 사용할지 여부를 결정해요. ClickHouse는 /etc/ssl/cert.pem 파일(또는 /etc/ssl/certs 디렉터리), 환경 변수 SSL_CERT_FILE(또는 SSL_CERT_DIR)이 지정하는 파일(또는 디렉터리), 그리고 각 배포판의 다른 잘 알려진 위치에서 그것들을 찾아요. 파일 시스템에서 CA 인증서가 발견되지 않고 명시적 caConfig가 구성되지 않았으며 바이너리가 임베디드 CA 인증서로 빌드된 경우(기본값, ENABLE_EMBEDDED_CA_CERTIFICATES 빌드 옵션이 제어), 임베디드 인증서를 대신 사용해요. 따라서 파일이 하나도 없는 최소 환경, 예를 들어 "from scratch"로 빌드된 컨테이너에서도 TLS가 작동해요. 임베디드 CA 인증서 없이 빌드된 경우에는 이 상황에서 오류가 발생해요.

openSSL.server.preferServerCiphers

클라이언트 선호 서버 암호화예요.

openSSL.server.privateKeyFile

PEM 인증서의 비밀 키가 있는 파일 경로예요. 파일은 키와 인증서를 동시에 포함할 수 있어요.

openSSL.server.privateKeyPassphraseHandler.name

비밀 키에 접근하기 위한 암호 문구를 요청하는 클래스(PrivateKeyPassphraseHandler 하위 클래스)예요. 예: <<privateKeyPassphraseHandler>>, <<name>KeyFileHandler</name>>, <<options><password>test</password></options>>, <</privateKeyPassphraseHandler>>.

openSSL.server.sessionCacheSize

서버가 캐시하는 세션의 최대 수예요. 값 0은 무제한 세션을 의미해요.

openSSL.server.sessionIdContext

서버가 생성된 각 식별자에 추가하는 고유한 무작위 문자 집합이에요. 문자열 길이는 <SSL_MAX_SSL_SESSION_ID_LENGTH>를 초과해선 안 돼요. 이 파라미터는 서버가 세션을 캐시하든 클라이언트가 캐싱을 요청하든 문제를 피하는 데 도움이 되므로 항상 권장돼요.

openSSL.server.sessionTimeout

서버에서 세션을 캐시하는 시간(시간)이에요.

openSSL.server.verificationDepth

검증 체인의 최대 길이예요. 인증서 체인 길이가 설정 값을 초과하면 검증이 실패해요.

openSSL.server.verificationMode

노드의 인증서를 확인하는 방법이에요. 세부 사항은 Context 클래스 설명에 있어요. 가능한 값: <none>, <relaxed>, <strict>, <once>.

opentelemetry_span_log

opentelemetry_span_log 시스템 테이블의 설정이에요.

다음 설정은 하위 태그로 구성할 수 있어요:

설정	설명	기본값	참고
database	데이터베이스 이름.
table	시스템 테이블 이름.
engine	시스템 테이블의 MergeTree 엔진 정의.		partition_by 또는 order_by가 정의되어 있으면 사용할 수 없어요. 지정하지 않으면 기본으로 MergeTree가 선택돼요
partition_by	시스템 테이블의 사용자 지정 파티셔닝 키.		시스템 테이블에 engine이 지정되어 있으면 partition_by 파라미터를 'engine' 안에 직접 지정해야 해요
ttl	테이블 TTL 지정.		시스템 테이블에 engine이 지정되어 있으면 ttl 파라미터를 'engine' 안에 직접 지정해야 해요
order_by	시스템 테이블의 사용자 지정 정렬 키. engine이 정의되어 있으면 사용할 수 없어요.		시스템 테이블에 engine이 지정되어 있으면 order_by 파라미터를 'engine' 안에 직접 지정해야 해요
storage_policy	테이블에 사용할 스토리지 정책 이름(선택).		시스템 테이블에 engine이 지정되어 있으면 storage_policy 파라미터를 'engine' 안에 직접 지정해야 해요
settings	MergeTree 동작을 제어하는 추가 파라미터(선택).		시스템 테이블에 engine이 지정되어 있으면 settings 파라미터를 'engine' 안에 직접 지정해야 해요
flush_interval_milliseconds	메모리 버퍼에서 테이블로 데이터를 플러시하는 주기.	7500
max_size_rows	로그의 최대 라인 수. 플러시되지 않은 로그가 max_size에 도달하면 로그가 디스크로 덤프돼요.	1048576
reserved_size_rows	로그를 위해 미리 할당하는 메모리 크기(라인 수).	8192
buffer_size_rows_flush_threshold	라인 수 임계값. 이 임계값에 도달하면 로그를 디스크로 플러시하는 작업이 백그라운드에서 시작돼요.	max_size_rows / 2
flush_on_crash	크래시 발생 시 로그를 디스크로 덤프할지 여부.	false

또한 모든 시스템 로그 테이블의 기본 플러시 정책을 제어하는 서버 수준 설정이 있어요:

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>

설정	설명	기본값
skip_alias_columns	true이면 ALIAS 열이 시스템 로그 테이블 스키마에서 제외돼요. S3 기반 시스템 로그에 필요해요.	false

예:

<opentelemetry_span_log>
    <engine>
        engine MergeTree
        partition by toYYYYMM(finish_date)
        order by (finish_date, finish_time_us, trace_id)
    </engine>
    <database>system</database>
    <table>opentelemetry_span_log</table>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    <max_size_rows>1048576</max_size_rows>
    <reserved_size_rows>8192</reserved_size_rows>
    <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
    <flush_on_crash>false</flush_on_crash>
</opentelemetry_span_log>

part_log

MergeTree와 관련된 이벤트를 기록해요. 예를 들어 데이터 추가나 병합이에요. 로그를 사용해 병합 알고리즘을 시뮬레이션하고 특성을 비교할 수 있어요. 병합 과정을 시각화할 수 있어요.

쿼리는 별도의 파일이 아니라 system.part_log 테이블에 기록돼요. table 파라미터에서 이 테이블의 이름을 구성할 수 있어요(아래 참고).

다음 설정은 하위 태그로 구성할 수 있어요:

설정	설명	기본값	참고
database	데이터베이스 이름.
table	시스템 테이블 이름.
engine	시스템 테이블의 MergeTree 엔진 정의.		partition_by 또는 order_by가 정의되어 있으면 사용할 수 없어요. 지정하지 않으면 기본으로 MergeTree가 선택돼요
partition_by	시스템 테이블의 사용자 지정 파티셔닝 키.		시스템 테이블에 engine이 지정되어 있으면 partition_by 파라미터를 'engine' 안에 직접 지정해야 해요
ttl	테이블 TTL 지정.		시스템 테이블에 engine이 지정되어 있으면 ttl 파라미터를 'engine' 안에 직접 지정해야 해요
order_by	시스템 테이블의 사용자 지정 정렬 키. engine이 정의되어 있으면 사용할 수 없어요.		시스템 테이블에 engine이 지정되어 있으면 order_by 파라미터를 'engine' 안에 직접 지정해야 해요
storage_policy	테이블에 사용할 스토리지 정책 이름(선택).		시스템 테이블에 engine이 지정되어 있으면 storage_policy 파라미터를 'engine' 안에 직접 지정해야 해요
settings	MergeTree 동작을 제어하는 추가 파라미터(선택).		시스템 테이블에 engine이 지정되어 있으면 settings 파라미터를 'engine' 안에 직접 지정해야 해요
flush_interval_milliseconds	메모리 버퍼에서 테이블로 데이터를 플러시하는 주기.	7500
max_size_rows	로그의 최대 라인 수. 플러시되지 않은 로그가 max_size에 도달하면 로그가 디스크로 덤프돼요.	1048576
reserved_size_rows	로그를 위해 미리 할당하는 메모리 크기(라인 수).	8192
buffer_size_rows_flush_threshold	라인 수 임계값. 이 임계값에 도달하면 로그를 디스크로 플러시하는 작업이 백그라운드에서 시작돼요.	max_size_rows / 2
flush_on_crash	크래시 발생 시 로그를 디스크로 덤프할지 여부.	false

또한 모든 시스템 로그 테이블의 기본 플러시 정책을 제어하는 서버 수준 설정이 있어요:

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>

설정	설명	기본값
skip_alias_columns	true이면 ALIAS 열이 시스템 로그 테이블 스키마에서 제외돼요. S3 기반 시스템 로그에 필요해요.	false

예시

<part_log>
    <database>system</database>
    <table>part_log</table>
    <partition_by>toMonday(event_date)</partition_by>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    <max_size_rows>1048576</max_size_rows>
    <reserved_size_rows>8192</reserved_size_rows>
    <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
    <flush_on_crash>false</flush_on_crash>
</part_log>

path

데이터를 포함하는 디렉터리의 경로예요.

끝 슬래시(/)가 필수예요.

예시

<path>/var/lib/clickhouse/</path>

per_cpu_untracked_memory_thread_buffer

각 스레드가 공유 per-CPU 예산에 닿지 않고 보유할 수 있는 추적되지 않는(untracked) 메모리 양(바이트)이에요. 작은 할당에 대한 per-CPU 북기록 비용을 분산시키며, 최악의 경우 max_per_cpu_untracked_memory * number_of_cpus 위에 추가되는 여유분이에요. 값 0은 여유분을 제거해요. 그러면 모든 할당이 공유 per-CPU 카운터를 갱신해요(가장 정확하지만 경합이 더 많음). Linux 전용이에요.

point_in_polygon_cache_size

상수 폴리곤 인자와 함께 pointInPolygon 함수가 사용하는 전처리된 폴리곤 캐시의 최대 크기(바이트)예요. 한도 위의 항목은 최근 사용 순(least recently used)으로 축출돼요. 0으로 설정하면 캐시를 비활성화해요. 캐시된 모든 폴리곤이 축출되고 이후 모든 쿼리가 상수 폴리곤을 새로 전처리해요. SYSTEM DROP POINT IN POLYGON CACHE 쿼리로 이 한도를 바꾸지 않고도 캐시를 수동으로 지울 수 있어요.

이 설정은 런타임에 수정할 수 있고 즉시 적용돼요.

prefixes_deserialization_thread_pool_thread_pool_queue_size

prefixes deserialization 스레드 풀에 예약(schedule)할 수 있는 작업의 최대 수예요.

0 값은 무제한을 의미해요.

prepare_system_log_tables_on_startup

true이면 ClickHouse가 시작 전에 구성된 모든 system.*_log 테이블을 만들어요. 일부 시작 스크립트가 이 테이블들에 의존한다면 유용할 수 있어요.

process_query_plan_packet

이 설정은 QueryPlan 패킷을 읽을 수 있게 해줘요. 이 패킷은 serialize_query_plan이 활성화된 분산 쿼리에서 보내져요. 쿼리 계획 바이너리 역직렬화의 버그로 인한 보안 문제를 피하기 위해 기본적으로 비활성화돼요.

예시

<process_query_plan_packet>true</process_query_plan_packet>

processors_profile_log

processors_profile_log 시스템 테이블의 설정이에요.

다음 설정은 하위 태그로 구성할 수 있어요:

설정	설명	기본값	참고
database	데이터베이스 이름.
table	시스템 테이블 이름.
engine	시스템 테이블의 MergeTree 엔진 정의.		partition_by 또는 order_by가 정의되어 있으면 사용할 수 없어요. 지정하지 않으면 기본으로 MergeTree가 선택돼요
partition_by	시스템 테이블의 사용자 지정 파티셔닝 키.		시스템 테이블에 engine이 지정되어 있으면 partition_by 파라미터를 'engine' 안에 직접 지정해야 해요
ttl	테이블 TTL 지정.		시스템 테이블에 engine이 지정되어 있으면 ttl 파라미터를 'engine' 안에 직접 지정해야 해요
order_by	시스템 테이블의 사용자 지정 정렬 키. engine이 정의되어 있으면 사용할 수 없어요.		시스템 테이블에 engine이 지정되어 있으면 order_by 파라미터를 'engine' 안에 직접 지정해야 해요
storage_policy	테이블에 사용할 스토리지 정책 이름(선택).		시스템 테이블에 engine이 지정되어 있으면 storage_policy 파라미터를 'engine' 안에 직접 지정해야 해요
settings	MergeTree 동작을 제어하는 추가 파라미터(선택).		시스템 테이블에 engine이 지정되어 있으면 settings 파라미터를 'engine' 안에 직접 지정해야 해요
flush_interval_milliseconds	메모리 버퍼에서 테이블로 데이터를 플러시하는 주기.	7500
max_size_rows	로그의 최대 라인 수. 플러시되지 않은 로그가 max_size에 도달하면 로그가 디스크로 덤프돼요.	1048576
reserved_size_rows	로그를 위해 미리 할당하는 메모리 크기(라인 수).	8192
buffer_size_rows_flush_threshold	라인 수 임계값. 이 임계값에 도달하면 로그를 디스크로 플러시하는 작업이 백그라운드에서 시작돼요.	max_size_rows / 2
flush_on_crash	크래시 발생 시 로그를 디스크로 덤프할지 여부.	false

또한 모든 시스템 로그 테이블의 기본 플러시 정책을 제어하는 서버 수준 설정이 있어요:

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>

설정	설명	기본값
skip_alias_columns	true이면 ALIAS 열이 시스템 로그 테이블 스키마에서 제외돼요. S3 기반 시스템 로그에 필요해요.	false

기본 설정은 다음과 같아요:

<processors_profile_log>
    <database>system</database>
    <table>processors_profile_log</table>
    <partition_by>toYYYYMM(event_date)</partition_by>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    <max_size_rows>1048576</max_size_rows>
    <reserved_size_rows>8192</reserved_size_rows>
    <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
    <flush_on_crash>false</flush_on_crash>
</processors_profile_log>

prometheus

Prometheus에서 스크래핑하기 위한 메트릭 데이터 노출이에요.

설정:

• endpoint – prometheus 서버가 메트릭을 스크래핑하는 HTTP 엔드포인트. '/'로 시작해요.
• port – endpoint의 포트.
• metrics – system.metrics 테이블의 메트릭을 노출해요.
• events – system.events 테이블의 메트릭을 노출해요.
• asynchronous_metrics – system.asynchronous_metrics 테이블의 현재 메트릭 값을 노출해요. 키-값 메트릭(CPU 코어, 블록 장치, 네트워크 인터페이스, 또는 디스크별로 나뉜 것)은 키를 라벨로 담은 키당 하나의 샘플로 노출돼요: ClickHouseAsyncMetrics_BlockReadBytes{device="sda"}. asynchronous_metrics_key_values_mode 서버 설정은 26.8 이전의 맹글된 이름으로 노출해요(ClickHouseAsyncMetrics_BlockReadBytes_sda), 또는 둘 다 동시에 노출할 수도 있어요.
• errors – 마지막 서버 재시작 이후 오류 코드별 오류 수를 노출해요. 이 정보는 system.errors에서도 얻을 수 있어요.
• labels – 노출되는 모든 메트릭에 추가되는 상수 라벨. 각 하위 요소가 하나의 라벨을 정의해요. 요소 이름은 라벨 이름이며([a-zA-Z_][a-zA-Z0-9_]*와 일치해야 함), 요소 값은 라벨 값이에요. 라벨 값은 from_env 속성 같은 표준 구성 치환을 지원해요. 라벨 이름이 __로 시작하거나(Prometheus가 예약), 이 엔드포인트가 활성 섹션 중 하나에 대해 이미 작성하는 라벨과 충돌하면 거부돼요. 그렇지 않으면 샘플이 같은 라벨 이름을 두 번 담게 되기 때문이에요. 따라서 예약 집합은 엔드포인트의 활성 내보내기 표면을 따릅니다: histograms가 활성화되면 le; info가 활성화되면 ClickHouse_Info 라벨(name, version, version_describe, version_major, version_minor, version_patch); asynchronous_metrics가 활성화되고 asynchronous_metrics_key_values_mode 서버 설정이 결정하는 키-값 형태로 게시될 때 키-값 비동기 메트릭의 키 라벨(channel, cpu, device, disk, interface, mc, sensor); 그리고 histograms/dimensional_metrics가 활성화되면 노출되는 히스토그램이나 차원 메트릭 계열이 사용하는 모든 라벨(예: group, direction, operation_type). 엔드포인트가 실제로 노출하는 것에 의존하므로, 어떤 이름은 한 엔드포인트에서는 유효하고 다른 엔드포인트에서는 거부될 수 있어요. 예를 들어 Keeper keeper_metrics_only 엔드포인트는 keeper_* 계열만 노출하므로 서버 계열만 사용하는 라벨은 그곳에서 허용돼요. 상수 라벨은 구성이 로드될 때( SYSTEM RELOAD CONFIG 포함) 같은 규칙으로 검증돼요. 상수 라벨이 충돌하게 만드는 재로드(그런 라벨을 추가하거나, asynchronous_metrics_key_values_mode를 변경해 키 라벨이 기록되기 시작하는 것)는 효과가 있기 전에 전체가 거부돼요. 같은 라벨 이름을 두 번 노출하는 대신.

예시

<clickhouse>
    <listen_host>0.0.0.0</listen_host>
    <http_port>8123</http_port>
    <tcp_port>9000</tcp_port>
    <prometheus>
        <endpoint>/metrics</endpoint>
        <port>9363</port>
        <metrics>true</metrics>
        <events>true</events>
        <asynchronous_metrics>true</asynchronous_metrics>
        <errors>true</errors>
        <labels>
            <environment>production</environment>
            <shard from_env="SHARD_NAME"></shard>
        </labels>
    </prometheus>
</clickhouse>

확인(127.0.0.1을 ClickHouse 서버의 IP 주소나 호스트네임으로 변경):

curl 127.0.0.1:9363/metrics

prometheus.keeper_metrics_only

keeper 관련 메트릭을 노출해요.

proxy

HTTP와 HTTPS 요청을 위한 프록시 서버를 정의해요. 현재 S3 스토리지, S3 테이블 함수, URL 함수가 지원해요.

프록시 서버를 정의하는 방법은 세 가지가 있어요:

• 환경 변수
• 프록시 목록
• 원격 프록시 리졸버.

특정 호스트에 대한 프록시 서버 우회는 no_proxy로도 지원돼요.

환경 변수

http_proxy와 https_proxy 환경 변수는 주어진 프로토콜에 대한 프록시 서버를 지정할 수 있게 해줘요. 시스템에 설정되어 있으면 매끄럽게 작동해야 해요.

주어진 프로토콜에 프록시 서버가 하나뿐이고 그 프록시 서버가 바뀌지 않는다면 이 방법이 가장 간단해요.

프록시 목록

이 접근 방식은 프로토콜에 대해 하나 이상의 프록시 서버를 지정할 수 있게 해줘요. 둘 이상의 프록시 서버가 정의되면 ClickHouse는 서로 다른 프록시를 라운드로빈 방식으로 사용해 서버 전반에 부하를 분산해요. 프로토콜에 프록시 서버가 여러 개 있고 프록시 서버 목록이 바뀌지 않는다면 이 방법이 가장 간단해요.

구성 템플릿

<proxy>
    <http>
        <uri>http://proxy1</uri>
        <uri>http://proxy2:3128</uri>
    </http>
    <https>
        <uri>http://proxy1:3128</uri>
    </https>
</proxy>

아래 탭에서 상위 필드를 선택해 하위 요소를 확인하세요:

• 와

필드	설명
<http>	하나 이상의 HTTP 프록시 목록
<https>	하나 이상의 HTTPS 프록시 목록

필드	설명
<uri>	프록시의 URI

원격 프록시 리졸버

프록시 서버가 동적으로 바뀔 수 있어요. 그 경우 리졸버의 엔드포인트를 정의할 수 있어요. ClickHouse는 그 엔드포인트에 빈 GET 요청을 보내고, 원격 리졸버가 프록시 호스트를 반환해야 해요. ClickHouse는 그것을 사용해 다음 템플릿으로 프록시 URI를 구성해요: \{proxy_scheme\}://\{proxy_host\}:{proxy_port}.

구성 템플릿

<proxy>
    <http>
        <resolver>
            <endpoint>http://resolver:8080/hostname</endpoint>
            <proxy_scheme>http</proxy_scheme>
            <proxy_port>80</proxy_port>
            <proxy_cache_time>10</proxy_cache_time>
        </resolver>
    </http>

    <https>
        <resolver>
            <endpoint>http://resolver:8080/hostname</endpoint>
            <proxy_scheme>http</proxy_scheme>
            <proxy_port>3128</proxy_port>
            <proxy_cache_time>10</proxy_cache_time>
        </resolver>
    </https>

</proxy>

아래 탭에서 상위 필드를 선택해 하위 요소를 확인하세요:

• 와

필드	설명
<http>	하나 이상의 리졸버 목록*
<https>	하나 이상의 리졸버 목록*

필드	설명
<resolver>	리졸버의 엔드포인트와 기타 세부 사항

여러 <resolver> 요소를 가질 수 있지만, 주어진 프로토콜에 대해 첫 번째 <resolver>만 사용돼요. 그 프로토콜의 다른 <resolver> 요소는 무시돼요. 즉 (필요하다면) 부하 분산은 원격 리졸버가 구현해야 해요.

필드	설명
<endpoint>	프록시 리졸버의 URI
<proxy_scheme>	최종 프록시 URI의 프로토콜. http 또는 https 둘 중 하나일 수 있어요.
<proxy_port>	프록시 리졸버의 포트 번호
<proxy_cache_time>	ClickHouse가 리졸버의 값을 캐시해야 하는 시간(초). 이 값을 0으로 설정하면 ClickHouse가 모든 HTTP 또는 HTTPS 요청마다 리졸버에 연락해요.

우선순위

프록시 설정은 다음 순서로 결정돼요:

순서	설정
1.	원격 프록시 리졸버
2.	프록시 목록
3.	환경 변수

ClickHouse는 요청 프로토콜에 대해 가장 높은 우선순위의 리졸버 유형을 확인해요. 정의되어 있지 않으면 다음 높은 우선순위의 리졸버 유형을 확인해 환경 리졸버에 도달할 때까지 진행해요. 이것은 리졸버 유형의 혼합 사용도 허용해요.

remap_executable

머신 코드("text")를 위해 huge pages를 사용해 메모리를 재할당하는 설정이에요.

이 기능은 매우 실험적이에요.

예시

<remap_executable>false</remap_executable>

replica_group_name

Replicated 데이터베이스의 복제본 그룹 이름이에요.

Replicated 데이터베이스가 만든 클러스터는 같은 그룹의 복제본으로 구성돼요. DDL 쿼리는 같은 그룹의 복제본만 기다려요.

• 기본값: ""

예시

<replica_group_name>backups</replica_group_name>

replicated_merge_tree

ReplicatedMergeTree 테이블의 미세 조정이에요. 이 설정은 더 높은 우선순위를 가져요.

자세한 내용은 MergeTreeSettings.h 헤더 파일을 참고해요.

예시

<replicated_merge_tree>
    <max_suspicious_broken_parts>5</max_suspicious_broken_parts>
</replicated_merge_tree>

restore_threads

RESTORE 요청을 실행할 최대 스레드 수예요.

send_crash_reports

ClickHouse 핵심 개발자 팀에 크래시 리포트를 보내기 위한 설정이에요.

특히 사전 프로덕션 환경에서 활성화해 주시면 매우 감사해요.

키:

키	설명
enabled	기능을 활성화하는 불리언 플래그, 기본 true. 크래시 리포트 전송을 피하려면 false로 설정.
endpoint	크래시 리포트 전송용 엔드포인트 URL을 재정의할 수 있어요.
send_logical_errors	LOGICAL_ERROR는 assert와 같으며 ClickHouse의 버그예요. 이 불리언 플래그는 이 예외 전송을 활성화해요(기본값: true).

권장 사용법

<send_crash_reports>
    <enabled>true</enabled>
</send_crash_reports>

series_keeper_path

generateSerialID 함수가 생성하는 자동 증가 숫자가 있는 Keeper 경로예요. 각 계열(series)은 이 경로 아래의 노드가 돼요.

ssh_server

호스트 키의 공개 부분은 첫 연결 시 SSH 클라이언트 측의 known_hosts 파일에 기록돼요.

호스트 키 구성은 기본적으로 비활성화돼요. 호스트 키 구성을 주석 해제하고 해당 ssh 키의 경로를 제공해 활성화하세요:

예:

<ssh_server>
    <host_rsa_key>path_to_the_ssh_key</host_rsa_key>
    <host_ecdsa_key>path_to_the_ssh_key</host_ecdsa_key>
    <host_ed25519_key>path_to_the_ssh_key</host_ed25519_key>
</ssh_server>

table_engines_require_grant

true로 설정하면 사용자가 특정 엔진으로 테이블을 만들려면 grant가 필요해요. 예: GRANT TABLE ENGINE ON TinyLog to user.

• 기본값: false

기본적으로 하위 호환성을 위해 특정 테이블 엔진으로 테이블을 만드는 것은 grant를 무시하지만, 이 설정을 true로 설정해 동작을 바꿀 수 있어요.

tcp_ssh_port

사용자가 내장 클라이언트를 통해 PTY 위에서 대화형으로 연결해 쿼리를 실행할 수 있게 하는 SSH 서버의 포트예요.

예:

<tcp_ssh_port>9022</tcp_ssh_port>

text_log

텍스트 메시지를 기록하기 위한 text_log 시스템 테이블의 설정이에요.

다음 설정은 하위 태그로 구성할 수 있어요:

설정	설명	기본값	참고
database	데이터베이스 이름.
table	시스템 테이블 이름.
engine	시스템 테이블의 MergeTree 엔진 정의.		partition_by 또는 order_by가 정의되어 있으면 사용할 수 없어요. 지정하지 않으면 기본으로 MergeTree가 선택돼요
partition_by	시스템 테이블의 사용자 지정 파티셔닝 키.		시스템 테이블에 engine이 지정되어 있으면 partition_by 파라미터를 'engine' 안에 직접 지정해야 해요
ttl	테이블 TTL 지정.		시스템 테이블에 engine이 지정되어 있으면 ttl 파라미터를 'engine' 안에 직접 지정해야 해요
order_by	시스템 테이블의 사용자 지정 정렬 키. engine이 정의되어 있으면 사용할 수 없어요.		시스템 테이블에 engine이 지정되어 있으면 order_by 파라미터를 'engine' 안에 직접 지정해야 해요
storage_policy	테이블에 사용할 스토리지 정책 이름(선택).		시스템 테이블에 engine이 지정되어 있으면 storage_policy 파라미터를 'engine' 안에 직접 지정해야 해요
settings	MergeTree 동작을 제어하는 추가 파라미터(선택).		시스템 테이블에 engine이 지정되어 있으면 settings 파라미터를 'engine' 안에 직접 지정해야 해요
flush_interval_milliseconds	메모리 버퍼에서 테이블로 데이터를 플러시하는 주기.	7500
max_size_rows	로그의 최대 라인 수. 플러시되지 않은 로그가 max_size에 도달하면 로그가 디스크로 덤프돼요.	1048576
reserved_size_rows	로그를 위해 미리 할당하는 메모리 크기(라인 수).	8192
buffer_size_rows_flush_threshold	라인 수 임계값. 이 임계값에 도달하면 로그를 디스크로 플러시하는 작업이 백그라운드에서 시작돼요.	max_size_rows / 2
flush_on_crash	크래시 발생 시 로그를 디스크로 덤프할지 여부.	false

또한 모든 시스템 로그 테이블의 기본 플러시 정책을 제어하는 서버 수준 설정이 있어요:

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>

설정	설명	기본값
skip_alias_columns	true이면 ALIAS 열이 시스템 로그 테이블 스키마에서 제외돼요. S3 기반 시스템 로그에 필요해요.	false

추가로:

설정	설명	기본값
level	테이블에 저장될 최대 메시지 레벨(기본값 Trace).	Trace

예시

<clickhouse>
    <text_log>
        <level>notice</level>
        <database>system</database>
        <table>text_log</table>
        <flush_interval_milliseconds>7500</flush_interval_milliseconds>
        <max_size_rows>1048576</max_size_rows>
        <reserved_size_rows>8192</reserved_size_rows>
        <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
        <flush_on_crash>false</flush_on_crash>
        <!-- <partition_by>event_date</partition_by> -->
        <engine>Engine = MergeTree PARTITION BY event_date ORDER BY event_time TTL event_date + INTERVAL 30 day</engine>
    </text_log>
</clickhouse>

thread_pool_queue_size

Global 스레드 풀에 예약(schedule)할 수 있는 작업의 최대 수예요. 큐 크기를 늘리면 더 많은 메모리를 사용해요. 이 값을 max_thread_pool_size와 같게 유지하는 것을 권장해요.

0 값은 무제한을 의미해요.

예시

<thread_pool_queue_size>12000</thread_pool_queue_size>

throw_on_unknown_workload

쿼리 설정 'workload'로 알 수 없는 WORKLOAD에 접근할 때의 동작을 정의해요.

• true이면 알 수 없는 워크로드에 접근하려는 쿼리에서 RESOURCE_ACCESS_DENIED 예외가 발생해요. WORKLOAD 계층이 수립되고 WORKLOAD 기본값을 포함한 후 모든 쿼리에 리소스 스케줄링을 강제하는 데 유용해요.
• false(기본값)이면 'workload' 설정이 알 수 없는 WORKLOAD를 가리키는 쿼리에 리소스 스케줄링 없는 무제한 접근이 제공돼요. WORKLOAD 기본값이 추가되기 전에 WORKLOAD 계층을 설정하는 동안 중요해요.

예시

<throw_on_unknown_workload>true</throw_on_unknown_workload>

참고

• Workload Scheduling

timezone

서버의 시간대예요. UTC 시간대 또는 지리적 위치의 IANA 식별자로 지정돼요(예: Africa/Abidjan).

시간대는 DateTime 필드가 텍스트 형식(화면이나 파일에 출력)으로 출력될 때와 문자열에서 DateTime을 얻을 때 String과 DateTime 형식 간 변환에 필요해요. 또한 입력 파라미터에서 시간대를 받지 않은 시간·날짜 작업 함수에서도 사용돼요.

예시

<timezone>Asia/Istanbul</timezone>

참고

• session_timezone

trace_log

trace_log 시스템 테이블 작업의 설정이에요.

다음 설정은 하위 태그로 구성할 수 있어요:

설정	설명	기본값	참고
database	데이터베이스 이름.
table	시스템 테이블 이름.
engine	시스템 테이블의 MergeTree 엔진 정의.		partition_by 또는 order_by가 정의되어 있으면 사용할 수 없어요. 지정하지 않으면 기본으로 MergeTree가 선택돼요
partition_by	시스템 테이블의 사용자 지정 파티셔닝 키.		시스템 테이블에 engine이 지정되어 있으면 partition_by 파라미터를 'engine' 안에 직접 지정해야 해요
ttl	테이블 TTL 지정.		시스템 테이블에 engine이 지정되어 있으면 ttl 파라미터를 'engine' 안에 직접 지정해야 해요
order_by	시스템 테이블의 사용자 지정 정렬 키. engine이 정의되어 있으면 사용할 수 없어요.		시스템 테이블에 engine이 지정되어 있으면 order_by 파라미터를 'engine' 안에 직접 지정해야 해요
storage_policy	테이블에 사용할 스토리지 정책 이름(선택).		시스템 테이블에 engine이 지정되어 있으면 storage_policy 파라미터를 'engine' 안에 직접 지정해야 해요
settings	MergeTree 동작을 제어하는 추가 파라미터(선택).		시스템 테이블에 engine이 지정되어 있으면 settings 파라미터를 'engine' 안에 직접 지정해야 해요
flush_interval_milliseconds	메모리 버퍼에서 테이블로 데이터를 플러시하는 주기.	7500
max_size_rows	로그의 최대 라인 수. 플러시되지 않은 로그가 max_size에 도달하면 로그가 디스크로 덤프돼요.	1048576
reserved_size_rows	로그를 위해 미리 할당하는 메모리 크기(라인 수).	8192
buffer_size_rows_flush_threshold	라인 수 임계값. 이 임계값에 도달하면 로그를 디스크로 플러시하는 작업이 백그라운드에서 시작돼요.	max_size_rows / 2
flush_on_crash	크래시 발생 시 로그를 디스크로 덤프할지 여부.	false

또한 모든 시스템 로그 테이블의 기본 플러시 정책을 제어하는 서버 수준 설정이 있어요:

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>

설정	설명	기본값
skip_alias_columns	true이면 ALIAS 열이 시스템 로그 테이블 스키마에서 제외돼요. S3 기반 시스템 로그에 필요해요.	false

기본 서버 구성 파일 config.xml에는 다음 설정 섹션이 포함돼요:

<trace_log>
    <database>system</database>
    <table>trace_log</table>
    <partition_by>toYYYYMM(event_date)</partition_by>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    <max_size_rows>1048576</max_size_rows>
    <reserved_size_rows>8192</reserved_size_rows>
    <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
    <flush_on_crash>false</flush_on_crash>
    <symbolize>true</symbolize>
</trace_log>

url_scheme_mappers

축약되거나 상징적인 URL 접두사를 전체 URL로 변환하는 구성이에요.

예:

<url_scheme_mappers>
    <s3>
        <to>https://{bucket}.s3.amazonaws.com</to>
    </s3>
    <gs>
        <to>https://storage.googleapis.com/{bucket}</to>
    </gs>
    <oss>
        <to>https://{bucket}.oss.aliyuncs.com</to>
    </oss>
</url_scheme_mappers>

validate_tcp_client_information

쿼리 패킷을 받을 때 클라이언트 정보 검증이 활성화될지 여부를 결정해요.

기본적으로 false예요:

<validate_tcp_client_information>false</validate_tcp_client_information>

wait_dictionaries_load_at_startup

이 설정은 dictionaries_lazy_load가 false일 때의 동작을 지정할 수 있게 해줘요. (dictionaries_lazy_load가 true이면 이 설정은 아무 영향도 없어요.)

wait_dictionaries_load_at_startup이 false이면 서버는 시작 시 모든 사전 로드를 시작하고, 그 로드와 병행해 연결을 받아요. 쿼리에서 사전이 처음 사용되면, 아직 로드되지 않은 경우 쿼리는 사전이 로드될 때까지 기다려요. wait_dictionaries_load_at_startup을 false로 설정하면 ClickHouse가 더 빨리 시작할 수 있지만, 일부 쿼리는 더 느리게 실행될 수 있어요(일부 사전이 로드되기를 기다려야 하기 때문).

wait_dictionaries_load_at_startup이 true이면 서버는 시작 시 모든 사전이 로드를 마칠 때까지(성공 여부와 관계없이) 기다린 후 어떤 연결도 받아요.

예시

<wait_dictionaries_load_at_startup>true</wait_dictionaries_load_at_startup>

webassembly_udf_engine

WebAssembly UDF를 실행하는 데 사용되는 엔진이에요. 유일하게 지원되는 값은 'wasmtime'이에요.

webterminal_allowed_origins

/webterminal WebSocket 세션을 열 수 있도록 허용된 전체 출처(scheme + host + 선택적 포트)의 쉼표 구분 목록이에요. 비어 있으면 동일 출처 정책이 엄격히 적용돼요(Origin이 요청의 scheme, host, port와 일치해야 함). 브라우저가 https를 사용하는데 request.isSecure()가 false인 TLS 종료 리버스 프록시 뒤의 배포에서 이 값을 설정해요. 예: https://example.com,https://app.example.com:8443.

더 알아보기 (Learn more)