query_* 서버 설정

query_* 서버 설정

이 설정들은 ClickHouse 서버의 쿼리 캐시와 각종 쿼리 로그 테이블(query_log, query_thread_log, query_views_log, query_metric_log), 그리고 쿼리 마스킹 규칙을 구성해요. ClickHouse 소스 코드에서 자동으로 생성된 참조 문서예요.

출처: 문서

본문

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

query_cache

Query cache 구성이에요.

다음 설정을 사용할 수 있어요:

설정 설명 기본값
max_entries 캐시에 저장되는 SELECT 쿼리 결과의 최대 개수. 1024
max_entry_size_in_bytes SELECT 쿼리 결과가 캐시에 저장되기 위해 가질 수 있는 최대 크기(바이트). 1048576
max_entry_size_in_rows SELECT 쿼리 결과가 캐시에 저장되기 위해 가질 수 있는 최대 행(row) 수. 30000000
max_size_in_bytes 캐시의 최대 크기(바이트). 0은 쿼리 캐시가 비활성화되었음을 의미. 1073741824
  • 변경된 설정은 즉시 적용돼요.
  • 쿼리 캐시의 데이터는 DRAM에 할당돼요. 메모리가 부족하면 max_size_in_bytes에 작은 값을 설정하거나 쿼리 캐시를 아예 비활성화하세요.

예시

<query_cache>
    <max_size_in_bytes>1073741824</max_size_in_bytes>
    <max_entries>1024</max_entries>
    <max_entry_size_in_bytes>1048576</max_entry_size_in_bytes>
    <max_entry_size_in_rows>30000000</max_entry_size_in_rows>
</query_cache>

query_log

log_queries=1 설정으로 수신된 쿼리를 기록하기 위한 설정이에요.

쿼리는 별도의 파일이 아니라 system.query_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

enable_user_query_log 파라미터(기본적으로 활성화)는 system.user_query_log를 만들어요. 이 테이블은 구성된 쿼리 로그 테이블의 자신의 레코드를 테이블 자체에 대한 접근 권한 없이 각 사용자에게 보여줘요. 이는 쿼리 로그가 로컬에 저장될 때만 작동해요. engine이 다른 서버에 위임하면(예: Distributed) enable_user_query_log를 비활성화해야 해요. system.user_query_log는 ClickHouse 프로토콜 서버 경계를 넘어 사용자별 접근 검사를 강제할 수 없고 그러한 백엔드에서 읽기를 거부하기 때문이에요.

테이블이 없으면 ClickHouse가 만들어요. ClickHouse 서버가 업데이트되면서 쿼리 로그의 구조가 변경된 경우, 이전 구조의 테이블은 이름이 바뀌고 새 테이블이 자동으로 생성돼요.

예시

<query_log>
    <database>system</database>
    <table>query_log</table>
    <engine>Engine = MergeTree PARTITION BY event_date ORDER BY event_time TTL event_date + INTERVAL 30 day</engine>
    <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>
    <enable_user_query_log>true</enable_user_query_log>
</query_log>

query_masking_rules

정규식 기반 규칙으로, 서버 로그, system.query_log, system.text_log, system.processes 테이블, 그리고 클라이언트로 보내는 로그에 저장되기 전에 쿼리와 모든 로그 메시지에 적용돼요. 이렇게 하면 이름, 이메일, 개인 식별자, 신용카드 번호 같은 민감한 데이터가 SQL 쿼리에서 로그로 유출되는 것을 막아줘요.

예시

<query_masking_rules>
    <rule>
        <name>hide SSN</name>
        <regexp>(^|\D)\d{3}-\d{2}-\d{4}($|\D)</regexp>
        <replace>000-00-0000</replace>
    </rule>
</query_masking_rules>

구성 필드:

설정 설명
name 규칙 이름(선택)
regexp RE2 호환 정규식(필수)
replace 민감한 데이터에 대한 치환 문자열(선택, 기본값 - 별표 6개)

마스킹 규칙은 전체 쿼리에 적용돼요(형식이 잘못되었거나 파싱할 수 없는 쿼리에서도 민감한 데이터 유출을 막기 위해).

system.events 테이블에는 쿼리 마스킹 규칙 매치 총 횟수인 QueryMaskingRulesMatch 카운터가 있어요.

분산 쿼리의 경우 각 서버를 개별적으로 구성해야 해요. 그렇지 않으면 다른 노드로 전달된 서브쿼리가 마스킹 없이 저장돼요.

query_metric_log

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

활성화

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

<clickhouse>
    <query_metric_log>
        <database>system</database>
        <table>query_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>
    </query_metric_log>
</clickhouse>

비활성화

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

<clickhouse>
    <query_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

query_thread_log

log_query_threads=1 설정으로 수신된 쿼리의 스레드를 기록하기 위한 설정이에요.

쿼리는 별도의 파일이 아니라 system.query_thread_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

테이블이 없으면 ClickHouse가 만들어요. ClickHouse 서버가 업데이트되면서 쿼리 스레드 로그의 구조가 변경된 경우, 이전 구조의 테이블은 이름이 바뀌고 새 테이블이 자동으로 생성돼요.

예시

<query_thread_log>
    <database>system</database>
    <table>query_thread_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>
</query_thread_log>

query_views_log

log_query_views=1 설정으로 수신된 쿼리에 의존하는 뷰(live, materialized 등)를 기록하기 위한 설정이에요.

쿼리는 별도의 파일이 아니라 system.query_views_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

테이블이 없으면 ClickHouse가 만들어요. ClickHouse 서버가 업데이트되면서 쿼리 뷰 로그의 구조가 변경된 경우, 이전 구조의 테이블은 이름이 바뀌고 새 테이블이 자동으로 생성돼요.

예시

<query_views_log>
    <database>system</database>
    <table>query_views_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>
</query_views_log>

더 알아보기 (Learn more)