Skip to main content
다음 설정은 system.settings에서 확인할 수 있으며, 소스를 기반으로 자동 생성됩니다.

add_http_cors_header

HTTP CORS 헤더를 추가합니다.

analyze_index_with_space_filling_curves

테이블 인덱스에 공간 충전 곡선(space-filling curve)이 있고(예: ORDER BY mortonEncode(x, y) 또는 ORDER BY hilbertEncode(x, y)), 쿼리에 해당 인수에 대한 조건이 있는 경우(예: x >= 10 AND x <= 20 AND y >= 20 AND y <= 30), 인덱스 분석에 공간 충전 곡선을 사용합니다.

analyzer_inline_views

활성화하면 분석기가 일반(구체화되지 않고 매개변수화되지 않은) 뷰를 해당 뷰를 정의하는 서브쿼리로 대체하여 프레디케이트 푸시다운 및 컬럼 프루닝과 같은 경계를 넘는 최적화를 수행할 수 있습니다.

any_join_distinct_right_table_keys

ANY INNER|LEFT JOIN 작업에서 기존 ClickHouse 서버 동작을 활성화합니다.
사용 사례가 기존 JOIN 동작에 의존하는 경우에만 이전 버전과의 호환성을 위해 이 설정을 사용하십시오.
기존 방식이 활성화되면:
  • ClickHouse가 왼쪽 테이블에서 오른쪽 테이블로의 다대일 키 매핑 로직을 사용하므로 t1 ANY LEFT JOIN t2t2 ANY RIGHT JOIN t1 작업의 결과는 서로 같지 않습니다.
  • ANY INNER JOIN 작업의 결과에는 SEMI LEFT JOIN 작업과 같이 왼쪽 테이블의 모든 행이 포함됩니다.
기존 방식이 비활성화되면:
  • ClickHouse가 ANY RIGHT JOIN 작업에서 일대다 키 매핑을 제공하는 로직을 사용하므로 t1 ANY LEFT JOIN t2t2 ANY RIGHT JOIN t1 작업의 결과는 동일합니다.
  • ANY INNER JOIN 작업의 결과에는 왼쪽 테이블과 오른쪽 테이블의 각 키마다 하나의 행이 포함됩니다.
가능한 값:
  • 0 — 기존 방식이 비활성화됩니다.
  • 1 — 기존 방식이 활성화됩니다.
관련 항목:

archive_adaptive_buffer_max_size_bytes

아카이브 파일(예: tar 아카이브)에 쓸 때 사용하는 적응형 버퍼의 최대 크기를 제한합니다

arrow_flight_request_descriptor_type

Arrow Flight 요청에 사용할 디스크립터 유형입니다. ‘path’는 데이터셋 이름을 경로 디스크립터로 전송합니다. ‘command’는 SQL 쿼리를 명령 디스크립터로 전송합니다(Dremio에 필요). 가능한 값:
  • ‘path’ — FlightDescriptor::Path를 사용합니다(기본값, 대부분의 Arrow Flight 서버에서 작동)
  • ‘command’ — SELECT 쿼리와 함께 FlightDescriptor::Command를 사용합니다(Dremio에 필요)

backup_slow_all_threads_after_retryable_s3_error

true로 설정하면 ‘Slow Down’과 같은 재시도 가능한 S3 오류가 단일 S3 요청에서 한 번이라도 발생한 후, 동일한 백업 엔드포인트에 S3 요청을 실행하는 모든 스레드의 속도가 느려집니다. false로 설정하면 각 스레드는 다른 스레드와 독립적으로 S3 요청의 백오프를 처리합니다.

cache_warmer_threads

ClickHouse Cloud에서만 적용됩니다. cache_populated_by_fetch가 활성화되면 새 데이터 파트를 파일 시스템 캐시에 사전 다운로드하는 데 사용할 백그라운드 스레드 수입니다. 비활성화하려면 0으로 설정하십시오.

calculate_text_stack_trace

쿼리 실행 중 예외가 발생하면 텍스트 스택 트레이스를 계산합니다. 기본값입니다. 이 기능에는 심볼 조회가 필요하므로, 잘못된 쿼리가 대량으로 실행될 때 퍼징 테스트가 느려질 수 있습니다. 일반적으로는 이 옵션을 비활성화하지 않는 것이 좋습니다.

cancel_http_readonly_queries_on_client_close

클라이언트가 응답을 기다리지 않고 연결을 닫으면 HTTP 읽기 전용 쿼리(예: SELECT)가 취소됩니다. Cloud 기본값: 1.

checksum_on_read

읽을 때 체크섬을 검증합니다. 이 설정은 기본적으로 활성화되어 있으며, 운영 환경에서는 항상 활성화해야 합니다. 이 설정을 비활성화해도 이점을 기대해서는 안 됩니다. 이 설정은 실험이나 벤치마크 용도로만 사용할 수 있습니다. 이 설정은 MergeTree 엔진 계열의 테이블에만 적용됩니다. 다른 테이블 엔진에서는 물론, 네트워크를 통해 데이터를 수신할 때도 항상 체크섬을 검증합니다.

connection_pool_max_wait_ms

연결 풀이 가득 찼을 때 연결을 기다리는 시간을 밀리초 단위로 지정합니다. Possible values:
  • 양의 정수
  • 0 — 무한 timeout

