add_http_cors_header
analyze_index_with_space_filling_curves
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 t2와t2 ANY RIGHT JOIN t1작업의 결과는 서로 같지 않습니다. ANY INNER JOIN작업의 결과에는SEMI LEFT JOIN작업과 같이 왼쪽 테이블의 모든 행이 포함됩니다.
- ClickHouse가
ANY RIGHT JOIN작업에서 일대다 키 매핑을 제공하는 로직을 사용하므로t1 ANY LEFT JOIN t2와t2 ANY RIGHT JOIN t1작업의 결과는 동일합니다. ANY INNER JOIN작업의 결과에는 왼쪽 테이블과 오른쪽 테이블의 각 키마다 하나의 행이 포함됩니다.
- 0 — 기존 방식이 비활성화됩니다.
- 1 — 기존 방식이 활성화됩니다.
archive_adaptive_buffer_max_size_bytes
arrow_flight_request_descriptor_type
- ‘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
calculate_text_stack_trace
cancel_http_readonly_queries_on_client_close
1.
checksum_on_read
connection_pool_max_wait_ms
- 양의 정수
- 0 — 무한 timeout
connections_with_failover_max_tries
convert_query_to_cnf
true로 설정하면 SELECT 쿼리가 연언 정규형(CNF)으로 변환됩니다. 쿼리를 CNF로 재작성하면 더 빠르게 실행되는 경우가 있습니다(자세한 설명은 이 GitHub 이슈를 참조하십시오).
예를 들어, 다음 SELECT 쿼리는 수정되지 않습니다(기본 동작):
convert_query_to_cnf를 true로 설정하고 어떻게 달라지는지 살펴보겠습니다:
WHERE 절이 CNF로 재작성되었지만 결과 집합은 동일하고 Boolean 논리는 변경되지 않았습니다:
count_matches_stop_at_empty_match
countMatches 함수에서 패턴이 길이가 0인 문자열과 일치하면 카운트를 중지합니다.
cross_to_inner_join_rewrite
data_type_default_nullable
- 1 — 컬럼 정의의 데이터 타입은 기본적으로
Nullable로 설정됩니다. - 0 — 컬럼 정의의 데이터 타입은 기본적으로
Nullable이 아닌 것으로 설정됩니다.
decimal_check_overflow
deduplicate_blocks_in_dependent_materialized_views
- 0 — 비활성화됨.
- 1 — 활성화됨.
defer_partition_pruning_after_final
FINAL 쿼리에서는 파티션 프루닝을 건너뜁니다. 이는 26.3에서 도입된 정확성 보장 동작입니다. FINAL은 프라이머리 키는 같지만 서로 다른 파티션에 있는 행의 중복을 제거해야 할 수 있는데, 파티션 프루닝을 적용하면 이러한 행이 중복 제거 입력에서 조용히 제외될 수 있습니다.
비활성화되면 FINAL을 사용하더라도 파티션 프루닝이 적용되어 26.3 이전 동작으로 돌아갑니다. 이는 파티션 컬럼에 대한 WHERE 프레디케이트가 있는 쿼리에서 훨씬 더 빠를 수 있지만, 동일한 프라이머리 키를 가진 행이 서로 다른 파티션에 존재할 수 없는 경우에만 올바릅니다. 예를 들어 이벤트 로그 테이블처럼 파티션 컬럼이 삽입 시점에 설정되고 이후에는 변경되지 않는 경우입니다.
이 설정은 파티션 키 컬럼이 sorting key에 포함되지 않은 파티션 테이블에만 영향을 줍니다. 그 외의 테이블에는 파티션 프루닝이 항상 적용됩니다.
가능한 값:
- 0 —
FINAL전에 파티션 프루닝 적용(26.3 이전 동작, 더 빠르지만 일반적으로는 안전하지 않음). - 1 —
FINAL이후로 파티션 프루닝 지연(기본값, 정확성 보장).
describe_compact_output
방언
discard_query_data
distinct_overflow_mode
throw: 예외를 발생시킵니다(기본값).break: 쿼리 실행을 중단하고 부분 결과를 반환합니다. 마치 입력 데이터가 소진된 것처럼 동작합니다.
do_not_merge_across_partitions_select_final
dynamic_throw_on_type_mismatch
true(기본값) — 예외를 발생시킵니다.false— 해당 행에NULL을 반환합니다.
enforce_strict_identifier_format
engine_url_skip_empty_files
- 0 — 빈 파일이 요청된 포맷과 호환되지 않으면
SELECT에서 예외가 발생합니다. - 1 — 빈 파일이면
SELECT가 빈 결과를 반환합니다.
exact_rows_before_limit
rows_before_limit_at_least 통계에 정확한 값을 제공하지만, 그 대신 limit 이전의 데이터를 끝까지 모두 읽어야 합니다
except_default_mode
exclude_materialize_skip_indexes_on_insert
execute_exists_as_scalar_subquery
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
fallback_to_stale_replicas_for_distributed_queries
SELECT를 수행할 때 사용됩니다.
기본값은 1(활성화)입니다.
file_like_engine_default_partition_strategy
filesystem_prefetches_limit
filesystem_prefetches_max_memory_usage를 사용하는 것이 더 권장됩니다.
final
- 0 - 비활성화
- 1 - 활성화
finalize_projection_parts_synchronously
flatten_nested
- 1 — nested 컬럼이 각각의 배열로 평탄화됩니다.
- 0 — nested 컬럼이 튜플의 단일 배열로 유지됩니다.
0으로 지정하면 임의의 수준으로 중첩할 수 있습니다.
예시
쿼리:
fsync_metadata
.sql 파일을 쓸 때 fsync 사용 여부를 설정합니다. 기본적으로 활성화되어 있습니다.
server에 지속적으로 생성되었다가 삭제되는 아주 작은 table이 수백만 개 있다면 비활성화하는 것이 적절할 수 있습니다.
functions_h3_default_if_invalid
geo_distance_returns_float64_on_float64_arguments
geoDistance, greatCircleDistance, greatCircleAngle 함수의 4개 인수가 모두 Float64이면 Float64를 반환하며, 내부 계산에는 배정밀도를 사용합니다. 이전 ClickHouse 버전에서는 이 함수들이 항상 Float32를 반환했습니다.
geotoh3_argument_order
glob_expansion_max_elements
h3togeo_lon_lat_result_order
h3ToGeo는 true일 때 (lon, lat)를 반환하고, 그렇지 않으면 (lat, lon)을 반환합니다.
handshake_timeout_ms
hedged_connection_timeout_ms
highlight_max_matches_per_row
- 양의 정수.
hnsw_candidate_list_size_for_search
hsts_max_age
idle_connection_timeout
- 양의 정수(0 - 0초 후 즉시 종료).
inject_random_order_for_select_without_order_by
interactive_delay
intersect_default_mode
least_greatest_legacy_null_behavior
legacy_column_name_of_tuple_literal
limit
- 0 — 행 수에 제한이 없습니다.
- 양의 정수.
load_marks_asynchronously
1.
lock_acquire_timeout
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
multiple_joins_try_to_keep_original_names
normalize_function_names
offset
- 0 — 건너뛰는 행이 없습니다.
- 양의 정수.
paimon_target_snapshot_id
parallelize_output_from_storages
partial_result_on_first_cancel
per_part_index_stats
poll_interval
polyglot_dialect
postgresql_fault_injection_probability
predicate_statistics_sample_rate
system.predicate_statistics_log에 수집합니다. N > 0으로 설정하면 쿼리 ID를 기준으로 전체 쿼리 중 약 1/N을 샘플링합니다. 0은 비활성화됨을 의미합니다.
prefetch_buffer_size
print_pretty_type_names
DESCRIBE 쿼리와 toTypeName() 함수에서 여러 단계로 중첩된 타입 이름을 들여쓰기로 보기 좋게 출력할 수 있습니다.
예시:
우선순위
push_external_roles_in_interserver_queries
query_metric_log_interval
collect_interval_milliseconds 값을 사용하고, 해당 값이 없으면 기본값 1000을 사용합니다.
단일 쿼리에 대한 수집을 비활성화하려면 query_metric_log_interval을 0으로 설정하세요.
기본값: -1
queue_max_wait_ms
rabbitmq_max_wait_ms
readonly
recursive_cte_max_steps_in_type_inference
getLeastSupertype를 반복적으로 적용하여 결정됩니다. 타입 확장을 비활성화하고 비재귀 부분의 타입만 사용하려면 0으로 설정하세요.
regexp_max_matches_per_row
- 양의 정수.
reject_expensive_hyperscan_regexps
remerge_sort_lowered_memory_bytes_ratio
remote_read_min_bytes_for_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
workload 쿼리 설정값을 사용하여 WORKLOAD 계층 구조를 통해 수행됩니다.
워크로드에 사용 가능한 메모리가 충분하지 않으면 쿼리는 시작되지 않으며, 예약이 충족될 때까지 pending 상태로 대기합니다.
값이 0이면 예약하지 않음을 의미합니다.
이 설정은 MEMORY RESERVATION 리소스가 생성된 경우에만 적용됩니다.
RESTORE 시 테이블 엔진을 ReplicatedMergeTree에서 SharedMergeTree로 대체합니다.
Cloud 기본값: 1.
result_overflow_mode
throw: 예외를 발생시킵니다(기본값).break: 쿼리 실행을 중지하고 부분 결과를 반환합니다. 마치 소스 데이터가 모두 소진된 것처럼 동작합니다.
Break는 실행을
block 수준에서만 중단합니다. 즉, 반환되는 행 수는
max_result_rows보다 많고, max_block_size의 배수이며,
max_threads에 따라 달라집니다.
예시
Query
Result
rows_before_aggregation
secondary_indices_enable_bulk_filtering
select_sequential_consistency
이 설정은 SharedMergeTree와 ReplicatedMergeTree에서 동작 방식이 다릅니다. SharedMergeTree에서
select_sequential_consistency가 어떻게 동작하는지는 SharedMergeTree 일관성을 참조하십시오.SELECT 쿼리의 순차 일관성을 활성화하거나 비활성화합니다. 이 설정을 사용하려면 insert_quorum_parallel이 비활성화되어 있어야 합니다(기본적으로 활성화됨).
가능한 값:
- 0 — 비활성화.
- 1 — 활성화.
insert_quorum으로 실행된 모든 이전 INSERT 쿼리의 데이터를 포함하는 레플리카에서만 클라이언트가 SELECT 쿼리를 실행하도록 허용합니다. 클라이언트가 일부 데이터만 가진 레플리카를 참조하면 ClickHouse는 예외를 발생시킵니다. SELECT 쿼리 결과에는 아직 레플리카 정족수에 기록되지 않은 데이터가 포함되지 않습니다.
insert_quorum_parallel이 활성화되어 있으면(기본값) select_sequential_consistency는 동작하지 않습니다. 병렬 INSERT 쿼리가 서로 다른 레플리카 정족수 집합에 기록될 수 있으므로, 단일 레플리카가 모든 쓰기를 수신했다고 보장할 수 없기 때문입니다.
관련 항목:
session_timezone
timeZone() 및 serverTimeZone()을 사용하여 세션 시간대와 서버 시간대를 확인할 수 있습니다.
가능한 값:
system.time_zones의 모든 시간대 이름(예:Europe/Berlin,UTC,Zulu)
- 첫 번째
SELECT쿼리에서 시간대를 명시하지 않고 사용한toDateTime()은session_timezone설정과 전역 시간대를 따릅니다. - 두 번째 쿼리에서는 String으로부터 DateTime을 파싱하며, 기존 컬럼
d의 유형과 시간대를 상속합니다. 따라서session_timezone설정과 전역 시간대는 반영되지 않습니다.
set_overflow_mode
throw: 예외를 발생시킵니다(기본값).break: 쿼리 실행을 중단하고 부분 결과를 반환합니다. 마치 원본 데이터가 소진된 것처럼 동작합니다.
single_join_prefer_left_table
skip_redundant_aliases_in_udf
- 1 — UDF에서 alias를 건너뛰고(대체하여) 처리합니다.
- 0 — UDF에서 alias를 건너뛰지 않고(대체하지 않고) 처리합니다.
sleep_after_receiving_query_ms
snappy_mode
file 및 url 같은 일반 파일 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
temporary_data_in_cache_reserve_space_wait_lock_timeout_milliseconds
throw_if_no_data_to_insert
clickhouse-client 또는 gRPC 인터페이스를 사용하는 INSERT에만 적용됩니다.
timeout_before_checking_execution_speed
min_execution_speed 이상이어야 함).
transfer_overflow_mode
throw: 예외를 발생시킵니다(기본값).break: 쿼리 실행을 중지하고 부분 결과를 반환합니다. 이는 소스 데이터가 모두 소진된 것처럼 동작합니다.
transform_null_in
NULL 값은 비교할 수 없습니다. NULL은 정의되지 않은 값을 의미하기 때문입니다. 따라서 expr = NULL 비교는 항상 false를 반환해야 합니다. 이 설정을 사용하면 IN 연산자에서 NULL = NULL이 true를 반환합니다.
Possible values:
예시
null_in 테이블을 예로 들어 보겠습니다:
traverse_shadow_remote_data_paths
union_default_mode
SELECT 쿼리 결과를 결합하는 모드를 설정합니다. 이 설정은 UNION ALL 또는 UNION DISTINCT를 명시적으로 지정하지 않고 UNION을 사용할 때만 적용됩니다.
가능한 값:
'DISTINCT'— ClickHouse는 쿼리를 결합한 결과에서 중복 행을 제거하여 출력합니다.'ALL'— ClickHouse는 쿼리를 결합한 결과에서 중복 행을 포함한 모든 행을 출력합니다.''—UNION과 함께 사용하면 ClickHouse에서 예외가 발생합니다.
unique_key_max_encoded_size
UNIQUE KEY 행의 순서를 보존하는 바이너리 인코딩의 최대 크기(바이트)입니다.
unknown_packet_in_send_data
variant_throw_on_type_mismatch
true(기본값) — 예외를 발생시킵니다.false— 해당 행에 대해 대신NULL을 반환합니다.