connections_with_failover_max_tries

분산 테이블 엔진에서 각 레플리카에 대해 연결을 시도할 수 있는 최대 횟수입니다.

convert_query_to_cnf

true로 설정하면 SELECT 쿼리가 연언 정규형(CNF)으로 변환됩니다. 쿼리를 CNF로 재작성하면 더 빠르게 실행되는 경우가 있습니다(자세한 설명은 이 GitHub 이슈를 참조하십시오). 예를 들어, 다음 SELECT 쿼리는 수정되지 않습니다(기본 동작):
결과는 다음과 같습니다.
convert_query_to_cnftrue로 설정하고 어떻게 달라지는지 살펴보겠습니다:
WHERE 절이 CNF로 재작성되었지만 결과 집합은 동일하고 Boolean 논리는 변경되지 않았습니다:
가능한 값: true, false

count_matches_stop_at_empty_match

countMatches 함수에서 패턴이 길이가 0인 문자열과 일치하면 카운트를 중지합니다.

cross_to_inner_join_rewrite

WHERE 절에 조인 표현식이 있으면 comma/cross join 대신 INNER JOIN을 사용합니다. 값: 0 - 재작성 안 함, 1 - 가능하면 comma/cross join에 적용, 2 - 모든 comma join을 강제로 재작성, cross - 가능한 경우

data_type_default_nullable

컬럼 정의에서 명시적인 NULL 또는 NOT NULL 수정자가 없는 데이터 타입을 널 허용으로 처리합니다. 가능한 값:
  • 1 — 컬럼 정의의 데이터 타입은 기본적으로 Nullable로 설정됩니다.
  • 0 — 컬럼 정의의 데이터 타입은 기본적으로 Nullable이 아닌 것으로 설정됩니다.

decimal_check_overflow

Decimal 산술/비교 연산에서 오버플로우를 검사합니다

deduplicate_blocks_in_dependent_materialized_views

복제된 테이블에서 데이터를 받는 materialized view에 대해 중복 제거 검사를 사용할지 설정합니다. 가능한 값:
  • 0 — 비활성화됨.
  • 1 — 활성화됨.
활성화하면 ClickHouse는 복제된 테이블에 종속된 materialized view에서 블록 중복 제거를 수행합니다. 이 설정은 실패로 인해 삽입 작업을 재시도할 때 materialized view에 중복 데이터가 포함되지 않도록 하는 데 유용합니다. 관련 항목

defer_partition_pruning_after_final

활성화되면(기본값) 파티션 키 컬럼이 sorting key에 포함되지 않은 테이블의 FINAL 쿼리에서는 파티션 프루닝을 건너뜁니다. 이는 26.3에서 도입된 정확성 보장 동작입니다. FINAL은 프라이머리 키는 같지만 서로 다른 파티션에 있는 행의 중복을 제거해야 할 수 있는데, 파티션 프루닝을 적용하면 이러한 행이 중복 제거 입력에서 조용히 제외될 수 있습니다. 비활성화되면 FINAL을 사용하더라도 파티션 프루닝이 적용되어 26.3 이전 동작으로 돌아갑니다. 이는 파티션 컬럼에 대한 WHERE 프레디케이트가 있는 쿼리에서 훨씬 더 빠를 수 있지만, 동일한 프라이머리 키를 가진 행이 서로 다른 파티션에 존재할 수 없는 경우에만 올바릅니다. 예를 들어 이벤트 로그 테이블처럼 파티션 컬럼이 삽입 시점에 설정되고 이후에는 변경되지 않는 경우입니다. 이 설정은 파티션 키 컬럼이 sorting key에 포함되지 않은 파티션 테이블에만 영향을 줍니다. 그 외의 테이블에는 파티션 프루닝이 항상 적용됩니다. 가능한 값:
  • 0 — FINAL 전에 파티션 프루닝 적용(26.3 이전 동작, 더 빠르지만 일반적으로는 안전하지 않음).
  • 1 — FINAL 이후로 파티션 프루닝 지연(기본값, 정확성 보장).

describe_compact_output

true로 설정하면 DESCRIBE 쿼리 결과에 컬럼명과 타입만 포함됩니다

방언

쿼리를 구문 분석할 때 사용할 방언입니다

discard_query_data

활성화되면 서버는 쿼리 결과 행을 클라이언트에 전송하지 않습니다. 쿼리는 여전히 서버에서 სრულ히 실행되고 로그에 기록되며, 클라이언트는 나머지 패킷을 계속 수신합니다. 섀도 트래픽, 벤치마크, 퍼징에 사용됩니다. 보조 쿼리에는 영향을 주지 않습니다. 네이티브 TCP 프로토콜에만 영향을 줍니다.

distinct_overflow_mode

데이터 양이 제한 중 하나를 초과할 때 어떻게 동작할지 설정합니다. 가능한 값:
  • throw: 예외를 발생시킵니다(기본값).
  • break: 쿼리 실행을 중단하고 부분 결과를 반환합니다. 마치 입력 데이터가 소진된 것처럼 동작합니다.

do_not_merge_across_partitions_select_final

서로 다른 파티션 간 머지를 피하여 FINAL 쿼리 성능을 개선합니다. 활성화하면 SELECT FINAL 쿼리 실행 중 서로 다른 파티션의 파트는 함께 머지되지 않습니다. 대신 각 파티션 내부에서만 별도로 머지됩니다. 따라서 파티션된 테이블을 사용할 때 쿼리 성능을 크게 향상시킬 수 있습니다.

dynamic_throw_on_type_mismatch

기본 구현을 사용해 Dynamic 컬럼에 함수를 적용할 때, 실제 타입이 함수와 호환되지 않는 행을 어떻게 처리할지 제어합니다:
  • true (기본값) — 예외를 발생시킵니다.
  • false — 해당 행에 NULL을 반환합니다.

enforce_strict_identifier_format

활성화하면 영숫자와 밑줄만 포함된 식별자만 허용합니다.

engine_url_skip_empty_files

URL 엔진 테이블에서 빈 파일을 건너뛸지 여부를 설정합니다. 가능한 값:
  • 0 — 빈 파일이 요청된 포맷과 호환되지 않으면 SELECT에서 예외가 발생합니다.
  • 1 — 빈 파일이면 SELECT가 빈 결과를 반환합니다.

exact_rows_before_limit

활성화하면 ClickHouse는 rows_before_limit_at_least 통계에 정확한 값을 제공하지만, 그 대신 limit 이전의 데이터를 끝까지 모두 읽어야 합니다

except_default_mode

EXCEPT 쿼리의 기본 모드를 설정합니다. 가능한 값: 빈 문자열, ‘ALL’, ‘DISTINCT’입니다. 비어 있으면 모드를 지정하지 않은 쿼리에서 예외가 발생합니다.

exclude_materialize_skip_indexes_on_insert

지정한 스킵 인덱스가 INSERT 중에 생성되어 저장되지 않도록 제외합니다. 제외된 스킵 인덱스는 머지 중 또는 명시적인 MATERIALIZE INDEX 쿼리를 통해 계속 생성되어 저장됩니다. materialize_skip_indexes_on_insert가 false이면 효과가 없습니다. 예시:

execute_exists_as_scalar_subquery

상관관계가 없는 EXISTS 서브쿼리를 스칼라 서브쿼리로 실행합니다. 스칼라 서브쿼리와 마찬가지로 캐시가 사용되며, 결과에는 상수 폴딩(constant folding)이 적용됩니다. Cloud 기본값: 0.

explain_query_plan_default

EXPLAIN PLAN에 사용되는 기본 포맷입니다. 가능한 값:
  • pretty (26.7부터 기본값) — actions, compact, pretty의 기본값이 true로 설정되어, 간결하고 가독성이 높으며 actions 정보가 포함된 계획을 생성합니다.
  • legacy — 26.7 이전 출력입니다.
EXPLAIN 문에서 actions, compact, pretty 옵션을 명시적으로 지정하면(예: EXPLAIN actions = 0, compact = 0, pretty = 0 SELECT ...) 항상 이 설정이 재정의됩니다. json = 1 또는 distributed = 1을 사용하는 EXPLAIN PLAN은 이 설정과 관계없이 26.7 이전 기본값(legacy)을 유지합니다. 단, actions, compact, pretty를 명시적으로 설정한 경우는 예외입니다. pretty 출력은 JSON 결과나 세그먼트별 분산 계획을 표현할 수 없으므로, 이러한 모드는 legacy 형식으로만 올바르게 렌더링됩니다.

extract_key_value_pairs_max_pairs_per_row

별칭: extract_kvp_max_pairs_per_row extractKeyValuePairs 함수가 생성할 수 있는 최대 쌍 수입니다. 과도한 메모리 사용을 방지하기 위한 보호 장치로 사용됩니다.

extremes

극값(쿼리 결과 컬럼의 최솟값과 최댓값)을 계산할지 여부입니다. 0 또는 1을 사용할 수 있습니다. 기본값은 0(비활성화)입니다. 자세한 내용은 “극값” 섹션을 참조하십시오.

fallback_to_stale_replicas_for_distributed_queries

업데이트된 데이터를 사용할 수 없을 때 쿼리를 오래된 레플리카로 보내도록 강제합니다. 복제를 참조하십시오. ClickHouse는 테이블의 오래된 레플리카 중에서 가장 적합한 레플리카를 선택합니다. 복제된 테이블(Replicated Table)을 가리키는 분산 테이블(distributed table)에서 SELECT를 수행할 때 사용됩니다. 기본값은 1(활성화)입니다.

file_like_engine_default_partition_strategy

파일 계열 엔진의 기본 파티션 전략입니다.

filesystem_prefetches_limit

프리페치의 최대 개수입니다. 0은 무제한을 의미합니다. 프리페치 개수를 제한하려면 설정 filesystem_prefetches_max_memory_usage를 사용하는 것이 더 권장됩니다.

final

쿼리의 모든 테이블에 FINAL 수정자를 자동으로 적용합니다. 여기에는 조인된 테이블, 하위 쿼리의 테이블, 그리고 FINAL을 적용할 수 있는 분산 테이블도 포함됩니다. 가능한 값:
  • 0 - 비활성화
  • 1 - 활성화
예시:

finalize_projection_parts_synchronously

활성화하면 INSERT 중에 프로젝션 파트가 동기적으로 최종화되어 최대 메모리 사용량이 줄어들지만, 그 대신 S3 업로드 병렬성은 낮아집니다. 기본적으로는 각 프로젝션의 출력 스트림이 전체 파트(모든 프로젝션 포함)가 최종화될 때까지 유지되므로 S3 업로드를 겹쳐서 수행할 수 있지만, 프로젝션 수에 비례해 최대 메모리 사용량이 증가합니다. 이 설정은 INSERT 경로에만 영향을 미치며, 머지와 mutation은 이미 프로젝션을 동기적으로 최종화합니다.

flatten_nested

nested 컬럼의 데이터 포맷을 설정합니다. 가능한 값:
  • 1 — nested 컬럼이 각각의 배열로 평탄화됩니다.
  • 0 — nested 컬럼이 튜플의 단일 배열로 유지됩니다.
사용 이 설정을 0으로 지정하면 임의의 수준으로 중첩할 수 있습니다. 예시 쿼리:
결과:
쿼리:
결과:

fsync_metadata

.sql 파일을 쓸 때 fsync 사용 여부를 설정합니다. 기본적으로 활성화되어 있습니다. server에 지속적으로 생성되었다가 삭제되는 아주 작은 table이 수백만 개 있다면 비활성화하는 것이 적절할 수 있습니다.

functions_h3_default_if_invalid

false인 경우 h3 함수(예: h3CellAreaM2)는 입력이 유효하지 않으면 예외를 발생시킵니다. true인 경우 0 또는 기본값을 반환합니다.

geo_distance_returns_float64_on_float64_arguments

geoDistance, greatCircleDistance, greatCircleAngle 함수의 4개 인수가 모두 Float64이면 Float64를 반환하며, 내부 계산에는 배정밀도를 사용합니다. 이전 ClickHouse 버전에서는 이 함수들이 항상 Float32를 반환했습니다.

geotoh3_argument_order

함수 ‘geoToH3’는 ‘lon_lat’로 설정된 경우 (lon, lat)를, ‘lat_lon’으로 설정된 경우 (lat, lon)을 허용합니다.

glob_expansion_max_elements

허용되는 주소의 최대 개수입니다(외부 스토리지, 테이블 함수 등).

h3togeo_lon_lat_result_order

함수 h3ToGeotrue일 때 (lon, lat)를 반환하고, 그렇지 않으면 (lat, lon)을 반환합니다.

handshake_timeout_ms

핸드셰이크 중 레플리카로부터 Hello packet을 수신할 때까지의 timeout이며, 밀리초 단위입니다.

hedged_connection_timeout_ms

Hedged 요청에서 레플리카에 연결할 때 적용되는 연결 타임아웃

highlight_max_matches_per_row

highlight 함수에서 행당 highlight 일치의 최대 개수를 설정합니다. 큰 텍스트에서 반복이 매우 많은 패턴을 highlight할 때 과도한 메모리 사용을 방지하는 데 사용됩니다. 사용 가능한 값:
  • 양의 정수.
벡터 유사도 인덱스를 검색할 때 사용하는 동적 후보 목록의 크기이며, ‘ef_search’라고도 합니다.

hsts_max_age

HSTS의 만료 시간입니다. 0은 HSTS를 비활성화한다는 뜻입니다.

idle_connection_timeout

지정된 초 수가 지나면 유휴 상태인 TCP 연결을 종료하는 timeout입니다. 가능한 값:
  • 양의 정수(0 - 0초 후 즉시 종료).

inject_random_order_for_select_without_order_by

활성화하면 ORDER BY 절이 없는 SELECT 쿼리에 ‘ORDER BY rand()‘를 삽입합니다. 서브쿼리 깊이 = 0인 경우에만 적용됩니다. 서브쿼리와 INSERT INTO … SELECT에는 영향을 주지 않습니다. 최상위 구문이 UNION이면 각 하위 쿼리에 ‘ORDER BY rand()‘를 개별적으로 삽입합니다. 테스트 및 개발에만 유용합니다(ORDER BY가 없으면 비결정적인 쿼리 결과가 발생할 수 있습니다).

interactive_delay

요청 실행이 취소되었는지 확인하고 Progress를 전송하는 간격을 마이크로초 단위로 지정합니다.

intersect_default_mode

INTERSECT 쿼리의 기본 모드를 설정합니다. 가능한 값: 빈 문자열, ‘ALL’, ‘DISTINCT’입니다. 빈 문자열이면 모드가 없는 쿼리에서 예외가 발생합니다.

least_greatest_legacy_null_behavior

활성화하면 ‘least’ 및 ‘greatest’ 함수는 인수 중 하나가 NULL인 경우 NULL을 반환합니다.

legacy_column_name_of_tuple_literal

해시 대신 큰 튜플 리터럴을 구성하는 모든 요소의 이름을 해당 컬럼명에 나열합니다. 이 설정은 호환성을 위해서만 존재합니다. 클러스터를 21.7 미만 버전에서 그 이상의 버전으로 롤링 업데이트하는 동안에는 ‘true’로 설정하는 것이 좋습니다.

limit

쿼리 결과에서 가져올 최대 행 수를 설정합니다. 이 설정은 LIMIT 절에서 지정한 값을 조정하므로, 쿼리에서 지정한 제한값은 이 설정에서 정한 제한값을 초과할 수 없습니다. 가능한 값:
  • 0 — 행 수에 제한이 없습니다.
  • 양의 정수.

load_marks_asynchronously

MergeTree 마크를 비동기식으로 로드합니다 Cloud 기본값: 1.

lock_acquire_timeout

잠금 요청이 실패하기 전까지 몇 초 동안 대기할지 정의합니다. 잠금 타임아웃은 테이블에 대해 읽기/쓰기 작업을 수행하는 동안 교착 상태를 방지하는 데 사용됩니다. 타임아웃이 만료되어 잠금 요청이 실패하면 ClickHouse 서버는 오류 코드 DEADLOCK_AVOIDED와 함께 “Locking attempt timed out! Possible deadlock avoided. Client should retry.” 예외를 발생시킵니다. 가능한 값:
  • 양의 정수(초 단위)
  • 0 — 잠금 타임아웃 없음

low_priority_query_wait_time_ms

쿼리 우선순위 지정 메커니즘이 사용되면(설정 priority 참조), 낮은 우선순위의 쿼리는 더 높은 우선순위의 쿼리가 완료될 때까지 대기합니다. 이 설정은 그 대기 시간을 지정합니다.

make_distributed_plan

분산 쿼리 계획을 생성합니다.

merge_table_max_tables_to_look_for_schema_inference

명시적인 스키마 없이 Merge 테이블을 생성하거나 merge 테이블 함수를 사용하는 경우, 지정된 개수를 넘지 않는 범위의 일치하는 테이블들을 합집합으로 하여 스키마를 추론합니다. 테이블 수가 이보다 많으면 처음 지정된 개수의 테이블을 기준으로 스키마를 추론합니다.

mongodb_throw_on_unsupported_query

활성화하면 MongoDB 쿼리를 구성할 수 없을 때 MongoDB 테이블에서 오류를 반환합니다. 그렇지 않으면 ClickHouse가 전체 테이블을 읽은 뒤 로컬에서 처리합니다. 이 옵션은 ‘allow_experimental_analyzer=0’일 때는 적용되지 않습니다.

multiple_joins_try_to_keep_original_names

여러 조인을 재작성할 때 최상위 표현식 목록에 alias를 추가하지 않습니다

normalize_function_names

함수 이름을 정규 이름으로 변환합니다

offset

쿼리가 결과 행을 반환하기 시작하기 전에 건너뛸 행 수를 설정합니다. OFFSET 절에서 지정한 offset 값을 조정하므로 두 값은 합산됩니다. 가능한 값:
  • 0 — 건너뛰는 행이 없습니다.
  • 양의 정수.
예시 입력 테이블:
쿼리:
결과:

paimon_target_snapshot_id

Paimon incremental 모드에서 쿼리 수준으로 대상 스냅샷을 읽습니다. 값이 >0이면 리더는 커밋된 워터마크를 앞으로 진행하지 않고 지정된 snapshot_id의 delta만 가져옵니다. 기본값: -1 (비활성화됨)

parallelize_output_from_storages

스토리지에서 읽는 단계의 출력을 병렬화합니다. 가능하면 스토리지에서 읽은 직후부터 쿼리 처리를 병렬로 수행할 수 있습니다.

partial_result_on_first_cancel

취소 후 쿼리가 부분 결과를 반환하도록 허용합니다.

per_part_index_stats

각 part의 로그 인덱스 통계를 기록합니다

poll_interval

서버의 쿼리 대기 루프를 지정한 초 수만큼 차단합니다.

polyglot_dialect

polyglot 트랜스파일러에서 사용할 소스 SQL 방언입니다(예: ‘sqlite’, ‘mysql’, ‘postgresql’, ‘snowflake’, ‘duckdb’).

postgresql_fault_injection_probability

내부 PostgreSQL 쿼리(복제용)가 실패할 대략적인 확률입니다. 유효한 값 범위는 [0.0f, 1.0f]입니다.

predicate_statistics_sample_rate

프레디케이트 선택도 통계를 system.predicate_statistics_log에 수집합니다. N > 0으로 설정하면 쿼리 ID를 기준으로 전체 쿼리 중 약 1/N을 샘플링합니다. 0은 비활성화됨을 의미합니다.

prefetch_buffer_size

파일 시스템에서 읽을 때 사용하는 프리페치 버퍼의 최대 크기입니다. 읽기 버퍼는 이보다 클 필요가 없으므로, 256 MiB를 초과하는 값은 256 MiB로 제한됩니다. DESCRIBE 쿼리와 toTypeName() 함수에서 여러 단계로 중첩된 타입 이름을 들여쓰기로 보기 좋게 출력할 수 있습니다. 예시:

우선순위

쿼리 우선순위입니다. 1이 가장 높으며, 값이 클수록 우선순위는 낮아집니다. 0은 우선순위를 사용하지 않음을 의미합니다.

push_external_roles_in_interserver_queries

쿼리 수행 시 요청을 시작한 노드의 사용자 역할을 다른 노드로 전달할지 설정합니다.

query_metric_log_interval

개별 쿼리에 대해 query_metric_log를 수집하는 밀리초 단위 인터벌입니다. 음수 값으로 설정하면 query_metric_log 설정collect_interval_milliseconds 값을 사용하고, 해당 값이 없으면 기본값 1000을 사용합니다. 단일 쿼리에 대한 수집을 비활성화하려면 query_metric_log_interval을 0으로 설정하세요. 기본값: -1

queue_max_wait_ms

동시 요청 수가 최대값을 초과하면 요청 큐에서 대기하는 시간입니다.

rabbitmq_max_wait_ms

재시도하기 전에 RabbitMQ에서 읽기를 기다리는 시간입니다.

readonly

0 - 읽기 전용 제한이 없습니다. 1 - 읽기 요청과 명시적으로 허용된 설정 변경만 가능합니다. 2 - 읽기 요청과 설정 변경만 가능하며, ‘readonly’ 설정은 변경할 수 없습니다.

recursive_cte_max_steps_in_type_inference

재귀 CTE의 컬럼 타입을 추론할 때 허용되는 최대 반복 횟수입니다. 컬럼 타입은 수렴할 때까지 UNION ALL의 비재귀 부분과 재귀 부분에 getLeastSupertype를 반복적으로 적용하여 결정됩니다. 타입 확장을 비활성화하고 비재귀 부분의 타입만 사용하려면 0으로 설정하세요.

regexp_max_matches_per_row

각 행에서 단일 정규식에 대해 일치할 수 있는 최대 개수를 설정합니다. extractAllGroupsHorizontal 함수에서 탐욕적 정규식을 사용할 때 메모리 과부하를 방지하는 데 사용합니다. Possible values:
  • 양의 정수.

reject_expensive_hyperscan_regexps

Hyperscan으로 평가할 때 NFA 상태 폭발로 인해 비용이 많이 들 가능성이 높은 패턴을 거부합니다.

remerge_sort_lowered_memory_bytes_ratio

remerge 후 메모리 사용량이 이 비율만큼 감소하지 않으면 remerge가 비활성화됩니다.

remote_read_min_bytes_for_seek

원격 읽기(URL, S3)에서 ignore를 사용해 읽는 대신 seek를 수행하기 위해 필요한 최소 바이트 수입니다.

rename_files_after_processing

  • 유형: String
  • 기본값: 빈 문자열
이 설정을 사용하면 file 테이블 함수로 처리한 파일의 이름 변경 패턴을 지정할 수 있습니다. 이 옵션을 설정하면 파일 처리가 성공한 경우에만 file 테이블 함수가 읽은 모든 파일의 이름이 플레이스홀더를 포함한 지정된 패턴에 따라 변경됩니다.

플레이스홀더

  • %a — 전체 원본 파일 이름(예: “sample.csv”)
  • %f — 확장자를 제외한 원본 파일 이름(예: “sample”)
  • %e — 점을 포함한 원본 파일 확장자(예: “.csv”)
  • %t — 타임스탬프(마이크로초 단위)
  • %% — 퍼센트 기호(”%“)

예시

  • 옵션: --rename_files_after_processing="processed_%f_%t%e"
  • 쿼리: SELECT * FROM file('sample.csv')
sample.csv를 성공적으로 읽으면 파일 이름이 processed_sample_1683473210851438.csv로 변경됩니다

replication_wait_for_inactive_replica_timeout

비활성 레플리카가 ALTER, OPTIMIZE 또는 TRUNCATE 쿼리를 실행할 때까지 대기할 시간(초)을 지정합니다. 가능한 값:
  • 0 — 대기하지 않습니다.
  • 음의 정수 — 무제한으로 대기합니다.
  • 양의 정수 — 대기할 초 수입니다.

reserve_memory

워크로드 스케줄링에 사용됩니다. 단일 서버에서 쿼리 실행에 사용할 수 있도록 예약되는 최소 RAM 용량입니다. 예약은 workload 쿼리 설정값을 사용하여 WORKLOAD 계층 구조를 통해 수행됩니다. 워크로드에 사용 가능한 메모리가 충분하지 않으면 쿼리는 시작되지 않으며, 예약이 충족될 때까지 pending 상태로 대기합니다. 값이 0이면 예약하지 않음을 의미합니다. 이 설정은 MEMORY RESERVATION 리소스가 생성된 경우에만 적용됩니다.

restore_replicated_merge_tree_to_shared_merge_tree

RESTORE 시 테이블 엔진을 ReplicatedMergeTree에서 SharedMergeTree로 대체합니다. Cloud 기본값: 1.

result_overflow_mode

결과 크기가 제한 중 하나를 초과할 경우 어떻게 처리할지 설정합니다. 가능한 값:
  • throw: 예외를 발생시킵니다(기본값).
  • break: 쿼리 실행을 중지하고 부분 결과를 반환합니다. 마치 소스 데이터가 모두 소진된 것처럼 동작합니다.
‘break’를 사용하는 것은 LIMIT를 사용하는 것과 유사합니다. Break는 실행을 block 수준에서만 중단합니다. 즉, 반환되는 행 수는 max_result_rows보다 많고, max_block_size의 배수이며, max_threads에 따라 달라집니다. 예시
Query
Result

rows_before_aggregation

활성화되면 ClickHouse는 rows_before_aggregation 통계의 정확한 값을 제공하며, 이는 집계 전에 읽은 행 수를 나타냅니

secondary_indices_enable_bulk_filtering

인덱스에 대한 일괄 필터링 알고리즘을 활성화합니다. 일반적으로 항상 더 나은 성능을 제공할 것으로 예상되지만, 호환성 및 제어를 위해 이 설정을 제공합니다.

select_sequential_consistency

이 설정은 SharedMergeTree와 ReplicatedMergeTree에서 동작 방식이 다릅니다. SharedMergeTree에서 select_sequential_consistency가 어떻게 동작하는지는 SharedMergeTree 일관성을 참조하십시오.
SELECT 쿼리의 순차 일관성을 활성화하거나 비활성화합니다. 이 설정을 사용하려면 insert_quorum_parallel이 비활성화되어 있어야 합니다(기본적으로 활성화됨). 가능한 값:
  • 0 — 비활성화.
  • 1 — 활성화.
사용 순차 일관성이 활성화되면 ClickHouse는 insert_quorum으로 실행된 모든 이전 INSERT 쿼리의 데이터를 포함하는 레플리카에서만 클라이언트가 SELECT 쿼리를 실행하도록 허용합니다. 클라이언트가 일부 데이터만 가진 레플리카를 참조하면 ClickHouse는 예외를 발생시킵니다. SELECT 쿼리 결과에는 아직 레플리카 정족수에 기록되지 않은 데이터가 포함되지 않습니다. insert_quorum_parallel이 활성화되어 있으면(기본값) select_sequential_consistency는 동작하지 않습니다. 병렬 INSERT 쿼리가 서로 다른 레플리카 정족수 집합에 기록될 수 있으므로, 단일 레플리카가 모든 쓰기를 수신했다고 보장할 수 없기 때문입니다. 관련 항목:

session_timezone

현재 세션 또는 쿼리의 암시적 시간대를 설정합니다. 암시적 시간대는 명시적으로 시간대가 지정되지 않은 DateTime/DateTime64 유형의 값에 적용되는 시간대입니다. 이 설정은 전역으로 구성된(서버 수준) 암시적 시간대보다 우선합니다. 값이 ” (빈 문자열)이면 현재 세션 또는 쿼리의 암시적 시간대는 서버 시간대와 같습니다. 함수 timeZone()serverTimeZone()을 사용하여 세션 시간대와 서버 시간대를 확인할 수 있습니다. 가능한 값:
  • system.time_zones의 모든 시간대 이름(예: Europe/Berlin, UTC, Zulu)
예시:
명시적으로 시간대를 지정하지 않은 내부 DateTime에 session 시간대 ‘America/Denver’를 할당합니다:
DateTime/DateTime64를 파싱하는 함수가 모두 session_timezone을 따르는 것은 아닙니다. 이로 인해 미묘한 오류가 발생할 수 있습니다. 다음 예시와 설명을 참조하십시오.
이 현상은 파싱 파이프라인이 서로 다르기 때문에 발생합니다:
  • 첫 번째 SELECT 쿼리에서 시간대를 명시하지 않고 사용한 toDateTime()session_timezone 설정과 전역 시간대를 따릅니다.
  • 두 번째 쿼리에서는 String으로부터 DateTime을 파싱하며, 기존 컬럼 d의 유형과 시간대를 상속합니다. 따라서 session_timezone 설정과 전역 시간대는 반영되지 않습니다.
관련 항목

set_overflow_mode

데이터 양이 제한값 중 하나를 초과할 때 어떻게 동작할지 설정합니다. 가능한 값:
  • throw: 예외를 발생시킵니다(기본값).
  • break: 쿼리 실행을 중단하고 부분 결과를 반환합니다. 마치 원본 데이터가 소진된 것처럼 동작합니다.

single_join_prefer_left_table

단일 JOIN에서 식별자가 모호한 경우 왼쪽 테이블을 우선합니다

skip_redundant_aliases_in_udf

사용자 정의 함수의 사용을 단순화하기 위해 중복 alias는 사용되지 않고(대체되어) 처리됩니다. 가능한 값:
  • 1 — UDF에서 alias를 건너뛰고(대체하여) 처리합니다.
  • 0 — UDF에서 alias를 건너뛰지 않고(대체하지 않고) 처리합니다.
예시 활성화 여부에 따른 차이: 쿼리:
결과:
쿼리:
결과:

sleep_after_receiving_query_ms

TCPHandler에서 쿼리를 수신한 후 대기하는 시간입니다.

snappy_mode

fileurl 같은 일반 파일 I/O 경로에서 snappy 압축에 사용할 wire 형식을 제어합니다. HTTP Content-Encoding: snappy는 항상 framing 포맷을 사용하며, 이 설정은 무시됩니다. 단일 snappy::Compress 호출로 생성되는 raw snappy 블록 포맷(예: SnappyBasicReadBuffer가 처리하는 Prometheus remote protocol payloads)은 별도의 프로토콜별 wire 형식이며, 이 설정으로 제어되지 않습니다. 가능한 값:
  • basic — Hadoop snappy 블록 포맷입니다. Hadoop에서 읽고 쓰는 파일과 호환됩니다. 읽기와 쓰기를 모두 지원합니다.
  • framed — Google에서 정의한 표준 streaming 포맷인 Snappy framing 포맷입니다. 읽기와 쓰기를 모두 지원합니다.

sort_overflow_mode

정렬 전에 수신된 행 수가 제한값 중 하나를 초과하면 어떻게 동작할지 설정합니다. 가능한 값:
  • throw: 예외를 발생시킵니다.
  • break: 쿼리 실행을 중단하고 부분 결과를 반환합니다.

splitby_max_substrings_includes_remaining_string

인수 max_substrings > 0이 지정된 splitBy*() 함수가 결과 배열의 마지막 요소에 남은 문자열을 포함할지 여부를 제어합니다. 가능한 값:
  • 0 - 남은 문자열은 결과 배열의 마지막 요소에 포함되지 않습니다.
  • 1 - 남은 문자열이 결과 배열의 마지막 요소에 포함됩니다. 이는 Spark의 split() 함수와 Python의 ‘string.split()’ 메서드의 동작과 같습니다.

stop_refreshable_materialized_views_on_startup

서버 시작 시 SYSTEM STOP VIEWS를 사용한 것처럼 갱신 가능 구체화 뷰가 스케줄되지 않도록 합니다. 이후 SYSTEM START VIEWS 또는 SYSTEM START VIEW <name>를 사용해 수동으로 시작할 수 있습니다. 새로 생성되는 뷰에도 적용됩니다. 갱신 가능하지 않은 materialized view에는 영향을 주지 않습니다.

tcp_keep_alive_timeout

TCP가 keepalive probe 전송을 시작하기 전에 연결이 유휴 상태로 유지되어야 하는 시간(초)입니다

temporary_data_in_cache_reserve_space_wait_lock_timeout_milliseconds

파일 시스템 캐시의 임시 데이터에 대한 공간 예약 시 캐시 잠금을 기다리는 시간

throw_if_no_data_to_insert

빈 INSERT를 허용하거나 금지합니다. 기본적으로 활성화되어 있으며, 빈 삽입이 발생하면 오류를 반환합니다. clickhouse-client 또는 gRPC 인터페이스를 사용하는 INSERT에만 적용됩니다.

timeout_before_checking_execution_speed

지정된 시간(초)이 지난 후 실행 속도가 너무 느린지 여부를 확인합니다(min_execution_speed 이상이어야 함).

transfer_overflow_mode

데이터 양이 제한값 중 하나를 초과할 때 어떻게 동작할지 설정합니다. 가능한 값:
  • throw: 예외를 발생시킵니다(기본값).
  • break: 쿼리 실행을 중지하고 부분 결과를 반환합니다. 이는 소스 데이터가 모두 소진된 것처럼 동작합니다.

transform_null_in

IN 연산자에서 NULL 값의 동등성 비교를 활성화합니다. 기본적으로 NULL 값은 비교할 수 없습니다. NULL은 정의되지 않은 값을 의미하기 때문입니다. 따라서 expr = NULL 비교는 항상 false를 반환해야 합니다. 이 설정을 사용하면 IN 연산자에서 NULL = NULLtrue를 반환합니다. Possible values:
  • 0 — IN 연산자에서 NULL 값 비교는 false를 반환합니다.
  • 1 — IN 연산자에서 NULL 값 비교는 true를 반환합니다.
예시 null_in 테이블을 예로 들어 보겠습니다:
쿼리:
결과:
쿼리:
결과:
관련 항목

traverse_shadow_remote_data_paths

system.remote_data_paths를 쿼리할 때 실제 테이블 데이터뿐 아니라 동결된 데이터(섀도 디렉터리)도 순회합니다.

union_default_mode

SELECT 쿼리 결과를 결합하는 모드를 설정합니다. 이 설정은 UNION ALL 또는 UNION DISTINCT를 명시적으로 지정하지 않고 UNION을 사용할 때만 적용됩니다. 가능한 값:
  • 'DISTINCT' — ClickHouse는 쿼리를 결합한 결과에서 중복 행을 제거하여 출력합니다.
  • 'ALL' — ClickHouse는 쿼리를 결합한 결과에서 중복 행을 포함한 모든 행을 출력합니다.
  • ''UNION과 함께 사용하면 ClickHouse에서 예외가 발생합니다.
예시는 UNION에서 확인하십시오.

unique_key_max_encoded_size

단일 UNIQUE KEY 행의 순서를 보존하는 바이너리 인코딩의 최대 크기(바이트)입니다.

unknown_packet_in_send_data

N번째 데이터 패킷에서 데이터를 보내는 대신 알 수 없는 패킷을 전송합니다

variant_throw_on_type_mismatch

기본 구현을 사용해 Variant 컬럼에 함수를 적용할 때, 실제 타입이 함수와 호환되지 않는 행을 어떻게 처리할지 제어합니다:
  • true (기본값) — 예외를 발생시킵니다.
  • false — 해당 행에 대해 대신 NULL을 반환합니다.

wait_changes_become_visible_after_commit_mode

커밋된 변경 사항이 최신 스냅샷에 실제로 반영될 때까지 기다립니다

워크로드

리소스 접근에 사용할 워크로드의 이름

write_full_path_in_iceberg_metadata

Iceberg 메타데이터 파일에 전체 경로(s3:// 포함)를 기록합니다.

zstd_window_log_max

ZSTD의 최대 윈도우 로그를 지정합니다(MergeTree 엔진 계열에는 사용되지 않습니다).
마지막 수정일 2026년 7월 24일