세션 설정

system.settings 테이블에서 확인할 수 있는 설정입니다.

아래 설정은 모두 테이블(table) system.settings에서도 확인할 수 있습니다. 이 설정들은 source에서 자동으로 생성됩니다.

​

add_http_cors_header

HTTP CORS 헤더를 추가합니다.

​

additional_result_filter

SELECT 쿼리 결과에 적용하는 추가 필터 표현식입니다. 이 설정은 어떤 하위 쿼리에도 적용되지 않습니다.

예시

INSERT INTO table_1 VALUES (1, 'a'), (2, 'bb'), (3, 'ccc'), (4, 'dddd');
SElECT * FROM table_1;

┌─x─┬─y────┐
│ 1 │ a    │
│ 2 │ bb   │
│ 3 │ ccc  │
│ 4 │ dddd │
└───┴──────┘

SELECT *
FROM table_1
SETTINGS additional_result_filter = 'x != 2'

┌─x─┬─y────┐
│ 1 │ a    │
│ 3 │ ccc  │
│ 4 │ dddd │
└───┴──────┘

​

additional_table_filters

지정된 테이블에서 읽어온 후 적용되는 추가 필터 표현식입니다.

예시

INSERT INTO table_1 VALUES (1, 'a'), (2, 'bb'), (3, 'ccc'), (4, 'dddd');
SELECT * FROM table_1;

┌─x─┬─y────┐
│ 1 │ a    │
│ 2 │ bb   │
│ 3 │ ccc  │
│ 4 │ dddd │
└───┴──────┘

SELECT *
FROM table_1
SETTINGS additional_table_filters = {'table_1': 'x != 2'}

┌─x─┬─y────┐
│ 1 │ a    │
│ 3 │ ccc  │
│ 4 │ dddd │
└───┴──────┘

​

aggregate_function_input_format

INSERT 작업 중 AggregateFunction 입력에 사용할 포맷입니다.

가능한 값:

• state — 직렬화된 상태를 담은 바이너리 문자열입니다(기본값). AggregateFunction 값이 바이너리 데이터로 제공된다고 간주하는 기본 동작입니다.
• value — 집계 함수 인수의 단일 값 또는 인수가 여러 개인 경우 그 값들의 튜플을 받는 포맷입니다. 해당 값들은 대응하는 IDataType 또는 DataTypeTuple을 사용해 역직렬화된 후 집계되어 상태를 형성합니다.
• array — 위 value 옵션에서 설명한 값들의 배열을 받는 포맷입니다. 배열의 모든 요소가 집계되어 상태를 형성합니다.

예시

다음 구조를 가진 테이블의 경우:

CREATE TABLE example (
    user_id UInt64,
    avg_session_length AggregateFunction(avg, UInt32)
);

aggregate_function_input_format = 'value'로 설정한 경우:

INSERT INTO example FORMAT CSV
123,456

aggregate_function_input_format = 'array' 설정 시:

INSERT INTO example FORMAT CSV
123,"[456,789,101]"

참고: value 및 array 포맷은 삽입 시 값을 생성하고 집계해야 하므로 기본 state 포맷보다 느립니다.

​

aggregate_functions_null_for_empty

쿼리 내 모든 집계 함수를 재작성하여 -OrNull 접미사를 추가하는 기능을 활성화하거나 비활성화합니다. SQL 표준 호환성을 위해 활성화하십시오. 분산 쿼리에서 일관된 결과를 얻기 위해 쿼리 재작성(count_distinct_implementation 설정과 유사) 방식으로 구현됩니다.

가능한 값:

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

예시

집계 함수가 포함된 다음 쿼리를 살펴보십시오:

SELECT SUM(-1), MAX(0) FROM system.one WHERE 0;

aggregate_functions_null_for_empty = 0이면 다음과 같이 출력됩니다:

┌─SUM(-1)─┬─MAX(0)─┐
│       0 │      0 │
└─────────┴────────┘

aggregate_functions_null_for_empty = 1로 설정하면 결과는 다음과 같습니다:

┌─SUMOrNull(-1)─┬─MAXOrNull(0)─┐
│          NULL │         NULL │
└───────────────┴──────────────┘

​

aggregation_in_order_max_block_bytes

프라이머리 키 순서대로 집계하는 동안 누적되는 블록의 최대 크기(바이트)입니다. 블록 크기가 작을수록 집계의 최종 머지 단계를 더 잘 병렬화할 수 있습니다.

​

aggregation_memory_efficient_merge_threads

메모리 효율 모드에서 중간 집계 결과를 머지하는 데 사용할 스레드 수입니다. 값이 클수록 메모리 사용량이 늘어납니다. 0은 ‘max_threads’와 동일합니다.

​

ai_function_max_api_calls_per_query

AI 함수가 쿼리당 보낼 수 있는 최대 HTTP 요청 수입니다. 비활성화하려면 0으로 설정하십시오.

​

ai_function_max_input_tokens_per_query

단일 쿼리에서 수행되는 모든 AI 함수 API 호출에 대해 허용되는 최대 총 입력(prompt) 토큰 수입니다. provider의 응답을 기준으로 누적 추적됩니다. 각 호출의 입력 토큰 수는 사전에 알 수 없으므로, 이 제한은 한 번의 호출에 해당하는 입력 토큰 수만큼 초과될 수 있습니다. 비활성화하려면 0으로 설정하십시오.

​

ai_function_max_output_tokens_per_query

단일 쿼리에서 수행되는 모든 AI 함수 API 호출의 총 출력(생성) 토큰 수의 최댓값입니다. provider의 응답을 기준으로 누적 추적됩니다. 호출의 출력 토큰 수는 사전에 알 수 없으므로 이 제한은 한 번의 호출에서 생성된 출력 토큰 수만큼 초과될 수 있습니다. 비활성화하려면 0으로 설정하십시오.

​

ai_function_max_retries

개별 API 요청에서 일시적인 오류가 발생했을 때 재시도할 수 있는 최대 횟수입니다. 각 재시도에는 ai_function_retry_initial_delay_ms를 시작값으로 하는 지수 백오프가 적용됩니다.

​

ai_function_request_timeout_sec

AI 함수가 수행하는 개별 HTTP 요청(AI chat completions 및 embedding API 호출)의 제한 시간(초)입니다. 요청이 이 시간 안에 완료되지 않으면 실패로 간주되며 ai_function_max_retries 설정에 따라 재시도될 수 있습니다.

​

ai_function_retry_initial_delay_ms

실패한 AI 함수 API 요청을 처음 재시도하기 전의 초기 지연 시간(밀리초)입니다. 이후 재시도할 때마다 지연 시간은 2배로 증가합니다(지수 백오프). 예를 들어, 기본 설정에서는 1000ms, 2000ms, 4000ms입니다.

​

ai_function_throw_on_error

true(기본값)인 경우, 모든 재시도를 소진한 후에도 AI 함수 호출이 영구적으로 실패하면 예외를 발생시키고 쿼리를 중단합니다. false인 경우, 실패한 행에는 컬럼 유형의 기본값(String의 경우 빈 문자열)이 적용되며 처리는 계속됩니다.

​

ai_function_throw_on_quota_exceeded

true(기본값)인 경우 AI 함수 할당량 한도(ai_function_max_input_tokens_per_query, ai_function_max_output_tokens_per_query 또는 ai_function_max_api_calls_per_query)를 초과하면 예외가 발생하며 쿼리가 중단됩니다. false인 경우 남은 행에는 컬럼 유형의 기본값이 적용됩니다(String의 경우 빈 문자열).

​

allow_aggregate_partitions_independently

파티션 키가 GROUP BY 키와 잘 맞는 경우, 별도의 스레드에서 파티션을 독립적으로 집계할 수 있도록 합니다. 파티션 수가 코어 수에 가깝고 각 파티션 크기가 대체로 비슷할 때 유용합니다.

​

allow_archive_path_syntax

File/S3 엔진/테이블 함수는 아카이브의 확장자가 올바르면 ’::‘가 포함된 경로를 <archive> :: <file>로 해석합니다.

​

allow_asynchronous_read_from_io_pool_for_merge_tree

MergeTree 테이블을 읽을 때 백그라운드 I/O 풀을 사용합니다. 이 설정은 I/O 제약이 있는 쿼리의 성능을 향상시킬 수 있습니다.

​

allow_calculating_subcolumns_sizes_for_merge_tree_reading

활성화되면 ClickHouse는 작업 및 블록 크기를 더 정확하게 계산할 수 있도록 각 서브컬럼을 읽는 데 필요한 파일 크기를 계산합니다.

​

allow_changing_replica_until_first_data_packet

활성화하면 헤지드 요청에서 이미 일부 진행이 있었더라도 첫 번째 데이터 패킷을 받을 때까지 새 연결을 시작할 수 있습니다 (단, receive_data_timeout 시간 초과 동안 Progress가 갱신되지 않은 경우). 비활성화하면 처음으로 진행이 발생한 이후에는 레플리카 변경을 허용하지 않습니다.

​

allow_create_index_without_type

TYPE 없이 CREATE INDEX 쿼리를 허용합니다. 해당 쿼리는 무시됩니다. SQL 호환성 테스트용입니다.

​

allow_custom_error_code_in_throwif

throwIf() 함수에서 사용자 지정 오류 코드를 사용할 수 있게 합니다. true이면 발생하는 예외에 예상치 못한 오류 코드가 사용될 수 있습니다.

​

allow_ddl

true로 설정된 경우 사용자가 DDL 쿼리를 실행할 수 있습니다.

​

allow_deprecated_database_ordinary

더 이상 권장되지 않는 Ordinary engine을 사용해 데이터베이스를 생성할 수 있도록 허용합니다

​

allow_deprecated_error_prone_window_functions

지원 중단 예정이며 오류가 발생하기 쉬운 윈도우 함수(neighbor, runningAccumulate, runningDifferenceStartingWithFirstValue, runningDifference)의 사용을 허용합니다

​

allow_deprecated_snowflake_conversion_functions

함수 snowflakeToDateTime, snowflakeToDateTime64, dateTimeToSnowflake, dateTime64ToSnowflake는 더 이상 권장되지 않으며 기본적으로 비활성화되어 있습니다. 대신 snowflakeIDToDateTime, snowflakeIDToDateTime64, dateTimeToSnowflakeID, dateTime64ToSnowflakeID 함수를 사용하십시오.

더 이상 권장되지 않는 함수를 다시 활성화하려면(예: 전환 기간 중) 이 설정을 true로 지정하십시오.

​

allow_deprecated_syntax_for_merge_tree

더 이상 권장되지 않는 엔진 정의 구문을 사용해 *MergeTree 테이블을 생성하도록 허용합니다

​

allow_distributed_ddl

true로 설정되면 사용자가 분산 DDL 쿼리를 실행할 수 있습니다.

​

allow_drop_detached

ALTER TABLE … DROP DETACHED PART[ITION] … 쿼리의 사용을 허용합니다

​

allow_dynamic_type_in_join_keys

JOIN 키에서 Dynamic 타입 사용을 허용합니다. 호환성을 위해 추가되었습니다. 다른 타입과 비교할 때 예상치 못한 결과가 발생할 수 있으므로 JOIN 키에서 Dynamic 타입을 사용하는 것은 권장되지 않습니다.

​

allow_execute_multiif_columnar

multiIf 함수를 열 지향 방식으로 실행하도록 허용합니다

​

allow_experimental_ai_functions

실험용 AI 함수(예: aiGenerateContent)를 활성화합니다. 이러한 함수는 AI 프로바이더에 외부 HTTP 요청을 보냅니다.

​

allow_experimental_analyzer

별칭: enable_analyzer

새 쿼리 분석기의 사용을 허용합니다.

​

allow_experimental_cleanup_old_data_files_compaction

Iceberg compaction 중 오래된 data files를 정리하도록 허용합니다.

​

allow_experimental_codecs

true로 설정하면 실험적인 압축 코덱을 지정할 수 있습니다(다만 아직 해당 코덱은 없으므로 이 옵션은 아무런 동작도 하지 않습니다).

​

allow_experimental_correlated_subqueries

상관 서브쿼리 실행을 허용합니다.

​

allow_experimental_database_glue_catalog

별칭: allow_database_glue_catalog

catalog_type = ‘glue’로 설정된 실험적 데이터베이스 엔진 DataLakeCatalog를 허용합니다

Cloud 기본값: 1.

​

allow_experimental_database_hms_catalog

catalog_type = ‘hms’인 실험적 데이터베이스 엔진 DataLakeCatalog 사용을 허용합니다

​

allow_experimental_database_iceberg

별칭: allow_database_iceberg

catalog_type = 'iceberg'인 실험적 데이터베이스 엔진 DataLakeCatalog의 사용을 허용합니다.

Cloud 기본값: 1.

​

allow_experimental_database_materialized_postgresql

Engine=MaterializedPostgreSQL(…)를 사용하는 데이터베이스 생성을 허용합니다.

​

allow_experimental_database_paimon_rest_catalog

catalog_type이 ‘paimon_rest’인 실험적 데이터베이스 엔진 DataLakeCatalog를 허용합니다

​

allow_experimental_database_unity_catalog

별칭: allow_database_unity_catalog

catalog_type가 ‘unity’인 실험적 데이터베이스 엔진 DataLakeCatalog의 사용을 허용합니다

Cloud 기본값: 1.

​

allow_experimental_delta_kernel_rs

실험용 delta-kernel-rs 구현 사용을 허용합니다.

​

allow_experimental_delta_lake_writes

delta-kernel 쓰기 기능을 활성화합니다.

​

allow_experimental_expire_snapshots

실험적 Iceberg 명령 ALTER TABLE ... EXECUTE expire_snapshots의 실행을 허용합니다.

​

allow_experimental_funnel_functions

퍼널 분석용 실험적 함수를 활성화합니다.

​

allow_experimental_geo_types_in_iceberg

Iceberg geometry 및 geography 필드 타입을 ClickHouse Geometry (Variant) 타입으로 파싱할 수 있도록 허용합니다.

​

allow_experimental_hash_functions

실험적 해시 함수를 활성화합니다

​

allow_experimental_iceberg_compaction

Iceberg 테이블에서 ‘OPTIMIZE’를 명시적으로 사용할 수 있도록 합니다.

​

allow_experimental_join_right_table_sorting

true로 설정되어 있고 join_to_sort_minimum_perkey_rows 및 join_to_sort_maximum_table_rows의 조건이 충족되면, left 해시 조인 또는 inner 해시 조인의 성능을 향상시키기 위해 오른쪽 테이블을 키 기준으로 재정렬합니다.

​

allow_experimental_json_lazy_type_hints

JSON 타입의 실험적 지연 타입 힌트를 활성화합니다. 이 기능은 타입 힌트 평가를 지연하여 JSON 타입 변환을 최적화할 수 있게 합니다.

​

allow_experimental_kafka_offsets_storage_in_keeper

Kafka 관련 오프셋을 ClickHouse Keeper에 저장하는 실험적 기능을 허용합니다. 활성화하면 Kafka 테이블 엔진에 ClickHouse Keeper 경로와 레플리카 이름을 지정할 수 있습니다. 그러면 일반적인 Kafka 엔진 대신, 커밋된 오프셋을 주로 ClickHouse Keeper에 저장하는 새로운 유형의 스토리지 엔진이 사용됩니다.

​

allow_experimental_kusto_dialect

SQL의 대안인 Kusto Query Language (KQL)을 활성화합니다.

​

allow_experimental_materialized_postgresql_table

MaterializedPostgreSQL 테이블 엔진의 사용을 허용합니다. 이 기능은 실험적이므로 기본적으로 비활성화되어 있습니다.

​

allow_experimental_nlp_functions

자연어 처리를 위한 실험적 함수를 활성화합니다.

​

allow_experimental_nullable_tuple_type

테이블에서 Nullable Tuple 컬럼을 생성할 수 있도록 합니다.

이 설정은 추출된 Tuple 서브컬럼이 Nullable이 될 수 있는지 여부는 제어하지 않습니다(예: Dynamic, Variant, JSON 또는 Tuple 컬럼에서 추출된 경우). 추출된 Tuple 서브컬럼이 Nullable이 될 수 있는지 제어하려면 allow_nullable_tuple_in_extracted_subcolumns를 사용하십시오.

​

allow_experimental_object_storage_queue_hive_partitioning

S3Queue/AzureQueue 엔진에서 Hive 파티셔닝 사용을 허용합니다

​

allow_experimental_paimon_storage_engine

Paimon* 테이블 엔진으로 테이블을 생성할 수 있도록 허용합니다.

​

allow_experimental_parallel_reading_from_replicas

별칭: enable_parallel_replicas

SELECT 쿼리를 실행할 때 각 세그먼트에서 최대 max_parallel_replicas개의 레플리카를 사용합니다. 읽기는 병렬로 수행되며 동적으로 조정됩니다. 0 - 비활성화, 1 - 활성화, 실패 시 자동으로 비활성화, 2 - 활성화, 실패 시 예외 발생

​

allow_experimental_polyglot_dialect

polyglot SQL 트랜스파일러를 활성화합니다. 30개 이상의 방언(MySQL, PostgreSQL, SQLite, Snowflake, DuckDB 등)의 SQL을 ClickHouse SQL로 트랜스파일합니다.

​

allow_experimental_prql_dialect

SQL의 대안인 PRQL을 활성화합니다.

​

allow_experimental_query_deduplication

part UUID를 기반으로 한 SELECT 쿼리용 실험적 데이터 중복 제거

​

allow_experimental_time_series_aggregate_functions

별칭: allow_experimental_ts_to_grid_aggregate_function

Prometheus와 유사한 시계열 리샘플링, rate 및 delta 계산을 위한 실험적인 timeSeries* 집계 함수입니다.

​

allow_experimental_time_series_table

TimeSeries 테이블 엔진을 사용하는 테이블의 생성을 허용합니다. 가능한 값은 다음과 같습니다:

• 0 — TimeSeries 테이블 엔진이 비활성화됩니다.
• 1 — TimeSeries 테이블 엔진이 활성화됩니다.

​

allow_experimental_unique_key

MergeTree 계열 엔진에서 UNIQUE KEY 절이 포함된 테이블을 생성할 수 있도록 합니다.

​

allow_experimental_window_view

WINDOW VIEW를 활성화합니다. 아직 충분히 안정화되지 않았습니다.

​

allow_experimental_ytsaurus_dictionary_source

YTsaurus 통합용 실험적 딕셔너리 소스입니다.

​

allow_experimental_ytsaurus_table_engine

YTsaurus 통합용 실험적 테이블 엔진입니다.

​

allow_experimental_ytsaurus_table_function

YTsaurus 통합용 실험적 테이블 엔진입니다.

​

allow_fuzz_query_functions

쿼리 문자열에 임의의 AST 뮤테이션을 적용하는 fuzzQuery 함수를 활성화합니다.

​

allow_general_join_planning

더 복잡한 조건을 처리할 수 있는 더 범용적인 조인 계획 알고리즘을 허용하지만, 해시 조인에서만 작동합니다. 해시 조인이 활성화되어 있지 않으면 이 설정값과 관계없이 일반적인 조인 계획 알고리즘이 사용됩니다.

​

allow_get_client_http_header

현재 HTTP 요청의 헤더 값을 가져올 수 있는 함수 getClientHTTPHeader의 사용을 허용합니다. Cookie와 같은 일부 헤더에는 민감한 정보가 포함될 수 있으므로, 보안상의 이유로 기본적으로는 활성화되어 있지 않습니다. X-ClickHouse-* 및 Authentication 헤더는 항상 제한되며, 이 함수로는 가져올 수 없다는 점에 유의하십시오.

​

allow_hyperscan

Hyperscan 라이브러리를 사용하는 함수를 허용합니다. 컴파일 시간이 지나치게 길어지거나 리소스를 과도하게 사용하는 것을 방지하려면 비활성화하십시오.

​

allow_iceberg_remove_orphan_files

Iceberg 테이블에서 ‘ALTER TABLE … EXECUTE remove_orphan_files()‘를 사용할 수 있도록 합니다.

​

allow_insert_into_iceberg

별칭: allow_experimental_insert_into_iceberg

Iceberg에 insert 쿼리를 실행하도록 허용합니다.

​

allow_introspection_functions

쿼리 프로파일링에 사용할 인트로스펙션 함수를 활성화하거나 비활성화합니다.

가능한 값:

• 1 — 인트로스펙션 함수가 활성화됩니다.
• 0 — 인트로스펙션 함수가 비활성화됩니다.

관련 항목

• Sampling Query Profiler
• 시스템 테이블 trace_log

​

allow_key_condition_coalesce_rewrite

인덱스 분석 전에 coalesce(a_1, ..., a_N) <op> const 형태의 프레디케이트(ifNull 형태나 상수가 왼쪽에 있는 동등한 경우 포함)를 (a_1 <op> const) OR (a_1 IS NULL AND a_2 <op> const) OR ... OR (a_1 IS NULL AND ... AND a_{N-1} IS NULL AND a_N <op> const) 형태의 논리합으로 재작성하므로, 각 a_i에 대한 컬럼별 프라이머리 키와 스킵 인덱스를 사용할 수 있습니다. coalesce(a, 42, b) 및 coalesce(a, b, 42)와 같은 일부 상수 포함 형태도 처리합니다. 인수 목록은 coalesce 자체와 마찬가지로 정규화되며(NULL 리터럴은 제거되고, 첫 번째 비-Nullable 인수 뒤의 인수는 제거됨), 후행 비-NULL 상수가 있으면 마지막 분기로 내보냅니다. 이 재작성은 인덱스 프루닝에만 추가로 적용되며, 런타임 필터링에는 계속 원래 프레디케이트를 사용합니다.

​

allow_materialized_view_with_bad_select

존재하지 않는 테이블 또는 컬럼을 참조하는 SELECT 쿼리가 포함된 CREATE MATERIALIZED VIEW를 허용합니다. 다만 구문상으로는 여전히 유효해야 합니다. 갱신 가능한 MV에는 적용되지 않습니다. 또한 SELECT 쿼리에서 MV 스키마를 추론해야 하는 경우(즉, CREATE에 컬럼 목록이 없고 TO 테이블도 없는 경우)에도 적용되지 않습니다. 원본 테이블보다 먼저 MV를 생성할 때 사용할 수 있습니다.

​

allow_named_collection_override_by_default

이름이 지정된 컬렉션의 필드 재정의를 기본적으로 허용합니다.

​

allow_non_metadata_alters

테이블 메타데이터뿐 아니라 디스크의 데이터에도 영향을 주는 alter 실행을 허용합니다.

​

allow_nonconst_timezone_arguments

toTimeZone(), fromUnixTimestamp*(), snowflakeToDateTime*()와 같은 특정 시간 관련 함수에서 상수가 아닌 시간대 인수를 허용합니다. 이 설정은 호환성을 위해서만 존재합니다. ClickHouse에서 시간대는 데이터 타입, 즉 컬럼의 속성입니다. 이 설정을 활성화하면 하나의 컬럼 안에서 서로 다른 값이 서로 다른 시간대를 가질 수 있다는 잘못된 인상을 줄 수 있습니다. 따라서 이 설정은 활성화하지 마십시오.

​

allow_nondeterministic_mutations

dictGet과 같은 비결정적 함수를 복제된 테이블(Replicated Table)의 뮤테이션에 사용할 수 있도록 허용하는 사용자 수준 설정입니다.

예를 들어 딕셔너리는 노드 간 동기화 상태가 서로 다를 수 있으므로, 딕셔너리에서 값을 가져오는 뮤테이션은 기본적으로 복제된 테이블에서 허용되지 않습니다. 이 설정을 활성화하면 이러한 동작이 가능해지며, 사용되는 데이터가 모든 노드에서 동기화되어 있는지 확인하는 책임은 사용자에게 있습니다.

예시

<profiles>
    <default>
        <allow_nondeterministic_mutations>1</allow_nondeterministic_mutations>

        <!-- ... -->
    </default>

    <!-- ... -->

</profiles>

​

allow_nondeterministic_optimize_skip_unused_shards

세그먼트 분할 키(sharding key)에서 비결정적 함수(rand 또는 dictGet 등, 단 후자는 업데이트와 관련해 몇 가지 주의 사항이 있음)를 허용합니다.

가능한 값:

• 0 — 허용되지 않습니다.
• 1 — 허용됩니다.

​

allow_nullable_tuple_in_extracted_subcolumns

Tuple(...) 유형의 추출된 서브컬럼을 Nullable(Tuple(...))로 지정할 수 있는지 제어합니다.

• false: Tuple(...)를 반환하고, 서브컬럼이 없는 행에는 기본 tuple 값을 사용합니다.
• true: Nullable(Tuple(...))를 반환하고, 서브컬럼이 없는 행에는 NULL을 사용합니다.

이 설정은 추출된 서브컬럼의 동작만 제어합니다. 테이블에서 Nullable(Tuple(...)) 컬럼을 생성할 수 있는지 여부는 제어하지 않습니다. 이는 allow_experimental_nullable_tuple_type에서 제어합니다.

ClickHouse는 서버 시작 시 로드된 이 설정 값을 사용합니다. SET 또는 쿼리 수준의 SETTINGS로 변경해도 추출된 서브컬럼 동작은 바뀌지 않습니다. 추출된 서브컬럼 동작을 변경하려면 시작 프로필 구성(예: users.xml)에서 allow_nullable_tuple_in_extracted_subcolumns를 업데이트한 후 서버를 다시 시작하십시오.

​

allow_prefetched_read_pool_for_local_filesystem

모든 파트가 로컬 파일 시스템에 있으면 prefetched 스레드 풀을 우선 사용합니다

​

allow_prefetched_read_pool_for_remote_filesystem

모든 파트가 원격 파일 시스템에 있는 경우 prefetched 스레드 풀을 우선 사용합니다

​

allow_push_predicate_ast_for_distributed_subqueries

analyzer가 활성화된 분산 서브쿼리에서 AST 수준의 프레디케이트 푸시를 허용합니다

​

allow_push_predicate_when_subquery_contains_with

서브쿼리에 WITH 절이 포함된 경우에도 push predicate를 허용합니다

​

allow_rank_dense_rank_arguments

하위 호환성을 위해 RANK 및 DENSE_RANK 윈도우 함수에 인수를 전달할 수 있도록 허용합니다.

SQL 표준에 따르면 RANK 및 DENSE_RANK는 인수를 받지 않습니다. 즉, 이 함수들은 OVER (ORDER BY ...) 윈도우만 기준으로 행의 순위를 매깁니다. ClickHouse 26.5 이전 버전에서는 RANK(x) OVER (...)와 같은 쿼리에서 인수를 아무 경고 없이 받아들인 뒤 무시했기 때문에 사용자에게 혼란을 주었습니다 (표시된 인수가 순위 계산에 영향을 주는 것처럼 보이지만 실제로는 그렇지 않았습니다).

이 설정이 false(기본값)이면 RANK 및 DENSE_RANK는 모든 인수를 거부하고 NUMBER_OF_ARGUMENTS_DOESNT_MATCH 예외를 발생시킵니다. true로 설정하면 이전의 완화된 동작이 복원되며, 26.5 이전과 같이 인수가 아무 경고 없이 무시됩니다.

​

allow_reorder_prewhere_conditions

조건을 WHERE에서 PREWHERE로 이동할 때, 필터링 최적화를 위해 조건의 순서를 재정렬할 수 있습니다

​

allow_settings_after_format_in_insert

INSERT 쿼리에서 FORMAT 뒤에 SETTINGS를 허용할지 여부를 제어합니다. SETTINGS의 일부가 값으로 해석될 수 있으므로, 사용은 권장되지 않습니다.

예시:

INSERT INTO FUNCTION null('foo String') SETTINGS max_threads=1 VALUES ('bar');

하지만 다음 쿼리는 allow_settings_after_format_in_insert를 활성화한 경우에만 동작합니다:

SET allow_settings_after_format_in_insert=1;
INSERT INTO FUNCTION null('foo String') VALUES ('bar') SETTINGS max_threads=1;

가능한 값:

• 0 — 허용하지 않습니다.
• 1 — 허용합니다.

사용 사례가 이전 구문에 의존하는 경우에만 이전 버전과의 호환성을 위해 이 설정을 사용하세요.

​

allow_simdjson

AVX2 명령어를 사용할 수 있는 경우 ‘JSON*’ 함수에서 simdjson 라이브러리를 사용할 수 있도록 합니다. 비활성화하면 rapidjson을 사용합니다.

​

allow_special_serialization_kinds_in_output_formats

Sparse 및 Replicated와 같은 특수 직렬화 종류를 사용하는 컬럼을 완전한 컬럼 표현으로 변환하지 않고 출력할 수 있도록 합니다. 이렇게 하면 formatting 중 불필요한 데이터 복사를 줄이는 데 도움이 됩니다.

​

allow_statistics

별칭: allow_experimental_statistics

컬럼에 통계를 정의하고 통계를 관리할 수 있습니다.

​

allow_statistics_optimize

별칭: allow_statistic_optimize

통계를 사용한 쿼리 최적화를 허용합니다

​

allow_suspicious_codecs

true로 설정하면 무의미한 압축 코덱을 지정할 수 있습니다.

​

allow_suspicious_fixed_string_types

CREATE TABLE 문에서 n > 256인 FixedString(n) 타입의 컬럼을 생성할 수 있도록 허용합니다. 길이가 256 이상인 FixedString은 의심스러우며, 대개 잘못 사용되었음을 의미합니다.

​

allow_suspicious_indices

동일한 표현식을 사용하는 프라이머리/보조 인덱스와 정렬 키를 거부합니다

​

allow_suspicious_low_cardinality_types

8바이트 이하의 고정 크기를 갖는 데이터 타입, 즉 숫자 데이터 타입과 FixedString(8_bytes_or_less)에 LowCardinality를 사용할 수 있도록 허용하거나 제한합니다.

작은 고정값에 LowCardinality를 사용하는 것은 일반적으로 비효율적입니다. ClickHouse는 각 행마다 숫자 인덱스를 저장하기 때문입니다. 그 결과 다음과 같은 문제가 발생할 수 있습니다.

• 디스크 공간 사용량이 늘어날 수 있습니다.
• 딕셔너리 크기에 따라 RAM 사용량이 더 높아질 수 있습니다.
• 추가 코딩/인코딩 작업으로 인해 일부 함수가 더 느리게 동작할 수 있습니다.

위에서 설명한 모든 이유로 인해 MergeTree 엔진 테이블의 머지 시간이 늘어날 수 있습니다.

가능한 값:

• 1 — LowCardinality 사용이 제한되지 않습니다.
• 0 — LowCardinality 사용이 제한됩니다.

​

allow_suspicious_primary_key

MergeTree에서 문제가 있을 수 있는 PRIMARY KEY/ORDER BY(예: SimpleAggregateFunction)를 허용합니다.

​

allow_suspicious_ttl_expressions

테이블의 어떤 컬럼에도 의존하지 않는 TTL 표현식은 거부합니다. 대부분 사용자 오류를 의미합니다.

​

allow_suspicious_types_in_group_by

GROUP BY 키로 Variant 및 Dynamic 타입을 사용하는 것을 허용하거나 제한합니다.

​

allow_suspicious_types_in_order_by

ORDER BY 키에서 Variant 및 Dynamic 타입의 사용 허용 여부를 제어합니다.

​

allow_suspicious_variant_types

CREATE TABLE 문에서 서로 유사한 variant type(예: 서로 다른 숫자형 또는 날짜형 타입)을 포함하는 Variant 타입을 지정할 수 있도록 합니다. 이 설정을 활성화하면 유사한 타입의 값을 다룰 때 일부 모호성이 생길 수 있습니다.

​

allow_unrestricted_reads_from_keeper

system.zookeeper 테이블에서 제한 없이(경로 조건 없이) 읽는 것을 허용합니다. 편리할 수 있지만 ZooKeeper에는 안전하지 않습니다.

​

alter_move_to_space_execute_async

ALTER TABLE MOVE … TO [DISK|VOLUME] 명령을 비동기적으로 실행합니다

​

alter_partition_verbose_result

파티션 및 파트 조작 작업이 성공적으로 적용된 파트에 대한 정보 표시를 활성화하거나 비활성화합니다. ATTACH PARTITION|PART 및 FREEZE PARTITION에 적용됩니다.

가능한 값:

• 0 — 자세히 표시하지 않습니다.
• 1 — 자세히 표시합니다.

예시

CREATE TABLE test(a Int64, d Date, s String) ENGINE = MergeTree PARTITION BY toYYYYMDECLARE(d) ORDER BY a;
INSERT INTO test VALUES(1, '2021-01-01', '');
INSERT INTO test VALUES(1, '2021-01-01', '');
ALTER TABLE test DETACH PARTITION ID '202101';

ALTER TABLE test ATTACH PARTITION ID '202101' SETTINGS alter_partition_verbose_result = 1;

┌─command_type─────┬─partition_id─┬─part_name────┬─old_part_name─┐
│ ATTACH PARTITION │ 202101       │ 202101_7_7_0 │ 202101_5_5_0  │
│ ATTACH PARTITION │ 202101       │ 202101_8_8_0 │ 202101_6_6_0  │
└──────────────────┴──────────────┴──────────────┴───────────────┘

ALTER TABLE test FREEZE SETTINGS alter_partition_verbose_result = 1;

┌─command_type─┬─partition_id─┬─part_name────┬─backup_name─┬─backup_path───────────────────┬─part_backup_path────────────────────────────────────────────┐
│ FREEZE ALL   │ 202101       │ 202101_7_7_0 │ 8           │ /var/lib/clickhouse/shadow/8/ │ /var/lib/clickhouse/shadow/8/data/default/test/202101_7_7_0 │
│ FREEZE ALL   │ 202101       │ 202101_8_8_0 │ 8           │ /var/lib/clickhouse/shadow/8/ │ /var/lib/clickhouse/shadow/8/data/default/test/202101_8_8_0 │
└──────────────┴──────────────┴──────────────┴─────────────┴───────────────────────────────┴─────────────────────────────────────────────────────────────┘

​

alter_sync

별칭: replication_alter_partitions_sync

ALTER, OPTIMIZE 또는 TRUNCATE 쿼리로 레플리카에서 실행되는 작업에 대해 어떻게 대기할지 지정합니다.

가능한 값:

• 0 — 대기하지 않습니다.
• 1 — 자체 실행이 완료될 때까지 대기합니다.
• 2 — 모두의 실행이 완료될 때까지 대기합니다.
• 3 - 활성 레플리카의 실행이 완료될 때까지만 대기합니다.

Cloud 기본값: 0.

alter_sync는 Replicated 및 SharedMergeTree 테이블에만 적용되며, Replicated 또는 Shared가 아닌 테이블에 대해서는 아무런 동작도 하지 않습니다.

​

alter_update_mode

UPDATE 명령을 포함한 ALTER 쿼리에 사용하는 모드입니다.

가능한 값:

• heavy - 일반 mutation을 실행합니다.
• lightweight - 가능하면 경량 업데이트를 실행하고, 그렇지 않으면 일반 mutation을 실행합니다.
• lightweight_force - 가능하면 경량 업데이트를 실행하고, 그렇지 않으면 예외를 발생시킵니다.

​

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_compatibility_allow_compound_identifiers_in_unflatten_nested

nested에 복합 식별자를 추가할 수 있도록 허용합니다. 이 설정은 쿼리 결과를 변경할 수 있으므로 호환성 설정입니다. 비활성화하면 SELECT a.b.c FROM table ARRAY JOIN a는 작동하지 않고, SELECT a FROM table에는 Nested a 결과에 a.b.c 컬럼이 포함되지 않습니다.

​

analyzer_compatibility_join_using_top_level_identifier

JOIN USING의 식별자를 projection에서 해석하도록 강제합니다(예를 들어 SELECT a + 1 AS b FROM t1 JOIN t2 USING (b)에서는 t1.b = t2.b가 아니라 t1.a + 1 = t2.b를 기준으로 join이 수행됩니다).

​

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 — 기존 방식이 활성화됩니다.

관련 항목:

• JOIN 엄격성

​

apply_deleted_mask

경량한 삭제로 삭제된 행을 필터링할 수 있도록 합니다. 비활성화하면 쿼리에서 해당 행을 읽을 수 있습니다. 이는 디버깅 및 “삭제 복구” 시나리오에 유용합니다.

​

apply_mutations_on_fly

true인 경우, 데이터 파트에 구체화되지 않은 뮤테이션(UPDATE 및 DELETE)이 SELECT 시 적용됩니다.

​

apply_patch_parts

true이면 경량 업데이트를 나타내는 patch parts가 SELECT 시 적용됩니다.

​

apply_patch_parts_join_cache_buckets

Join 모드에서 patch parts 적용을 위한 임시 캐시의 버킷 수입니다.

​

apply_prewhere_after_final

활성화하면 ReplacingMergeTree 및 유사한 엔진에서 PREWHERE 조건이 FINAL 처리 후에 적용됩니다. 이는 PREWHERE가 중복된 행들 사이에서 값이 달라질 수 있는 컬럼을 참조하고, 필터링하기 전에 FINAL이 최종적으로 선택될 행을 먼저 결정하도록 하려는 경우에 유용합니다. 비활성화하면 PREWHERE는 읽는 중에 적용됩니다. 참고: apply_row_level_security_after_final이 활성화되어 있고 행 정책이 정렬 키가 아닌 컬럼을 사용하는 경우, 올바른 실행 순서를 유지하기 위해 PREWHERE도 지연됩니다(행 정책은 PREWHERE보다 먼저 적용되어야 합니다).

​

apply_row_policy_after_final

활성화하면 *MergeTree 테이블에서 FINAL 처리 후에 행 정책과 PREWHERE가 적용됩니다. (특히 ReplacingMergeTree에서 해당됩니다.) 비활성화하면 행 정책은 FINAL 전에 적용되며, 이 경우 정책이 ReplacingMergeTree 또는 유사한 엔진에서 중복 제거에 사용되어야 하는 행을 필터링하면 결과가 달라질 수 있습니다.

행 정책 표현식이 ORDER BY의 컬럼에만 의존하는 경우에는 최적화를 위해 여전히 FINAL 전에 적용됩니다. 이러한 필터링은 중복 제거 결과에 영향을 주지 않기 때문입니다.

가능한 값:

• 0 — 행 정책과 PREWHERE가 FINAL 전에 적용됩니다(기본값).
• 1 — 행 정책과 PREWHERE가 FINAL 후에 적용됩니다.

​

apply_settings_from_server

클라이언트가 서버에서 설정을 받아들일지 여부입니다.

이 설정은 클라이언트 측에서 수행되는 작업에만 영향을 미치며, 특히 INSERT 입력 데이터의 파싱과 쿼리 결과의 형식 지정에 적용됩니다. 대부분의 쿼리 실행은 서버에서 이루어지므로 이 설정의 영향을 받지 않습니다.

일반적으로 이 설정은 클라이언트(클라이언트 명령줄 인수, SET 쿼리 또는 SELECT 쿼리의 SETTINGS 섹션)가 아니라 사용자 프로필(users.xml 또는 ALTER USER 같은 쿼리)에서 설정해야 합니다. 클라이언트를 통해 false로 변경할 수는 있지만 true로는 변경할 수 없습니다(사용자 프로필에 apply_settings_from_server = false가 설정되어 있으면 서버가 설정을 보내지 않기 때문입니다).

참고로 초기에(24.12) 서버 설정(send_settings_to_client)이 있었지만, 이후 사용성을 개선하기 위해 이 클라이언트 설정으로 대체되었습니다.

​

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에 필요함)

​

ast_fuzzer_any_query

false(기본값)인 경우 서버 측 AST 퍼저(ast_fuzzer_runs로 제어)는 읽기 전용 쿼리(SELECT, EXPLAIN, SHOW, DESCRIBE, EXISTS)만 퍼징합니다. true인 경우에는 DDL 및 INSERT를 포함한 모든 쿼리 타입을 퍼징합니다.

​

ast_fuzzer_runs

일반 쿼리가 실행될 때마다 그 뒤에 무작위 쿼리를 실행하고 결과는 폐기하는 서버 측 AST 퍼저를 활성화합니다.

• 0: 비활성화(기본값)입니다.
• 0보다 크고 1보다 작은 값: 퍼즈된 쿼리 1개를 실행할 확률입니다.
• 1 이상인 값: 일반 쿼리마다 실행할 퍼즈된 쿼리 수입니다.

퍼저는 모든 세션의 모든 쿼리에서 AST 조각을 누적하며, 시간이 지날수록 점점 더 흥미로운 뮤테이션을 생성합니다. 실패한 퍼즈 쿼리는 자동으로 폐기되며, 결과는 클라이언트에 반환되지 않습니다.

​

asterisk_include_alias_columns

와일드카드 쿼리(SELECT *)에 ALIAS 컬럼을 포함합니다.

가능한 값:

• 0 - 비활성화됨
• 1 - 활성화됨

​

asterisk_include_materialized_columns

와일드카드 쿼리(SELECT *)에 MATERIALIZED 컬럼을 포함할지 설정합니다.

사용 가능한 값:

• 0 - 비활성화
• 1 - 활성화

​

asterisk_include_virtual_columns

와일드카드 쿼리(SELECT *)에 가상 컬럼을 포함합니다.

가능한 값:

• 0 - 비활성화됨
• 1 - 활성화됨

​

async_insert

true인 경우, INSERT 쿼리의 데이터는 큐에 저장되며 이후 백그라운드에서 테이블로 플러시됩니다. wait_for_async_insert가 false이면 INSERT 쿼리는 거의 즉시 처리되며, 그렇지 않으면 클라이언트는 데이터가 테이블로 플러시될 때까지 기다립니다.

​

async_insert_busy_timeout_decrease_rate

적응형 비동기 삽입 타임아웃 감소 시 적용되는 지수 증가율

​

async_insert_busy_timeout_increase_rate

적응형 비동기 삽입 타임아웃이 증가할 때의 지수 증가율

​

async_insert_busy_timeout_max_ms

별칭: async_insert_busy_timeout_ms

첫 번째 데이터가 도착한 시점부터, 쿼리별로 수집된 데이터를 덤프하기 전까지 대기하는 최대 시간입니다.

Cloud 기본값: 1000 (1s).

​

async_insert_busy_timeout_min_ms

async_insert_use_adaptive_busy_timeout을 통해 자동 조정이 활성화된 경우, 첫 데이터가 들어온 시점부터 쿼리별로 수집된 데이터를 기록하기 전까지 대기하는 최소 시간입니다. 또한 적응형 알고리즘의 초기값으로도 사용됩니다.

​

async_insert_deduplicate

복제된 테이블(Replicated Table)에서 async INSERT 쿼리의 삽입 블록에 대해 중복 제거를 수행할지 지정합니다.

​

async_insert_max_data_size

삽입되기 전에 쿼리별로 수집되는 미파싱 데이터의 최대 크기(바이트)

Cloud 기본값: 104857600 (100 MiB).

​

async_insert_max_query_number

삽입이 수행되기 전까지 허용되는 최대 삽입 쿼리 수입니다. 이 설정은 async_insert_deduplicate가 1인 경우에만 적용됩니다.

​

async_insert_poll_timeout_ms

비동기 삽입 큐의 데이터를 폴링할 때의 timeout

​

async_insert_use_adaptive_busy_timeout

true로 설정하면 비동기 삽입에 적응형 busy 타임아웃을 사용합니다

​

async_query_sending_for_remote

원격 쿼리 실행 시 연결 생성과 쿼리 전송을 비동기로 수행하도록 합니다.

기본적으로 활성화되어 있습니다.

​

async_socket_for_remote

원격 쿼리를 실행할 때 소켓에서 비동기적으로 읽도록 합니다.

기본적으로 활성화되어 있습니다.

​

automatic_parallel_replicas_min_bytes_per_replica

병렬 레플리카를 자동으로 활성화하기 위해 레플리카당 읽어야 하는 바이트 수의 임계값입니다(automatic_parallel_replicas_mode=1인 경우에만 적용됨). 0은 임계값이 없음을 의미합니다. 읽어야 하는 총 바이트 수는 수집된 통계를 기반으로 추정됩니다.

​

automatic_parallel_replicas_mode

수집된 통계를 기반으로 병렬 레플리카를 사용한 실행으로 자동 전환할지 설정합니다. 이를 사용하려면 enable_analyzer = 1, enable_parallel_replicas != 0, parallel_replicas_local_plan = 1이 필요하며, cluster_for_parallel_replicas도 제공해야 합니다. 0 - 비활성화, 1 - 활성화, 2 - 통계 수집만 활성화됨(병렬 레플리카를 사용한 실행으로의 전환은 비활성화됨).

​

azure_allow_parallel_part_upload

Azure 멀티파트 업로드에 여러 스레드를 사용합니다.

​

azure_check_objects_after_upload

Azure blob storage에 업로드된 각 객체를 검사하여 업로드가 정상적으로 완료되었는지 확인합니다

​

azure_connect_timeout_ms

Azure 디스크 호스트의 연결 타임아웃입니다.

​

azure_create_new_file_on_insert

Azure engine 테이블에서 각 삽입 시 새 파일을 생성할지 여부를 설정합니다

​

azure_ignore_file_doesnt_exist

특정 키를 읽을 때 파일이 존재하지 않더라도 이를 무시합니다.

Possible values:

• 1 — SELECT는 빈 결과를 반환합니다.
• 0 — SELECT는 예외를 발생시킵니다.

​

azure_list_object_keys_size

ListObject 요청으로 한 번에 반환할 수 있는 최대 파일 수

​

azure_max_blocks_in_multipart_upload

Azure 멀티파트 업로드의 최대 블록 수입니다.

​

azure_max_get_burst

초당 요청 수 제한에 도달하기 전에 동시에 실행할 수 있는 최대 요청 수입니다. 기본값(0)은 azure_max_get_rps와 같습니다.

​

azure_max_get_rps

스로틀링이 시작되기 전까지 허용되는 Azure GET 요청의 초당 수 제한입니다. 0은 무제한을 의미합니다.

​

azure_max_inflight_parts_for_one_file

멀티파트 업로드 요청에서 동시에 업로드할 수 있는 파트의 최대 개수입니다. 0은 무제한입니다.

​

azure_max_put_burst

초당 요청 수 제한에 도달하기 전에 동시에 보낼 수 있는 최대 요청 수입니다. 기본값(0)은 azure_max_put_rps와 동일합니다.

​

azure_max_put_rps

스로틀링이 적용되기 전 Azure PUT request의 초당 요청 수 제한입니다. 0은 무제한을 의미합니다.

​

azure_max_redirects

허용되는 Azure 리디렉션 홉의 최대 수입니다.

​

azure_max_single_part_copy_size

Azure blob storage에 단일 파트 복사 방식으로 복사할 수 있는 객체의 최대 크기입니다.

​

azure_max_single_part_upload_size

Azure blob storage에 단일 파트 업로드(singlepart upload)로 업로드할 수 있는 객체의 최대 크기입니다.

​

azure_max_single_read_retries

Azure blob storage에서 단일 읽기를 수행할 때 재시도할 수 있는 최대 횟수입니다.

​

azure_max_unexpected_write_error_retries

Azure blob storage에 쓰는 중 예기치 않은 오류가 발생했을 때의 최대 재시도 횟수

​

azure_max_upload_part_size

Azure blob storage에 멀티파트 업로드를 수행할 때 업로드할 파트의 최대 크기입니다.

​

azure_min_upload_part_size

Azure blob storage로 멀티파트 업로드를 수행할 때 각 업로드 파트의 최소 크기입니다.

​

azure_request_timeout_ms

Azure로 데이터를 송수신할 때 적용되는 유휴 시간 제한입니다. 단일 TCP 읽기 또는 쓰기 호출이 이 시간 동안 블로킹되면 실패합니다.

​

azure_sdk_max_retries

Azure SDK의 최대 재시도 횟수

​

azure_sdk_retry_initial_backoff_ms

Azure SDK의 재시도 사이 최소 백오프

​

azure_sdk_retry_max_backoff_ms

Azure SDK의 재시도 간 최대 백오프

​

azure_skip_empty_files

S3 엔진에서 빈 파일 건너뛰기를 활성화하거나 비활성화합니다.

가능한 값:

• 0 — 빈 파일이 요청된 포맷과 호환되지 않으면 SELECT가 예외를 발생시킵니다.
• 1 — 빈 파일에 대해 SELECT는 빈 결과를 반환합니다.

​

azure_strict_upload_part_size

Azure Blob Storage로 멀티파트 업로드를 수행할 때 각 업로드 파트의 정확한 크기입니다.

​

azure_throw_on_zero_files_match

glob 확장 규칙에 따라 일치하는 파일이 0개이면 오류를 발생시킵니다.

가능한 값:

• 1 — SELECT가 예외를 발생시킵니다.
• 0 — SELECT가 빈 결과를 반환합니다.

​

azure_truncate_on_insert

azure 엔진 테이블에서 삽입 전에 TRUNCATE를 수행할지 여부를 설정합니다.

​

azure_upload_part_size_multiply_factor

Azure blob storage에 대한 단일 쓰기에서 azure_multiply_parts_count_threshold개의 파트가 업로드될 때마다 azure_min_upload_part_size에 이 계수를 곱합니다.

​

azure_upload_part_size_multiply_parts_count_threshold

이 개수만큼의 파트가 Azure blob storage에 업로드될 때마다 azure_min_upload_part_size에 azure_upload_part_size_multiply_factor를 곱합니다.

​

azure_use_adaptive_timeouts

true로 설정하면 모든 Azure 요청에서 처음 두 번의 시도는 더 짧은 송신 및 수신 timeout으로 수행됩니다. false로 설정하면 모든 시도가 동일한 timeout으로 수행됩니다.

​

backup_restore_batch_size_for_keeper_multi

백업 또는 복원 중 [Zoo]Keeper로 보내는 다중 요청의 Batch 최대 크기

​

backup_restore_batch_size_for_keeper_multiread

백업 또는 복원 중 [Zoo]Keeper에 대한 multiread 요청에 사용되는 Batch의 최대 크기

​

backup_restore_failure_after_host_disconnected_for_seconds

BACKUP ON CLUSTER 또는 RESTORE ON CLUSTER 작업 중 호스트가 이 시간 동안 ZooKeeper에 임시 ‘alive’ 노드를 다시 생성하지 못하면 전체 백업 또는 복원은 실패한 것으로 간주됩니다. 이 값은 장애 발생 후 호스트가 ZooKeeper에 다시 연결하는 데 필요한 합리적인 최대 시간보다 크게 설정해야 합니다. 0은 무제한을 의미합니다.

​

backup_restore_finish_timeout_after_error_sec

현재 BACKUP ON CLUSTER 또는 RESTORE ON CLUSTER 작업에서 시작 노드가 다른 호스트가 ‘오류’ 노드에 반응하여 작업을 중지할 때까지 대기하는 시간을 지정합니다.

​

backup_restore_keeper_fault_injection_probability

백업 또는 복원 중 Keeper 요청이 실패할 대략적인 확률입니다. 유효한 값 범위는 인터벌 [0.0f, 1.0f]입니다.

​

backup_restore_keeper_fault_injection_seed

0 - 랜덤 시드, 그 밖에는 설정값

​

backup_restore_keeper_max_retries

BACKUP 또는 RESTORE 작업 도중 [Zoo]Keeper 작업에 대해 허용되는 최대 재시도 횟수입니다. 일시적인 [Zoo]Keeper 장애로 인해 전체 작업이 실패하지 않도록 충분히 크게 설정해야 합니다.

​

backup_restore_keeper_max_retries_while_handling_error

BACKUP ON CLUSTER 또는 RESTORE ON CLUSTER 작업에서 오류를 처리하는 동안 수행되는 [Zoo]Keeper 작업의 최대 재시도 횟수입니다.

​

backup_restore_keeper_max_retries_while_initializing

BACKUP ON CLUSTER 또는 RESTORE ON CLUSTER 작업 초기화 중 [Zoo]Keeper 작업의 최대 재시도 횟수입니다.

​

backup_restore_keeper_retry_initial_backoff_ms

backup 또는 복원 중 [Zoo]Keeper 작업에 대한 초기 백오프 타임아웃

​

backup_restore_keeper_retry_max_backoff_ms

백업 또는 복원 중 [Zoo]Keeper 작업의 최대 백오프 타임아웃

Cloud 기본값: 60000.

​

backup_restore_keeper_value_max_size

백업 중 [Zoo]Keeper 노드에 저장되는 데이터의 최대 크기

​

backup_restore_s3_retry_attempts

Aws::Client::RetryStrategy용 설정입니다. Aws::Client는 자체적으로 재시도하며, 0은 재시도를 수행하지 않음을 의미합니다. 이 설정은 백업/복원에만 적용됩니다.

​

backup_restore_s3_retry_initial_backoff_ms

백업 및 복원 중 첫 번째 재시도 전에 적용되는 초기 백오프 지연 시간(밀리초)입니다. 이후 각 재시도마다 지연 시간이 지수적으로 증가하며, 최대값은 backup_restore_s3_retry_max_backoff_ms로 지정됩니다.

​

backup_restore_s3_retry_jitter_factor

백업 및 복원 작업 중 Aws::Client::RetryStrategy의 재시도 백오프 지연에 적용되는 지터 계수입니다. 계산된 백오프 지연은 [1.0, 1.0 + jitter] 범위의 임의 계수와 곱해지며, 최대 backup_restore_s3_retry_max_backoff_ms까지 적용됩니다. 값은 [0.0, 1.0] 인터벌에 있어야 합니다

​

backup_restore_s3_retry_max_backoff_ms

백업 및 복원 작업에서 재시도 간 최대 지연 시간(밀리초)입니다.

​

backup_slow_all_threads_after_retryable_s3_error

true로 설정하면 동일한 백업 엔드포인트로 S3 요청을 실행하는 모든 스레드의 속도가 ‘Sleep Down’과 같은 재시도 가능한 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.

​

cast_ipv4_ipv6_default_on_conversion_error

IPv4로 CAST하는 연산자, IPv6 유형으로 CAST하는 연산자, 그리고 toIPv4, toIPv6 함수는 변환 오류가 발생하면 예외를 발생시키는 대신 기본값을 반환합니다.

​

cast_keep_nullable

CAST 연산에서 Nullable 데이터 타입을 유지할지 여부를 설정합니다.

이 설정이 활성화되어 있고 CAST 함수의 인수가 Nullable이면 결과도 Nullable 타입으로 변환됩니다. 이 설정이 비활성화되면 결과는 항상 지정된 대상 타입 그대로 반환됩니다.

Possible values:

• 0 — CAST 결과는 지정된 대상 타입 그대로 반환됩니다.
• 1 — 인수 타입이 Nullable이면 CAST 결과는 Nullable(DestinationDataType)으로 변환됩니다.

예시

다음 쿼리는 정확히 대상 데이터 타입으로 결과를 반환합니다.

SET cast_keep_nullable = 0;
SELECT CAST(toNullable(toInt32(0)) AS Int32) as x, toTypeName(x);

결과:

┌─x─┬─toTypeName(CAST(toNullable(toInt32(0)), 'Int32'))─┐
│ 0 │ Int32                                             │
└───┴───────────────────────────────────────────────────┘

다음 쿼리를 실행하면 대상 데이터 타입에 Nullable 수정자가 적용된 결과가 반환됩니다:

SET cast_keep_nullable = 1;
SELECT CAST(toNullable(toInt32(0)) AS Int32) as x, toTypeName(x);

결과:

┌─x─┬─toTypeName(CAST(toNullable(toInt32(0)), 'Int32'))─┐
│ 0 │ Nullable(Int32)                                   │
└───┴───────────────────────────────────────────────────┘

관련 항목

• CAST 함수

​

cast_string_to_date_time_mode

String에서 캐스트할 때 날짜 및 시간의 텍스트 표현을 해석할 파서를 선택할 수 있습니다.

가능한 값:

• 'best_effort' — 확장 파싱을 활성화합니다.

  ClickHouse는 기본 YYYY-MM-DD HH:MM:SS 포맷과 모든 ISO 8601 날짜 및 시간 포맷을 파싱할 수 있습니다. 예를 들어 '2018-06-08T01:02:03.000Z'가 있습니다.

• 'best_effort_us' — best_effort와 유사합니다(parseDateTimeBestEffortUS에서 차이점을 확인하십시오)

• 'basic' — 기본 파서를 사용합니다.

  ClickHouse는 기본 YYYY-MM-DD HH:MM:SS 또는 YYYY-MM-DD 포맷만 파싱할 수 있습니다. 예를 들어 2019-08-20 10:18:56 또는 2019-08-20가 있습니다.

관련 항목:

• DateTime 데이터 타입.
• 날짜 및 시간을 다루는 함수.

​

cast_string_to_dynamic_use_inference

String을 Dynamic으로 변환할 때 타입 추론을 사용합니다

​

cast_string_to_variant_use_inference

String에서 Variant로 변환할 때 타입 추론을 사용합니다.

​

check_named_collection_dependencies

DROP NAMED COLLECTION이 이를 참조하는 테이블에 문제를 일으키지 않는지 확인합니다

​

check_query_single_value_result

MergeTree 계열 엔진에서 CHECK TABLE 쿼리 결과에 표시되는 세부 수준을 정의합니다.

가능한 값:

• 0 — 쿼리에서 테이블의 각 개별 데이터 파트에 대한 검사 상태를 표시합니다.
• 1 — 쿼리에서 테이블 전체의 검사 상태를 표시합니다.

​

check_referential_table_dependencies

DDL 쿼리(DROP TABLE 또는 RENAME 등)가 참조 의존성을 손상시키지 않는지 확인합니다

​

check_table_dependencies

DDL 쿼리(DROP TABLE 또는 RENAME 등)로 인해 의존 관계가 깨지지 않는지 확인합니다

​

checksum_on_read

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

​

cloud_mode

Cloud 모드

Cloud 기본값: 1.

​

cloud_mode_database_engine

Cloud에서 허용되는 데이터베이스 엔진입니다. 1은 DDL을 재작성해 복제된 데이터베이스를 사용하고, 2는 DDL을 재작성해 Shared 데이터베이스를 사용합니다.

Cloud 기본값: 2.

​

cloud_mode_engine

Cloud에서 허용되는 엔진 계열입니다.

• 0 - 모두 허용
• 1 - DDLs를 *ReplicatedMergeTree를 사용하도록 재작성
• 2 - DDLs를 SharedMergeTree를 사용하도록 재작성
• 3 - 원격 디스크를 명시적으로 지정한 경우를 제외하고 DDLs를 SharedMergeTree를 사용하도록 재작성
• 4 - 3과 동일하며, 추가로 Distributed 대신 Alias를 사용합니다(Alias table은 Distributed table의 대상 테이블을 가리키므로 해당 로컬 테이블을 사용합니다)

public part를 최소화하기 위한 UInt64

Cloud 기본값: 2.

​

cluster_for_parallel_replicas

현재 서버가 속한 세그먼트의 클러스터

Cloud 기본값: default.

​

cluster_function_process_archive_on_multiple_nodes

true로 설정하면 cluster 함수에서 아카이브를 처리하는 성능이 향상됩니다. 이전 버전에서 아카이브와 함께 cluster 함수를 사용하는 경우, 호환성을 유지하고 25.7+로 업그레이드할 때 오류를 방지하려면 false로 설정해야 합니다.

​

cluster_table_function_buckets_batch_size

bucket 분할 세분화 수준을 사용하는 cluster 테이블 함수에서 작업의 분산 처리에 사용되는 배치의 대략적인 크기(바이트 단위)를 정의합니다. 시스템은 최소 이 크기에 도달할 때까지 데이터를 누적합니다. 실제 크기는 데이터 경계에 맞추기 위해 약간 더 커질 수 있습니다.

​

cluster_table_function_split_granularity

CLUSTER TABLE FUNCTION을 실행할 때 데이터를 작업으로 어떻게 나눌지 제어합니다.

이 설정은 클러스터 전체에 작업을 분산할 때의 세분화 수준을 정의합니다:

• file — 각 작업이 파일 전체를 처리합니다.
• bucket — 파일 내부의 데이터 블록별로 작업을 생성합니다(예: Parquet row group).

소수의 대용량 파일을 처리할 때는 bucket과 같이 더 세밀한 세분화 수준을 선택하면 병렬성을 높일 수 있습니다. 예를 들어 Parquet 파일에 여러 row group이 포함된 경우, bucket 세분화 수준을 사용하면 각 group을 서로 다른 워커가 독립적으로 처리할 수 있습니다.

​

collect_hash_table_stats_during_aggregation

메모리 할당을 최적화하기 위해 해시 테이블 통계를 수집하도록 설정합니다

​

collect_hash_table_stats_during_joins

메모리 할당을 최적화하기 위해 해시 테이블 통계를 수집하도록 합니다.

​

호환성

compatibility 설정을 사용하면, 설정에 지정한 이전 버전의 ClickHouse 기본 설정을 ClickHouse에서 사용합니다.

일부 설정이 기본값이 아닌 값으로 지정되어 있으면 해당 설정값은 그대로 유지됩니다(compatibility 설정은 수정되지 않은 설정에만 적용됩니다).

이 설정에는 22.3, 22.8과 같은 ClickHouse 버전 번호를 문자열로 지정합니다. 빈 값은 이 설정이 비활성화되었음을 의미합니다.

기본값은 비활성화입니다.

ClickHouse Cloud에서는 서비스 수준의 기본 호환성 설정을 ClickHouse Cloud Support에서 설정해야 합니다. 설정이 필요하면 지원 케이스를 제출하세요. 하지만 호환성 설정은 세션에서 SET compatibility = '22.3'를 사용하거나 쿼리에서 SETTINGS compatibility = '22.3'를 사용하는 등 표준 ClickHouse 설정 메커니즘을 통해 사용자, 역할(Role), 프로필(profile), 쿼리 또는 세션(session) 수준에서 재정의할 수 있습니다.

​

compatibility_ignore_auto_increment_in_create_table

true이면 컬럼 선언에서 AUTO_INCREMENT 키워드를 무시하고, 그렇지 않으면 오류를 반환합니다. MySQL에서 마이그레이션을 더 쉽게 수행할 수 있습니다.

​

compatibility_ignore_collation_in_create_table

CREATE TABLE에서 Collation을 무시하는 호환성 설정

​

compatibility_s3_presigned_url_query_in_path

호환성: 활성화하면 사전 서명된 URL 쿼리 매개변수(예: X-Amz-*)를 S3 key에 포함합니다(기존 동작). 따라서 ’?’는 경로에서 와일드카드로 동작합니다. 비활성화하면(기본값) 사전 서명된 URL 쿼리 매개변수는 URL 쿼리에 유지되어 ’?’가 와일드카드로 해석되지 않도록 합니다.

​

compile_aggregate_expressions

집계 함수를 네이티브 코드로 JIT 컴파일할지 여부를 설정합니다. 이 설정을 활성화하면 성능이 향상될 수 있습니다.

가능한 값:

• 0 — JIT 컴파일 없이 집계를 수행합니다.
• 1 — JIT 컴파일을 사용해 집계를 수행합니다.

관련 항목

• min_count_to_compile_aggregate_expression

​

compile_expressions

일부 스칼라 함수와 연산자를 네이티브 코드로 컴파일합니다.

​

compile_sort_description

정렬 설명을 네이티브 코드로 컴파일합니다.

​

connect_timeout

레플리카가 없으면 연결 타임아웃이 적용됩니다.

​

connect_timeout_with_failover_ms

cluster 정의에서 ‘shard’ 및 ‘replica’ 섹션을 사용하는 경우, 분산 테이블 엔진이 원격 서버에 연결할 때 적용되는 밀리초 단위의 timeout입니다. 연결에 실패하면 여러 레플리카에 대해 연결을 여러 번 시도합니다.

​

connect_timeout_with_failover_secure_ms

보안 연결에서 첫 번째 정상 레플리카를 선택하기 위한 연결 타임아웃입니다.

​

connection_pool_max_wait_ms

연결 풀(connection pool)이 가득 찼을 때 연결을 위해 밀리초 단위로 대기하는 시간입니다.

가능한 값:

• 양의 정수입니다.
• 0 — 무한 타임아웃입니다.

​

connections_with_failover_max_tries

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

​

convert_query_to_cnf

true로 설정하면 SELECT 쿼리가 논리곱 정규형(CNF)으로 변환됩니다. 쿼리를 CNF로 재작성하면 더 빠르게 실행될 수 있는 경우가 있습니다(자세한 설명은 이 GitHub issue를 참조하십시오).

예시로, 다음 SELECT 쿼리는 수정되지 않습니다(기본 동작).

EXPLAIN SYNTAX
SELECT *
FROM
(
    SELECT number AS x
    FROM numbers(20)
) AS a
WHERE ((x >= 1) AND (x <= 5)) OR ((x >= 10) AND (x <= 15))
SETTINGS convert_query_to_cnf = false;

결과는 다음과 같습니다:

┌─explain────────────────────────────────────────────────────────┐
│ SELECT x                                                       │
│ FROM                                                           │
│ (                                                              │
│     SELECT number AS x                                         │
│     FROM numbers(20)                                           │
│     WHERE ((x >= 1) AND (x <= 5)) OR ((x >= 10) AND (x <= 15)) │
│ ) AS a                                                         │
│ WHERE ((x >= 1) AND (x <= 5)) OR ((x >= 10) AND (x <= 15))     │
│ SETTINGS convert_query_to_cnf = 0                              │
└────────────────────────────────────────────────────────────────┘

convert_query_to_cnf를 true로 설정한 뒤 어떤 점이 달라지는지 살펴보겠습니다:

EXPLAIN SYNTAX
SELECT *
FROM
(
    SELECT number AS x
    FROM numbers(20)
) AS a
WHERE ((x >= 1) AND (x <= 5)) OR ((x >= 10) AND (x <= 15))
SETTINGS convert_query_to_cnf = true;

WHERE 절은 CNF로 다시 작성되지만, 결과 집합은 완전히 동일합니다. 즉, Boolean 논리는 변경되지 않습니다:

┌─explain───────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ SELECT x                                                                                                              │
│ FROM                                                                                                                  │
│ (                                                                                                                     │
│     SELECT number AS x                                                                                                │
│     FROM numbers(20)                                                                                                  │
│     WHERE ((x <= 15) OR (x <= 5)) AND ((x <= 15) OR (x >= 1)) AND ((x >= 10) OR (x <= 5)) AND ((x >= 10) OR (x >= 1)) │
│ ) AS a                                                                                                                │
│ WHERE ((x >= 10) OR (x >= 1)) AND ((x >= 10) OR (x <= 5)) AND ((x <= 15) OR (x >= 1)) AND ((x <= 15) OR (x <= 5))     │
│ SETTINGS convert_query_to_cnf = 1                                                                                     │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

가능한 값: true, false

​

correlated_subqueries_default_join_kind

상관관계가 제거된 쿼리 계획에서 사용할 조인 종류를 제어합니다. 기본값은 right이며, 이는 상관관계가 제거된 계획에 오른쪽에 서브쿼리 입력이 있는 RIGHT JOIN이 포함된다는 의미입니다.

가능한 값:

• left - 상관관계 제거 과정에서 LEFT JOIN이 생성되며 입력 테이블은 왼쪽에 배치됩니다.
• right - 상관관계 제거 과정에서 RIGHT JOIN이 생성되며 입력 테이블은 오른쪽에 배치됩니다.

​

correlated_subqueries_substitute_equivalent_expressions

CROSS JOIN을 생성하는 대신 필터 표현식을 사용해 동등한 표현식을 추론하고 이를 대체합니다.

​

correlated_subqueries_use_in_memory_buffer

반복 평가를 방지하기 위해 상관 서브쿼리 입력에 인메모리 버퍼를 사용합니다.

​

count_distinct_implementation

COUNT(DISTINCT …) 구문을 실행할 때 사용할 uniq* 함수를 지정합니다.

가능한 값:

• uniq
• uniqCombined
• uniqCombined64
• uniqHLL12
• uniqExact

​

count_distinct_optimization

count distinct를 group by 서브쿼리로 재작성합니다

​

count_matches_stop_at_empty_match

countMatches 함수에서 패턴이 길이가 0인 문자열과 일치하면 개수 계산을 중지합니다.

​

create_if_not_exists

기본적으로 CREATE 문에 IF NOT EXISTS를 적용합니다. 이 설정 또는 IF NOT EXISTS를 지정하고 해당 이름의 테이블이 이미 존재하는 경우 예외가 발생하지 않습니다.

​

create_index_ignore_unique

CREATE UNIQUE INDEX에서 UNIQUE 키워드를 무시합니다. SQL 호환성 테스트용 설정입니다.

​

create_replicated_merge_tree_fault_injection_probability

ZooKeeper에 메타데이터를 생성한 후 테이블 생성 과정에서 장애 주입이 발생할 확률

​

create_table_empty_primary_key_by_default

ORDER BY와 PRIMARY KEY를 지정하지 않은 경우 빈 프라이머리 키를 가진 *MergeTree 테이블을 생성할 수 있도록 합니다

​

cross_join_min_bytes_to_compress

CROSS JOIN에서 압축할 블록의 최소 크기입니다. 값이 0이면 이 임계값이 비활성화됩니다. 이 블록은 두 임계값(행 수 기준 또는 바이트 기준) 중 하나에 도달하면 압축됩니다.

​

cross_join_min_rows_to_compress

CROSS JOIN에서 block을 압축하기 위한 최소 행 수입니다. 값이 0이면 이 임계값을 비활성화한다는 의미입니다. 이 block은 두 임계값(행 수 기준 또는 바이트 기준) 중 하나에 도달하면 압축됩니다.

​

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 or NOT NULL를 지정하지 않은 데이터 타입을 널 허용(Nullable)으로 처리합니다.

가능한 값:

• 1 — 컬럼 정의의 데이터 타입이 기본적으로 Nullable로 설정됩니다.
• 0 — 컬럼 정의의 데이터 타입이 기본적으로 Nullable이 아닌 것으로 설정됩니다.

​

database_atomic_wait_for_drop_and_detach_synchronously

모든 DROP 및 DETACH 쿼리에 SYNC 수정자를 추가합니다.

가능한 값:

• 0 — 쿼리가 지연되어 실행됩니다.
• 1 — 쿼리가 지연 없이 실행됩니다.

​

database_datalake_require_metadata_access

데이터베이스 엔진 DataLakeCatalog에서 테이블 메타데이터를 가져올 권한이 없을 때 오류를 발생시킬지 여부를 지정합니다.

​

database_replicated_allow_explicit_uuid

0 - 복제된 데이터베이스의 테이블에 UUID를 명시적으로 지정할 수 없습니다. 1 - 허용합니다. 2 - 허용하지만 지정된 UUID는 무시하고 대신 임의의 UUID를 생성합니다.

​

database_replicated_allow_heavy_create

Replicated 데이터베이스 엔진에서 오래 실행되는 DDL 쿼리(CREATE AS SELECT 및 POPULATE)를 허용합니다. 다만 이 설정은 DDL 큐를 오랫동안 차단할 수 있습니다.

​

database_replicated_allow_only_replicated_engine

Replicated 엔진을 사용하는 데이터베이스에서는 복제된 테이블만 생성할 수 있습니다.

Cloud 기본값: 1.

​

database_replicated_allow_replicated_engine_arguments

0 - 복제된 데이터베이스의 *MergeTree 테이블에서 ZooKeeper 경로와 레플리카 이름을 명시적으로 지정할 수 없습니다. 1 - 허용합니다. 2 - 허용하지만 지정된 경로는 무시하고 대신 기본 경로를 사용합니다. 3 - 허용하며 경고를 기록하지 않습니다.

​

database_replicated_always_detach_permanently

데이터베이스 엔진이 Replicated인 경우, DETACH TABLE을 DETACH TABLE PERMANENTLY로 실행합니다

​

database_replicated_enforce_synchronous_settings

일부 쿼리에서 동기식 대기를 강제합니다(관련 항목: database_atomic_wait_for_drop_and_detach_synchronously, mutations_sync, alter_sync). 이 설정은 활성화하지 않는 것이 권장되지 않습니다.

​

database_replicated_initial_query_timeout_sec

초기 DDL 쿼리가 복제된 데이터베이스에서 이전 DDL 큐 항목을 처리할 때까지 대기하는 시간을 초 단위로 설정합니다.

가능한 값:

• 양의 정수입니다.
• 0 — 무제한입니다.

​

database_shared_drop_table_delay_seconds

삭제된 테이블이 Shared database에서 실제로 제거되기까지의 지연 시간(초)입니다. 이 시간 내에는 UNDROP TABLE 문을 사용해 테이블을 복구할 수 있습니다.

​

decimal_check_overflow

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

​

종속된 materialized view의 블록 중복 제거

복제된 테이블에서 데이터를 받는 materialized view의 중복 제거 검사 활성화 여부를 설정합니다.

가능한 값:

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

활성화하면 ClickHouse는 복제된 테이블에 종속된 materialized view에서 블록 중복 제거를 수행합니다. 이 설정은 장애로 인해 삽입 작업을 재시도할 때 materialized view에 중복 데이터가 포함되지 않도록 하는 데 유용합니다.

관련 항목

• IN 연산자에서의 NULL 처리

​

deduplicate_insert

INSERT INTO의 블록 중복 제거를 활성화하거나 비활성화합니다(복제된 테이블의 경우). 이 설정은 insert_deduplicate 및 async_insert_deduplicate 설정을 재정의합니다. 이 설정의 가능한 값은 다음 세 가지입니다:

• disable — INSERT INTO 쿼리의 중복 제거를 비활성화합니다.
• enable — INSERT INTO 쿼리의 중복 제거를 활성화합니다.
• backward_compatible_choice — 특정 삽입 유형에서 insert_deduplicate 또는 async_insert_deduplicate가 활성화된 경우 중복 제거를 활성화합니다.

​

deduplicate_insert_select

INSERT SELECT의 블록 중복 제거를 활성화하거나 비활성화합니다(복제된 테이블(Replicated* tables)용). 이 설정은 INSERT SELECT 쿼리에서 insert_deduplicate 및 deduplicate_insert보다 우선 적용됩니다. 이 설정에는 가능한 값이 네 가지 있습니다:

• disable — INSERT SELECT 쿼리의 중복 제거가 비활성화됩니다.
• force_enable — INSERT SELECT 쿼리의 중복 제거가 활성화됩니다. SELECT 결과가 안정적이지 않으면 예외가 발생합니다.
• enable_when_possible — insert_deduplicate가 활성화되어 있고 SELECT 결과가 안정적이면 중복 제거가 활성화되며, 그렇지 않으면 비활성화됩니다.
• enable_even_for_bad_queries - insert_deduplicate가 활성화되어 있으면 중복 제거가 활성화됩니다. SELECT 결과가 안정적이지 않으면 경고가 기록되지만, 쿼리는 중복 제거를 적용한 채 실행됩니다. 이 옵션은 이전 버전과의 호환성을 위한 것입니다. 예기치 않은 결과가 발생할 수 있으므로 가능하면 다른 옵션을 사용하십시오.

​

default_materialized_view_sql_security

materialized view를 생성할 때 SQL SECURITY 옵션의 기본값을 설정할 수 있습니다. SQL security에 대한 자세한 내용.

기본값은 DEFINER입니다.

​

default_max_bytes_in_join

제한이 필요하지만 max_bytes_in_join이 설정되지 않은 경우, 오른쪽 테이블의 최대 크기입니다.

​

default_normal_view_sql_security

일반 뷰 생성 시 기본 SQL SECURITY 옵션을 설정할 수 있습니다. SQL security에 대한 자세한 내용.

기본값은 INVOKER입니다.

​

default_table_engine

CREATE 문에서 ENGINE이 설정되지 않았을 때 사용할 기본 테이블 엔진입니다.

가능한 값:

• 유효한 테이블 엔진 이름을 나타내는 문자열

Cloud 기본값: SharedMergeTree.

예시

쿼리:

SET default_table_engine = 'Log';

SELECT name, value, changed FROM system.settings WHERE name = 'default_table_engine';

결과:

┌─name─────────────────┬─value─┬─changed─┐
│ default_table_engine │ Log   │       1 │
└──────────────────────┴───────┴─────────┘

이 예시에서는 Engine을 지정하지 않은 모든 새 테이블이 Log 테이블 엔진을 사용합니다:

쿼리:

CREATE TABLE my_table (
    x UInt32,
    y UInt32
);

SHOW CREATE TABLE my_table;

결과:

┌─statement────────────────────────────────────────────────────────────────┐
│ CREATE TABLE default.my_table
(
    `x` UInt32,
    `y` UInt32
)
ENGINE = Log
└──────────────────────────────────────────────────────────────────────────┘

​

default_temporary_table_engine

임시 테이블용 default_table_engine과 동일합니다.

이 예시에서는 Engine을 지정하지 않은 새 임시 테이블은 모두 Log 테이블 엔진을 사용합니다:

쿼리:

SET default_temporary_table_engine = 'Log';

CREATE TEMPORARY TABLE my_table (
    x UInt32,
    y UInt32
);

SHOW CREATE TEMPORARY TABLE my_table;

결과:

┌─statement────────────────────────────────────────────────────────────────┐
│ CREATE TEMPORARY TABLE default.my_table
(
    `x` UInt32,
    `y` UInt32
)
ENGINE = Log
└──────────────────────────────────────────────────────────────────────────┘

​

default_view_definer

뷰 생성 시 기본 DEFINER 옵션을 설정할 수 있습니다. SQL security에 대해 자세히 알아보기.

기본값은 CURRENT_USER입니다.

​

defer_partition_pruning_after_final

활성화되면(기본값) 파티션 키 컬럼이 정렬 키의 일부가 아닌 테이블의 FINAL 쿼리에서는 파티션 프루닝이 적용되지 않습니다. 이는 26.3에서 도입된, 정확성을 보장하는 동작입니다. FINAL은 동일한 기본 키(primary key)를 공유하지만 서로 다른 파티션에 있는 행을 중복 제거해야 할 수 있으며, 파티션 프루닝이 적용되면 이런 행이 중복 제거 입력에서 조용히 제외될 수 있습니다.

비활성화되면 FINAL을 사용하더라도 파티션 프루닝이 적용되어 26.3 이전 동작으로 되돌아갑니다. 이는 파티션 컬럼에 대한 WHERE 프레디케이트가 있는 쿼리에서 훨씬 더 빠를 수 있지만, 동일한 기본 키를 가진 행이 서로 다른 파티션에 존재할 수 없을 때만 올바릅니다. 예를 들어, 삽입 시점에 파티션 컬럼이 설정되고 이후에는 절대 변경되지 않는 이벤트 로그 테이블이 이에 해당합니다.

이 설정은 파티션 키 컬럼이 정렬 키에 포함되지 않은 파티션 테이블에만 영향을 미치며, 그 외의 테이블에는 항상 파티션 프루닝이 적용됩니다.

가능한 값:

• 0 — FINAL 전에 파티션 프루닝 적용(26.3 이전 동작, 더 빠르지만 일반적인 경우에는 안전하지 않음).
• 1 — FINAL 이후로 파티션 프루닝 지연(기본값, 정확성 보장).

​

delta_lake_enable_engine_predicate

delta-kernel의 내부 데이터 프루닝을 활성화합니다.

​

delta_lake_enable_expression_visitor_logging

DeltaLake expression visitor의 Test 수준 로그를 활성화합니다. 이 로그는 테스트 로깅에서도 지나치게 상세할 수 있습니다.

​

delta_lake_insert_max_bytes_in_data_file

delta lake에서 단일 데이터 파일에 삽입할 수 있는 최대 바이트 수를 정의합니다.

​

delta_lake_insert_max_rows_in_data_file

delta lake에서 단일 데이터 파일에 삽입할 수 있는 최대 행 수를 정의합니다.

​

delta_lake_log_metadata

delta lake 메타데이터 파일을 system table에 로깅하도록 설정합니다.

​

delta_lake_reload_schema_for_consistency

활성화하면 쿼리 분석에 사용되는 스키마와 실행에 사용되는 스키마 간의 일관성을 보장하기 위해 각 쿼리를 실행하기 전에 DeltaLake 메타데이터에서 스키마를 다시 로드합니다.

​

delta_lake_snapshot_end_version

읽을 delta lake snapshot의 종료 버전입니다. 값이 -1이면 최신 버전을 읽습니다(값 0은 유효한 snapshot 버전입니다).

​

delta_lake_snapshot_start_version

읽을 delta lake snapshot의 시작 버전입니다. 값이 -1이면 최신 버전을 읽으며, 0도 유효한 snapshot version 값입니다.

​

delta_lake_snapshot_version

읽을 Delta Lake 스냅샷 버전입니다. 값이 -1이면 최신 버전을 읽습니다(값 0은 유효한 스냅샷 버전입니다).

​

delta_lake_throw_on_engine_predicate_error

delta-kernel에서 스캔 프레디케이트를 분석하는 중 오류가 발생하면 예외를 발생시키도록 설정합니다.

​

describe_compact_output

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

​

describe_include_subcolumns

DESCRIBE 쿼리에서 서브컬럼도 설명에 포함되도록 합니다. 예를 들어 Tuple의 멤버나 맵, 널 허용, 배열 데이터 타입의 서브컬럼이 이에 해당합니다.

가능한 값:

• 0 — DESCRIBE 쿼리에 서브컬럼이 포함되지 않습니다.
• 1 — DESCRIBE 쿼리에 서브컬럼이 포함됩니다.

예시

DESCRIBE SQL 문 예시를 참조하십시오.

​

describe_include_virtual_columns

값이 true이면 테이블의 가상 컬럼이 DESCRIBE 쿼리 결과에 포함됩니다

​

방언

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

​

dictionary_use_async_executor

딕셔너리 소스를 읽는 파이프라인을 여러 스레드에서 실행합니다. 로컬 CLICKHOUSE 소스를 사용하는 딕셔너리에서만 지원됩니다.

​

dictionary_validate_primary_key_type

딕셔너리의 프라이머리 키 유형을 검증합니다. 기본적으로 단순 레이아웃의 id 유형은 암묵적으로 UInt64로 변환됩니다.

​

distinct_overflow_mode

데이터 양이 제한값 중 하나를 초과할 때 어떻게 처리할지 설정합니다.

가능한 값:

• throw: 예외를 발생시킵니다(기본값).
• break: 쿼리 실행을 중단하고 부분 결과를 반환합니다. 마치 원본 데이터가 소진된 것처럼 동작합니다.

​

distributed_aggregation_memory_efficient

분산 집계의 메모리 절약 모드가 활성화되어 있는지 나타냅니다.

​

distributed_background_insert_batch

별칭: distributed_directory_monitor_batch_inserts

삽입된 데이터의 배치 전송 사용 여부를 설정합니다.

배치 전송이 활성화되면 분산 테이블 엔진은 삽입된 데이터의 여러 파일을 각각 따로 전송하는 대신 한 번의 작업으로 함께 전송하려고 시도합니다. 배치 전송은 서버 및 네트워크 리소스를 더 효율적으로 활용하여 클러스터 성능을 향상시킵니다.

가능한 값:

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

​

distributed_background_insert_max_sleep_time_ms

별칭: distributed_directory_monitor_max_sleep_time_ms

분산 테이블 엔진이 데이터를 전송할 때의 최대 인터벌입니다. distributed_background_insert_sleep_time_ms 설정에 지정된 인터벌이 지수적으로 증가하는 것을 제한합니다.

가능한 값:

• 밀리초 단위의 양의 정수입니다.

​

distributed_background_insert_sleep_time_ms

별칭: distributed_directory_monitor_sleep_time_ms

분산 테이블 엔진이 데이터를 전송할 때 사용하는 기본 인터벌입니다. 실제 인터벌은 오류 발생 시 지수적으로 증가합니다.

가능한 값:

• 밀리초 단위의 양의 정수입니다.

​

distributed_background_insert_split_batch_on_failure

별칭: distributed_directory_monitor_split_batch_on_failure

실패 시 배치를 분할하는 기능을 활성화하거나 비활성화합니다.

경우에 따라 원격 세그먼트로 특정 배치를 전송하는 작업이, 이후의 복잡한 파이프라인(예: GROUP BY가 포함된 MATERIALIZED VIEW) 때문에 Memory limit exceeded 또는 이와 유사한 오류로 실패할 수 있습니다. 이 경우 재시도해도 도움이 되지 않으며(그 결과 해당 테이블의 분산 전송이 멈출 수 있습니다), 해당 배치의 파일을 하나씩 전송하면 INSERT가 성공할 수 있습니다.

따라서 이 설정을 1로 지정하면 이러한 배치에 대해서는 배칭이 비활성화됩니다(즉, 실패한 배치에 대해 distributed_background_insert_batch를 일시적으로 비활성화합니다).

가능한 값:

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

이 설정은 손상된 배치에도 영향을 미칩니다(비정상적인 server(머신) 종료가 발생하고 분산 테이블 엔진에 fsync_after_insert/fsync_directories가 설정되지 않은 경우 이러한 배치가 나타날 수 있습니다).

이 기능은 성능에 악영향을 줄 수 있으므로 자동 배치 분할에 의존하지 마십시오.

​

distributed_background_insert_timeout

별칭: insert_distributed_timeout

분산 테이블에 대한 삽입 쿼리의 시간 초과입니다. 이 설정은 insert_distributed_sync가 활성화된 경우에만 사용됩니다. 값이 0이면 시간 초과가 없음을 의미합니다.

​

distributed_cache_alignment

ClickHouse Cloud에서만 적용됩니다. 테스트용 설정이므로 변경하지 마십시오.

​

distributed_cache_bypass_connection_pool

ClickHouse Cloud에서만 효과가 있습니다. Distributed Cache 연결 풀을 우회할 수 있도록 허용합니다

​

distributed_cache_connect_backoff_max_ms

ClickHouse Cloud에서만 적용됩니다. Distributed Cache 연결 생성 시 최대 백오프 시간(밀리초)입니다.

​

distributed_cache_connect_backoff_min_ms

ClickHouse Cloud에서만 효과가 있습니다. Distributed Cache 연결 생성의 최소 백오프 시간(밀리초)입니다.

​

distributed_cache_connect_max_tries

ClickHouse Cloud에서만 적용됩니다. 연결에 실패한 경우 Distributed Cache에 다시 연결을 시도하는 횟수입니다

​

distributed_cache_connect_timeout_ms

ClickHouse Cloud에서만 효과가 있습니다. Distributed Cache 서버에 연결할 때의 연결 타임아웃입니다.

​

distributed_cache_credentials_refresh_period_seconds

ClickHouse Cloud에서만 적용됩니다. 자격 증명 갱신 주기입니다.

​

distributed_cache_data_packet_ack_window

ClickHouse Cloud에서만 적용됩니다. 단일 Distributed Cache 읽기 요청에서 DataPacket 시퀀스에 대한 ACK를 전송하는 윈도우입니다

​

distributed_cache_discard_connection_if_unread_data

ClickHouse Cloud에서만 적용됩니다. 읽지 않은 데이터가 일부 있으면 연결을 폐기합니다.

​

distributed_cache_fetch_metrics_only_from_current_az

ClickHouse Cloud에서만 적용됩니다. system.distributed_cache_metrics, system.distributed_cache_events에서는 현재 가용 영역에서만 메트릭을 가져옵니다.

​

distributed_cache_file_cache_name

ClickHouse Cloud에서만 적용됩니다. CI 테스트 전용 설정으로, Distributed Cache에서 사용할 파일 시스템 캐시 이름을 지정합니다.

​

distributed_cache_log_mode

ClickHouse Cloud에서만 효과가 있습니다. system.distributed_cache_log에 기록하는 모드입니다.

​

distributed_cache_max_unacked_inflight_packets

ClickHouse Cloud에서만 적용됩니다. 단일 Distributed Cache 읽기 요청에서 아직 확인 응답을 받지 못한 전송 중 패킷의 최대 개수입니다.

​

distributed_cache_min_bytes_for_seek

ClickHouse Cloud에서만 적용됩니다. Distributed Cache에서 seek를 수행하는 데 필요한 최소 바이트 수입니다.

​

distributed_cache_pool_behaviour_on_limit

ClickHouse Cloud에서만 적용됩니다. pool 한도에 도달했을 때 Distributed Cache 연결의 동작을 지정합니다.

​

distributed_cache_prefer_bigger_buffer_size

ClickHouse Cloud에서만 효과가 있습니다. filesystem_cache_prefer_bigger_buffer_size와 동일하지만 Distributed Cache용입니다.

​

distributed_cache_read_only_from_current_az

ClickHouse Cloud에서만 적용됩니다. 현재 가용 영역에서만 읽도록 허용합니다. 비활성화하면 모든 가용 영역의 모든 캐시 서버에서 읽습니다.

​

distributed_cache_read_request_max_tries

ClickHouse Cloud에서만 적용됩니다. Distributed Cache 읽기 요청이 실패한 경우의 최대 재시도 횟수입니다.

​

distributed_cache_receive_response_wait_milliseconds

ClickHouse Cloud에서만 적용됩니다. Distributed Cache에서 요청에 대한 데이터를 받기까지 대기하는 시간(밀리초)입니다.

​

distributed_cache_receive_timeout_milliseconds

ClickHouse Cloud에서만 적용됩니다. Distributed Cache에서 어떤 종류의 응답이든 수신할 때까지 대기하는 시간을 밀리초 단위로 지정합니다.

Cloud 기본값: 20000.

​

distributed_cache_receive_timeout_ms

ClickHouse Cloud에서만 적용됩니다. Distributed Cache 서버에서 데이터를 수신할 때의 타임아웃이며, 단위는 밀리초입니다. 이 인터벌 동안 바이트를 전혀 수신하지 못하면 예외가 발생합니다.

​

distributed_cache_send_timeout_ms

ClickHouse Cloud에서만 적용됩니다. 분산 캐시 서버로 데이터를 전송할 때의 제한 시간이며, 단위는 밀리초입니다. 클라이언트가 데이터를 전송해야 하지만 이 시간 동안 바이트를 전혀 전송하지 못하면 예외가 발생합니다.

​

distributed_cache_tcp_keep_alive_timeout_ms

ClickHouse Cloud에서만 적용됩니다. TCP가 keepalive 프로브를 보내기 시작하기 전에 Distributed Cache 서버와의 연결이 유휴 상태로 유지되어야 하는 시간을 밀리초 단위로 지정합니다.

​

distributed_cache_throw_on_error

ClickHouse Cloud에서만 적용됩니다. Distributed Cache와 통신하는 중에 발생한 예외나 Distributed Cache로부터 받은 예외를 다시 발생시킵니다. 그렇지 않으면 오류 발생 시 Distributed Cache를 건너뛰도록 폴백합니다.

​

distributed_cache_use_clients_cache_for_read

ClickHouse Cloud에서만 적용됩니다. 읽기 요청에 클라이언트 캐시를 사용합니다.

​

distributed_cache_use_clients_cache_for_write

ClickHouse Cloud에서만 효과가 있습니다. 쓰기 요청에 클라이언트 캐시를 사용합니다.

​

distributed_cache_wait_connection_from_pool_milliseconds

ClickHouse Cloud에서만 적용됩니다. distributed_cache_pool_behaviour_on_limit이 wait인 경우, 연결 풀(connection pool)에서 연결을 얻기까지 대기하는 시간을 밀리초 단위로 지정합니다.

​

distributed_cache_write_request_max_tries

ClickHouse Cloud에서만 적용됩니다. Distributed Cache 쓰기 요청이 실패할 경우 다시 시도하는 횟수입니다.

​

distributed_connections_pool_size

단일 분산 테이블에 대한 모든 쿼리를 분산 처리할 때 원격 서버와 동시에 맺을 수 있는 최대 연결 수입니다. 값은 cluster의 서버 수 이상으로 설정하는 것이 좋습니다.

​

distributed_ddl_entry_format_version

분산 DDL(ON CLUSTER) 쿼리의 호환 버전

Cloud 기본값: 6.

​

distributed_ddl_output_mode

분산 DDL 쿼리 결과의 포맷을 설정합니다.

가능한 값:

• throw — 쿼리가 완료된 모든 호스트의 쿼리 실행 상태가 포함된 결과 집합을 반환합니다. 일부 호스트에서 쿼리가 실패한 경우 첫 번째 예외를 다시 발생시킵니다. 일부 호스트에서 아직 쿼리가 완료되지 않았고 distributed_ddl_task_timeout을 초과한 경우 TIMEOUT_EXCEEDED 예외를 발생시킵니다.
• none — throw와 비슷하지만 분산 DDL 쿼리는 결과 집합을 반환하지 않습니다.
• null_status_on_timeout — 해당 호스트에서 쿼리가 아직 완료되지 않은 경우 TIMEOUT_EXCEEDED를 발생시키는 대신, 결과 집합의 일부 행에서 실행 상태로 NULL을 반환합니다.
• never_throw — 일부 호스트에서 쿼리가 실패한 경우에도 TIMEOUT_EXCEEDED를 발생시키지 않으며 예외도 다시 발생시키지 않습니다.
• none_only_active - none과 비슷하지만 Replicated 데이터베이스의 비활성 레플리카는 기다리지 않습니다. 참고: 이 모드에서는 일부 레플리카에서 쿼리가 실행되지 않았고 나중에 백그라운드에서 실행될 예정인지 파악할 수 없습니다.
• null_status_on_timeout_only_active — null_status_on_timeout과 비슷하지만 Replicated 데이터베이스의 비활성 레플리카는 기다리지 않습니다
• throw_only_active — throw와 비슷하지만 Replicated 데이터베이스의 비활성 레플리카는 기다리지 않습니다

Cloud 기본값: none_only_active.

​

distributed_ddl_task_timeout

클러스터의 모든 호스트로부터 DDL 쿼리 응답을 기다리는 시간 제한을 설정합니다. DDL 요청이 모든 호스트에서 수행되지 않으면 응답에 시간 초과 오류가 포함되며, 요청은 비동기 모드로 실행됩니다. 음수 값은 무제한을 의미합니다.

Possible values:

• 양의 정수.
• 0 — 비동기 모드.
• 음의 정수 — 무제한 시간 초과.

​

distributed_foreground_insert

별칭: insert_distributed_sync

Distributed 테이블에 데이터를 동기식으로 삽입할지 여부를 설정합니다.

기본적으로 Distributed 테이블에 데이터를 삽입하면 ClickHouse 서버는 데이터를 백그라운드 모드로 클러스터 노드에 전송합니다. distributed_foreground_insert=1이면 데이터가 동기식으로 처리되며, 모든 세그먼트에 모든 데이터가 저장된 후에만 INSERT 작업이 성공합니다(internal_replication이 true이면 각 세그먼트에서 최소 1개의 레플리카에 저장).

가능한 값:

• 0 — 데이터가 백그라운드 모드로 삽입됩니다.
• 1 — 데이터가 동기식 모드로 삽입됩니다.

Cloud 기본값: 1.

관련 항목

• 분산 테이블 엔진
• 분산 테이블 관리

​

distributed_group_by_no_merge

분산 쿼리 처리(distributed query processing)에서 서로 다른 서버의 집계 상태를 머지하지 않습니다. 서로 다른 세그먼트에 서로 다른 키가 있음이 확실할 때 사용할 수 있습니다.

가능한 값:

• 0 — 비활성화됨(최종 쿼리 처리는 initiator 노드에서 수행됩니다).
• 1 - 분산 쿼리 처리에서 서로 다른 서버의 집계 상태를 머지하지 않습니다(쿼리는 세그먼트에서 완전히 처리되고 initiator는 데이터만 프록시합니다). 서로 다른 세그먼트에 서로 다른 키가 있음이 확실할 때 사용할 수 있습니다.
• 2 - 1과 같지만 ORDER BY와 LIMIT는 initiator에 적용합니다(distributed_group_by_no_merge=1처럼 쿼리가 원격 노드에서 완전히 처리되는 경우에는 불가능함). ORDER BY 및/또는 LIMIT가 있는 쿼리에 사용할 수 있습니다.

예시

SELECT *
FROM remote('127.0.0.{2,3}', system.one)
GROUP BY dummy
LIMIT 1
SETTINGS distributed_group_by_no_merge = 1
FORMAT PrettyCompactMonoBlock

┌─dummy─┐
│     0 │
│     0 │
└───────┘

SELECT *
FROM remote('127.0.0.{2,3}', system.one)
GROUP BY dummy
LIMIT 1
SETTINGS distributed_group_by_no_merge = 2
FORMAT PrettyCompactMonoBlock

┌─dummy─┐
│     0 │
└───────┘

​

distributed_index_analysis

인덱스 분석이 레플리카 간에 분산되어 수행됩니다. 공유 스토리지와 클러스터의 대규모 데이터에 유용합니다. cluster_for_parallel_replicas의 레플리카를 사용합니다.

관련 항목

• distributed_index_analysis_for_non_shared_merge_tree
• distributed_index_analysis_min_parts_to_activate
• distributed_index_analysis_min_indexes_bytes_to_activate

​

distributed_index_analysis_for_non_shared_merge_tree

SharedMergeTree가 아닌 엔진(Cloud 전용 엔진)에서도 distributed index analysis를 활성화합니다.

​

distributed_index_analysis_only_on_coordinator

활성화하면 분산 인덱스 분석은 coordinator에서만 수행됩니다. 이렇게 하면 프레디케이트에 서브쿼리(예: IN (SELECT ...))가 포함될 때 생성되는 O(N^2) 쿼리를 방지할 수 있습니다. 그렇지 않으면 각 팔로워 레플리카가 자체 분산 인덱스 분석을 개별적으로 트리거하기 때문입니다. 다만 서브쿼리에서 큰 테이블을 사용하는 경우에는 분산 인덱스 분석의 효율성이 떨어집니다.

​

distributed_insert_skip_read_only_replicas

분산 테이블에 대한 INSERT 쿼리에서 읽기 전용 레플리카를 건너뛸지 여부를 설정합니다.

가능한 값:

• 0 — INSERT가 평소처럼 수행되며, 읽기 전용 레플리카로 전송되면 실패합니다
• 1 — 시작 노드가 데이터를 세그먼트로 보내기 전에 읽기 전용 레플리카를 건너뜁니다.

​

distributed_plan_default_reader_bucket_count

분산 쿼리의 병렬 읽기에 사용되는 기본 작업 수입니다. 작업은 레플리카 간에 분배됩니다.

​

distributed_plan_default_shuffle_join_bucket_count

분산 shuffle-hash-join의 기본 버킷 개수입니다.

​

distributed_plan_execute_locally

분산 쿼리 계획의 모든 작업을 로컬에서 실행합니다. 테스트와 디버깅에 유용합니다.

​

distributed_plan_force_exchange_kind

분산 쿼리 단계 간에 지정된 종류의 Exchange 연산자를 강제로 사용합니다.

가능한 값:

• ” - 어떤 종류의 Exchange 연산자도 강제하지 않고 옵티마이저가 선택하도록 합니다.
• ‘Persisted’ - 객체 스토리지의 임시 파일을 사용합니다.
• ‘Streaming’ - 네트워크를 통해 exchange 데이터를 스트리밍합니다.

​

distributed_plan_force_shuffle_aggregation

분산 쿼리 계획에서 PartialAggregation + Merge 대신 Shuffle 집계 전략을 사용합니다.

​

distributed_plan_max_rows_to_broadcast

분산 쿼리 계획에서 shuffle join 대신 broadcast join을 사용하기 위한 최대 행 수입니다.

​

distributed_plan_optimize_exchanges

분산 쿼리 계획에서 불필요한 exchange를 제거합니다. 디버깅할 때는 비활성화하십시오.

​

distributed_plan_prefer_replicas_over_workers

레플리카에서 실행하기 위해 분산 쿼리 계획을 직렬화합니다.

​

distributed_product_mode

분산 서브쿼리의 동작 방식을 변경합니다.

ClickHouse는 쿼리에 분산 테이블의 곱이 포함된 경우, 즉 분산 테이블에 대한 쿼리에 분산 테이블에 대한 non-GLOBAL 서브쿼리가 포함된 경우 이 설정을 적용합니다.

제한 사항:

• IN 및 JOIN 서브쿼리에만 적용됩니다.
• FROM 절에서 2개 이상의 세그먼트를 포함하는 분산 테이블을 사용하는 경우에만 적용됩니다.
• 서브쿼리가 2개 이상의 세그먼트를 포함하는 분산 테이블과 관련된 경우에만 적용됩니다.
• 테이블 값 함수인 remote에는 사용되지 않습니다.

가능한 값:

• deny — 기본값입니다. 이러한 유형의 서브쿼리 사용을 금지합니다(“Double-distributed in/JOIN subqueries is denied” 예외를 반환합니다).
• local — 대상 서버(세그먼트)에 맞게 서브쿼리의 데이터베이스와 테이블을 로컬 것으로 대체하고, 일반 IN/JOIN.은 그대로 유지합니다.
• global — IN/JOIN 쿼리를 GLOBAL IN/GLOBAL JOIN.으로 대체합니다.
• allow — 이러한 유형의 서브쿼리 사용을 허용합니다.

​

distributed_push_down_limit

각 세그먼트에 LIMIT를 개별적으로 적용할지 여부를 활성화하거나 비활성화합니다.

이를 통해 다음을 방지할 수 있습니다.

• 네트워크를 통해 불필요한 추가 행을 전송하는 것
• initiator 노드에서 LIMIT를 초과하는 행을 처리하는 것

21.9 버전부터는 distributed_push_down_limit가 다음 조건 중 하나 이상을 만족하는 경우에만 쿼리 실행 방식을 변경하므로, 더 이상 부정확한 결과가 발생하지 않습니다.

• distributed_group_by_no_merge > 0.
• 쿼리에 GROUP BY/DISTINCT/LIMIT BY는 없고, ORDER BY/LIMIT는 있습니다.
• 쿼리에 GROUP BY/DISTINCT/LIMIT BY와 ORDER BY/LIMIT가 있으며, 다음 조건을 만족합니다.
  • optimize_skip_unused_shards가 활성화되어 있습니다.
  • optimize_distributed_group_by_sharding_key가 활성화되어 있습니다.

가능한 값:

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

관련 항목:

• distributed_group_by_no_merge
• optimize_skip_unused_shards
• optimize_distributed_group_by_sharding_key

​

distributed_replica_error_cap

• 유형: 부호 없는 정수
• 기본값: 1000

각 레플리카의 오류 수는 이 값까지만 반영되므로, 단일 레플리카에 오류가 과도하게 누적되는 것을 방지합니다.

관련 항목:

• load_balancing
• 테이블 엔진 Distributed
• distributed_replica_error_half_life
• distributed_replica_max_ignored_errors

​

distributed_replica_error_half_life

• 유형: 초
• 기본값: 60초

분산 테이블의 오류 수가 얼마나 빠르게 0으로 감소하는지 제어합니다. 레플리카를 한동안 사용할 수 없어 오류가 5개 누적되었고 distributed_replica_error_half_life가 1초로 설정된 경우, 마지막 오류 발생 후 3초가 지나면 해당 레플리카는 정상으로 간주됩니다.

관련 항목:

• load_balancing
• 테이블 엔진 Distributed
• distributed_replica_error_cap
• distributed_replica_max_ignored_errors

​

distributed_replica_max_ignored_errors

• 유형: unsigned int
• 기본값: 0

레플리카를 선택할 때(load_balancing 알고리즘 기준) 무시할 오류 수입니다.

관련 항목:

• load_balancing
• 테이블 엔진 Distributed
• distributed_replica_error_cap
• distributed_replica_error_half_life

​

do_not_merge_across_partitions_select_final

서로 다른 파티션 간 머지를 방지하여 FINAL 쿼리 성능을 개선합니다.

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

​

dynamic_disk_allow_from_env

동적 디스크 구성, 즉 disk() 함수의 인수에서 from_env 치환을 사용할 수 있도록 합니다. 테이블 스토리지를 정의할 때 사용자가 임의의 환경 변수를 읽지 못하도록 기본적으로 비활성화되어 있습니다.

​

dynamic_disk_allow_from_zk

동적 디스크 구성(즉, disk() 함수의 인수)에서 from_zk 치환을 사용할 수 있도록 허용합니다. 기본적으로 비활성화되어 있습니다.

​

dynamic_disk_allow_include

동적 디스크 구성(즉, disk() 함수의 인수)에서 include를 사용할 수 있도록 합니다. 기본적으로 비활성화되어 있습니다.

​

dynamic_throw_on_type_mismatch

기본 구현을 사용해 Dynamic 컬럼에 함수를 적용할 때, 실제 타입이 해당 함수와 호환되지 않는 행에서 어떻게 처리할지 제어합니다:

• true (기본값) — 예외를 발생시킵니다.
• false — 대신 해당 행에는 NULL을 반환합니다.

​

empty_result_for_aggregation_by_constant_keys_on_empty_set

빈 입력 집합에서 상수 키를 기준으로 집계할 때 빈 결과를 반환합니다.

​

empty_result_for_aggregation_by_empty_set

빈 집합에 대해 키 없이 집계할 때 빈 결과를 반환합니다.

​

enable_adaptive_memory_spill_scheduler

processor가 데이터를 외부 스토리지로 적응적으로 spill하도록 트리거합니다. 현재는 grace join만 지원됩니다.

​

enable_add_distinct_to_in_subqueries

IN 서브쿼리에서 DISTINCT를 활성화합니다. 이 설정은 트레이드오프가 있는 설정입니다. 활성화하면 고유한 값만 전송되므로 분산 IN 서브쿼리용으로 전송되는 임시 테이블의 크기를 크게 줄일 수 있으며, 세그먼트 간 데이터 전송도 상당히 빨라질 수 있습니다. 하지만 이 설정을 활성화하면 중복 제거(DISTINCT)를 수행해야 하므로 각 노드에서 추가 병합 작업이 필요합니다. 네트워크 전송이 병목이고 추가 병합 비용을 감수할 수 있다면 이 설정을 사용하십시오.

​

enable_automatic_decision_for_merging_across_partitions_for_final

이 설정을 사용하면 파티션 키 표현식이 결정적이고, 파티션 키 표현식에 사용된 모든 컬럼이 기본 키에 포함되어 있을 때 ClickHouse가 이 최적화를 자동으로 활성화합니다. 이 자동 판단을 통해 동일한 기본 키 값을 가진 행은 항상 같은 파티션에 속하게 되므로, 파티션 간 머지를 피해도 안전합니다.

​

enable_blob_storage_log

blob storage 작업 정보를 system.blob_storage_log 테이블에 기록합니다

​

enable_blob_storage_log_for_read_operations

blob storage 읽기 작업 정보를 system.blob_storage_log 테이블에 기록합니다. enable_blob_storage_log도 활성화되어 있어야 합니다.

​

enable_early_constant_folding

함수와 서브쿼리의 결과를 분석해 상수가 있으면 쿼리를 재작성하는 쿼리 최적화를 활성화합니다

​

enable_extended_results_for_datetime_functions

확장된 범위의 Date32(Date 타입 대비) 또는 DateTime64(DateTime 타입 대비) 결과를 반환할지 여부를 활성화하거나 비활성화합니다.

Possible values:

• 0 — 함수는 모든 인수 타입에 대해 Date 또는 DateTime을 반환합니다.
• 1 — 함수는 인수가 Date32 또는 DateTime64인 경우 Date32 또는 DateTime64를 반환하고, 그 외의 경우에는 Date 또는 DateTime을 반환합니다.

아래 표는 다양한 날짜-시간 함수에서 이 설정이 어떻게 동작하는지 보여줍니다.

함수	enable_extended_results_for_datetime_functions = 0	enable_extended_results_for_datetime_functions = 1
toStartOfYear	Date 또는 DateTime을 반환	Date/DateTime 입력 시 Date/DateTime을 반환합니다 Date32/DateTime64 입력 시 Date32/DateTime64를 반환합니다
toStartOfISOYear	Date 또는 DateTime을 반환	Date/DateTime 입력 시 Date/DateTime을 반환합니다 Date32/DateTime64 입력 시 Date32/DateTime64를 반환합니다
toStartOfQuarter	Date 또는 DateTime을 반환합니다	Date/DateTime 입력 시 Date/DateTime을 반환합니다 Date32/DateTime64 입력 시 Date32/DateTime64를 반환합니다
toStartOfMonth	Date 또는 DateTime을 반환	Date/DateTime 입력에는 Date/DateTime를 반환합니다 Date32/DateTime64 입력에는 Date32/DateTime64를 반환합니다
toStartOfWeek	Date 또는 DateTime 반환	Date/DateTime 입력 시 Date/DateTime을 반환합니다 Date32/DateTime64 입력 시 Date32/DateTime64를 반환합니다
toLastDayOfWeek	Date 또는 DateTime을 반환	Date/DateTime 입력의 경우 Date/DateTime을 반환합니다 Date32/DateTime64 입력의 경우 Date32/DateTime64를 반환합니다
toLastDayOfMonth	Date 또는 DateTime을 반환합니다	Date/DateTime 입력 시 Date/DateTime을 반환합니다 Date32/DateTime64 입력 시 Date32/DateTime64를 반환합니다
toMonday	Date 또는 DateTime 반환	Date/DateTime 입력에는 Date/DateTime이 반환됩니다 Date32/DateTime64 입력에는 Date32/DateTime64가 반환됩니다
toStartOfDay	DateTime을 반환합니다 참고: 1970-2149 범위를 벗어난 값에서는 잘못된 결과가 반환됩니다	Date/DateTime 입력의 경우 DateTime을 반환합니다 Date32/DateTime64 입력의 경우 DateTime64를 반환합니다
toStartOfHour	DateTime을 반환합니다 참고: 1970-2149 범위를 벗어나는 값은 잘못된 결과를 반환할 수 있습니다.	Date/DateTime 입력의 경우 DateTime을 반환합니다 Date32/DateTime64 입력의 경우 DateTime64를 반환합니다
toStartOfFifteenMinutes	DateTime을 반환합니다 참고: 1970-2149 범위를 벗어나는 값에 대해서는 잘못된 결과가 반환됩니다.	Date/DateTime 입력의 경우 DateTime을 반환합니다 Date32/DateTime64 입력의 경우 DateTime64를 반환합니다
toStartOfTenMinutes	DateTime을 반환합니다 참고: 1970-2149 범위를 벗어나는 값에서는 잘못된 결과가 반환됩니다	Date/DateTime 입력에는 DateTime을 반환합니다 Date32/DateTime64 입력에는 DateTime64를 반환합니다
toStartOfFiveMinutes	DateTime을 반환합니다 참고: 1970-2149 범위를 벗어나는 값에서는 잘못된 결과가 반환됩니다	Date/DateTime 입력 시 DateTime을 반환합니다 Date32/DateTime64 입력 시 DateTime64를 반환합니다
toStartOfMinute	DateTime을 반환합니다 참고: 1970-2149 범위를 벗어나는 값에 대해서는 잘못된 결과가 반환됩니다	Date/DateTime 입력에는 DateTime을 반환합니다 Date32/DateTime64 입력에는 DateTime64를 반환합니다
timeSlot	DateTime을 반환합니다 참고: 1970-2149 범위를 벗어나는 값에서는 잘못된 결과가 반환됩니다	Date/DateTime 입력의 경우 DateTime을 반환합니다 Date32/DateTime64 입력의 경우 DateTime64를 반환합니다

​

enable_filesystem_cache

원격 파일 시스템에 캐시를 사용합니다. 이 설정은 디스크의 캐시를 켜거나 끄는 기능은 아니며(디스크 구성에서 설정해야 함), 필요에 따라 일부 쿼리에서 캐시를 우회할 수 있게 합니다.

​

enable_filesystem_cache_log

각 쿼리에 대한 파일 시스템 캐시 로그를 기록할 수 있습니다

​

enable_filesystem_cache_on_write_operations

write-through 캐시를 활성화하거나 비활성화합니다. false로 설정하면 쓰기 작업에서 write-through 캐시가 비활성화됩니다. true로 설정하면 server config의 cache disk 구성 섹션에서 cache_on_write_operations가 활성화되어 있는 경우 write-through 캐시가 활성화됩니다. 자세한 내용은 “로컬 캐시 사용”을 참조하십시오.

Cloud 기본값: 1.

​

enable_filesystem_read_prefetches_log

쿼리 실행 중 system.filesystem prefetch_log에 기록합니다. 테스트 또는 디버깅 용도로만 사용해야 하며, 기본적으로 활성화하는 것은 권장되지 않습니다.

​

enable_full_text_index

별칭: allow_experimental_full_text_index

true로 설정하면 텍스트 인덱스 사용을 허용합니다.

​

enable_global_with_statement

WITH 문을 UNION 쿼리와 모든 서브쿼리에 전파합니다

​

enable_hdfs_pread

HDFS 파일에서 pread 사용 여부를 설정합니다. 기본적으로 hdfsPread를 사용합니다. 비활성화하면 HDFS 파일을 읽을 때 hdfsRead와 hdfsSeek를 사용합니다.

​

enable_http_compression

HTTP 요청에 대한 응답에서 데이터 압축을 활성화하거나 비활성화합니다.

자세한 내용은 HTTP 인터페이스 설명을 참조하십시오.

가능한 값:

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

​

enable_job_stack_trace

job 실행 결과 예외가 발생하면 job 생성자의 스택 트레이스를 출력합니다. 성능 오버헤드를 방지하기 위해 기본적으로 비활성화됩니다.

​

enable_join_fixed_hash_table_conversion

키가 값 범위가 작은 단일 정수일 때 조인을 위해 해시 테이블을 평면 배열로 변환할 수 있게 합니다.

​

enable_join_runtime_filters

런타임에 오른쪽에서 수집한 JOIN 키 집합을 사용해 왼쪽을 필터링합니다.

​

enable_join_transitive_predicates

기존 join 조건에서 전이적 동등 join 프레디케이트를 추론합니다. 예를 들어 A.x = B.x 및 B.x = C.x가 주어지면, 생성된 A.x = C.x 프레디케이트가 추가되어 join 순서 옵티마이저가 직접적인 (A JOIN C) 계획을 고려할 수 있습니다.

​

enable_lazy_columns_replication

JOIN 및 ARRAY JOIN에서 지연 컬럼 복제를 활성화합니다. 이를 통해 메모리에서 동일한 행을 여러 번 불필요하게 복사하지 않아도 됩니다.

​

enable_lightweight_delete

별칭: allow_experimental_lightweight_delete

MergeTree 테이블에서 경량한 삭제 DELETE 뮤테이션을 활성화합니다.

​

enable_lightweight_update

별칭: allow_experimental_lightweight_update

경량 업데이트를 사용할 수 있게 합니다.

​

enable_materialized_cte

구체화된 공통 테이블 표현식을 활성화합니다. 이 설정은 enable_global_with_statement보다 우선 적용됩니다.

​

enable_memory_bound_merging_of_aggregation_results

집계에 메모리 제한 기반 병합 전략을 사용하도록 설정합니다.

​

enable_multiple_prewhere_read_steps

AND로 결합된 조건이 여러 개 있으면 WHERE의 더 많은 조건을 PREWHERE로 이동하고, 디스크 읽기와 필터링을 여러 단계에 걸쳐 수행합니다

​

enable_named_columns_in_function_tuple

모든 이름이 고유하고 따옴표 없이 식별자로 취급할 수 있으면 function tuple()에서 이름이 지정된 Tuple을 생성합니다.

​

enable_optimize_predicate_expression

SELECT 쿼리에서 프레디케이트 푸시다운을 활성화합니다.

프레디케이트 푸시다운은 분산 쿼리의 네트워크 트래픽을 크게 줄일 수 있습니다.

가능한 값:

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

사용법

다음 쿼리를 살펴보십시오:

1. SELECT count() FROM test_table WHERE date = '2018-10-10'
2. SELECT count() FROM (SELECT * FROM test_table) WHERE date = '2018-10-10'

enable_optimize_predicate_expression = 1이면 ClickHouse가 처리 과정에서 WHERE를 서브쿼리에 적용하므로, 두 쿼리의 실행 시간은 동일합니다.

enable_optimize_predicate_expression = 0이면 서브쿼리가 끝난 후 WHERE 절이 전체 데이터에 적용되므로, 두 번째 쿼리의 실행 시간이 훨씬 길어집니다.

​

enable_optimize_predicate_expression_to_final_subquery

프레디케이트를 final subquery로 푸시하는 것을 허용합니다.

​

enable_order_by_all

ORDER BY ALL 구문을 사용한 정렬 기능을 활성화하거나 비활성화합니다. 자세한 내용은 ORDER BY를 참조하십시오.

가능한 값:

• 0 — ORDER BY ALL을 비활성화합니다.
• 1 — ORDER BY ALL을 활성화합니다.

예시

쿼리:

CREATE TABLE TAB(C1 Int, C2 Int, ALL Int) ENGINE=Memory();

INSERT INTO TAB VALUES (10, 20, 30), (20, 20, 10), (30, 10, 20);

SELECT * FROM TAB ORDER BY ALL; -- ALL이 모호하다는 오류 반환

SELECT * FROM TAB ORDER BY ALL SETTINGS enable_order_by_all = 0;

결과:

┌─C1─┬─C2─┬─ALL─┐
│ 20 │ 20 │  10 │
│ 30 │ 10 │  20 │
│ 10 │ 20 │  30 │
└────┴────┴─────┘

​

enable_parallel_blocks_marshalling

분산 쿼리에만 적용됩니다. 활성화되면 블록은 initiator로 전송되기 전/후에 파이프라인 스레드에서 (역)직렬화 및 (역)압축됩니다(즉, 기본 설정보다 더 높은 병렬성으로 처리됩니다).

​

enable_parsing_to_custom_serialization

값이 true이면 테이블에서 얻은 직렬화 힌트에 따라 데이터를 사용자 지정 직렬화(예: Sparse)가 적용된 컬럼으로 직접 파싱할 수 있습니다.

​

enable_positional_arguments

GROUP BY, LIMIT BY, ORDER BY SQL 문에서 위치 인수 지원을 활성화하거나 비활성화합니다.

가능한 값:

• 0 — 위치 인수가 지원되지 않습니다.
• 1 — 위치 인수가 지원됩니다. 컬럼 이름 대신 컬럼 번호를 사용할 수 있습니다.

예시

쿼리:

CREATE TABLE positional_arguments(one Int, two Int, three Int) ENGINE=Memory();

INSERT INTO positional_arguments VALUES (10, 20, 30), (20, 20, 10), (30, 10, 20);

SELECT * FROM positional_arguments ORDER BY 2,3;

결과:

┌─one─┬─two─┬─three─┐
│  30 │  10 │   20  │
│  20 │  20 │   10  │
│  10 │  20 │   30  │
└─────┴─────┴───────┘

​

enable_positional_arguments_for_projections

PROJECTION 정의에서 위치 인수 지원을 활성화하거나 비활성화합니다. 관련 설정인 enable_positional_arguments도 참조하십시오.

이 설정은 전문가 수준의 설정이므로 ClickHouse를 막 시작했다면 변경하지 않는 것이 좋습니다.

가능한 값:

• 0 — 위치 인수가 지원되지 않습니다.
• 1 — 위치 인수가 지원됩니다. 컬럼 이름 대신 컬럼 번호를 사용할 수 있습니다.

​

enable_producing_buckets_out_of_order_in_aggregation

메모리 효율적인 집계(distributed_aggregation_memory_efficient 참조)에서 버킷을 순서와 다르게 생성할 수 있도록 허용합니다. 이 설정을 사용하면 집계 버킷 크기가 한쪽으로 치우친 경우, 레플리카가 id가 낮은 일부 큰 버킷을 계속 처리하는 동안 id가 더 높은 버킷을 initiator에 전송할 수 있어 성능이 향상될 수 있습니다. 단점은 메모리 사용량이 증가할 수 있다는 점입니다.

​

enable_reads_from_query_cache

활성화되어 있으면 SELECT 쿼리 결과를 쿼리 캐시에서 가져옵니다.

가능한 값:

• 0 - 비활성화
• 1 - 활성화

​

enable_s3_requests_logging

S3 요청에 대한 매우 상세한 로깅을 활성화합니다. 디버깅 용도로만 사용하는 것이 적절합니다.

​

enable_scalar_subquery_optimization

true로 설정하면 스칼라 서브쿼리가 큰 스칼라 값을 직렬화/역직렬화하지 않도록 하며, 가능하면 동일한 서브쿼리를 두 번 이상 실행하지 않도록 합니다.

​

enable_scopes_for_with_statement

비활성화하면 상위 WITH 절의 선언은 현재 범위에서 선언된 것처럼 동일한 범위에서 동작합니다.

이 설정은 이전 분석기가 실행할 수 있었던 일부 잘못된 쿼리도 실행할 수 있게 하기 위한 분석기 호환성 설정입니다.

​

enable_shared_storage_snapshot_in_query

활성화하면 단일 쿼리 내의 모든 서브쿼리가 각 테이블에 대해 동일한 StorageSnapshot을 공유합니다. 이렇게 하면 동일한 테이블에 여러 번 액세스하더라도 쿼리 전체에서 데이터에 대한 일관된 보기가 보장됩니다.

이는 데이터 파트의 내부 일관성이 중요한 쿼리에 필요합니다. 예시:

SELECT
    count()
FROM events
WHERE (_part, _part_offset) IN (
    SELECT _part, _part_offset
    FROM events
    WHERE user_id = 42
)

이 설정을 사용하지 않으면 외부 쿼리와 내부 쿼리가 서로 다른 데이터 스냅샷을 기준으로 동작할 수 있어 잘못된 결과가 발생할 수 있습니다.

이 설정을 활성화하면 계획 단계가 끝난 뒤 스냅샷에서 불필요한 데이터 파트를 제거하는 최적화가 비활성화됩니다. 그 결과, 오래 실행되는 쿼리가 실행되는 전체 동안 더 이상 사용되지 않는 파트를 계속 참조할 수 있으므로, 파트 정리가 지연되고 스토리지 부담이 커질 수 있습니다.

이 설정은 현재 MergeTree 엔진 계열의 테이블에만 적용됩니다.

가능한 값:

• 0 - 비활성화됨
• 1 - 활성화됨

​

enable_sharing_sets_for_mutations

IN 서브쿼리를 위해 생성된 Set 객체를 동일한 뮤테이션의 서로 다른 작업 간에 공유할 수 있도록 합니다. 이렇게 하면 메모리 사용량과 CPU 사용량이 줄어듭니다

​

enable_software_prefetch_in_aggregation

집계 시 소프트웨어 프리페치를 사용하도록 설정합니다

​

enable_software_prefetch_in_join

대규모 해시 테이블의 메모리 접근 지연 시간을 완화하기 위해 해시 조인의 프로브 단계에서 소프트웨어 프리페치를 사용하도록 설정합니다.

​

enable_time_time64_type

별칭: allow_experimental_time_time64_type

Time 및 Time64 데이터 타입을 생성할 수 있습니다.

​

enable_unaligned_array_join

크기가 서로 다른 여러 배열에 대해 ARRAY JOIN을 허용합니다. 이 설정을 활성화하면 배열 크기가 가장 긴 배열에 맞춰 조정됩니다.

​

enable_url_encoding

URL 엔진 테이블에서 URI 경로의 디코딩/인코딩을 활성화하거나 비활성화합니다.

기본적으로 비활성화되어 있습니다.

​

enable_vertical_final

활성화하면 FINAL 수행 시 행을 병합하는 대신 행을 삭제된 것으로 표시한 다음 나중에 필터링하여 중복 행을 제거합니다

​

enable_writes_to_query_cache

이 옵션을 활성화하면 SELECT 쿼리의 결과가 쿼리 캐시에 저장됩니다.

Possible values:

• 0 - 비활성화
• 1 - 활성화

​

enforce_strict_identifier_format

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

​

engine_file_allow_create_multiple_files

포맷에 접미사(JSON, ORC, Parquet 등)가 있는 경우, File 엔진 테이블에서 각 삽입 시마다 새 파일을 생성할지 여부를 설정합니다. 이 옵션을 활성화하면 삽입할 때마다 다음 패턴을 따르는 이름의 새 파일이 생성됩니다.

data.Parquet -> data.1.Parquet -> data.2.Parquet 등

가능한 값:

• 0 — INSERT 쿼리가 파일 끝에 새 데이터를 추가합니다.
• 1 — INSERT 쿼리가 새 파일을 생성합니다.

​

engine_file_empty_if_not_exists

파일이 없어도 File 엔진 테이블에서 데이터를 조회할 수 있습니다.

가능한 값:

• 0 — SELECT가 예외를 발생시킵니다.
• 1 — SELECT가 빈 결과를 반환합니다.

​

engine_file_skip_empty_files

File 엔진 테이블에서 빈 파일을 스킵할지 여부를 설정합니다.

가능한 값:

• 0 — 빈 파일이 요청된 포맷과 호환되지 않으면 SELECT가 예외를 발생시킵니다.
• 1 — 빈 파일에 대해 SELECT는 빈 결과를 반환합니다.

​

engine_file_truncate_on_insert

File 엔진 테이블에서 삽입 전에 파일 내용을 비울지 여부를 설정합니다.

가능한 값:

• 0 — INSERT 쿼리는 새 데이터를 파일 끝에 추가합니다.
• 1 — INSERT 쿼리는 파일의 기존 내용을 새 데이터로 대체합니다.

​

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이면 이 설정은 적용되지 않습니다.

예시:

CREATE TABLE tab
(
    a UInt64,
    b UInt64,
    INDEX idx_a a TYPE minmax,
    INDEX idx_b b TYPE set(3)
)
ENGINE = MergeTree ORDER BY tuple();

SET exclude_materialize_skip_indexes_on_insert='idx_a'; -- idx_a는 삽입 시 업데이트되지 않습니다
--SET exclude_materialize_skip_indexes_on_insert='idx_a, idx_b'; -- 두 인덱스 모두 삽입 시 업데이트되지 않습니다

INSERT INTO tab SELECT number, number / 50 FROM numbers(100); -- idx_b만 업데이트됩니다

-- 세션 설정이므로 쿼리 단위로 지정할 수 있습니다
INSERT INTO tab SELECT number, number / 50 FROM numbers(100, 100) SETTINGS exclude_materialize_skip_indexes_on_insert='idx_b';

ALTER TABLE tab MATERIALIZE INDEX idx_a; -- 이 쿼리로 인덱스를 명시적으로 구체화할 수 있습니다

SET exclude_materialize_skip_indexes_on_insert = DEFAULT; -- 설정을 기본값으로 재설정합니다

​

execute_exists_as_scalar_subquery

비상관 EXISTS 서브쿼리를 스칼라 서브쿼리로 실행합니다. 스칼라 서브쿼리와 마찬가지로 캐시가 사용되며, 결과에 상수 폴딩이 적용됩니다.

Cloud 기본값: 0.

​

external_storage_connect_timeout_sec

연결 timeout은 초 단위입니다. 현재는 MySQL에서만 지원됩니다.

​

external_storage_max_read_bytes

external engine를 사용하는 테이블이 이력 데이터를 플러시할 때 최대 바이트 수를 제한합니다. 현재는 MySQL 테이블 엔진, 데이터베이스 엔진, 딕셔너리에서만 지원됩니다. 값이 0이면 이 설정은 비활성화됩니다.

​

external_storage_max_read_rows

외부 엔진이 있는 테이블에서 이력 데이터를 플러시할 때의 최대 행 수를 제한합니다. 현재는 MySQL 테이블 엔진, 데이터베이스 엔진, 딕셔너리에서만 지원됩니다. 값이 0이면 이 설정은 비활성화됩니다.

​

external_storage_rw_timeout_sec

읽기/쓰기 timeout의 초 단위 값입니다. 현재 MySQL에서만 지원됩니다.

​

external_table_functions_use_nulls

mysql, postgresql, odbc 테이블 함수가 널 허용 컬럼을 사용하는 방식을 정의합니다.

가능한 값:

• 0 — 테이블 함수가 널 허용 컬럼을 명시적으로 사용합니다.
• 1 — 테이블 함수가 널 허용 컬럼을 암묵적으로 사용합니다.

사용법

이 설정을 0으로 지정하면 테이블 함수는 널 허용 컬럼을 만들지 않고, NULL 대신 기본값을 삽입합니다. 이는 배열 내부의 NULL 값에도 적용됩니다.

​

external_table_strict_query

true로 설정하면 외부 테이블에 대한 쿼리에서 표현식을 로컬 필터로 변환할 수 없습니다.

​

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는 테이블의 오래된 레플리카 중에서 가장 적합한 레플리카를 선택합니다.

복제된 테이블을 가리키는 분산 테이블에서 SELECT를 수행할 때 사용됩니다.

기본값은 1(활성화)입니다.

​

filesystem_cache_allow_background_download

원격 스토리지에서 읽은 데이터에 대해 파일 시스템 캐시가 백그라운드 다운로드를 큐에 추가하도록 허용합니다. 비활성화하면 현재 쿼리/세션에서는 다운로드가 포그라운드에서 수행됩니다.

​

filesystem_cache_boundary_alignment

파일 시스템 캐시의 경계 정렬입니다. 이 설정은 디스크가 아닌 읽기에만 적용됩니다(예: 원격 테이블 엔진/테이블 함수의 캐시에는 적용되지만, MergeTree 테이블의 Storage 구성에는 적용되지 않습니다). 값이 0이면 정렬을 적용하지 않습니다.

​

filesystem_cache_enable_background_download_during_fetch

ClickHouse Cloud에서만 적용됩니다. 파일 시스템 캐시에서 공간을 예약하기 위해 캐시를 잠그는 데 대기하는 시간

​

filesystem_cache_enable_background_download_for_metadata_files_in_packed_storage

ClickHouse Cloud에서만 효과가 있습니다. 파일 시스템 캐시에서 공간을 예약하기 위해 캐시를 잠그는 데 걸리는 대기 시간

​

filesystem_cache_max_download_size

하나의 쿼리로 다운로드할 수 있는 원격 파일 시스템 캐시의 최대 크기

​

filesystem_cache_name

무상태 테이블 엔진 또는 데이터 레이크에 사용할 파일 시스템 캐시 이름

​

filesystem_cache_prefer_bigger_buffer_size

파일 시스템 캐시가 활성화된 경우, 캐시 성능을 저하시키는 작은 파일 세그먼트의 쓰기를 방지하기 위해 더 큰 버퍼 크기를 선호합니다. 반면, 이 설정을 활성화하면 메모리 사용량이 증가할 수 있습니다.

​

filesystem_cache_reserve_space_wait_lock_timeout_milliseconds

파일 시스템 캐시에서 공간을 예약하기 위해 캐시 잠금을 획득할 때까지 대기하는 시간

​

filesystem_cache_segments_batch_size

read buffer가 캐시에서 요청할 수 있는 단일 파일 세그먼트 배치의 크기를 제한합니다. 값이 너무 낮으면 캐시에 대한 요청이 과도하게 많아지고, 너무 크면 캐시에서의 eviction이 느려질 수 있습니다.

​

filesystem_cache_skip_download_if_exceeds_per_query_cache_write_limit

별칭: skip_download_if_exceeds_query_cache

쿼리 캐시 크기를 초과하면 원격 파일 시스템에서 다운로드를 건너뜁니다

​

filesystem_prefetch_max_memory_usage

프리페치의 최대 메모리 사용량입니다.

Cloud 기본값: 총 메모리의 10%.

​

filesystem_prefetch_step_bytes

바이트 단위의 프리페치 간격입니다. 0은 auto를 의미합니다. 즉, 대략적으로 최적에 가까운 프리페치 간격이 자동으로 결정되지만, 항상 100% 최적이라고는 할 수 없습니다. 실제 값은 설정 filesystem_prefetch_min_bytes_for_single_read_task에 따라 달라질 수 있습니다.

​

filesystem_prefetch_step_marks

마크 기준 프리페치 간격입니다. 0은 auto를 의미합니다. 즉, 대략적으로 최적의 프리페치 간격이 자동으로 결정되지만, 항상 100% 최적은 아닐 수 있습니다. 실제 값은 filesystem_prefetch_min_bytes_for_single_read_task 설정에 따라 달라질 수 있습니다.

​

filesystem_prefetches_limit

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

​

final

쿼리의 모든 테이블에 FINAL 수정자를 자동으로 적용합니다. 여기에는 FINAL을 적용할 수 있는 테이블, 조인된 테이블, 하위 쿼리의 테이블, 그리고 분산 테이블이 포함됩니다.

가능한 값:

• 0 - 비활성화됨
• 1 - 활성화됨

예시:

CREATE TABLE test
(
    key Int64,
    some String
)
ENGINE = ReplacingMergeTree
ORDER BY key;

INSERT INTO test FORMAT Values (1, 'first');
INSERT INTO test FORMAT Values (1, 'second');

SELECT * FROM test;
┌─key─┬─some───┐
│   1 │ second │
└─────┴────────┘
┌─key─┬─some──┐
│   1 │ first │
└─────┴───────┘

SELECT * FROM test SETTINGS final = 1;
┌─key─┬─some───┐
│   1 │ second │
└─────┴────────┘

SET final = 1;
SELECT * FROM test;
┌─key─┬─some───┐
│   1 │ second │
└─────┴────────┘

​

finalize_projection_parts_synchronously

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

​

flatten_nested

nested 컬럼의 데이터 포맷을 설정합니다.

가능한 값:

• 1 — Nested 컬럼이 별도의 배열로 펼쳐집니다.
• 0 — Nested 컬럼이 튜플의 단일 배열로 유지됩니다.

사용법

설정값이 0이면 임의의 중첩 수준을 사용할 수 있습니다.

예시

쿼리:

SET flatten_nested = 1;
CREATE TABLE t_nest (`n` Nested(a UInt32, b UInt32)) ENGINE = MergeTree ORDER BY tuple();

SHOW CREATE TABLE t_nest;

결과:

┌─statement───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ CREATE TABLE default.t_nest
(
    `n.a` Array(UInt32),
    `n.b` Array(UInt32)
)
ENGINE = MergeTree
ORDER BY tuple()
SETTINGS index_granularity = 8192 │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

쿼리:

SET flatten_nested = 0;

CREATE TABLE t_nest (`n` Nested(a UInt32, b UInt32)) ENGINE = MergeTree ORDER BY tuple();

SHOW CREATE TABLE t_nest;

결과:

┌─statement──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ CREATE TABLE default.t_nest
(
    `n` Nested(a UInt32, b UInt32)
)
ENGINE = MergeTree
ORDER BY tuple()
SETTINGS index_granularity = 8192 │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

​

force_aggregate_partitions_independently

적용할 수 있지만 휴리스틱에 따라 사용하지 않도록 결정된 경우에도 이 최적화를 강제로 사용합니다

​

force_aggregation_in_order

이 설정은 서버가 분산 쿼리를 지원하기 위해 내부적으로 사용합니다. 정상 동작에 문제가 생길 수 있으므로 수동으로 변경하지 마십시오. (분산 집계 중 원격 노드에서 순서에 따른 집계를 강제로 사용합니다).

​

force_data_skipping_indices

지정된 data skipping indices가 사용되지 않으면 쿼리 실행을 비활성화합니다.

다음 예시를 살펴보십시오:

CREATE TABLE data
(
    key Int,
    d1 Int,
    d1_null Nullable(Int),
    INDEX d1_idx d1 TYPE minmax GRANULARITY 1,
    INDEX d1_null_idx assumeNotNull(d1_null) TYPE minmax GRANULARITY 1
)
Engine=MergeTree()
ORDER BY key;

SELECT * FROM data_01515;
SELECT * FROM data_01515 SETTINGS force_data_skipping_indices=''; -- 쿼리 실행 시 CANNOT_PARSE_TEXT 오류가 발생합니다.
SELECT * FROM data_01515 SETTINGS force_data_skipping_indices='d1_idx'; -- 쿼리 실행 시 INDEX_NOT_USED 오류가 발생합니다.
SELECT * FROM data_01515 WHERE d1 = 0 SETTINGS force_data_skipping_indices='d1_idx'; -- 정상.
SELECT * FROM data_01515 WHERE d1 = 0 SETTINGS force_data_skipping_indices='`d1_idx`'; -- 정상 (전체 기능 파서 사용 예시).
SELECT * FROM data_01515 WHERE d1 = 0 SETTINGS force_data_skipping_indices='`d1_idx`, d1_null_idx'; -- d1_null_idx가 사용되지 않으므로 쿼리 실행 시 INDEX_NOT_USED 오류가 발생합니다.
SELECT * FROM data_01515 WHERE d1 = 0 AND assumeNotNull(d1_null) = 0 SETTINGS force_data_skipping_indices='`d1_idx`, d1_null_idx'; -- 정상.

​

force_grouping_standard_compatibility

인수가 집계 키로 사용되지 않으면 GROUPING 함수가 1을 반환하도록 합니다

​

force_index_by_date

날짜 기준 인덱스를 사용할 수 없으면 쿼리 실행을 비활성화합니다.

MergeTree 엔진 계열의 테이블에서 작동합니다.

force_index_by_date=1이면 ClickHouse는 쿼리에 데이터 범위를 제한하는 데 사용할 수 있는 날짜 키 조건이 있는지 확인합니다. 적절한 조건이 없으면 예외를 발생시킵니다. 다만, 해당 조건이 실제로 읽어야 하는 데이터 양을 줄이는지는 확인하지 않습니다. 예를 들어 Date != ' 2000-01-01 ' 조건은 테이블의 모든 데이터와 일치하더라도 허용됩니다(즉, 쿼리 실행 시 전체 스캔이 필요합니다). MergeTree 테이블의 데이터 범위에 관한 자세한 내용은 MergeTree를 참조하십시오.

​

force_optimize_projection

프로젝션 최적화가 활성화된 경우(optimize_use_projections 설정 참조) SELECT 쿼리에서 프로젝션을 반드시 사용할지 여부를 설정합니다.

가능한 값:

• 0 — 프로젝션 최적화 사용은 필수가 아닙니다.
• 1 — 프로젝션 최적화 사용이 필수입니다.

​

force_optimize_projection_name

비어 있지 않은 문자열로 설정하면, 이 프로젝션이 쿼리에서 최소 한 번은 사용되는지 확인합니다.

가능한 값:

• string: 쿼리에서 사용되는 프로젝션 이름

​

force_optimize_skip_unused_shards

optimize_skip_unused_shards가 활성화되어 있고 사용되지 않는 세그먼트를 스키핑할 수 없는 경우, 쿼리 실행 허용 여부를 제어합니다. 스키핑할 수 없는 상태에서 이 설정이 활성화되어 있으면 예외가 발생합니다.

가능한 값:

• 0 — 비활성화. ClickHouse는 예외를 발생시키지 않습니다.
• 1 — 활성화. 테이블에 샤딩 키가 있는 경우에만 쿼리 실행이 비활성화됩니다.
• 2 — 활성화. 테이블에 샤딩 키가 정의되어 있는지와 관계없이 쿼리 실행이 비활성화됩니다.

​

force_optimize_skip_unused_shards_nesting

분산 쿼리의 중첩 수준에 따라 force_optimize_skip_unused_shards의 적용 범위를 제어합니다(따라서 이 설정을 사용하려면 force_optimize_skip_unused_shards도 여전히 필요합니다). 이는 한 Distributed 테이블이 다른 Distributed 테이블을 조회하는 경우를 의미합니다.

가능한 값:

• 0 - 비활성화됩니다. force_optimize_skip_unused_shards는 항상 작동합니다.
• 1 — 첫 번째 수준에서만 force_optimize_skip_unused_shards를 활성화합니다.
• 2 — 두 번째 수준까지 force_optimize_skip_unused_shards를 활성화합니다.

​

force_primary_key

프라이머리 키 인덱스를 사용할 수 없으면 쿼리 실행을 비활성화합니다.

MergeTree 엔진 계열의 테이블에서 작동합니다.

force_primary_key=1이면 ClickHouse는 쿼리에 데이터 범위를 제한하는 데 사용할 수 있는 프라이머리 키 조건이 있는지 확인합니다. 적절한 조건이 없으면 예외를 발생시킵니다. 다만, 해당 조건으로 읽어야 하는 데이터 양이 실제로 줄어드는지는 확인하지 않습니다. MergeTree 테이블의 데이터 범위에 관한 자세한 내용은 MergeTree를 참조하십시오.

​

force_remove_data_recursively_on_drop

DROP 쿼리 시 데이터를 재귀적으로 삭제합니다. ‘Directory not empty’ 오류를 방지하지만, 분리된 데이터도 조용히 삭제할 수 있습니다.

​

formatdatetime_e_with_space_padding

함수 formatDateTime의 포매터 ‘%e’는 한 자리 수 일을 앞에 공백 한 칸을 붙여 출력합니다. 예를 들어 ‘2’가 아니라 ’ 2’로 출력됩니다.

​

formatdatetime_f_prints_scale_number_of_digits

함수 ‘formatDateTime’의 Formatter ‘%f’는 DateTime64에서 고정된 6자리가 아니라 scale 값만큼의 자릿수만 출력합니다.

​

formatdatetime_f_prints_single_zero

함수 formatDateTime에서 Formatter ‘%f’는 포맷된 값에 초의 소수 부분이 없으면 0 6개 대신 0 하나를 출력합니다.

​

formatdatetime_format_without_leading_zeros

함수 formatDateTime의 Formatter ‘%c’, ‘%l’, ‘%k’는 월과 시간을 앞의 0 없이 출력합니다.

​

formatdatetime_parsedatetime_m_is_month_name

함수 ‘formatDateTime’ 및 ‘parseDateTime’에서 Formatter ‘%M’은 분 대신 월 이름을 출력하거나 월 이름으로 파싱합니다.

​

fsync_metadata

.sql 파일을 쓸 때 fsync의 사용 여부를 설정합니다. 기본값은 활성화입니다.

서버에 지속적으로 생성되고 삭제되는 아주 작은 테이블이 수백만 개 있다면 이를 비활성화하는 것이 적절할 수 있습니다.

​

function_date_trunc_return_type_behavior

dateTrunc 함수의 반환 유형 동작을 변경할 수 있습니다.

가능한 값:

• 0 - 두 번째 인수가 DateTime64/Date32이면, 첫 번째 인수의 시간 단위와 관계없이 반환 유형은 DateTime64/Date32입니다.
• 1 - Date32의 경우 결과는 항상 Date입니다. DateTime64의 경우 시간 단위가 second 이상이면 결과는 DateTime입니다.

​

function_implementation

특정 대상 또는 variant(실험적)에 사용할 함수 구현을 선택합니다. 비어 있으면 모두 활성화됩니다.

​

function_json_value_return_type_allow_complex

json_value 함수가 구조체, 배열, 맵과 같은 복합 유형을 반환하도록 허용할지 여부를 제어합니다.

SELECT JSON_VALUE('{"hello":{"world":"!"}}', '$.hello') settings function_json_value_return_type_allow_complex=true

┌─JSON_VALUE('{"hello":{"world":"!"}}', '$.hello')─┐
│ {"world":"!"}                                    │
└──────────────────────────────────────────────────┘

1 row in set. Elapsed: 0.001 sec.

가능한 값:

• true — 허용합니다.
• false — 허용하지 않습니다.

​

function_json_value_return_type_allow_nullable

JSON_VALUE 함수에서 값이 없을 때 NULL을 반환하도록 허용할지 제어합니다.

SELECT JSON_VALUE('{"hello":"world"}', '$.b') settings function_json_value_return_type_allow_nullable=true;

┌─JSON_VALUE('{"hello":"world"}', '$.b')─┐
│ ᴺᵁᴸᴸ                                   │
└────────────────────────────────────────┘

1 row in set. Elapsed: 0.001 sec.

가능한 값:

• true — 허용
• false — 허용 안 함

​

function_locate_has_mysql_compatible_argument_order

함수 locate의 인수 순서를 제어합니다.

가능한 값:

• 0 — 함수 locate는 (haystack, needle[, start_pos]) 인수를 허용합니다.
• 1 — 함수 locate는 (needle, haystack[, start_pos]) 인수를 허용합니다. (MySQL 호환 동작)

​

function_range_max_elements_in_block

함수 range로 생성되는 데이터 양에 대한 안전 임계값을 설정합니다. 데이터 블록(block)당 함수가 생성할 수 있는 최대 값 개수를 정의합니다(블록의 각 행에 있는 배열 크기의 합계).

가능한 값:

• 양의 정수.

관련 항목

• max_block_size
• min_insert_block_size_rows

​

function_sleep_max_microseconds_per_block

함수 sleep이 각 블록(block)에서 대기할 수 있는 최대 마이크로초 수입니다. 이보다 큰 값으로 호출하면 예외가 발생합니다. 이는 안전 임계값입니다.

​

function_visible_width_behavior

visibleWidth 동작의 버전입니다. 0 - code point 개수만 계산합니다. 1 - 너비가 0인 문자와 결합 문자를 정확히 계산하고, 전각 문자는 2로 계산하며, 탭 너비를 추정하고, 삭제 문자도 계산합니다.

​

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

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

​

grace_hash_join_initial_buckets

grace hash join의 초기 버킷 수

​

grace_hash_join_max_buckets

grace hash join 버킷 수의 최대값

​

group_by_overflow_mode

집계할 고유 키 수가 제한을 초과할 때 어떤 동작을 수행할지 설정합니다:

• throw: 예외를 발생시킵니다
• break: 쿼리 실행을 중지하고 부분 결과를 반환합니다
• any: 집합에 이미 들어간 키에 대해서만 집계를 계속하고, 새 키는 집합에 추가하지 않습니다.

any 값을 사용하면 GROUP BY의 근사 계산을 수행할 수 있습니다. 이 근사 계산의 품질은 데이터의 통계적 특성에 따라 달라집니다.

​

group_by_two_level_threshold

키 수가 몇 개부터 2단계 집계가 시작되는지를 지정합니다. 0은 임계값이 설정되지 않았음을 의미합니다.

​

group_by_two_level_threshold_bytes

집계 상태의 크기가 몇 바이트 이상일 때 2단계 집계를 사용하기 시작하는지 지정합니다. 0이면 임계값이 설정되지 않습니다. 임계값 중 하나 이상에 도달하면 2단계 집계를 사용합니다.

​

group_by_use_nulls

GROUP BY 절이 집계 키 타입을 처리하는 방식을 변경합니다. ROLLUP, CUBE 또는 GROUPING SETS 지정자를 사용하면 일부 결과 행을 생성할 때 일부 집계 키가 사용되지 않을 수 있습니다. 이러한 키에 해당하는 컬럼은 이 설정에 따라 해당 행에서 기본값 또는 NULL로 채워집니다.

가능한 값:

• 0 — 누락된 값을 채울 때 집계 키 타입의 기본값을 사용합니다.
• 1 — ClickHouse는 SQL 표준에 정의된 방식과 동일하게 GROUP BY를 실행합니다. 집계 키 타입은 널 허용으로 변환됩니다. 해당 집계 키가 사용되지 않은 행의 컬럼은 NULL로 채워집니다.

관련 항목:

• GROUP BY 절

​

h3togeo_lon_lat_result_order

함수 h3ToGeo는 값이 true이면 (lon, lat)을, 그렇지 않으면 (lat, lon)을 반환합니다.

​

handshake_timeout_ms

핸드셰이크 중 레플리카로부터 Hello 패킷을 수신할 때 적용되는 밀리초 단위의 타임아웃입니다.

​

hdfs_create_new_file_on_insert

HDFS 엔진 테이블에서 각 삽입 시 새 파일을 생성할지 여부를 설정합니다. 활성화하면 삽입할 때마다 다음과 유사한 이름의 새 HDFS 파일이 생성됩니다.

초기: data.Parquet.gz -> data.1.Parquet.gz -> data.2.Parquet.gz 등입니다.

가능한 값:

• 0 — INSERT 쿼리가 파일 끝에 새 데이터를 추가합니다.
• 1 — INSERT 쿼리가 새 파일을 생성합니다.

​

hdfs_ignore_file_doesnt_exist

특정 키를 읽을 때 파일이 존재하지 않으면 해당 파일의 부재를 무시합니다.

가능한 값:

• 1 — SELECT는 빈 결과를 반환합니다.
• 0 — SELECT는 예외를 발생시킵니다.

​

hdfs_replication

실제 복제본 수는 hdfs 파일을 생성할 때 지정할 수 있습니다.

​

hdfs_skip_empty_files

HDFS 엔진 테이블에서 빈 파일을 스키핑할지 설정합니다.

Possible values:

• 0 — 빈 파일이 요청한 포맷과 호환되지 않으면 SELECT가 예외를 발생시킵니다.
• 1 — 빈 파일이면 SELECT가 빈 결과를 반환합니다.

​

hdfs_throw_on_zero_files_match

glob 확장 규칙에 따라 일치하는 파일이 0개이면 오류를 발생시킵니다.

가능한 값:

• 1 — SELECT는 예외를 발생시킵니다.
• 0 — SELECT는 빈 결과를 반환합니다.

​

hdfs_truncate_on_insert

HDFS 엔진 테이블에서 삽입 전에 파일을 비울지 여부를 설정합니다. 비활성화된 경우 HDFS에 해당 파일이 이미 있으면 삽입을 시도할 때 예외가 발생합니다.

가능한 값:

• 0 — INSERT 쿼리는 파일 끝에 새 데이터를 추가합니다.
• 1 — INSERT 쿼리는 파일의 기존 내용을 새 데이터로 대체합니다.

​

hedged_connection_timeout_ms

Hedged 요청에서 레플리카와의 연결을 설정할 때의 연결 타임아웃

​

highlight_max_matches_per_row

highlight 함수에서 행당 highlight 일치의 최대 횟수를 설정합니다. 큰 텍스트에서 반복이 많은 패턴을 highlight할 때 과도한 메모리 사용을 방지하는 데 사용합니다.

가능한 값:

• 양의 정수.

​

hnsw_candidate_list_size_for_search

벡터 유사도 인덱스를 검색할 때 사용하는 동적 후보 목록의 크기로, ‘ef_search’라고도 합니다.

​

hsts_max_age

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

​

http_connection_timeout

HTTP 연결 타임아웃(초).

가능한 값:

• 양의 정수.
• 0 - 비활성화(무제한 타임아웃).

​

http_headers_progress_interval_ms

HTTP headers X-ClickHouse-Progress는 지정된 인터벌마다 최대 한 번만 전송됩니다.

​

http_headers_read_timeout

모든 HTTP 요청 헤더를 읽는 최대 시간을 초 단위로 지정합니다. 이는 각 읽기 작업별 제한 시간이 아니라 헤더 파싱 단계 전체에 적용되는 총 제한 시간입니다. 클라이언트가 헤더 데이터를 조금씩 천천히 보내 연결을 계속 열어 두는 slowloris 유형의 공격을 방지합니다.

​

http_make_head_request

http_make_head_request 설정을 사용하면 HTTP에서 데이터를 읽는 동안 HEAD 요청을 실행해 크기 등 읽을 파일의 정보를 가져올 수 있습니다. 이 설정은 기본적으로 활성화되어 있으므로, server가 HEAD 요청을 지원하지 않는 경우에는 비활성화하는 것이 좋습니다.

​

http_max_field_name_size

HTTP 헤더 필드 이름의 최대 길이

​

http_max_field_value_size

HTTP 헤더 필드 값의 최대 길이

​

http_max_fields

HTTP 헤더의 최대 필드 수

​

http_max_multipart_form_data_size

multipart/form-data 콘텐츠 크기 제한입니다. 이 설정은 URL 매개변수로는 해석할 수 없으므로 사용자 프로필에 설정해야 합니다. 콘텐츠는 쿼리 실행이 시작되기 전에 메모리에서 해석되고 외부 테이블(external table)이 생성된다는 점에 유의하십시오. 또한 이 단계에 영향을 미치는 제한은 이것뿐입니다(max memory usage 및 max execution time 제한은 HTTP 폼 데이터를 읽는 동안에는 적용되지 않습니다).

​

http_max_request_header_size

모든 HTTP 요청 헤더의 전체 최대 크기(이름과 값을 합친 크기)를 바이트 단위로 지정합니다.

​

http_max_request_param_data_size

미리 정의된 HTTP 요청에서 쿼리 매개변수로 사용되는 요청 데이터 크기의 제한입니다.

​

http_max_tries

HTTP를 통해 읽기를 시도하는 최대 횟수입니다.

​

http_max_uri_size

HTTP 요청 URI의 최대 길이를 설정합니다.

가능한 값:

• 양의 정수.

​

http_native_compression_disable_checksumming_on_decompress

클라이언트의 HTTP POST 데이터를 압축 해제할 때 체크섬 검증 사용 여부를 설정합니다. ClickHouse 네이티브 압축 포맷에서만 사용되며, gzip 또는 deflate에는 사용되지 않습니다.

자세한 내용은 HTTP 인터페이스 설명을 참조하십시오.

가능한 값:

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

​

http_receive_timeout

HTTP 수신 timeout입니다(초 단위).

가능한 값:

• 임의의 양의 정수.
• 0 - 비활성화됨(무한 timeout).

​

http_response_buffer_size

클라이언트에 HTTP 응답을 보내거나(http_wait_end_of_query가 활성화된 경우) 디스크로 플러시하기 전에 서버 메모리에 버퍼링할 바이트 수입니다.

​

http_response_headers

성공적으로 쿼리가 실행되었을 때 서버가 응답으로 반환하는 HTTP 헤더를 추가하거나 재정의할 수 있습니다. 이 설정은 HTTP 인터페이스에만 영향을 줍니다.

헤더가 이미 기본값으로 설정되어 있으면 제공된 값이 이를 재정의합니다. 헤더가 기본값으로 설정되어 있지 않으면 헤더 목록에 추가됩니다. 서버가 기본적으로 설정한 헤더 중 이 설정으로 재정의되지 않은 헤더는 그대로 유지됩니다.

이 설정을 사용하면 헤더를 상수 값으로 설정할 수 있습니다. 현재는 동적으로 계산된 값으로 헤더를 설정할 수 없습니다.

이름과 값에는 모두 ASCII 제어 문자를 포함할 수 없습니다.

사용자가 설정을 수정할 수 있는 UI 애플리케이션을 구현하면서 동시에 반환된 헤더를 기준으로 동작을 결정하는 경우, 이 설정은 readonly로 제한하는 것이 좋습니다.

예시: SET http_response_headers = '{"Content-Type": "image/png"}'

​

http_retry_initial_backoff_ms

HTTP를 통해 읽기를 재시도할 때 적용되는 최소 백오프 시간(밀리초)

​

http_retry_max_backoff_ms

http를 통해 읽기를 재시도할 때 백오프에 적용되는 최대 밀리초 수

​

http_send_timeout

HTTP 전송 timeout입니다(초 단위).

가능한 값:

• 모든 양의 정수.
• 0 - 비활성화됨(무한 timeout).

default profile에만 적용됩니다. 변경 사항을 적용하려면 서버를 재시작해야 합니다.

​

http_skip_not_found_url_for_globs

HTTP_NOT_FOUND 오류가 발생한 글롭 패턴의 URL은 건너뜁니다

​

http_wait_end_of_query

서버 측 HTTP 응답 버퍼링을 활성화합니다.

​

http_write_exception_in_output_format

유효한 출력이 생성되도록 예외도 출력 형식에 맞춰 작성합니다. JSON 및 XML 포맷에서 작동합니다.

​

http_zlib_compression_level

enable_http_compression = 1인 경우, HTTP 요청에 대한 응답에서 데이터 압축 수준을 설정합니다.

가능한 값: 1~9의 숫자입니다.

​

iceberg_compaction_data_cleanup

데이터가 삭제되기까지의 시간입니다.

​

iceberg_compaction_delay_bias

백그라운드 compaction 작업 2회 사이의 최소 지연 시간입니다.

​

iceberg_data_file_size_lower_threshold_compaction

Iceberg의 compaction data files에 적용되는 임계값입니다.

​

iceberg_data_file_size_upper_threshold_compaction

Iceberg의 compaction 데이터 파일에 대한 임계값입니다.

​

iceberg_delete_data_on_drop

삭제 시 모든 Iceberg 파일도 함께 삭제할지 여부입니다.

​

iceberg_expire_default_max_ref_age_ms

해당 속성이 없으면 expire_snapshots가 사용하는 Iceberg 테이블 속성 history.expire.max-ref-age-ms의 기본값입니다.

​

iceberg_expire_default_max_snapshot_age_ms

해당 속성이 없을 때 expire_snapshots에서 사용하는 Iceberg 테이블 속성 history.expire.max-snapshot-age-ms의 기본값입니다.

​

iceberg_expire_default_min_snapshots_to_keep

expire_snapshots에서 해당 속성이 없을 경우 사용되는 Iceberg 테이블 속성 history.expire.min-snapshots-to-keep의 기본값입니다.

​

iceberg_insert_max_bytes_in_data_file

삽입 작업 시 Iceberg Parquet 데이터 파일의 최대 바이트 수입니다.

​

iceberg_insert_max_partitions

Iceberg 테이블 엔진에서 한 번의 삽입 작업에 허용되는 최대 파티션 수입니다.

​

iceberg_insert_max_rows_in_data_file

삽입 작업 시 Iceberg Parquet 데이터 파일의 최대 행 수입니다.

​

iceberg_max_number_datafiles_to_compact

Iceberg에서 데이터 파일 compaction의 임계값입니다.

​

iceberg_metadata_compression_method

.metadata.json 파일의 압축 메서드입니다.

​

iceberg_metadata_log_level

system.iceberg_metadata_log에 기록되는 Iceberg 테이블 메타데이터의 로깅 수준을 제어합니다. 일반적으로 이 설정은 디버깅 목적으로 수정할 수 있습니다.

가능한 값:

• none - 메타데이터를 기록하지 않습니다.
• metadata - 루트 metadata.json 파일을 기록합니다.
• manifest_list_metadata - 위 항목에 더해 스냅샷에 해당하는 avro manifest 목록의 메타데이터를 기록합니다.
• manifest_list_entry - 위 항목에 더해 avro manifest 목록 항목을 기록합니다.
• manifest_file_metadata - 위 항목에 더해 순회한 avro manifest 파일의 메타데이터를 기록합니다.
• manifest_file_entry - 위 항목에 더해 순회한 avro manifest 파일 항목을 기록합니다.

​

iceberg_metadata_staleness_ms

0이 아닌 경우, 지정된 staleness 윈도우보다 더 최근의 캐시된 metadata snapshot이 있으면 원격 catalog에서 iceberg metadata를 가져오지 않습니다. 0이면 원격 catalog에서 항상 최신 metadata 버전을 가져옵니다. 이 값을 0이 아닌 값으로 설정하면 staleness를 감수하는 대신 읽기 작업의 지연 시간을 낮출 수 있습니다.

​

iceberg_orphan_files_older_than_seconds

Iceberg 테이블에서 고아 파일을 제거할 때 적용되는 기본 보관 기간 임계값(초)입니다. 이 값보다 최신인 파일은 고아 파일로 간주되지 않습니다. remove_orphan_files() 프로시저 호출에서 older_than 인수를 생략한 경우 사용됩니다. 기본값은 259200(3일)입니다.

​

iceberg_snapshot_id

특정 snapshot id로 Iceberg 테이블을 쿼리합니다.

​

iceberg_timestamp_ms

특정 타임스탬프 시점에 유효했던 스냅샷을 사용해 Iceberg 테이블을 쿼리합니다.

​

idle_connection_timeout

지정된 초 수 동안 유휴 상태인 TCP 연결을 닫기 위한 timeout입니다.

가능한 값:

• 양의 정수(0 - 0초 후 즉시 닫음).

​

ignore_cold_parts_seconds

ClickHouse Cloud에서만 적용됩니다. 새 데이터 파트는 사전에 워밍업되거나(cache_populated_by_fetch 참조) 지정된 초 수만큼 지난 후까지 SELECT 쿼리에서 제외됩니다. Replicated-/SharedMergeTree에만 적용됩니다.

​

ignore_data_skipping_indices

쿼리에서 해당 인덱스를 사용하는 경우, 지정된 스키핑 인덱스를 무시합니다.

다음 예시를 살펴보십시오:

CREATE TABLE data
(
    key Int,
    x Int,
    y Int,
    INDEX x_idx x TYPE minmax GRANULARITY 1,
    INDEX y_idx y TYPE minmax GRANULARITY 1,
    INDEX xy_idx (x,y) TYPE minmax GRANULARITY 1
)
Engine=MergeTree()
ORDER BY key;

INSERT INTO data VALUES (1, 2, 3);

SELECT * FROM data;
SELECT * FROM data SETTINGS ignore_data_skipping_indices=''; -- 이 쿼리는 CANNOT_PARSE_TEXT 오류를 발생시킵니다.
SELECT * FROM data SETTINGS ignore_data_skipping_indices='x_idx'; -- 정상.
SELECT * FROM data SETTINGS ignore_data_skipping_indices='na_idx'; -- 정상.

SELECT * FROM data WHERE x = 1 AND y = 1 SETTINGS ignore_data_skipping_indices='xy_idx',force_data_skipping_indices='xy_idx' ; -- xy_idx가 명시적으로 무시되므로 이 쿼리는 INDEX_NOT_USED 오류를 발생시킵니다.
SELECT * FROM data WHERE x = 1 AND y = 2 SETTINGS ignore_data_skipping_indices='xy_idx';

인덱스를 전혀 무시하지 않는 쿼리:

EXPLAIN indexes = 1 SELECT * FROM data WHERE x = 1 AND y = 2;

Expression ((Projection + Before ORDER BY))
  Filter (WHERE)
    ReadFromMergeTree (default.data)
    Indexes:
      PrimaryKey
        Condition: true
        Parts: 1/1
        Granules: 1/1
      Skip
        Name: x_idx
        Description: minmax GRANULARITY 1
        Parts: 0/1
        Granules: 0/1
      Skip
        Name: y_idx
        Description: minmax GRANULARITY 1
        Parts: 0/0
        Granules: 0/0
      Skip
        Name: xy_idx
        Description: minmax GRANULARITY 1
        Parts: 0/0
        Granules: 0/0

xy_idx 인덱스를 무시하는 경우:

EXPLAIN indexes = 1 SELECT * FROM data WHERE x = 1 AND y = 2 SETTINGS ignore_data_skipping_indices='xy_idx';

Expression ((Projection + Before ORDER BY))
  Filter (WHERE)
    ReadFromMergeTree (default.data)
    Indexes:
      PrimaryKey
        Condition: true
        Parts: 1/1
        Granules: 1/1
      Skip
        Name: x_idx
        Description: minmax GRANULARITY 1
        Parts: 0/1
        Granules: 0/1
      Skip
        Name: y_idx
        Description: minmax GRANULARITY 1
        Parts: 0/0
        Granules: 0/0

MergeTree 엔진 계열의 테이블에 적용됩니다.

​

ignore_drop_queries_probability

활성화되면 서버는 지정된 확률로 모든 DROP table 쿼리를 무시합니다(Memory 및 JOIN 엔진의 경우 DROP을 TRUNCATE로 대체합니다). 테스트 목적으로 사용됩니다

​

ignore_format_null_for_explain

활성화하면 EXPLAIN 쿼리에서 FORMAT Null은 무시되고 대신 기본 출력 형식이 사용됩니다. 비활성화하면 FORMAT Null이 포함된 EXPLAIN 쿼리는 출력을 생성하지 않습니다(이전 버전과 호환되는 동작).

​

ignore_materialized_views_with_dropped_target_table

뷰로 푸시할 때 대상 테이블이 삭제된 MV를 무시합니다

​

ignore_on_cluster_for_replicated_access_entities_queries

복제된 액세스 엔터티 관리 쿼리에서 ON CLUSTER 절을 무시합니다.

​

ignore_on_cluster_for_replicated_database

복제된 데이터베이스에 대한 DDL 쿼리에서는 ON CLUSTER 절을 항상 무시합니다.

​

ignore_on_cluster_for_replicated_named_collections_queries

복제된 이름이 지정된 컬렉션 관리 쿼리에서는 ON CLUSTER 절을 무시합니다.

​

ignore_on_cluster_for_replicated_udf_queries

복제된 UDF에 대한 관리 쿼리에서 ON CLUSTER 절을 무시합니다.

​

implicit_select

SELECT 키워드를 앞에 붙이지 않아도 간단한 SELECT 쿼리를 작성할 수 있도록 허용합니다. 따라서 계산기처럼 사용할 때 편리하며, 예를 들어 1 + 2도 유효한 쿼리가 됩니다.

clickhouse-local에서는 기본적으로 활성화되어 있으며, 명시적으로 비활성화할 수 있습니다.

​

implicit_table_at_top_level

비어 있지 않으면 최상위 수준에서 FROM 없이 실행되는 쿼리는 system.one 대신 이 테이블에서 읽습니다.

이 설정은 clickhouse-local에서 입력 데이터를 처리할 때 사용됩니다. 사용자가 이 설정을 명시적으로 지정할 수도 있지만, 이러한 용도로 사용하도록 의도된 것은 아닙니다.

서브쿼리는 이 설정의 영향을 받지 않습니다(스칼라, FROM, IN 서브쿼리 모두 해당). UNION, INTERSECT, EXCEPT 연쇄의 최상위 수준 SELECT는 괄호로 어떻게 그룹화되었는지와 관계없이 동일하게 처리되며, 이 설정의 영향을 받습니다. 이 설정이 VIEW와 분산 쿼리에 어떤 영향을 미치는지는 정의되어 있지 않습니다.

이 설정에는 테이블 이름을 지정할 수 있습니다(이 경우 현재 데이터베이스를 기준으로 테이블이 확인됩니다). 또는 ‘database.table’ 형식의 한정된 이름을 지정할 수도 있습니다. 데이터베이스 이름과 테이블 이름은 모두 따옴표 없이 작성해야 하며, 단순 식별자만 허용됩니다.

​

implicit_transaction

활성화되어 있고 아직 트랜잭션 내에 있지 않은 경우, 쿼리를 전체 트랜잭션(begin + commit 또는 rollback)으로 감쌉니다.

​

inject_random_order_for_select_without_order_by

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

​

insert_allow_materialized_columns

설정이 활성화되면 INSERT에서 materialized 컬럼 사용을 허용합니다.

​

insert_deduplicate

INSERT 시 블록 중복 제거를 활성화하거나 비활성화합니다(Replicated* 테이블).

가능한 값:

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

기본적으로 복제된 테이블에 INSERT 문으로 삽입된 블록은 중복 제거됩니다(데이터 복제 참조). 복제된 테이블에서는 기본적으로 각 파티션마다 가장 최근의 100개 블록에 대해서만 중복 제거가 수행됩니다(replicated_deduplication_window, replicated_deduplication_window_seconds 참조). 복제되지 않은 테이블은 non_replicated_deduplication_window를 참조하십시오.

​

insert_deduplication_token

이 설정을 사용하면 MergeTree/ReplicatedMergeTree에서 사용자 지정 중복 제거 의미 체계를 제공할 수 있습니다. 예를 들어 각 INSERT 문에 이 설정의 고유한 값을 지정하면 동일하게 삽입된 데이터가 중복 제거되지 않도록 할 수 있습니다.

가능한 값:

• 모든 문자열

insert_deduplication_token은 비어 있지 않은 경우에만 중복 제거에 사용됩니다.

복제된 테이블에서는 기본적으로 각 파티션에 대해 가장 최근의 100개 삽입만 중복 제거됩니다(replicated_deduplication_window, replicated_deduplication_window_seconds 참조). 복제되지 않은 테이블은 non_replicated_deduplication_window를 참조하십시오.

insert_deduplication_token은 파티션 수준에서 작동합니다(insert_deduplication checksum과 동일). 여러 파티션에서 동일한 insert_deduplication_token을 사용할 수 있습니다.

예시:

CREATE TABLE test_table
( A Int64 )
ENGINE = MergeTree
ORDER BY A
SETTINGS non_replicated_deduplication_window = 100;

INSERT INTO test_table SETTINGS insert_deduplication_token = 'test' VALUES (1);

-- insert_deduplication_token이 다르므로 다음 삽입은 중복 제거되지 않습니다
INSERT INTO test_table SETTINGS insert_deduplication_token = 'test1' VALUES (1);

-- insert_deduplication_token이 이전 삽입 중 하나와 동일하므로
-- 다음 삽입은 중복 제거됩니다
INSERT INTO test_table SETTINGS insert_deduplication_token = 'test' VALUES (2);

SELECT * FROM test_table

┌─A─┐
│ 1 │
└───┘
┌─A─┐
│ 1 │
└───┘

​

insert_keeper_fault_injection_probability

삽입 중 Keeper 요청이 실패할 대략적인 확률입니다. 유효한 값은 인터벌 [0.0f, 1.0f] 범위에 있어야 합니다.

​

insert_keeper_fault_injection_seed

0 - 랜덤 시드, 그 외에는 설정값

​

insert_keeper_max_retries

이 설정은 복제된 MergeTree에 데이터를 삽입하는 동안 ClickHouse Keeper(또는 ZooKeeper) 요청에 대해 허용되는 최대 재시도 횟수를 설정합니다. 네트워크 오류, Keeper 세션 타임아웃 또는 요청 타임아웃으로 실패한 Keeper 요청만 재시도 대상으로 간주됩니다.

가능한 값:

• 양의 정수입니다.
• 0 — 재시도는 비활성화됩니다

Cloud 기본값: 20.

Keeper 요청 재시도는 일정 시간 후에 수행됩니다. 이 시간은 다음 설정으로 제어됩니다: insert_keeper_retry_initial_backoff_ms, insert_keeper_retry_max_backoff_ms. 첫 번째 재시도는 insert_keeper_retry_initial_backoff_ms 후에 수행됩니다. 이후 대기 시간은 다음과 같이 계산됩니다:

timeout = min(insert_keeper_retry_max_backoff_ms, latest_timeout * 2)

예를 들어 insert_keeper_retry_initial_backoff_ms=100, insert_keeper_retry_max_backoff_ms=10000, insert_keeper_max_retries=8이면 타임아웃은 100, 200, 400, 800, 1600, 3200, 6400, 10000이 됩니다.

장애 허용 외에도 재시도는 사용자 경험을 개선하는 데 목적이 있습니다. 예를 들어 업그레이드로 인해 Keeper가 다시 시작되더라도 INSERT 실행 중 오류를 반환하지 않도록 해줍니다.

​

insert_keeper_retry_initial_backoff_ms

INSERT 쿼리 실행 중 실패한 Keeper 요청을 재시도할 때의 초기 timeout(밀리초 단위)입니다

가능한 값:

• 양의 정수입니다.
• 0 — timeout 없음

​

insert_keeper_retry_max_backoff_ms

INSERT 쿼리 실행 중 실패한 Keeper 요청을 재시도할 때의 최대 timeout(밀리초)

가능한 값:

• 양의 정수
• 0 — 최대 timeout이 제한되지 않음

​

insert_null_as_default

널 허용이 아닌 데이터 타입의 컬럼에 default values 대신 NULL을 삽입할지 여부를 설정합니다. 만약 컬럼 타입이 nullable이 아니고 이 설정이 비활성화되어 있으면 NULL을 삽입할 때 예외가 발생합니다. 컬럼 타입이 nullable인 경우에는 이 설정과 관계없이 NULL 값이 그대로 삽입됩니다.

이 설정은 INSERT … SELECT 쿼리에 적용됩니다. 참고로 SELECT 서브쿼리는 UNION ALL 절로 연결될 수 있습니다.

가능한 값:

• 0 — 널 허용이 아닌 컬럼에 NULL을 삽입하면 예외가 발생합니다.
• 1 — NULL 대신 컬럼의 기본값이 삽입됩니다.

​

insert_quorum

이 설정은 SharedMergeTree에는 적용되지 않습니다. 자세한 내용은 SharedMergeTree 일관성을 참조하십시오.

쿼럼 쓰기를 활성화합니다.

• insert_quorum < 2이면 쿼럼 쓰기가 비활성화됩니다.
• insert_quorum >= 2이면 쿼럼 쓰기가 활성화됩니다.
• insert_quorum = 'auto'이면 과반수(number_of_replicas / 2 + 1)를 쿼럼 수로 사용합니다.

쿼럼 쓰기

INSERT는 insert_quorum_timeout 동안 ClickHouse가 insert_quorum개의 레플리카에 데이터를 정상적으로 기록한 경우에만 성공합니다. 어떤 이유로든 쓰기에 성공한 레플리카 수가 insert_quorum에 도달하지 못하면 해당 쓰기는 실패한 것으로 간주되며, ClickHouse는 이미 데이터가 기록된 모든 레플리카에서 삽입된 블록을 삭제합니다.

insert_quorum_parallel이 비활성화되면 쿼럼에 포함된 모든 레플리카의 상태가 일관되게 유지됩니다. 즉, 이전의 모든 INSERT 쿼리 데이터를 포함합니다(INSERT 시퀀스가 선형화됨). insert_quorum으로 기록된 데이터를 읽을 때 insert_quorum_parallel이 비활성화되어 있으면, select_sequential_consistency를 사용하여 SELECT 쿼리에 대해 순차 일관성을 활성화할 수 있습니다.

ClickHouse는 다음 경우 예외를 발생시킵니다.

• 쿼리 시점에 사용 가능한 레플리카 수가 insert_quorum보다 적은 경우
• insert_quorum_parallel이 비활성화되어 있고, 이전 블록이 아직 insert_quorum개의 레플리카에 삽입되지 않은 상태에서 데이터를 쓰려고 시도하는 경우. 이 상황은 사용자가 insert_quorum을 사용하는 이전 INSERT 쿼리가 완료되기 전에 같은 테이블에 또 다른 INSERT 쿼리를 수행하려고 할 때 발생할 수 있습니다.

관련 항목:

• insert_quorum_timeout
• insert_quorum_parallel
• select_sequential_consistency

​

insert_quorum_parallel

이 설정은 SharedMergeTree에는 적용되지 않습니다. 자세한 내용은 SharedMergeTree 일관성을 참조하십시오.

quorum INSERT 쿼리의 병렬 처리를 활성화하거나 비활성화합니다. 활성화하면 이전 쿼리가 아직 완료되지 않았더라도 추가 INSERT 쿼리를 보낼 수 있습니다. 비활성화하면 동일한 테이블에 대한 추가 쓰기가 거부됩니다.

가능한 값:

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

관련 항목:

• insert_quorum
• insert_quorum_timeout
• select_sequential_consistency

​

insert_quorum_timeout

쿼럼에 대한 쓰기 타임아웃으로, 단위는 밀리초입니다. 타임아웃이 지났는데도 아직 쓰기가 이루어지지 않았다면 ClickHouse는 예외를 발생시키며, 클라이언트는 동일한 블록을 동일한 레플리카 또는 다른 레플리카에 쓰기 위해 쿼리를 다시 실행해야 합니다.

관련 항목:

• insert_quorum
• insert_quorum_parallel
• select_sequential_consistency

​

insert_shard_id

0이 아니면, 데이터를 동기적으로 삽입할 분산 테이블의 세그먼트를 지정합니다.

insert_shard_id 값이 올바르지 않으면 서버가 예외를 발생시킵니다.

requested_cluster의 세그먼트 수를 확인하려면 서버 구성을 확인하거나 다음 쿼리를 사용하십시오:

SELECT uniq(shard_num) FROM system.clusters WHERE cluster = 'requested_cluster';

가능한 값:

• 0 — 비활성화됨.
• 해당 분산 테이블의 1부터 shards_num 사이의 임의의 숫자.

예시

쿼리:

CREATE TABLE x AS system.numbers ENGINE = MergeTree ORDER BY number;
CREATE TABLE x_dist AS x ENGINE = Distributed('test_cluster_two_shards_localhost', currentDatabase(), x);
INSERT INTO x_dist SELECT * FROM numbers(5) SETTINGS insert_shard_id = 1;
SELECT * FROM x_dist ORDER BY number ASC;

결과:

┌─number─┐
│      0 │
│      0 │
│      1 │
│      1 │
│      2 │
│      2 │
│      3 │
│      3 │
│      4 │
│      4 │
└────────┘

​

interactive_delay

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

​

intersect_default_mode

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

​

jemalloc_collect_profile_samples_in_trace_log

trace 로그에서 jemalloc의 메모리 할당 및 해제 샘플을 수집합니다.

​

jemalloc_enable_profiler

해당 쿼리에 jemalloc 프로파일러를 활성화합니다. Jemalloc은 메모리 할당을 샘플링하고, 샘플링된 할당에 대한 모든 메모리 해제를 기록합니다. 프로파일은 SYSTEM JEMALLOC FLUSH PROFILE을 사용해 플러시할 수 있으며, 메모리 할당 분석에 활용할 수 있습니다. 샘플은 구성 옵션 jemalloc_collect_global_profile_samples_in_trace_log 또는 쿼리 설정 jemalloc_collect_profile_samples_in_trace_log를 사용해 system.trace_log에 저장할 수도 있습니다. 메모리 할당 프로파일링을 참조하십시오.

​

jemalloc_profile_text_collapsed_use_count

jemalloc 힙 프로파일에 ‘collapsed’ 출력 형식을 사용할 때 바이트 대신 할당 횟수를 기준으로 집계합니다. false(기본값)인 경우 각 스택은 현재 사용 중인 바이트 수를 기준으로 가중치가 적용되며, true인 경우 현재 사용 중인 할당 횟수를 기준으로 가중치가 적용됩니다.

​

jemalloc_profile_text_output_format

system.jemalloc_profile_text 테이블에서 jemalloc 힙 프로파일에 사용하는 출력 형식입니다. 값은 ‘raw’(원시 프로파일), ‘symbolized’(심볼이 포함된 jeprof 포맷), 또는 ‘collapsed’(플레임 그래프 포맷)일 수 있습니다.

​

jemalloc_profile_text_symbolize_with_inline

jemalloc 힙 프로파일을 symbolized할 때 인라인 프레임을 포함할지 여부를 지정합니다. 활성화하면 인라인 프레임이 포함되어 symbolization 과정이 크게 느려질 수 있으며, 비활성화하면 이를 건너뜁니다. ‘symbolized’ 및 ‘collapsed’ 출력 형식에만 영향을 줍니다.

​

join_algorithm

어떤 JOIN 조인 알고리즘을 사용할지 지정합니다.

여러 알고리즘을 지정할 수 있으며, kind/엄격성과 테이블 엔진에 따라 특정 쿼리에 사용할 수 있는 알고리즘이 선택됩니다.

가능한 값:

• grace_hash

Grace hash join을 사용합니다. Grace hash는 메모리 사용을 제한하면서도 복잡한 조인을 높은 성능으로 수행할 수 있는 알고리즘 옵션입니다.

grace join의 첫 번째 단계에서는 오른쪽 테이블을 읽고 키 컬럼의 hash 값에 따라 N개의 버킷으로 분할합니다(초기 N 값은 grace_hash_join_initial_buckets임). 이렇게 하면 각 버킷을 독립적으로 처리할 수 있습니다. 첫 번째 버킷의 행은 메모리 내 해시 테이블에 추가하고, 나머지는 디스크에 저장합니다. 해시 테이블이 메모리 한도(예: max_bytes_in_join로 설정된 값)를 초과할 만큼 커지면 버킷 수를 늘리고 각 행에 할당된 버킷을 다시 계산합니다. 현재 버킷에 속하지 않는 행은 모두 플러시한 뒤 다시 할당됩니다.

INNER/LEFT/RIGHT/FULL ALL/ANY JOIN을 지원합니다.

• hash

해시 조인 알고리즘을 사용합니다. kind와 엄격성의 모든 조합을 지원하며, JOIN ON 절에서 OR로 결합된 여러 조인 키도 지원하는 가장 범용적인 구현입니다.

hash 알고리즘을 사용할 때는 JOIN의 오른쪽 부분을 RAM에 올립니다.

• parallel_hash

데이터를 버킷으로 분할하고, 해시 테이블 하나 대신 여러 개를 동시에 구축하여 이 과정을 더 빠르게 수행하는 hash 조인의 변형입니다.

parallel_hash 알고리즘을 사용할 때는 JOIN의 오른쪽 부분을 RAM에 올립니다.

• partial_merge

오른쪽 테이블만 완전히 정렬하는 sort-merge 알고리즘의 변형입니다.

RIGHT JOIN과 FULL JOIN은 ALL 엄격성에서만 지원됩니다(SEMI, ANTI, ANY, ASOF는 지원되지 않음).

partial_merge 알고리즘을 사용할 때 ClickHouse는 데이터를 정렬한 뒤 디스크에 dump합니다. ClickHouse의 partial_merge 알고리즘은 고전적인 구현과 약간 다릅니다. 먼저 ClickHouse는 오른쪽 테이블을 조인 키 기준으로 블록 단위로 정렬하고, 정렬된 블록에 대해 MinMax 인덱스를 생성합니다. 그런 다음 왼쪽 테이블의 일부를 join key 기준으로 정렬한 후 오른쪽 테이블과 조인합니다. MinMax 인덱스는 필요하지 않은 오른쪽 테이블 블록을 건너뛰는 데에도 사용됩니다.

• direct

direct(nested loop라고도 함) 알고리즘은 왼쪽 테이블의 행을 키로 사용해 오른쪽 테이블에서 lookup을 수행합니다. 이는 딕셔너리, EmbeddedRocksDB, MergeTree 테이블과 같은 특수 스토리지에서 지원됩니다.

MergeTree 테이블의 경우 이 알고리즘은 조인 키 필터를 스토리지 계층에 직접 푸시다운합니다. 키에 대해 테이블의 프라이머리 키 인덱스를 lookup에 사용할 수 있으면 더 효율적일 수 있지만, 그렇지 않으면 왼쪽 테이블의 각 블록마다 오른쪽 테이블 전체를 스캔합니다.

INNER 및 LEFT 조인만 지원하며, 다른 조건이 없는 단일 컬럼 동등 조인 키만 지원합니다.

• auto

auto로 설정하면 먼저 hash 조인을 시도하고, 메모리 한도를 초과하면 실행 중에 다른 알고리즘으로 전환합니다.

• full_sorting_merge

조인 전에 조인 대상 테이블을 완전히 정렬하는 sort-merge 알고리즘입니다.

• prefer_partial_merge

ClickHouse는 가능하면 항상 partial_merge 조인을 사용하고, 그렇지 않으면 hash를 사용합니다. Deprecated이며, partial_merge,hash와 같습니다.

• default (deprecated)

레거시 값이므로 더 이상 사용하지 마십시오. direct,hash와 같으며, 즉 direct 조인과 hash 조인을 이 순서대로 사용하려고 시도합니다.

​

join_any_take_last_row

ANY 엄격성을 사용하는 JOIN 작업의 동작을 변경합니다.

이 설정은 Join 테이블 엔진을 사용하는 JOIN 작업에만 적용됩니다.

가능한 값:

• 0 — 오른쪽 테이블에 일치하는 행이 2개 이상 있으면, 발견된 첫 번째 행만 조인됩니다.
• 1 — 오른쪽 테이블에 일치하는 행이 2개 이상 있으면, 발견된 마지막 행만 조인됩니다.

관련 항목:

• JOIN 절
• Join 테이블 엔진
• join_default_strictness

​

join_default_strictness

JOIN 절의 기본 엄격성을 설정합니다.

가능한 값:

• ALL — 오른쪽 테이블에 일치하는 행이 여러 개 있으면, ClickHouse는 일치하는 행들로 카테시안 곱을 만듭니다. 이는 표준 SQL에서 일반적인 JOIN 동작입니다.
• ANY — 오른쪽 테이블에 일치하는 행이 여러 개 있으면, 처음 찾은 행만 조인됩니다. 오른쪽 테이블에 일치하는 행이 하나뿐이면 ANY와 ALL의 결과는 같습니다.
• ASOF — 정확히 일치하지 않을 수 있는 시퀀스를 조인할 때 사용합니다.
• 빈 문자열 — 쿼리에서 ALL 또는 ANY를 지정하지 않으면 ClickHouse는 예외를 발생시킵니다.

​

join_on_disk_max_files_to_merge

디스크에서 실행되는 MergeJoin 연산의 병렬 정렬에 허용되는 파일 수를 제한합니다.

이 설정값이 클수록 더 많은 RAM을 사용하고, 필요한 디스크 I/O는 더 적어집니다.

가능한 값:

• 2 이상의 임의의 양의 정수.

​

join_output_by_rowlist_perkey_rows_threshold

해시 조인에서 행 목록으로 출력할지 결정하는 데 사용하는 오른쪽 테이블(table)의 키별 평균 행 수 하한값입니다.

​

join_overflow_mode

다음 JOIN 제한 중 하나에 도달했을 때 ClickHouse가 수행할 동작을 정의합니다:

• max_bytes_in_join
• max_rows_in_join

가능한 값:

• THROW — ClickHouse가 예외를 발생시키고 작업을 중단합니다.
• BREAK — ClickHouse가 작업을 중단하고 예외를 발생시키지 않습니다.

기본값: THROW.

관련 항목

• JOIN 절
• Join 테이블 엔진

​

join_runtime_bloom_filter_bytes

JOIN 런타임 필터에 사용되는 블룸 필터의 크기(바이트)입니다(enable_join_runtime_filters 설정 참조).

​

join_runtime_bloom_filter_hash_functions

JOIN 런타임 필터로 사용되는 블룸 필터의 해시 함수 개수입니다(enable_join_runtime_filters 설정 참조).

​

join_runtime_bloom_filter_max_ratio_of_set_bits

런타임 블룸 필터에서 1로 설정된 비트 수가 이 비율을 초과하면, 오버헤드를 줄이기 위해 필터를 완전히 비활성화합니다.

​

join_runtime_filter_blocks_to_skip_before_reenabling

이전에 필터링 비율이 낮아 비활성화된 런타임 필터를 동적으로 다시 활성화하기 전에 건너뛸 블록 수입니다.

​

join_runtime_filter_exact_values_limit

런타임 필터에서 요소를 Set에 있는 그대로 저장할 수 있는 최대 개수입니다. 이 임계값을 초과하면 블룸 필터로 전환됩니다.

​

join_runtime_filter_pass_ratio_threshold_for_disabling

통과한 행 수를 검사한 행 수로 나눈 비율이 이 임계값보다 크면 런타임 필터의 성능이 좋지 않은 것으로 간주되어, 오버헤드를 줄이기 위해 다음 join_runtime_filter_blocks_to_skip_before_reenabling개 블록 동안 비활성화됩니다.

​

join_to_sort_maximum_table_rows

왼쪽 조인 또는 내부 조인에서 오른쪽 테이블을 키 기준으로 다시 정렬할지 판단하는 데 사용되는 오른쪽 테이블의 최대 행 수.

​

join_to_sort_minimum_perkey_rows

왼쪽 조인 또는 내부 조인에서 오른쪽 테이블을 키별로 재정렬할지 결정하기 위한, 오른쪽 테이블의 키별 평균 행 수의 하한입니다. 이 설정은 희소한 테이블 키에는 이 최적화가 적용되지 않도록 합니다

​

join_use_nulls

JOIN 동작 방식을 설정합니다. 테이블을 병합할 때 빈 셀이 생길 수 있습니다. ClickHouse는 이 설정에 따라 이를 서로 다르게 채웁니다.

가능한 값:

• 0 — 빈 셀은 해당 필드 유형의 기본값으로 채워집니다.
• 1 — JOIN이 표준 SQL과 동일한 방식으로 동작합니다. 해당 필드의 유형은 Nullable로 변환되며, 빈 셀은 NULL로 채워집니다.

​

joined_block_split_single_row

해시 조인 결과를 왼쪽 테이블의 단일 행에 대응하는 행 단위로 청크로 분할할 수 있도록 합니다. 이 설정은 오른쪽 테이블에서 일치하는 항목이 많은 행이 있을 때 메모리 사용량을 줄일 수 있지만, CPU 사용량은 증가할 수 있습니다. 이 설정이 적용되려면 max_joined_block_size_rows != 0이 반드시 설정되어 있어야 합니다. 이 설정을 max_joined_block_size_bytes와 함께 사용하면, 오른쪽 테이블에서 일치하는 항목이 많은 큰 행이 일부 포함된 편향된 데이터에서 과도한 메모리 사용량을 방지하는 데 도움이 됩니다.

​

joined_subquery_requires_alias

이름을 올바르게 한정할 수 있도록 조인된 서브쿼리와 테이블 함수에 별칭을 지정하도록 강제합니다.

​

kafka_disable_num_consumers_limit

사용 가능한 CPU 코어 수에 따라 적용되는 kafka_num_consumers 제한을 비활성화합니다.

​

kafka_max_wait_ms

재시도하기 전에 Kafka에서 메시지를 읽기 위해 대기하는 시간을 밀리초 단위로 지정합니다.

가능한 값:

• 양의 정수입니다.
• 0 — timeout이 무한대입니다.

관련 항목:

• Apache Kafka

​

keeper_map_strict_mode

KeeperMap 작업 중 추가 검사를 수행합니다. 예를 들어 이미 존재하는 키에 삽입하면 예외를 발생시킵니다

​

keeper_max_retries

일반 Keeper 작업의 최대 재시도 횟수

​

keeper_retry_initial_backoff_ms

일반 Keeper 작업에 대한 초기 백오프 타임아웃

​

keeper_retry_max_backoff_ms

일반적인 Keeper 작업의 최대 백오프 시간 제한

​

least_greatest_legacy_null_behavior

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

​

legacy_column_name_of_tuple_literal

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

​

lightweight_delete_mode

경량한 삭제의 일부로 실행되는 내부 업데이트 쿼리의 모드입니다.

가능한 값:

• alter_update - 무거운 mutation을 생성하는 ALTER UPDATE 쿼리를 실행합니다.
• lightweight_update - 가능하면 경량 업데이트를 실행하고, 그렇지 않으면 ALTER UPDATE를 실행합니다.
• lightweight_update_force - 가능하면 경량 업데이트를 실행하고, 그렇지 않으면 예외를 발생시킵니다.

​

lightweight_deletes_sync

mutations_sync와 같지만, 경량한 삭제의 실행만 제어합니다.

가능한 값:

값	설명
0	뮤테이션이 비동기적으로 실행됩니다.
1	현재 서버에서 경량한 삭제가 완료될 때까지 쿼리가 대기합니다.
2	모든 레플리카(있는 경우)에서 경량한 삭제가 완료될 때까지 쿼리가 대기합니다.
3	쿼리는 활성 레플리카만 기다립니다. SharedMergeTree에서만 지원됩니다. ReplicatedMergeTree에서는 mutations_sync = 2와 동일하게 동작합니다.

관련 항목

• ALTER 쿼리의 동기성
• 뮤테이션

Cloud 기본값: 1.

​

limit

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

가능한 값:

• 0 — 행 수에 제한이 없습니다.
• 양의 정수.

​

load_balancing

분산 쿼리 처리에 사용할 레플리카 선택 알고리즘을 지정합니다.

ClickHouse는 다음 레플리카 선택 알고리즘을 지원합니다.

• 무작위 (기본값)
• 가장 가까운 호스트명
• 호스트명 Levenshtein 거리
• 정의된 순서대로
• 첫 번째 또는 무작위
• 라운드 로빈

관련 항목:

• distributed_replica_max_ignored_errors

​

Random (기본 설정)

load_balancing = random

각 레플리카의 오류 수를 집계합니다. 쿼리는 오류가 가장 적은 레플리카로 전송되며, 이러한 레플리카가 여러 개이면 그중 아무 레플리카로나 전송됩니다. 단점: 서버와의 물리적 근접성은 고려되지 않으며, 레플리카마다 데이터가 다르면 반환되는 데이터도 달라집니다.

​

Nearest Hostname

load_balancing = nearest_hostname

각 레플리카의 오류 수를 집계합니다. 5분마다 오류 수를 2로 정수 나눗셈합니다. 따라서 최근 시점의 오류 수는 지수 평활 방식으로 계산됩니다. 최소 오류 수를 가진 레플리카가 하나뿐이면(즉, 다른 레플리카에서는 최근에 오류가 발생한 경우) 해당 레플리카로 쿼리를 보냅니다. 동일한 최소 오류 수를 가진 레플리카가 여러 개 있으면, 구성 파일에 있는 server의 호스트명과 가장 유사한 호스트명을 가진 레플리카로 쿼리를 보냅니다(두 호스트명의 길이 중 짧은 쪽까지, 같은 위치에서 서로 다른 문자의 수를 기준으로 합니다).

예를 들어 example01-01-1과 example01-01-2는 한 위치만 다르지만, example01-01-1과 example01-02-2는 두 위치에서 다릅니다. 이 메서드는 다소 원시적으로 보일 수 있지만, 네트워크 토폴로지에 관한 외부 데이터가 필요 없고, IP 주소도 비교하지 않습니다. IPv6 주소에서는 이런 비교가 복잡하기 때문입니다.

따라서 동등한 레플리카가 있으면 이름이 가장 가까운 레플리카를 우선합니다. 또한 동일한 server로 쿼리를 보내면, 장애가 없는 한 분산 쿼리도 동일한 server들로 전달된다고 가정할 수 있습니다. 따라서 레플리카마다 서로 다른 데이터가 저장되어 있더라도, 쿼리는 대체로 동일한 결과를 반환합니다.

​

호스트명 Levenshtein 거리

load_balancing = hostname_levenshtein_distance

nearest_hostname와 동일하지만, Levenshtein distance를 기준으로 호스트명을 비교합니다. 예시:

example-clickhouse-0-0 ample-clickhouse-0-0
1

example-clickhouse-0-0 example-clickhouse-1-10
2

example-clickhouse-0-0 example-clickhouse-12-0
3

​

정의된 순서대로

load_balancing = in_order

오류 수가 같은 레플리카는 구성에 지정된 순서대로 액세스됩니다. 어느 레플리카를 우선할지 정확히 알고 있을 때 이 메서드가 적합합니다.

​

첫 번째 또는 임의

load_balancing = first_or_random

이 알고리즘은 집합의 첫 번째 레플리카를 선택하고, 첫 번째 레플리카를 사용할 수 없으면 임의의 레플리카를 선택합니다. 교차 복제 토폴로지 구성에서는 효과적이지만, 다른 구성에서는 유용하지 않습니다.

first_or_random 알고리즘은 in_order 알고리즘의 문제를 해결합니다. in_order에서는 레플리카 하나에 장애가 발생하면 다음 레플리카에 부하가 2배로 몰리고, 나머지 레플리카는 평소와 같은 양의 트래픽을 처리합니다. first_or_random 알고리즘을 사용하면 계속 사용 가능한 레플리카에 부하가 고르게 분산됩니다.

load_balancing_first_offset 설정을 사용하면 첫 번째 레플리카를 명시적으로 지정할 수 있습니다. 이를 통해 레플리카 간 쿼리 워크로드의 리밸런싱을 더 세밀하게 제어할 수 있습니다.

​

라운드 로빈

load_balancing = round_robin

이 알고리즘은 오류 수가 동일한 레플리카들에 대해 라운드 로빈 정책을 사용합니다(round_robin 정책을 사용하는 쿼리만 집계합니다).

​

load_balancing_first_offset

FIRST_OR_RANDOM load balancing strategy를 사용할 때 우선적으로 쿼리를 보낼 레플리카를 지정합니다.

​

load_marks_asynchronously

MergeTree 마크를 비동기적으로 로드합니다.

Cloud 기본값: 1.

​

local_filesystem_read_method

로컬 파일 시스템에서 데이터를 읽는 메서드입니다. 다음 중 하나를 사용할 수 있습니다: read, pread, mmap, io_uring, pread_threadpool.

‘io_uring’ 메서드는 Experimental 기능이며, 동시 읽기 및 쓰기가 발생하는 환경에서는 Log, TinyLog, StripeLog, File, Set, Join 및 append 가능한 파일을 사용하는 기타 테이블에서는 동작하지 않습니다. 인터넷에서 ‘io_uring’에 관한 여러 글을 읽더라도 이에 현혹되지 마십시오. 이는 파일 읽기에 더 나은 메서드가 아니며, 예외적으로 아주 많은 수의 작은 IO 요청이 있는 경우에만 유리할 수 있지만 ClickHouse는 그런 경우에 해당하지 않습니다. ‘io_uring’을 활성화할 이유는 없습니다.

​

local_filesystem_read_prefetch

로컬 파일 시스템에서 데이터를 읽을 때 프리페치를 사용할지 여부입니다.

​

lock_acquire_timeout

잠금 요청이 실패하기 전까지 몇 초 동안 대기할지를 정의합니다.

잠금 시간 제한은 테이블에 대한 읽기/쓰기 작업을 수행하는 동안 교착 상태를 방지하기 위해 사용됩니다. 시간 제한이 만료되어 잠금 요청이 실패하면 ClickHouse 서버는 오류 코드 DEADLOCK_AVOIDED와 함께 “Locking attempt timed out! Possible deadlock avoided. Client should retry.” 예외를 발생시킵니다.

Possible values:

• 양의 정수(초)
• 0 — 잠금 시간 제한 없음

​

log_comment

system.query_log 테이블의 log_comment 필드 값과 서버 로그에 기록할 설명 텍스트를 지정합니다.

이 설정을 사용하면 서버 로그의 가독성을 높일 수 있습니다. 또한 clickhouse-test를 실행한 후 system.query_log에서 테스트와 관련된 쿼리를 선별하는 데도 도움이 됩니다.

가능한 값:

• max_query_size를 넘지 않는 임의의 문자열입니다. max_query_size를 초과하면 서버에서 예외가 발생합니다.

예시

쿼리:

SET log_comment = 'log_comment test', log_queries = 1;
SELECT 1;
SYSTEM FLUSH LOGS;
SELECT type, query FROM system.query_log WHERE log_comment = 'log_comment test' AND event_date >= yesterday() ORDER BY event_time DESC LIMIT 2;

결과:

┌─type────────┬─query─────┐
│ QueryStart  │ SELECT 1; │
│ QueryFinish │ SELECT 1; │
└─────────────┴───────────┘

​

log_formatted_queries

포맷된 쿼리를 system.query_log 시스템 테이블에 기록할 수 있습니다(system.query_log의 formatted_query 컬럼이 채워집니다).

가능한 값:

• 0 — 포맷된 쿼리는 시스템 테이블에 기록되지 않습니다.
• 1 — 포맷된 쿼리가 시스템 테이블에 기록됩니다.

​

log_processors_profiles

실행 중 또는 데이터를 기다리는 동안 프로세서가 소비한 시간을 system.processors_profile_log 테이블에 기록합니다.

관련 항목:

• system.processors_profile_log
• EXPLAIN PIPELINE

​

log_profile_events

쿼리 성능 관련 통계를 query_log, query_thread_log 및 query_views_log에 기록합니다.

​

log_queries

쿼리 로깅을 설정합니다.

이 설정이 적용되면 ClickHouse에 전송된 쿼리는 query_log 서버 구성 매개변수의 규칙에 따라 로깅됩니다.

예시:

log_queries=1

​

log_queries_cut_to_length

쿼리 길이가 지정된 임계값(바이트)보다 크면, 쿼리 로그에 기록할 때 쿼리를 잘라냅니다. 또한 일반 텍스트 로그에 출력되는 쿼리의 길이도 제한합니다.

​

log_queries_min_query_duration_ms

활성화된 경우(0이 아닌 값), 이 설정값보다 더 빨리 완료되는 쿼리는 로그에 기록되지 않습니다(MySQL Slow Query Log의 long_query_time과 비슷하다고 생각하면 됩니다). 즉, 이러한 쿼리는 다음 테이블에서 찾을 수 없습니다.

• system.query_log
• system.query_thread_log

다음 유형의 쿼리만 로그에 기록됩니다.

• QUERY_FINISH

• EXCEPTION_WHILE_PROCESSING

• 유형: 밀리초

• 기본값: 0 (모든 쿼리)

​

log_queries_min_type

query_log에 기록할 최소 유형입니다.

가능한 값:

• QUERY_START (=1)
• QUERY_FINISH (=2)
• EXCEPTION_BEFORE_START (=3)
• EXCEPTION_WHILE_PROCESSING (=4)

query_log에 기록할 항목을 제한하는 데 사용할 수 있습니다. 예를 들어 오류에만 관심이 있다면 EXCEPTION_WHILE_PROCESSING을 사용할 수 있습니다:

log_queries_min_type='EXCEPTION_WHILE_PROCESSING'

​

log_queries_probability

지정한 확률에 따라 무작위로 선택된 쿼리 샘플만 query_log, query_thread_log, query_views_log 시스템 테이블(system tables)에 기록하도록 합니다. 초당 쿼리량이 많은 경우 부하를 줄이는 데 도움이 됩니다.

가능한 값:

• 0 — 시스템 테이블에 쿼리가 기록되지 않습니다.
• [0..1] 범위의 양의 부동소수점 수입니다. 예를 들어 설정 값이 0.5이면 전체 쿼리의 약 절반이 시스템 테이블에 기록됩니다.
• 1 — 모든 쿼리가 시스템 테이블에 기록됩니다.

​

log_query_settings

쿼리 설정을 query_log와 OpenTelemetry 스팬 로그에 기록합니다.

​

log_query_threads

쿼리 스레드 로깅을 설정합니다.

쿼리 스레드는 system.query_thread_log 테이블에 기록됩니다. 이 설정은 log_queries가 true일 때만 적용됩니다. 이 설정이 활성화되면 ClickHouse가 실행한 쿼리의 스레드는 query_thread_log 서버 구성 매개변수의 규칙에 따라 기록됩니다.

Possible values:

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

예시

log_query_threads=1

​

log_query_views

쿼리 view의 로깅을 설정합니다.

이 설정이 활성화된 상태에서 ClickHouse가 실행한 쿼리에 연결된 뷰(구체화된 뷰(Materialized View) 또는 라이브 view)가 있으면 query_views_log 서버 구성 매개변수에 기록됩니다.

예시:

log_query_views=1

​

low_cardinality_allow_in_native_format

Native 포맷에서 LowCardinality 데이터 타입의 사용을 허용하거나 제한합니다.

LowCardinality 사용이 제한되면 ClickHouse 서버는 SELECT 쿼리에서는 LowCardinality 컬럼을 일반 컬럼으로 변환하고, INSERT 쿼리에서는 일반 컬럼을 LowCardinality 컬럼으로 변환합니다.

이 설정은 주로 LowCardinality 데이터 타입을 지원하지 않는 서드파티 클라이언트에 필요합니다.

가능한 값:

• 1 — LowCardinality 사용이 제한되지 않습니다.
• 0 — LowCardinality 사용이 제한됩니다.

​

low_cardinality_max_dictionary_size

스토리지 파일 시스템에 쓸 수 있는 LowCardinality 데이터 타입의 공유 전역 딕셔너리 최대 크기를 행 수 기준으로 설정합니다. 이 설정은 딕셔너리가 무제한으로 커질 때 발생할 수 있는 RAM 문제를 방지합니다. 최대 딕셔너리 크기 제한으로 인해 인코딩할 수 없는 데이터는 모두 ClickHouse가 일반 방식으로 기록합니다.

가능한 값:

• 양의 정수 아무거나 가능합니다.

​

low_cardinality_use_single_dictionary_for_part

데이터 파트(data part)에 단일 딕셔너리를 사용할지 여부를 설정합니다.

기본적으로 ClickHouse 서버는 딕셔너리의 크기를 모니터링하며, 딕셔너리에 오버플로우가 발생하면 다음 딕셔너리에 쓰기를 시작합니다. 여러 개의 딕셔너리가 생성되지 않도록 하려면 low_cardinality_use_single_dictionary_for_part = 1로 설정하십시오.

가능한 값:

• 1 — 데이터 파트에 여러 개의 딕셔너리를 생성할 수 없습니다.
• 0 — 데이터 파트에 여러 개의 딕셔너리를 생성할 수 있습니다.

​

low_priority_query_wait_time_ms

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

​

make_distributed_plan

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

​

materialize_skip_indexes_on_insert

INSERT 시 스킵 인덱스를 생성하고 저장할지 여부를 지정합니다. 비활성화하면 스킵 인덱스는 머지 중 또는 명시적으로 MATERIALIZE INDEX를 실행할 때만 생성되고 저장됩니다.

관련 항목: exclude_materialize_skip_indexes_on_insert.

​

materialize_statistics_on_insert

INSERT 시 통계를 생성하여 함께 삽입할지 여부를 지정합니다. 비활성화하면 통계는 머지 중 또는 명시적인 MATERIALIZE STATISTICS를 통해 생성되고 저장됩니다

​

materialize_ttl_after_modify

ALTER MODIFY TTL 쿼리 이후 기존 데이터에도 TTL을 적용합니다

​

materialized_views_ignore_errors

MATERIALIZED VIEW의 오류를 무시하고, MV와 관계없이 원래 block을 테이블로 전달할 수 있도록 합니다

​

materialized_views_squash_parallel_inserts

생성되는 파트 수를 줄이기 위해, 단일 INSERT 쿼리의 병렬 삽입에서 materialized view 대상 테이블로 들어가는 삽입을 합칩니다. false로 설정되어 있고 parallel_view_processing이 활성화된 경우, INSERT 쿼리는 각 max_insert_thread마다 대상 테이블에 파트를 생성합니다.

​

max_analyze_depth

인터프리터가 수행하는 최대 분석 횟수입니다.

​

max_ast_depth

쿼리 구문 트리의 최대 중첩 깊이입니다. 이 값을 초과하면 예외가 발생합니다.

현재는 구문 분석 중에는 검사하지 않고, 쿼리 구문 분석이 끝난 후에만 검사합니다. 즉, 구문 분석 중에 지나치게 깊은 구문 트리가 생성될 수 있지만, 쿼리는 실패합니다.

​

max_ast_elements

쿼리 구문 트리의 최대 요소 수입니다. 이 값을 초과하면 예외가 발생합니다.

현재는 파싱 중에는 이를 검사하지 않고, 쿼리 파싱이 끝난 후에만 검사합니다. 즉, 파싱 중에 지나치게 깊은 구문 트리가 생성될 수 있지만, 쿼리는 실패합니다.

​

max_autoincrement_series

generateSerialID 함수가 생성할 수 있는 series 수의 제한입니다.

각 series는 Keeper의 노드 하나를 나타내므로, 그 수는 최대 수백만 개 수준으로 유지하는 것이 좋습니다.

​

max_backup_bandwidth

server의 특정 Backup에 대한 초당 최대 읽기 속도(바이트)입니다. 0은 제한이 없음을 의미합니다.

​

max_block_size

ClickHouse에서는 데이터가 컬럼 파트의 집합인 블록 단위로 처리됩니다. 단일 블록에 대한 내부 처리 사이클은 효율적이지만, 각 블록을 처리할 때마다 무시할 수 없는 비용이 발생합니다.

max_block_size 설정은 테이블(table)에서 데이터를 로드할 때 단일 블록에 포함할 권장 최대 행 수를 나타냅니다. 항상 max_block_size 크기의 블록이 테이블에서 로드되는 것은 아닙니다. ClickHouse가 더 적은 데이터만 읽어오면 된다고 판단하면 더 작은 블록을 처리합니다.

각 블록을 처리할 때 발생하는 비용이 커지지 않도록 블록 크기는 너무 작아서는 안 됩니다. 또한 LIMIT 절이 있는 쿼리가 첫 번째 블록을 처리한 후 빠르게 실행되도록 블록 크기가 너무 커서도 안 됩니다. max_block_size를 설정할 때는 여러 스레드에서 많은 컬럼을 추출할 때 메모리를 과도하게 사용하지 않도록 하고, 최소한의 cache 지역성도 유지하는 것을 목표로 해야 합니다.

​

max_bytes_before_external_group_by

Cloud 기본값: 레플리카당 메모리 용량의 절반입니다.

GROUP BY 절을 외부 메모리에서 실행하도록 설정하거나 해제합니다. (외부 메모리의 GROUP BY 참조)

가능한 값:

• 단일 GROUP BY 작업에서 사용할 수 있는 최대 RAM 용량(바이트)입니다.
• 0 — 외부 메모리의 GROUP BY가 비활성화됩니다.

GROUP BY 작업 중 메모리 사용량이 이 바이트 단위 임계값을 초과하면 ‘외부 집계’ 모드가 활성화됩니다(데이터를 디스크에 spill).

권장 값은 사용 가능한 시스템 메모리의 절반입니다.

​

max_bytes_before_external_join

0이 아닌 값으로 설정하고 join_algorithm이 hash, parallel_hash, default 또는 auto인 경우, 오른쪽 데이터가 이 바이트 수를 초과하면 디스크 스필이 가능하도록 해시 조인이 자동으로 grace hash join으로 변환됩니다. 0(기본값)으로 설정하면 이 절대 바이트 임계값은 비활성화되지만, max_bytes_ratio_before_external_join(기본값 0.5)에 의해 자동 스필이 계속 발생할 수 있습니다. 자동 스필을 완전히 비활성화하려면 두 값을 모두 0으로 설정하십시오. 이 설정은 조인 최적화를 통한 read in order를 방지합니다.

​

max_bytes_before_external_sort

Cloud 기본값: 레플리카당 메모리 용량의 절반.

ORDER BY 절을 외부 메모리(external memory)에서 실행할지 여부를 설정합니다. ORDER BY 구현 세부 사항을 참조하십시오. ORDER BY 작업 중 메모리 사용량이 바이트 기준으로 이 임계값을 초과하면 “외부 정렬” 모드(데이터를 디스크로 기록)가 활성화됩니다.

가능한 값:

• 단일 ORDER BY 작업에 사용할 수 있는 최대 RAM 용량(바이트)입니다. 권장 값은 사용 가능한 시스템 메모리의 절반입니다.
• 0 — 외부 메모리에서 ORDER BY를 실행하지 않습니다.

​

max_bytes_before_remerge_sort

ORDER BY와 LIMIT를 함께 사용하는 경우, 메모리 사용량이 지정된 임계값을 초과하면 최종 머지 전에 블록을 추가로 머지하는 단계를 수행하여 상위 LIMIT 행만 유지합니다.

​

max_bytes_for_lazy_final

lazy FINAL 최적화에서 집합에 허용되는 최대 바이트 수입니다. 이 값을 초과하면 일반 FINAL로 대체됩니다.

​

max_bytes_in_distinct

DISTINCT를 사용할 때 해시 테이블이 사용하는 메모리에 있는 상태의 최대 바이트 수(비압축 바이트 기준)입니다.

​

max_bytes_in_join

테이블을 조인할 때 사용되는 해시 테이블의 최대 크기(바이트 수)입니다.

이 설정은 SELECT … JOIN 연산과 Join 테이블 엔진에 적용됩니다.

쿼리에 조인이 포함되어 있으면 ClickHouse는 각 중간 결과에 대해 이 설정을 확인합니다.

제한에 도달하면 ClickHouse는 서로 다른 동작을 수행할 수 있습니다. 수행할 동작을 선택하려면 join_overflow_mode 설정을 사용하십시오.

가능한 값:

• 양의 정수.
• 0 — 메모리 제어가 비활성화됩니다.

​

max_bytes_in_set

서브쿼리로 생성된 IN 절의 Set에서 사용하는 최대 바이트 수(비압축 데이터 기준)입니다.

​

max_bytes_ratio_before_external_group_by

사용 가능한 메모리 중 GROUP BY에 사용할 수 있는 비율입니다. 이 한도에 도달하면 집계에 외부 메모리를 사용합니다.

예를 들어 0.6으로 설정하면 GROUP BY는 실행 시작 시 사용 가능한 메모리의 60% (server/user/merges 기준)까지 사용할 수 있으며, 그 이후에는 외부 집계를 사용하기 시작합니다.

​

max_bytes_ratio_before_external_join

JOIN에 사용할 수 있는 가용 메모리 비율입니다. 이 한도에 도달하면 해시 조인은 오른쪽 데이터를 디스크로 스필할 수 있도록 grace hash join으로 전환됩니다.

예를 들어 0.6으로 설정하면, JOIN은 실행 시작 시 오른쪽 해시 테이블에 대해 가용 메모리(서버/사용자/머지에 사용 가능한 메모리 기준)의 60%까지 사용할 수 있습니다. 이후에는 디스크로 스필하기 시작합니다.

max_bytes_before_external_join와 max_bytes_ratio_before_external_join가 모두 설정된 경우에는 계산된 임계값 중 더 작은 값이 사용됩니다. 비율이 0이면 절대값 설정만 적용됩니다.

join_algorithm이 hash, parallel_hash, default, 또는 auto이고 임시 데이터 경로가 구성된 경우에만 적용됩니다.

​

max_bytes_ratio_before_external_sort

ORDER BY에 사용할 수 있는 가용 메모리의 비율입니다. 이 한도에 도달하면 외부 정렬이 사용됩니다.

예를 들어 0.6으로 설정하면 실행 시작 시 ORDER BY에 가용 메모리의 60%(server/user/merges 기준)까지 사용할 수 있으며, 그 이후부터는 외부 정렬을 사용하기 시작합니다.

참고로 max_bytes_before_external_sort는 여전히 적용되며, 디스크 스필은 정렬 블록이 max_bytes_before_external_sort보다 큰 경우에만 수행됩니다.

​

max_bytes_to_read

쿼리 실행 시 테이블에서 읽을 수 있는 최대 바이트 수(압축되지 않은 데이터 기준)입니다. 이 제한은 처리되는 각 데이터 청크마다 확인되며, 가장 안쪽의 테이블 표현식에만 적용됩니다. 또한 원격 서버에서 읽는 경우에는 원격 서버에서만 확인됩니다.

​

max_bytes_to_read_leaf

분산 쿼리를 실행할 때 리프 노드의 로컬 테이블에서 읽을 수 있는 최대 바이트 수(비압축 데이터 기준)입니다. 분산 쿼리는 각 세그먼트(리프)에 여러 하위 쿼리를 보낼 수 있지만, 이 제한은 리프 노드의 읽기 단계에서만 검사되며 루트 노드의 결과 병합 단계에서는 무시됩니다.

예를 들어, 클러스터가 2개의 세그먼트로 구성되어 있고 각 세그먼트에 100바이트의 데이터가 있는 테이블이 포함되어 있다고 가정하겠습니다. max_bytes_to_read=150 설정으로 두 테이블의 모든 데이터를 읽는 분산 쿼리는 전체 크기가 200바이트이므로 실패합니다. max_bytes_to_read_leaf=150인 쿼리는 리프 노드가 최대 100바이트만 읽으므로 성공합니다.

이 제한은 처리되는 각 데이터 청크에 대해 검사됩니다.

이 설정은 prefer_localhost_replica=1과 함께 사용할 때 불안정합니다.

​

max_bytes_to_sort

정렬 전에 처리되는 최대 바이트 수입니다. ORDER BY 작업을 위해 지정된 양보다 많은 비압축 바이트를 처리해야 하는 경우, 동작은 기본적으로 throw로 설정된 sort_overflow_mode에 따라 결정됩니다.

​

max_bytes_to_transfer

GLOBAL IN/JOIN 절이 실행될 때 원격 서버로 전달되거나 임시 테이블(temporary table)에 저장될 수 있는 최대 바이트 수입니다(압축되지 않은 데이터).

​

max_columns_to_read

단일 쿼리에서 테이블에서 읽을 수 있는 최대 컬럼 수입니다. 쿼리에서 지정된 수보다 더 많은 컬럼을 읽어야 하면 예외가 발생합니다.

이 설정은 지나치게 복잡한 쿼리를 방지하는 데 유용합니다.

0 값은 제한이 없음을 의미합니다.

​

max_compress_block_size

테이블에 쓰기 전에 데이터를 압축할 때, 비압축 데이터 블록의 최대 크기를 지정합니다. 기본값은 1,048,576(1 MiB)입니다. 더 작은 블록 크기를 지정하면 일반적으로 압축률은 약간 낮아지지만, 캐시 지역성 덕분에 압축 및 압축 해제 속도는 약간 빨라지고 메모리 사용량은 줄어듭니다.

이 설정은 전문가 수준의 설정이므로 ClickHouse를 막 사용하기 시작한 단계라면 변경하지 않는 것이 좋습니다.

압축용 블록(바이트로 구성된 메모리 청크)과 쿼리 처리용 블록(테이블의 행 집합)을 혼동하지 마십시오.

​

max_concurrent_queries_for_all_users

이 설정값이 현재 동시에 처리 중인 쿼리 수보다 작거나 같으면 예외를 발생시킵니다.

예시: max_concurrent_queries_for_all_users는 모든 사용자에 대해 99로 설정할 수 있으며, 데이터베이스 관리자는 서버에 과부하가 걸린 경우에도 조사용 쿼리를 실행할 수 있도록 자신의 값은 100으로 설정할 수 있습니다.

하나의 쿼리나 사용자에 대한 설정 변경은 다른 쿼리에 영향을 주지 않습니다.

가능한 값:

• 양의 정수
• 0 — 제한 없음

예시

<max_concurrent_queries_for_all_users>99</max_concurrent_queries_for_all_users>

관련 항목

• max_concurrent_queries

Cloud 기본값: 1000.

​

max_concurrent_queries_for_user

사용자당 동시에 처리할 수 있는 최대 쿼리 수입니다.

가능한 값:

• 양의 정수
• 0 — 제한 없음

예시

<max_concurrent_queries_for_user>5</max_concurrent_queries_for_user>

​

max_consume_snapshots

증분 읽기당 처리할 Paimon 스냅샷의 최대 개수입니다. 0은 제한이 없음을 의미합니다.

​

max_distributed_connections

단일 분산 테이블에 대해 하나의 쿼리를 분산 처리할 때 원격 서버와 동시에 설정할 수 있는 최대 연결 수입니다. 이 값은 클러스터 내 서버 수보다 작지 않게 설정하는 것이 좋습니다.

다음 매개변수는 분산 테이블을 생성할 때(그리고 서버를 시작할 때)만 사용되므로 런타임에 변경할 필요가 없습니다.

​

max_distributed_depth

분산(Distributed) 테이블에서 재귀 쿼리의 최대 깊이를 제한합니다.

이 값을 초과하면 서버에서 예외가 발생합니다.

가능한 값:

• 양의 정수.
• 0 — 깊이 제한 없음.

​

max_download_buffer_size

각 thread에서 병렬 다운로드(예: URL 엔진)에 사용하는 buffer의 최대 크기입니다.

​

max_download_threads

데이터 다운로드에 사용할 최대 스레드 수입니다(예: URL 엔진).

​

max_estimated_execution_time

쿼리의 최대 예상 실행 시간을 초 단위로 지정합니다. 이 값은 각 데이터 블록에서 timeout_before_checking_execution_speed 이 만료될 때마다 확인됩니다.

​

max_execution_speed

초당 실행할 수 있는 최대 행 수입니다. timeout_before_checking_execution_speed 기간이 만료되면 각 데이터 블록에서 이를 확인합니다. 실행 속도가 너무 높으면 속도가 제한됩니다.

​

max_execution_speed_bytes

초당 최대 실행 바이트 수입니다. 모든 데이터 블록에서 timeout_before_checking_execution_speed 시간이 만료되면 이를 검사합니다. 실행 속도가 너무 높으면 속도가 제한됩니다.

​

max_execution_time

최대 쿼리 실행 시간(초)입니다.

max_execution_time 매개변수는 다소 이해하기 어려울 수 있습니다. 이 매개변수는 현재 쿼리 실행 속도를 기준으로 한 보간값에 따라 동작합니다. (이 동작은 timeout_before_checking_execution_speed로 제어됩니다.)

예상 실행 시간이 지정된 max_execution_time를 초과하면 ClickHouse가 쿼리를 중단합니다. 기본적으로 timeout_before_checking_execution_speed는 10초로 설정되어 있습니다. 즉, 쿼리가 10초 동안 실행된 후부터 ClickHouse가 전체 실행 시간을 추정하기 시작합니다. 예를 들어 max_execution_time를 3600초(1시간)로 설정한 경우, 예상 시간이 이 3600초 제한을 초과하면 ClickHouse가 쿼리를 종료합니다. timeout_before_checking_execution_speed를 0으로 설정하면 ClickHouse는 max_execution_time의 기준으로 실제 경과 시간을 사용합니다.

쿼리 런타임이 지정된 초 수를 초과하면 동작은 timeout_overflow_mode에 따라 결정되며, 기본값은 throw입니다.

타임아웃은 데이터 처리 중 지정된 지점에서만 확인되므로, 쿼리도 그 지점에서만 중지될 수 있습니다. 현재는 집계 상태를 병합하는 중이나 쿼리 분석 중에는 중지할 수 없으므로, 실제 실행 시간은 이 설정값보다 길어질 수 있습니다.

​

max_execution_time_leaf

의미상 max_execution_time와 유사하지만, 분산 또는 원격 쿼리에서 리프 노드에만 적용됩니다.

예를 들어, 초기 노드에는 제한을 두지 않으면서 리프 노드의 실행 시간만 10s로 제한하려면, 중첩된 서브쿼리 설정에 max_execution_time을 두는 대신 다음과 같이 합니다:

SELECT count()
FROM cluster(cluster, view(SELECT * FROM t SETTINGS max_execution_time = 10));

쿼리 설정으로 max_execution_time_leaf를 사용할 수 있습니다:

SELECT count()
FROM cluster(cluster, view(SELECT * FROM t)) SETTINGS max_execution_time_leaf = 10;

​

max_expanded_ast_elements

alias와 별표(*)를 확장한 후 쿼리 구문 트리의 최대 크기(노드 수)입니다.

​

max_fetch_partition_retries_count

다른 호스트에서 파티션을 가져올 때 재시도하는 횟수입니다.

​

max_final_threads

FINAL 수정자가 적용된 SELECT 쿼리의 데이터 읽기 단계에서 사용할 병렬 스레드의 최대 개수를 설정합니다.

가능한 값:

• 양의 정수
• 0 또는 1 — 비활성화됩니다. SELECT 쿼리는 단일 스레드로 실행됩니다.

​

max_http_get_redirects

허용되는 HTTP GET 리디렉션 홉의 최대 개수입니다. 악의적인 서버가 요청을 예상치 못한 서비스로 리디렉션하는 것을 방지하기 위한 추가 보안 조치가 적용되도록 합니다.\n\n이 문제는 외부 서버가 다른 주소로 리디렉션했는데, 그 주소가 회사 인프라 내부 주소인 것처럼 보일 때 발생합니다. 이 경우 내부 server로 HTTP request를 보내면서 인증을 우회해 내부 네트워크의 내부 API를 요청하거나 Redis, Memcached 등의 다른 서비스에 쿼리를 보낼 수 있습니다. 내부 인프라(localhost에서 실행 중인 항목 포함)가 없거나 해당 server를 신뢰할 수 있다면 리디렉션을 허용해도 안전합니다. 다만 URL이 HTTPS가 아니라 HTTP를 사용하는 경우에는 원격 server뿐 아니라 ISP와 그 사이에 있는 모든 네트워크까지 신뢰해야 한다는 점에 유의하십시오.

Cloud 기본값: 10.

​

max_hyperscan_regexp_length

hyperscan multi-match 함수에서 각 정규식의 최대 길이를 정의합니다.

가능한 값:

• 양의 정수입니다.
• 0 - 길이 제한이 없습니다.

예시

쿼리:

SELECT multiMatchAny('abcd', ['ab','bcd','c','d']) SETTINGS max_hyperscan_regexp_length = 3;

결과:

┌─multiMatchAny('abcd', ['ab', 'bcd', 'c', 'd'])─┐
│                                              1 │
└────────────────────────────────────────────────┘

쿼리:

SELECT multiMatchAny('abcd', ['ab','bcd','c','d']) SETTINGS max_hyperscan_regexp_length = 2;

결과:

Exception: Regexp length too large.

관련 항목

• max_hyperscan_regexp_total_length

​

max_hyperscan_regexp_total_length

각 hyperscan multi-match 함수에서 사용하는 모든 정규식의 총 길이 최댓값을 설정합니다.

Possible values:

• 양의 정수입니다.
• 0 - 길이에 제한이 없습니다.

예시

쿼리:

SELECT multiMatchAny('abcd', ['a','b','c','d']) SETTINGS max_hyperscan_regexp_total_length = 5;

결과:

┌─multiMatchAny('abcd', ['a', 'b', 'c', 'd'])─┐
│                                           1 │
└─────────────────────────────────────────────┘

쿼리:

SELECT multiMatchAny('abcd', ['ab','bc','c','d']) SETTINGS max_hyperscan_regexp_total_length = 5;

결과:

Exception: Total regexp lengths too large.

관련 항목

• max_hyperscan_regexp_length

​

max_insert_block_size

별칭: max_insert_block_size_rows

테이블에 삽입할 때 형성되는 블록의 최대 크기(행 수 기준)입니다.

이 설정은 다음 두 가지 상황에서 블록 형성을 제어합니다.

1. 포맷 파싱: 서버가 임의의 인터페이스(HTTP, 인라인 데이터가 포함된 clickhouse-client, gRPC, PostgreSQL wire protocol)를 통해 행 기반 입력 형식(CSV, TSV, JSONEachRow 등)을 파싱할 때, 다음 조건에서 블록이 생성됩니다.

   • min_insert_block_size_rows AND min_insert_block_size_bytes에 모두 도달한 경우, OR
   • max_insert_block_size_rows OR max_insert_block_size_bytes 중 하나에 도달한 경우

   참고: clickhouse-client 또는 clickhouse-local로 파일을 읽는 경우에는 클라이언트 자체가 데이터를 파싱하므로, 이 설정은 클라이언트 측에 적용됩니다.

2. INSERT 작업: INSERT 쿼리 실행 중이거나 데이터가 materialized views를 통해 흐를 때는 use_strict_insert_block_limits에 따라 이 설정의 동작이 달라집니다.

   • 활성화된 경우: 다음 조건에서 블록이 생성됩니다.

     • 최소 임계값(AND): min_insert_block_size_rows AND min_insert_block_size_bytes에 모두 도달
     • 최대 임계값(OR): max_insert_block_size_rows OR max_insert_block_size_bytes 중 하나에 도달

   • 비활성화된 경우: min_insert_block_size_rows OR min_insert_block_size_bytes 중 하나에 도달하면 블록이 생성됩니다. max_insert_block_size 설정은 적용되지 않습니다.

가능한 값:

• 양의 정수.

​

max_insert_block_size_bytes

테이블에 삽입할 때 구성되는 블록의 최대 크기(바이트 단위)입니다.

이 설정은 max_insert_block_size_rows와 함께 작동하며 같은 맥락에서 블록 형성을 제어합니다. 이러한 설정이 언제, 어떻게 적용되는지에 대한 자세한 내용은 max_insert_block_size_rows를 참조하십시오.

가능한 값:

• 양의 정수입니다.
• 0 — 블록 형성에 이 설정이 사용되지 않습니다.

​

max_insert_delayed_streams_for_parallel_write

최종 part 플러시를 지연하기 위한 최대 스트림(컬럼) 수입니다. 기본값은 자동이며, 기반 저장소(underlying storage)가 병렬 쓰기를 지원하는 경우(예: S3) 100이고, 그렇지 않으면 비활성화됩니다.

Cloud 기본값: 50.

​

max_insert_threads

INSERT SELECT 쿼리 실행에 사용할 수 있는 최대 스레드 수입니다.

가능한 값:

• 0 (또는 1) — INSERT SELECT는 병렬 실행되지 않습니다.
• 양의 정수. 1보다 커야 합니다.

Cloud 기본값:

• 메모리 8 GiB 노드는 1
• 메모리 16 GiB 노드는 2
• 더 큰 노드는 4

병렬 INSERT SELECT는 SELECT 부분도 병렬로 실행될 때만 효과가 있습니다. max_threads 설정을 참조하십시오. 값이 클수록 메모리 사용량도 증가합니다.

​

max_insert_threads_min_free_memory_per_thread

max_threads가 아니라 max_insert_threads에 적용된다는 점만 제외하면 max_threads_min_free_memory_per_thread와 동일합니다. 기본값이 더 큰 이유는 삽입 파이프라인이 일반적으로 읽기 파이프라인보다 스레드당 더 큰 버퍼(MergeTree 파트, compression 블록)를 유지하기 때문입니다.

여유 메모리 양이 max_insert_threads에 이 값을 곱한 값보다 적으면, max_insert_threads는 이에 맞게 최소 1까지 줄어듭니다.

이 제한을 비활성화하려면 0으로 설정합니다.

​

max_joined_block_size_bytes

JOIN 결과 block의 최대 크기(바이트 단위)입니다(조인 알고리즘이 이를 지원하는 경우). 0은 무제한을 의미합니다.

​

max_joined_block_size_rows

JOIN 결과의 최대 block 크기입니다(조인 알고리즘이 이를 지원하는 경우). 0은 무제한을 의미합니다.

​

벡터 검색 쿼리의 최대 LIMIT

이 설정값보다 큰 LIMIT를 사용하는 SELECT 쿼리에는 벡터 유사도 인덱스를 사용할 수 없습니다. 벡터 유사도 인덱스에서 메모리 오버플로우가 발생하지 않도록 하는 데 도움이 됩니다.

​

max_local_read_bandwidth

로컬 읽기의 초당 최대 바이트 수입니다.

​

max_local_write_bandwidth

로컬 쓰기의 초당 최대 속도를 바이트 단위로 나타냅니다.

​

max_memory_usage

Cloud 기본값: 레플리카의 RAM 용량에 따라 달라집니다.

단일 서버에서 쿼리를 실행할 때 사용할 수 있는 RAM의 최대량입니다. 값이 0이면 제한이 없음을 의미합니다.

이 설정은 사용 가능한 메모리 용량이나 시스템의 전체 메모리 용량을 고려하지 않습니다. 이 제한은 단일 서버 내 단일 쿼리에 적용됩니다.

SHOW PROCESSLIST를 사용하면 각 쿼리의 현재 메모리 사용량을 확인할 수 있습니다. 최대 메모리 사용량은 각 쿼리별로 추적되며 로그에 기록됩니다.

다음 String 및 Array 인수를 사용하는 집계 함수의 상태에 대해서는 메모리 사용량이 완전히 추적되지 않습니다.

• min
• max
• any
• anyLast
• argMin
• argMax

메모리 사용량은 매개변수 max_memory_usage_for_user 및 max_server_memory_usage에 의해서도 제한됩니다.

​

max_memory_usage_for_user

단일 서버에서 사용자의 쿼리를 실행할 때 사용할 수 있는 최대 RAM 용량입니다. 0은 무제한을 의미합니다.

기본적으로 이 용량에는 제한이 없습니다(max_memory_usage_for_user = 0).

max_memory_usage 설명도 참고하십시오.

예를 들어 clickhouse_read라는 이름의 사용자에 대해 max_memory_usage_for_user를 1000바이트로 설정하려면, 다음 SQL 문을 사용할 수 있습니다.

ALTER USER clickhouse_read SETTINGS max_memory_usage_for_user = 1000;

제대로 적용되었는지 확인하려면 클라이언트에서 로그아웃했다가 다시 로그인한 후 getSetting 함수를 사용하십시오:

SELECT getSetting('max_memory_usage_for_user');

​

max_network_bandwidth

네트워크를 통한 데이터 전송 속도를 초당 바이트 수 기준으로 제한합니다. 이 설정은 모든 쿼리에 적용됩니다.

가능한 값:

• 양의 정수입니다.
• 0 — 대역폭 제어가 비활성화됩니다.

​

max_network_bandwidth_for_all_users

네트워크를 통해 데이터가 초당 바이트 단위로 전송되는 속도를 제한합니다. 이 설정은 서버에서 동시에 실행되는 모든 쿼리에 적용됩니다.

가능한 값:

• 양의 정수입니다.
• 0 — 데이터 전송 속도 제어가 비활성화됩니다.

​

max_network_bandwidth_for_user

네트워크를 통한 데이터 전송 속도를 초당 바이트 수 기준으로 제한합니다. 이 설정은 한 사용자가 실행하는 모든 동시 실행 쿼리에 적용됩니다.

가능한 값:

• 양의 정수입니다.
• 0 — 데이터 전송 속도 제한이 비활성화됩니다.

​

max_network_bytes

쿼리를 실행할 때 네트워크를 통해 수신하거나 전송하는 데이터 양(바이트 단위)을 제한합니다. 이 설정은 각 개별 쿼리에 적용됩니다.

가능한 값:

• 양의 정수입니다.
• 0 — 데이터 양 제한이 비활성화됩니다.

​

max_number_of_partitions_for_independent_aggregation

최적화를 적용하기 위한 테이블의 최대 파티션 수

​

max_os_cpu_wait_time_ratio_to_throw

쿼리 거부를 판단할 때 기준이 되는 OS CPU 대기 시간(OSCPUWaitMicroseconds 메트릭)과 사용 시간(OSCPUVirtualTimeMicroseconds 메트릭) 간의 최대 비율입니다. 확률 계산에는 최소 비율과 최대 비율 사이의 선형 보간을 사용하며, 이 지점에서 확률은 1이 됩니다.

​

max_parallel_replicas

쿼리 실행 시 각 세그먼트에서 사용할 수 있는 최대 레플리카 수입니다.

가능한 값:

• 양의 정수.

추가 정보

이 옵션은 사용하는 설정에 따라 결과가 달라질 수 있습니다.

​

SAMPLE 키를 사용한 병렬 처리

쿼리를 여러 서버에서 병렬로 실행하면 더 빠르게 처리될 수 있습니다. 하지만 다음과 같은 경우에는 쿼리 성능이 저하될 수 있습니다.

• 파티셔닝 키에서 샘플링 키의 위치가 효율적인 범위 스캔에 적합하지 않습니다.
• 테이블에 샘플링 키를 추가하면 다른 컬럼으로 필터링하는 효율이 떨어집니다.
• 샘플링 키가 계산 비용이 큰 표현식입니다.
• 클러스터의 지연 시간 분포에 긴 꼬리가 있어, 더 많은 서버에 쿼리할수록 전체 쿼리 지연 시간이 증가합니다.

​

parallel_replicas_custom_key를 사용한 병렬 처리

이 설정은 모든 복제된 테이블(Replicated Table)에서 유용합니다.

​

max_parser_backtracks

최대 파서 백트래킹 횟수입니다(재귀 하강 파싱 과정에서 서로 다른 대안을 몇 번 시도할 수 있는지 나타냅니다).

​

max_parser_depth

재귀 하강 parser의 최대 재귀 깊이를 제한합니다. 이를 통해 스택 크기를 제어할 수 있습니다.

가능한 값:

• 양의 정수
• 0 — 재귀 깊이가 무제한입니다.

​

max_parsing_threads

병렬 파싱을 지원하는 입력 형식에서 데이터를 파싱할 때 사용할 최대 스레드 수입니다. 기본적으로 자동으로 결정됩니다.

​

max_partition_size_to_drop

쿼리 시점에 파티션을 삭제하는 작업에 적용되는 제한입니다. 값 0은 제한 없이 파티션을 삭제할 수 있음을 의미합니다.

Cloud 기본값: 1 TB.

이 쿼리 설정은 해당 서버 설정 값을 재정의합니다. max_partition_size_to_drop를 참조하십시오.

​

max_partitions_per_insert_block

단일 삽입 블록에 포함될 수 있는 최대 파티션 수를 제한하며, 블록에 파티션이 너무 많이 포함되어 있으면 예외가 발생합니다.

• 양의 정수입니다.
• 0 — 파티션 수에 제한이 없습니다.

세부 정보

데이터를 삽입할 때 ClickHouse는 삽입된 블록의 파티션 수를 계산합니다. 파티션 수가 max_partitions_per_insert_block보다 많으면 ClickHouse는 throw_on_max_partitions_per_insert_block 설정에 따라 경고를 로그에 기록하거나 예외를 발생시킵니다. 예외 텍스트는 다음과 같습니다.

“단일 INSERT 블록의 파티션 수가 너무 많습니다 (partitions_count partitions, limit is ” + toString(max_partitions) + ”). 이 제한은 ‘max_partitions_per_insert_block’ 설정으로 제어됩니다. 많은 수의 파티션을 사용하는 것은 흔한 오해입니다. 이는 server 시작 지연, INSERT 쿼리 지연, SELECT 쿼리 지연을 포함한 심각한 성능 저하를 초래합니다. table의 권장 총 파티션 수는 1000..10000 미만입니다. 파티셔닝은 SELECT 쿼리 속도를 높이기 위한 것이 아니라는 점에 유의하십시오 (범위 쿼리를 빠르게 만드는 데는 ORDER BY key로 충분합니다). 파티션은 데이터 조작(DROP PARTITION 등)을 위한 것입니다.”

많은 수의 파티션을 사용하는 것은 흔한 오해이므로, 이 설정은 안전 임계값입니다.

​

max_partitions_to_read

단일 쿼리에서 액세스할 수 있는 파티션의 최대 수를 제한합니다.

테이블 생성 시 지정한 설정 값은 쿼리 수준 설정으로 재정의할 수 있습니다.

가능한 값:

• 양의 정수
• -1 - 무제한(기본값)

테이블 설정에서도 MergeTree 설정 max_partitions_to_read를 지정할 수 있습니다.

​

max_parts_to_move

하나의 쿼리에서 이동할 수 있는 파트 개수를 제한합니다. 0은 무제한을 의미합니다.

​

max_projection_rows_to_use_projection_index

프로젝션 인덱스에서 읽을 행 수가 이 임계값 이하인 경우, ClickHouse는 쿼리 실행 중 프로젝션 인덱스를 적용하려고 시도합니다.

​

max_query_size

SQL parser가 파싱할 수 있는 쿌리 문자열의 최대 바이트 수입니다. INSERT 쿼리의 VALUES 절에 있는 데이터는 별도의 stream parser(O(1) RAM 사용)로 처리되므로 이 제한의 적용을 받지 않습니다.

max_query_size는 SQL 쿼리 내에서 설정할 수 없습니다(예: SELECT now() SETTINGS max_query_size=10000). ClickHouse는 쿼리를 파싱하기 위해 버퍼를 할당해야 하며, 이 버퍼의 크기는 max_query_size 설정에 따라 결정됩니다. 그리고 이 설정은 쿼리가 실행되기 전에 미리 구성되어 있어야 합니다.

​

max_rand_distribution_parameter

randChiSquared, randStudentT, randFisherF와 같은 난수 분포 함수에서 분포 형상 매개변수의 최댓값입니다. 극단적인 매개변수 값으로 인해 계산 시간이 과도하게 길어지는 것을 방지합니다.

​

max_rand_distribution_trials

randBinomial 및 randNegativeBinomial과 같은 난수 분포 함수에 허용되는 최대 시행 횟수입니다. 시행 횟수가 매우 큰 경우 계산 시간이 지나치게 길어지는 것을 방지합니다.

​

max_read_buffer_size

파일 시스템에서 읽을 때 사용하는 buffer의 최대 크기입니다.

​

max_read_buffer_size_local_fs

local filesystem에서 읽을 때 사용하는 버퍼의 최대 크기입니다. 0으로 설정하면 max_read_buffer_size가 사용됩니다.

​

max_read_buffer_size_remote_fs

원격 파일 시스템에서 읽을 때 사용하는 버퍼의 최대 크기입니다. 0으로 설정하면 max_read_buffer_size가 사용됩니다.

​

max_recursive_cte_evaluation_depth

재귀 CTE 평가 깊이의 최대 제한

​

max_remote_read_network_bandwidth

읽기 작업의 네트워크 데이터 전송 최대 속도(초당 바이트 수)입니다.

​

max_remote_write_network_bandwidth

쓰기 시 네트워크를 통한 데이터 전송의 최대 속도를 초당 바이트 수로 나타낸 값입니다.

​

max_replica_delay_for_distributed_queries

분산 쿼리에서 지연이 큰 레플리카를 제외합니다. 복제를 참조하십시오.

시간을 초 단위로 지정합니다. 레플리카의 지연이 설정된 값보다 크거나 같으면 해당 레플리카는 사용되지 않습니다.

가능한 값:

• 양의 정수.
• 0 — 레플리카 지연을 확인하지 않습니다.

0이 아닌 지연이 있는 레플리카를 전혀 사용하지 않으려면 이 매개변수를 1로 설정하십시오.

복제된 테이블(replicated tables)을 가리키는 분산 테이블(distributed table)에서 SELECT를 수행할 때 사용됩니다.

​

max_result_bytes

결과 크기를 바이트 단위(압축되지 않은 기준)로 제한합니다. 임계값에 도달하면 현재 데이터 블록의 처리를 마친 후 쿼리가 중지되지만, 결과의 마지막 블록은 잘라내지 않으므로 결과 크기가 임계값보다 커질 수 있습니다.

주의 사항

이 임계값을 계산할 때는 메모리에 있는 결과 크기도 함께 고려합니다. 결과 크기 자체는 작더라도 메모리에서 더 큰 데이터 구조를 참조할 수 있으며, 예를 들어 LowCardinality 컬럼의 딕셔너리와 AggregateFunction 컬럼의 Arena가 이에 해당하므로, 결과 크기가 작아도 임계값을 초과할 수 있습니다.

이 설정은 상당히 저수준이므로 주의해서 사용해야 합니다

​

max_result_rows

Cloud 기본값: 0.

결과의 행 수를 제한합니다. 이 제한은 서브쿼리에도 적용되며, 분산 쿼리의 일부를 실행할 때는 원격 서버에서도 검사됩니다. 값이 0이면 제한이 적용되지 않습니다.

임계값에 도달하면 쿼리는 데이터 블록 처리를 마친 후 중지되지만 결과의 마지막 블록은 잘라내지 않으므로 결과 크기가 임계값보다 클 수 있습니다.

​

max_reverse_dictionary_lookup_cache_size_bytes

dictGetKeys 함수에서 사용하는 쿼리별 역방향 딕셔너리 조회 캐시의 최대 크기(바이트)입니다. 이 캐시는 동일한 쿼리 내에서 딕셔너리를 다시 스캔하지 않도록 속성 값별로 직렬화된 키 튜플을 저장합니다. 제한에 도달하면 항목이 LRU 방식으로 제거됩니다. 캐시를 비활성화하려면 0으로 설정하십시오.

​

max_rows_for_lazy_final

lazy FINAL 최적화에서 집합의 최대 행 수입니다. 이를 초과하면 일반 FINAL로 전환됩니다.

​

max_rows_in_distinct

DISTINCT를 사용할 때 서로 다른 행의 최대 개수입니다.

​

max_rows_in_join

테이블을 조인할 때 사용되는 해시 테이블의 행 수를 제한합니다.

이 설정은 SELECT … JOIN 작업과 Join 테이블 엔진에 적용됩니다.

쿼리에 여러 조인이 포함된 경우 ClickHouse는 각 중간 결과마다 이 설정을 확인합니다.

제한에 도달하면 ClickHouse는 서로 다른 방식으로 처리할 수 있습니다. 어떤 동작을 수행할지는 join_overflow_mode 설정에서 선택하십시오.

가능한 값:

• 양의 정수
• 0 — 행 수에 제한이 없습니다.

​

max_rows_in_set

서브쿼리에서 생성된 IN 절의 데이터 집합에 허용되는 최대 행 수입니다.

​

max_rows_in_set_to_optimize_join

조인을 수행하기 전에 서로의 행 집합을 기준으로 조인되는 테이블을 필터링하는 데 사용할 집합의 최대 크기입니다.

가능한 값:

• 0 — 비활성화합니다.
• 임의의 양의 정수.

​

max_rows_to_group_by

집계 시 생성되는 고유 키의 최대 개수입니다. 이 설정을 사용하면 집계를 수행할 때 메모리 사용량을 제한할 수 있습니다.

GROUP BY 수행 중 집계에서 지정된 개수보다 많은 행(고유한 GROUP BY 키)이 생성되면, 동작은 ‘group_by_overflow_mode’에 따라 결정됩니다. 기본값은 throw이지만, 근사 GROUP BY 모드로 전환할 수도 있습니다.

​

max_rows_to_read

쿼리를 실행할 때 테이블에서 읽을 수 있는 최대 행 수입니다. 이 제한은 처리되는 각 데이터 청크마다 검사되며, 가장 안쪽의 테이블 표현식에만 적용됩니다. 원격 서버에서 읽는 경우에는 원격 서버에서만 검사됩니다.

​

max_rows_to_read_leaf

분산 쿼리를 실행할 때 리프 노드의 로컬 테이블에서 읽을 수 있는 최대 행 수입니다. 분산 쿼리는 각 세그먼트(리프 노드)에 여러 하위 쿼리를 보낼 수 있지만, 이 제한은 리프 노드의 읽기 단계에서만 검사되며 루트 노드에서 결과를 병합하는 단계에서는 무시됩니다.

예를 들어, 클러스터가 2개의 세그먼트로 구성되어 있고 각 세그먼트에 100개의 행이 있는 테이블이 있다고 가정합니다. max_rows_to_read=150 설정으로 두 테이블의 모든 데이터를 읽도록 한 분산 쿼리는 전체 행 수가 200행이므로 실패합니다. max_rows_to_read_leaf=150인 쿼리는 리프 노드가 최대 100행만 읽으므로 성공합니다.

이 제한은 처리되는 각 데이터 청크에 대해 검사됩니다.

이 설정은 prefer_localhost_replica=1과 함께 사용할 때 안정적이지 않습니다.

​

max_rows_to_sort

정렬 전에 허용되는 최대 행 수입니다. 이 설정을 사용하면 정렬 시 메모리 사용량을 제한할 수 있습니다. ORDER BY 작업에서 지정된 수보다 많은 레코드를 처리해야 하는 경우, 동작 방식은 sort_overflow_mode에 따라 결정되며, 기본값은 throw입니다.

​

max_rows_to_transfer

GLOBAL IN/JOIN 절이 실행될 때 원격 서버로 전달되거나 임시 테이블(temporary table)에 저장될 수 있는 최대 크기(행 수)입니다.

​

max_sessions_for_user

ClickHouse 서버에서 인증된 사용자 1명당 동시에 사용할 수 있는 최대 세션 수입니다.

예시:

<profiles>
    <single_session_profile>
        <max_sessions_for_user>1</max_sessions_for_user>
    </single_session_profile>
    <two_sessions_profile>
        <max_sessions_for_user>2</max_sessions_for_user>
    </two_sessions_profile>
    <unlimited_sessions_profile>
        <max_sessions_for_user>0</max_sessions_for_user>
    </unlimited_sessions_profile>
</profiles>
<users>
    <!-- 사용자 Alice는 ClickHouse 서버에 동시에 한 번만 연결할 수 있습니다. -->
    <Alice>
        <profile>single_session_user</profile>
    </Alice>
    <!-- 사용자 Bob은 동시에 2개의 세션을 사용할 수 있습니다. -->
    <Bob>
        <profile>two_sessions_profile</profile>
    </Bob>
    <!-- 사용자 Charles는 동시 세션 수에 제한 없이 사용할 수 있습니다. -->
    <Charles>
        <profile>unlimited_sessions_profile</profile>
    </Charles>
</users>

가능한 값:

• 양의 정수
• 0 - 동시 session 수 무제한(기본값)

​

max_size_to_preallocate_for_aggregation

집계 전에 전체 해시 테이블에서 총 몇 개의 요소에 대해 공간을 미리 할당할 수 있는지

​

max_size_to_preallocate_for_joins

조인 전에 모든 해시 테이블에서 전체적으로 미리 공간을 할당할 수 있는 요소 수

​

max_skip_unavailable_shards_num

skip_unavailable_shards가 활성화되면 별도 오류 없이 건너뛸 수 있는 세그먼트의 최대 개수를 제한합니다. 사용할 수 없는 세그먼트 수가 이 값을 초과하면 조용히 건너뛰는 대신 예외가 발생합니다.

값이 0이면 제한이 없음을 의미합니다(기본 동작으로, 사용할 수 없는 모든 세그먼트를 건너뛸 수 있습니다).

​

max_skip_unavailable_shards_ratio

skip_unavailable_shards가 활성화되면, 오류 없이 건너뛸 수 있는 세그먼트 비율의 최댓값(0~1)을 제한합니다. 사용할 수 없는 세그먼트의 비율이 전체 세그먼트 대비 이 값을 초과하면, 조용히 건너뛰는 대신 예외가 발생합니다.

값이 0이면 제한이 없음을 의미합니다(기본 동작 — 사용할 수 없는 모든 세그먼트를 건너뛸 수 있습니다).

​

max_streams_for_files_processing_in_cluster_functions

0이 아니면 Cluster 테이블 함수에서 파일의 데이터를 읽는 스레드 수를 제한합니다.

​

max_streams_for_merge_tree_reading

0이 아니면 MergeTree 테이블의 읽기 스트림 개수를 제한합니다.

​

max_streams_for_union_step

UNION 단계에서 동시에 활성화되는 데이터 스트림 수를 제한합니다(UNION DISTINCT는 UNION ALL 단계 다음에 DISTINCT 단계를 적용하는 방식으로 구현되므로 UNION ALL과 UNION DISTINCT 모두에 적용됩니다). UNION 쿼리에 서브쿼리가 많으면 모든 서브쿼리가 동시에 읽기 버퍼를 열어, 메모리 사용량이 서브쿼리 수에 비례하게 됩니다. 이 설정은 Concat 프로세서를 삽입해 파이프라인을 좁힘으로써, 한 번에 활성화되는 스트림 수가 최대 이 값까지만 되도록 하여 피크 메모리를 크게 줄입니다. 실제 제한값은 이 값과 max_threads * max_streams_for_union_step_to_max_threads_ratio 중 더 작은 값입니다(둘 중 하나가 0이면 해당 값은 무시됨). 둘 다 0이면 파이프라인 축소가 적용되지 않습니다.

​

max_streams_for_union_step_to_max_threads_ratio

이 비율에 max_threads를 곱한 값으로 UNION 단계에서 동시에 활성화할 수 있는 스트림 수의 제한이 결정됩니다(UNION ALL과 UNION DISTINCT 모두에 적용됨). 실제 제한은 이 계산값과 max_streams_for_union_step 중 더 작은 값입니다(둘 중 하나가 0이면 무시됨). 예를 들어 max_threads = 8이고 이 비율을 1로 설정하면 동시에 활성화되는 스트림은 최대 8개입니다. 이 비율 기반 제한을 비활성화하려면 0으로 설정하십시오.

​

max_streams_multiplier_for_merge_tables

Merge 테이블에서 읽을 때 더 많은 스트림을 요청합니다. 스트림은 Merge 테이블이 사용하는 테이블 전반에 분산됩니다. 이렇게 하면 스레드 간에 작업을 더 고르게 분배할 수 있으며, 특히 대상 테이블들의 크기가 서로 다를 때 유용합니다.

​

max_streams_to_max_threads_ratio

스레드 수보다 많은 소스를 사용할 수 있게 하여 작업이 스레드 전체에 더 고르게 분산되도록 합니다. 이는 임시적인 해결책으로 간주됩니다. 앞으로는 소스 수를 스레드 수와 같게 유지하면서도, 각 소스가 자신에게 할당 가능한 작업을 동적으로 선택할 수 있게 될 것으로 예상되기 때문입니다.

​

max_subquery_depth

쿼리에 지정된 개수보다 많은 중첩 서브쿼리가 있으면 예외를 발생시킵니다.

이 설정을 사용하면 클러스터 사용자가 지나치게 복잡한 쿼리를 작성하지 않도록 보호하는 안전장치를 둘 수 있습니다.

​

max_table_size_to_drop

쿼리 시점에 테이블을 삭제할 때 적용되는 제한입니다. 값이 0이면 아무런 제한 없이 모든 테이블을 삭제할 수 있습니다.

Cloud 기본값: 1 TB.

이 쿼리 설정은 해당 server 설정을 덮어씁니다. max_table_size_to_drop를 참조하십시오.

​

max_temporary_columns

쿼리를 실행할 때 상수 컬럼을 포함해 동시에 RAM에 유지해야 하는 임시 컬럼의 최대 개수입니다. 중간 계산 결과로 메모리에 생성되는 임시 컬럼 수가 지정한 개수를 초과하면 예외가 발생합니다.

이 설정은 지나치게 복잡한 쿼리를 방지하는 데 유용합니다.

0은 제한이 없음을 의미합니다.

​

max_temporary_data_on_disk_size_for_query

동시에 실행되는 모든 쿼리에서 디스크의 임시 파일이 사용할 수 있는 최대 데이터 양(바이트)입니다.

가능한 값:

• 양의 정수
• 0 — 무제한(기본값)

​

max_temporary_data_on_disk_size_for_user

동시에 실행되는 해당 사용자의 모든 쿼리에서 디스크의 임시 파일이 사용할 수 있는 최대 데이터 크기를 바이트 단위로 지정합니다.

가능한 값:

• 양의 정수
• 0 — 제한 없음(기본값)

​

max_temporary_non_const_columns

max_temporary_columns와 마찬가지로, 쿼리 실행 시 동시에 RAM에 유지해야 하는 임시 컬럼의 최대 개수입니다. 단, 상수 컬럼은 제외합니다.

상수 컬럼은 쿼리 실행 중 매우 자주 생성되지만, 계산 리소스를 거의 사용하지 않습니다.

​

max_threads

원격 서버에서 데이터를 가져오는 스레드(‘max_distributed_connections’ 매개변수 참고)를 제외한, 쿼리 처리에 사용되는 최대 스레드 수입니다.

이 매개변수는 쿼리 처리 파이프라인의 동일한 단계를 병렬로 수행하는 스레드에 적용됩니다. 예를 들어 테이블에서 읽을 때, 최소 ‘max_threads’개의 스레드를 사용하여 함수가 포함된 표현식을 계산하고, WHERE로 필터링하며, GROUP BY를 위한 사전 집계를 병렬로 수행할 수 있다면 ‘max_threads’가 사용됩니다.

LIMIT으로 인해 빠르게 완료되는 쿼리의 경우 더 낮은 ‘max_threads’를 설정할 수 있습니다. 예를 들어 필요한 수의 항목이 모든 블록에 포함되어 있고 max_threads = 8이면, 실제로는 블록 하나만 읽어도 충분하지만 8개의 블록을 가져오게 됩니다. max_threads 값이 작을수록 메모리 사용량도 줄어듭니다.

기본적으로 max_threads 설정은 ClickHouse에서 사용할 수 있는 하드웨어 스레드 수(CPU 코어 수)와 일치합니다. 예외적으로, 32개 미만의 CPU 코어를 가진 x86 프로세서에서 SMT(예: Intel HyperThreading)를 사용하는 경우 ClickHouse는 기본적으로 논리 코어 수(= 물리 코어 수 x 2)를 사용합니다.

SMT(예: Intel HyperThreading)가 없는 경우에는 CPU 코어 수와 같습니다.

ClickHouse Cloud 사용자의 경우 기본값은 auto(N) 형식으로 표시되며, 여기서 N은 서비스의 vCPU 크기(예: 2vCPU/8GiB, 4vCPU/16GiB 등)와 일치합니다. 모든 서비스 크기 목록은 Cloud Console의 설정 탭에서 확인하십시오.

​

max_threads_for_indexes

인덱스를 처리하는 데 사용할 수 있는 최대 스레드 수입니다.

​

max_threads_min_free_memory_per_thread

서버가 메모리 압박 상태일 때 max_threads를 낮춰, 메모리 한도에 도달할 가능성이 높은 고병렬 쿼리가 시작되지 않도록 합니다.

여유 메모리는 서버의 max_server_memory_usage에서 전역 memory tracker가 현재 추적 중인 메모리 사용량을 뺀 값으로 계산됩니다. 이 여유 메모리가 max_threads에 이 값을 곱한 값보다 작으면, N * value <= free_memory를 만족하는 가장 큰 N이 되도록 max_threads가 줄어들며, 최솟값은 1입니다.

이 제한을 비활성화하려면 0으로 설정합니다.

예를 들어 기본값이 1 GiB이고 여유 메모리가 32 GiB이면 max_threads는 32로 제한됩니다. 여유 메모리가 1 GiB이면 1로 낮아집니다.

이 설정은 읽기 측 병렬 처리(SELECT, UNION, INTERSECT/EXCEPT, 그리고 INSERT ... SELECT의 SELECT 측)에 적용됩니다. 쓰기 측은 max_insert_threads_min_free_memory_per_thread를 참조하십시오.

​

max_untracked_memory

작은 메모리 할당 및 해제는 스레드 로컬 변수에 모아 두며, 그 크기(절댓값 기준)가 지정된 값보다 커질 때만 추적하거나 프로파일링합니다. 이 값이 ‘memory_profiler_step’보다 크면 실제로는 ‘memory_profiler_step’으로 낮춰집니다.

​

max_wkb_geometry_elements

readWKB 및 관련 함수가 파싱하는 동안 단일 WKB 지오메트리 요소에 허용되는 점, 링 또는 폴리곤의 최대 개수입니다. 이 설정은 잘못된 WKB 데이터로 인한 과도한 메모리 할당을 방지합니다. 하드코딩된 제한값(1억)을 사용하려면 0으로 설정하십시오.

​

memory_overcommit_ratio_denominator

전역 수준에서 하드 메모리 제한에 도달했을 때 적용되는 소프트 메모리 제한을 나타냅니다. 이 값은 쿼리의 오버커밋 비율을 계산하는 데 사용됩니다. 값이 0이면 쿼리를 건너뜁니다. 자세한 내용은 memory overcommit을 참조하십시오.

​

memory_overcommit_ratio_denominator_for_user

이 설정은 사용자 수준에서 하드 메모리 제한에 도달했을 때 적용되는 소프트 메모리 제한을 나타냅니다. 이 값은 쿼리의 오버커밋 비율을 계산하는 데 사용됩니다. 0은 해당 쿼리를 건너뜀을 의미합니다. 자세한 내용은 memory overcommit을 참조하십시오.

​

memory_profiler_sample_max_allocation_size

지정한 값 이하 크기의 메모리 할당을 memory_profiler_sample_probability와 동일한 확률로 무작위 수집합니다. 0은 비활성화를 의미합니다. 이 임계값이 예상대로 작동하게 하려면 max_untracked_memory를 0으로 설정하는 것이 좋습니다.

​

memory_profiler_sample_min_allocation_size

지정한 값 이상인 무작위 메모리 할당을 memory_profiler_sample_probability와 동일한 확률로 수집합니다. 0은 비활성화를 의미합니다. 이 임계값이 예상대로 작동하도록 하려면 ‘max_untracked_memory’를 0으로 설정하는 것이 좋습니다.

​

memory_profiler_sample_probability

무작위 메모리 할당과 메모리 해제를 수집하여 ‘MemorySample’ trace_type으로 system.trace_log에 기록합니다. 이 확률은 할당 크기와 관계없이 각 alloc/free에 적용됩니다(memory_profiler_sample_min_allocation_size 및 memory_profiler_sample_max_allocation_size로 변경 가능). 샘플링은 추적되지 않은 메모리 양이 ‘max_untracked_memory’를 초과할 때만 수행됩니다. 더 세밀한 샘플링이 필요하면 ‘max_untracked_memory’를 0으로 설정하는 것이 좋습니다.

​

memory_profiler_step

메모리 프로파일러의 간격을 설정합니다. 쿼리의 메모리 사용량이 바이트 수 기준으로 각 다음 간격을 초과할 때마다 메모리 프로파일러가 메모리 할당 stacktrace를 수집하여 trace_log에 기록합니다.

Possible values:

• 바이트 수를 나타내는 양의 정수

• 메모리 프로파일러를 비활성화하려면 0

​

memory_tracker_fault_probability

exception safety 테스트를 위해, 지정된 확률에 따라 메모리를 할당할 때마다 예외를 발생시킵니다.

​

memory_usage_overcommit_max_wait_microseconds

사용자 수준에서 메모리 오버커밋이 발생한 경우, 메모리가 해제될 때까지 thread가 대기하는 최대 시간입니다. timeout에 도달할 때까지도 메모리가 해제되지 않으면 예외가 발생합니다. memory overcommit에 관해 자세히 알아보십시오.

​

merge_table_max_tables_to_look_for_schema_inference

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

​

merge_tree_coarse_index_granularity

데이터를 검색할 때 ClickHouse는 인덱스 파일의 데이터 마크를 확인합니다. 필요한 키가 특정 범위에 있다고 판단되면, ClickHouse는 해당 범위를 merge_tree_coarse_index_granularity개의 하위 범위로 나누고 그 안에서 필요한 키를 재귀적으로 검색합니다.

가능한 값:

• 임의의 양의 짝수 정수.

​

merge_tree_compact_parts_min_granules_to_multibuffer_read

ClickHouse Cloud에서만 적용됩니다. 병렬 읽기와 프리페치를 지원하는 multibuffer reader를 사용하기 위한 MergeTree 테이블의 compact part stripe 내 그래뉼 수입니다. remote fs에서 읽을 때 multibuffer reader를 사용하면 read request 수가 증가합니다.

​

merge_tree_determine_task_size_by_prewhere_columns

읽기 작업 크기를 정할 때 prewhere 컬럼의 크기만 사용할지 여부입니다.

​

merge_tree_max_bytes_to_use_cache

ClickHouse가 하나의 쿼리에서 merge_tree_max_bytes_to_use_cache바이트보다 많은 데이터를 읽어야 하는 경우, 압축 해제된 블록 캐시를 사용하지 않습니다.

압축 해제된 블록 캐시는 쿼리를 위해 추출한 데이터를 저장합니다. ClickHouse는 이 캐시를 사용해 반복되는 소규모 쿼리의 응답 속도를 높입니다. 이 설정은 많은 양의 데이터를 읽는 쿼리로 인해 캐시가 비효율적으로 소모되는 것을 방지합니다. uncompressed_cache_size 서버 설정은 압축 해제된 블록 캐시의 크기를 정의합니다.

가능한 값:

• 양의 정수.

​

merge_tree_max_rows_to_use_cache

ClickHouse가 하나의 쿼리에서 merge_tree_max_rows_to_use_cache행보다 많은 데이터를 읽어야 하는 경우, 압축 해제된 블록 캐시를 사용하지 않습니다.

압축 해제된 블록 캐시는 쿼리를 위해 추출된 데이터를 저장합니다. ClickHouse는 이 캐시를 사용해 반복되는 소규모 쿼리의 응답 속도를 높입니다. 이 설정은 많은 양의 데이터를 읽는 쿼리로 인해 캐시가 비효율적으로 교체되는 것을 방지합니다. uncompressed_cache_size 서버 설정은 압축 해제된 블록 캐시의 크기를 정의합니다.

가능한 값:

• 임의의 양의 정수.

​

merge_tree_min_bytes_for_concurrent_read

MergeTree 엔진 테이블의 단일 파일에서 읽어야 하는 바이트 수가 merge_tree_min_bytes_for_concurrent_read를 초과하면, ClickHouse는 여러 스레드를 사용해 해당 파일을 동시에 읽으려고 시도합니다.

가능한 값:

• 양의 정수.

​

merge_tree_min_bytes_for_concurrent_read_for_remote_filesystem

원격 파일 시스템에서 읽는 경우, MergeTree 엔진이 읽기를 병렬화하기 전에 하나의 파일에서 읽어야 하는 최소 바이트 수입니다. 이 설정의 사용은 권장하지 않습니다.

가능한 값:

• 양의 정수.

​

merge_tree_min_bytes_for_seek

하나의 파일에서 읽어야 하는 두 데이터 블록 사이의 거리가 merge_tree_min_bytes_for_seek 바이트보다 작으면, ClickHouse는 추가 seek이 발생하지 않도록 두 블록을 모두 포함하는 파일 범위를 순차적으로 읽습니다.

가능한 값:

• 임의의 양의 정수.

​

merge_tree_min_bytes_per_task_for_remote_reading

별칭: filesystem_prefetch_min_bytes_for_single_read_task

작업당 읽는 최소 바이트 수입니다.

​

merge_tree_min_read_task_size

작업 크기에 대한 엄격한 하한입니다(그래뉼 수가 적고 사용 가능한 스레드 수가 많더라도 더 작은 작업은 할당하지 않습니다

​

merge_tree_min_rows_for_concurrent_read

MergeTree 테이블 파일에서 읽어야 하는 행 수가 merge_tree_min_rows_for_concurrent_read를 초과하면 ClickHouse는 여러 스레드를 사용해 해당 파일을 동시에 읽으려고 시도합니다.

가능한 값:

• 양의 정수.

​

merge_tree_min_rows_for_concurrent_read_for_remote_filesystem

원격 파일 시스템에서 읽을 때 MergeTree 엔진이 읽기를 병렬화하기 전에 단일 파일에서 읽어야 하는 최소 행 수입니다. 이 설정은 사용하지 않는 것을 권장합니다.

가능한 값:

• 양의 정수.

​

merge_tree_min_rows_for_seek

하나의 파일에서 읽어야 하는 두 데이터 블록 사이의 거리가 merge_tree_min_rows_for_seek행보다 작으면, ClickHouse는 파일 내에서 seek를 수행하지 않고 데이터를 순차적으로 읽습니다.

가능한 값:

• 임의의 양의 정수.

​

merge_tree_read_split_ranges_into_intersecting_and_non_intersecting_injection_probability

PartsSplitter 테스트용 - 지정된 확률에 따라 MergeTree에서 읽을 때마다 읽기 범위를 교차하는 범위와 교차하지 않는 범위로 분할합니다.

​

merge_tree_storage_snapshot_sleep_ms

MergeTree 테이블의 스토리지 스냅샷을 생성할 때 인위적인 지연(밀리초)을 추가합니다. 테스트 및 디버깅 용도로만 사용됩니다.

가능한 값:

• 0 - 지연 없음(기본값)
• N - 밀리초 단위 지연

​

merge_tree_use_const_size_tasks_for_remote_reading

원격 테이블에서 읽을 때 고정 크기 작업을 사용할지 여부입니다.

​

merge_tree_use_deserialization_prefixes_cache

MergeTree에서 원격 디스크를 읽을 때 파일 프리픽스의 컬럼 메타데이터를 캐시하도록 설정합니다.

​

merge_tree_use_prefixes_deserialization_thread_pool

MergeTree의 Wide 파트에서 프리픽스를 병렬로 읽을 때 스레드 풀을 사용하도록 설정합니다. 이 스레드 풀의 크기는 서버 설정 max_prefixes_deserialization_thread_pool_size로 제어됩니다.

​

merge_tree_use_v1_object_and_dynamic_serialization

활성화하면 MergeTree에서 JSON 및 Dynamic 타입에 대해 V2 대신 V1 직렬화 버전이 사용됩니다. 이 설정 변경은 서버를 다시 시작한 후에만 적용됩니다.

​

metrics_perf_events_enabled

활성화되면 일부 perf 이벤트가 쿼리 실행 전 과정에서 측정됩니다.

​

metrics_perf_events_list

쿼리 실행 전반에 걸쳐 측정할 perf 메트릭의 쉼표로 구분된 목록입니다. 비어 있으면 모든 이벤트를 의미합니다. 사용 가능한 이벤트는 sources의 PerfEventInfo를 참조하십시오.

​

min_bytes_to_use_direct_io

스토리지 디스크에 대한 직접 I/O 접근을 사용하기 위한 최소 데이터 크기입니다.

ClickHouse는 테이블에서 데이터를 읽을 때 이 설정을 사용합니다. 읽어야 하는 모든 데이터의 총 저장소 크기가 min_bytes_to_use_direct_io바이트를 초과하면 ClickHouse는 O_DIRECT 옵션을 사용해 스토리지 디스크에서 데이터를 읽습니다.

가능한 값:

• 0 — 직접 I/O가 비활성화됩니다.
• 양의 정수.

​

min_bytes_to_use_mmap_io

이 설정은 Experimental 기능입니다. 커널에서 사용자 공간으로 데이터를 복사하지 않고 큰 파일을 읽기 위한 최소 메모리 크기를 설정합니다. mmap/munmap은 느리므로 권장 임계값은 약 64 MB입니다. 이 설정은 큰 파일에서만 유효하며, 데이터가 페이지 캐시에 있을 때만 도움이 됩니다.

가능한 값:

• 양의 정수
• 0 — 큰 파일을 커널에서 사용자 공간으로 데이터를 복사하는 방식으로만 읽습니다.

​

min_chunk_bytes_for_parallel_parsing

• 유형: 부호 없는 정수
• 기본값: 1 MiB

각 스레드가 병렬로 파싱할 최소 청크 크기(바이트)입니다.

​

min_compress_block_size

MergeTree 테이블에 적용됩니다. 쿼리 처리 시 지연 시간을 줄이기 위해, 다음 마크를 기록할 때 블록 크기가 min_compress_block_size 이상이면 해당 블록을 압축합니다. 기본값은 65,536입니다.

비압축 데이터가 max_compress_block_size보다 작으면, 실제 블록 크기는 이 값보다 작아지지 않으며, 하나의 마크에 해당하는 데이터 양보다도 작아지지 않습니다.

예시를 살펴보겠습니다. 테이블 생성 시 index_granularity를 8192로 설정했다고 가정합니다.

UInt32 유형의 컬럼(값당 4바이트)을 기록한다고 가정합니다. 8192개 행을 기록하면 총 데이터 크기는 32KB가 됩니다. min_compress_block_size = 65,536이므로 2개의 마크마다 압축 블록이 하나 생성됩니다.

String 유형의 URL 컬럼(값당 평균 크기 60바이트)을 기록한다고 가정합니다. 8192개 행을 기록하면 평균적으로 500KB보다 약간 작은 데이터가 됩니다. 이는 65,536보다 크므로 각 마크마다 압축 블록이 하나 생성됩니다. 이 경우 디스크에서 단일 마크 범위의 데이터를 읽을 때는 추가 데이터를 압축 해제하지 않습니다.

이 설정은 전문가 수준의 설정이므로, ClickHouse를 막 시작한 단계라면 변경하지 마십시오.

​

min_count_to_compile_aggregate_expression

JIT 컴파일을 시작하기 위한 동일한 집계 표현식의 최소 개수입니다. compile_aggregate_expressions 설정이 활성화된 경우에만 작동합니다.

가능한 값:

• 양의 정수입니다.
• 0 — 동일한 집계 표현식은 항상 JIT 컴파일됩니다.

​

min_count_to_compile_expression

동일한 표현식이 컴파일되기 전에 실행되어야 하는 최소 횟수입니다.

​

min_count_to_compile_sort_description

동일한 정렬 설명이 JIT 컴파일되기 전에 나타나야 하는 횟수

​

min_execution_speed

초당 행 수 기준의 최소 실행 속도입니다. 매 데이터 블록마다 timeout_before_checking_execution_speed 시간이 지나면 검사합니다. 실행 속도가 이보다 낮으면 예외가 발생합니다.

​

min_execution_speed_bytes

초당 실행 바이트 수의 최솟값입니다. timeout_before_checking_execution_speed 시간이 만료되면 모든 데이터 블록마다 확인합니다. 실행 속도가 이 값보다 낮으면 예외가 발생합니다.

​

min_external_table_block_size_bytes

외부 테이블로 전달되는 블록이 충분히 크지 않으면, 지정한 바이트 크기가 되도록 블록을 병합합니다.

​

min_external_table_block_size_rows

블록이 충분히 크지 않으면 외부 테이블(external table)로 전달되는 블록을 지정된 행 수에 맞게 합칩니다.

​

min_filtered_ratio_for_lazy_final

lazy FINAL 최적화에서 인덱스 분석으로 필터링되는 마크의 최소 비율입니다. 필터링된 마크 비율이 이 값보다 작으면 일반 FINAL로 대체됩니다. 값이 0이면 이 검사는 비활성화됩니다.

​

min_free_disk_bytes_to_perform_insert

삽입을 수행하기 위한 최소 여유 디스크 공간(바이트)입니다.

​

min_free_disk_ratio_to_perform_insert

삽입을 수행하기 위한 최소 여유 디스크 공간 비율입니다.

​

min_free_disk_space_for_temporary_data

외부 정렬 및 집계에 사용하는 임시 데이터를 기록할 때 확보해 둘 최소 디스크 공간입니다.

​

min_hit_rate_to_use_consecutive_keys_optimization

집계에서 연속 키 최적화에 사용되는 캐시가 활성화된 상태로 유지되기 위한 최소 적중률

​

min_insert_block_size_bytes

테이블에 삽입할 때 형성되는 블록의 최소 크기(바이트 단위)입니다.

이 설정은 min_insert_block_size_rows와 함께 동작하며, 동일한 컨텍스트(포맷 파싱 및 INSERT 작업)에서 블록 형성을 제어합니다. 이러한 설정이 언제, 어떻게 적용되는지에 대한 자세한 내용은 min_insert_block_size_rows를 참조하십시오.

가능한 값:

• 양의 정수입니다.
• 0 — 이 설정은 블록 형성에 사용되지 않습니다.

​

min_insert_block_size_bytes_for_materialized_views

INSERT 쿼리로 테이블에 삽입할 수 있는 블록의 최소 바이트 수를 설정합니다. 이보다 작은 블록은 더 큰 블록으로 합쳐집니다. 이 설정은 materialized view에 삽입되는 블록에만 적용됩니다. 이 값을 조정하면 materialized view로 푸시할 때 블록 합치기를 제어하여 과도한 메모리 사용을 방지할 수 있습니다.

가능한 값:

• 임의의 양의 정수입니다.
• 0 — 블록 합치기가 비활성화됩니다.

관련 항목

• min_insert_block_size_bytes

​

min_insert_block_size_rows

테이블에 삽입할 때 생성되는 블록의 최소 크기(행 수)입니다.

이 설정은 다음 두 가지 상황에서 블록 형성을 제어합니다.

1. 포맷 파싱: 서버가 모든 인터페이스(HTTP, 인라인 데이터가 포함된 clickhouse-client, gRPC, PostgreSQL wire 프로토콜)에서 행 기반 입력 형식(CSV, TSV, JSONEachRow 등)을 파싱할 때, 다음 조건에서 블록이 생성됩니다.

   • min_insert_block_size_rows AND min_insert_block_size_bytes에 모두 도달한 경우, OR
   • max_insert_block_size_rows OR max_insert_block_size_bytes 중 하나에 도달한 경우

   참고: clickhouse-client 또는 clickhouse-local로 파일을 읽는 경우에는 클라이언트 자체가 데이터를 파싱하므로, 이 설정은 클라이언트 측에 적용됩니다.

2. INSERT 작업: INSERT 쿼리 실행 중이거나 데이터가 구체화된 뷰(Materialized View)를 통과할 때, 이 설정의 동작은 use_strict_insert_block_limits에 따라 달라집니다.

   • 활성화된 경우: 다음 조건에서 블록이 생성됩니다.

     • 최소 임계값(AND): min_insert_block_size_rows AND min_insert_block_size_bytes에 모두 도달
     • 최대 임계값(OR): max_insert_block_size_rows OR max_insert_block_size_bytes 중 하나에 도달

   • 비활성화된 경우(기본값): min_insert_block_size_rows OR min_insert_block_size_bytes 중 하나에 도달하면 블록이 생성됩니다. max_insert_block_size 설정은 적용되지 않습니다.

가능한 값:

• 양의 정수입니다.
• 0 — 이 설정은 블록 형성에 사용되지 않습니다.

​

min_insert_block_size_rows_for_materialized_views

INSERT 쿼리로 테이블에 삽입할 수 있는 블록의 최소 행 수를 설정합니다. 이보다 작은 블록은 더 큰 블록으로 합쳐집니다. 이 설정은 materialized view에 삽입되는 블록에만 적용됩니다. 이 값을 조정하면 materialized view로 전달되는 블록의 병합을 제어하여 과도한 메모리 사용을 방지할 수 있습니다.

가능한 값:

• 임의의 양의 정수
• 0 — 블록 병합이 비활성화됩니다.

관련 항목

• min_insert_block_size_rows

​

min_joined_block_size_bytes

JOIN 입력 및 출력 블록의 최소 크기(바이트)입니다(조인 알고리즘이 이를 지원하는 경우). 작은 블록은 더 큰 블록으로 병합됩니다. 0은 제한이 없음을 의미합니다.

​

min_joined_block_size_rows

JOIN 입력 및 출력 block의 최소 행 수입니다(조인 알고리즘이 이를 지원하는 경우). 작은 block은 더 큰 block으로 합쳐집니다. 0은 제한이 없음을 의미합니다.

​

min_os_cpu_wait_time_ratio_to_throw

쿼리 거부를 판단할 때 기준으로 사용하는, OS CPU 대기 시간(OSCPUWaitMicroseconds 메트릭)과 CPU 사용 시간(OSCPUVirtualTimeMicroseconds 메트릭) 사이의 최소 비율입니다. 확률 계산에는 최소 비율과 최대 비율 사이의 선형 보간이 사용되며, 이 지점에서 확률은 0입니다.

​

min_outstreams_per_resize_after_split

파이프라인 생성 중 분할이 수행된 뒤 Resize 또는 StrictResize processor의 출력 stream 최소 개수를 지정합니다. 분할 후 stream 개수가 이 값보다 작으면 분할 작업은 수행되지 않습니다.

​

Resize Node란 무엇인가

Resize 노드는 쿼리 파이프라인에서 흐르는 데이터 스트림 수를 조정하는 프로세서입니다. 여러 스레드나 프로세서에 워크로드를 고르게 분산할 수 있도록 스트림 수를 늘리거나 줄일 수 있습니다. 예를 들어, 쿼리에 더 높은 병렬성이 필요하면 Resize 노드는 단일 스트림을 여러 스트림으로 분할할 수 있습니다. 반대로 여러 스트림을 더 적은 수의 스트림으로 머지해 데이터 처리를 통합할 수도 있습니다.

Resize 노드는 데이터 블록의 구조를 유지하면서 데이터가 각 스트림에 고르게 분산되도록 합니다. 이를 통해 리소스 활용도를 최적화하고 쿼리 성능을 개선할 수 있습니다.

​

Resize Node를 분할해야 하는 이유

파이프라인 실행 중에는 중앙 허브 역할을 하는 Resize 노드의 ExecutingGraph::Node::status_mutex에서 경합이 심하게 발생하며, 특히 코어 수가 많은 환경에서 더욱 두드러집니다. 이러한 경합은 다음과 같은 문제를 일으킵니다.

1. ExecutingGraph::updateNode의 지연 시간이 증가하여 쿼리 성능에 직접적인 영향을 줍니다.
2. 스핀락 경합(native_queued_spin_lock_slowpath)으로 인해 과도한 CPU 사이클이 낭비되어 효율이 저하됩니다.
3. CPU 활용률이 낮아져 병렬성과 처리량이 제한됩니다.

​

Resize 노드가 분할되는 방식

1. 분할이 가능한지 확인하기 위해 출력 스트림 수를 검사합니다. 즉, 분할된 각 processor의 출력 스트림 수가 min_outstreams_per_resize_after_split 임계값 이상이어야 합니다.
2. Resize 노드는 더 작은 Resize 노드들로 분할되며, 각 노드는 동일한 수의 포트를 갖고 입력 및 출력 스트림의 부분 집합을 처리합니다.
3. 각 그룹은 독립적으로 처리되므로 lock 경합이 줄어듭니다.

​

임의의 입력/출력을 사용하는 Resize 노드 분할

경우에 따라 입력/출력을 분할된 Resize 노드 수로 균등하게 나눌 수 없으면, 일부 입력은 NullSource에 연결되고 일부 출력은 NullSink에 연결됩니다. 이렇게 하면 전체 데이터 흐름에 영향을 주지 않고 분할할 수 있습니다.

​

설정의 목적

min_outstreams_per_resize_after_split 설정은 Resize 노드 분할이 실질적인 효과를 내도록 하고, 병렬 처리 효율을 떨어뜨릴 수 있는 지나치게 적은 수의 스트림이 생성되는 것을 방지합니다. 이 설정은 최소 출력 스트림 수를 강제하여, 스트림 분할 및 병합이 포함된 시나리오에서 병렬성과 오버헤드 간의 균형을 유지하고 쿼리 실행을 최적화하는 데 도움이 됩니다.

​

설정 비활성화

Resize 노드의 split을 비활성화하려면 이 설정 값을 0으로 지정하십시오. 그러면 pipeline 생성 중 Resize 노드가 분할되지 않아 더 작은 노드로 나뉘지 않고 원래 구조를 유지합니다.

​

min_table_rows_to_use_projection_index

테이블에서 읽을 것으로 예상되는 행 수가 이 임계값 이상이면, ClickHouse는 쿼리 실행 중 projection 인덱스를 사용하려고 시도합니다.

​

mongodb_throw_on_unsupported_query

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

​

move_all_conditions_to_prewhere

WHERE 절에서 PREWHERE 절로 이동할 수 있는 모든 조건을 이동합니다

​

move_primary_key_columns_to_end_of_prewhere

기본 키(primary key) 컬럼이 포함된 PREWHERE 조건을 AND 체인의 끝으로 이동합니다. 이러한 조건은 기본 키 분석 과정에서 이미 고려될 가능성이 높으므로, PREWHERE 필터링에는 큰 도움이 되지 않을 수 있습니다.

​

multiple_joins_try_to_keep_original_names

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

​

mutations_execute_nondeterministic_on_initiator

true이면 상수 비결정적 함수(예: now() 함수)는 initiator에서 실행되고, UPDATE 및 DELETE 쿼리에서는 리터럴로 대체됩니다. 이렇게 하면 상수 비결정적 함수를 사용하는 뮤테이션을 실행하는 동안 레플리카 간 데이터 동기화를 유지하는 데 도움이 됩니다. 기본값: false.

​

mutations_execute_subqueries_on_initiator

true이면 스칼라 서브쿼리가 initiator에서 실행되며 UPDATE 및 DELETE 쿼리에서는 리터럴로 대체됩니다. 기본값은 false입니다.

​

mutations_max_literal_size_to_replace

UPDATE 및 DELETE 쿼리에서 대체할 직렬화된 리터럴의 최대 크기(바이트 단위)입니다. 위의 두 설정 중 하나 이상이 활성화된 경우에만 이 설정이 적용됩니다. 기본값: 16384 (16 KiB).

​

mutations_sync

ALTER TABLE ... UPDATE|DELETE|MATERIALIZE INDEX|MATERIALIZE PROJECTION|MATERIALIZE COLUMN|MATERIALIZE STATISTICS 쿼리(mutations)를 동기적으로 실행할 수 있습니다.

가능한 값:

값	설명
0	뮤테이션이 비동기적으로 실행됩니다.
1	현재 서버에서 모든 뮤테이션이 완료될 때까지 쿼리가 대기합니다.
2	모든 레플리카(있는 경우)에서 모든 뮤테이션이 완료될 때까지 쿼리가 대기합니다.
3	활성 레플리카에 대해서만 쿼리가 대기합니다. SharedMergeTree에서만 지원됩니다. ReplicatedMergeTree에서는 mutations_sync = 2와 동일하게 동작합니다.

​

mysql_datatypes_support_level

MySQL 타입을 해당하는 ClickHouse 타입으로 어떻게 변환할지 정의합니다. decimal, datetime64, date2Date32, date2String을 임의로 조합한 쉼표로 구분된 목록입니다. 최신 매핑(decimal, datetime64, date2Date32)은 모두 기본적으로 활성화되어 있습니다.

• decimal: 정밀도가 허용되면 NUMERIC 및 DECIMAL 타입을 Decimal로 변환합니다.
• datetime64: 정밀도가 0이 아니면 DATETIME 및 TIMESTAMP 타입을 DateTime 대신 DateTime64로 변환합니다.
• date2Date32: DATE를 Date 대신 Date32로 변환합니다. date2String보다 우선 적용됩니다.
• date2String: DATE를 Date 대신 String으로 변환합니다. datetime64가 설정되면 이 옵션은 무시됩니다.

​

mysql_map_fixed_string_to_text_in_show_columns

활성화하면 FixedString ClickHouse 데이터 타입이 SHOW COLUMNS에서 TEXT로 표시됩니다.

MySQL wire 프로토콜을 통해 연결한 경우에만 적용됩니다.

• 0 - BLOB를 사용합니다.
• 1 - TEXT를 사용합니다.

​

mysql_map_string_to_text_in_show_columns

활성화하면 ClickHouse의 String 데이터 타입이 SHOW COLUMNS에서 TEXT로 표시됩니다.

MySQL wire protocol을 통해 연결된 경우에만 적용됩니다.

• 0 - BLOB를 사용합니다.
• 1 - TEXT를 사용합니다.

​

mysql_max_rows_to_insert

MySQL 스토리지 엔진의 MySQL 배치 삽입 시 최대 행 수

​

network_compression_method

클라이언트/서버 및 서버/서버 간 통신을 압축하는 데 사용하는 코덱입니다.

가능한 값:

• NONE — 압축을 사용하지 않습니다.
• LZ4 — LZ4 코덱을 사용합니다.
• LZ4HC — LZ4HC 코덱을 사용합니다.
• ZSTD — ZSTD 코덱을 사용합니다.

관련 항목

• network_zstd_compression_level

​

network_zstd_compression_level

ZSTD 압축 수준을 조정합니다. network_compression_method가 ZSTD로 설정된 경우에만 적용됩니다.

가능한 값:

• 1~15의 양의 정수.

​

normalize_function_names

함수 이름을 정식 이름으로 정규화합니다

​

number_of_mutations_to_delay

뮤테이션이 적용된 테이블에 완료되지 않은 뮤테이션이 이 수 이상 있으면, 해당 테이블의 뮤테이션 속도를 인위적으로 늦춥니다. 0 - 비활성화

​

number_of_mutations_to_throw

뮤테이션이 적용된 테이블에 완료되지 않은 뮤테이션이 최소 해당 수만큼 있으면 ‘Too many mutations …’ 예외를 발생시킵니다. 0 - 비활성화

​

odbc_bridge_connection_pool_size

ODBC bridge에서 각 connection 설정 문자열별 연결 풀 크기입니다.

​

odbc_bridge_use_connection_pooling

ODBC bridge에서 연결 풀링을 사용합니다. false로 설정하면 매번 새 연결이 생성됩니다.

​

offset

쿼리 결과에서 행을 반환하기 시작하기 전에 건너뛸 행 수를 설정합니다. OFFSET 절에서 설정한 오프셋을 조정하므로 두 값은 합산됩니다.

가능한 값:

• 0 — 건너뛸 행이 없습니다.
• 양의 정수.

예시

입력 테이블:

CREATE TABLE test (i UInt64) ENGINE = MergeTree() ORDER BY i;
INSERT INTO test SELECT number FROM numbers(500);

쿼리:

SET limit = 5;
SET offset = 7;
SELECT * FROM test LIMIT 10 OFFSET 100;

결과:

┌───i─┐
│ 107 │
│ 108 │
│ 109 │
└─────┘

​

opentelemetry_start_keeper_trace_probability

ZooKeeper 요청에 대해 trace를 시작할 확률입니다. 부모 trace 유무와 관계없이 적용됩니다.

가능한 값:

• ‘auto’ - opentelemetry_start_trace_probability 설정과 같습니다
• 0 — tracing이 비활성화됩니다
• 0 to 1 — 확률(예: 1.0 = 항상 활성화)

​

opentelemetry_start_trace_probability

ClickHouse가 실행된 쿼리에 대해 추적을 시작할 확률을 설정합니다(상위 추적 컨텍스트가 제공되지 않은 경우).

가능한 값:

• 0 — 실행된 모든 쿨리에 대한 추적이 비활성화됩니다(상위 추적 컨텍스트가 제공되지 않은 경우).
• [0..1] 범위의 양의 부동소수점 수입니다. 예를 들어 설정 값이 0,5이면 ClickHouse는 평균적으로 쿼리의 절반에서 추적을 시작할 수 있습니다.
• 1 — 실행된 모든 쿼리에 대한 추적이 활성화됩니다.

​

opentelemetry_trace_cpu_scheduling

워크로드의 선점형 CPU 스케줄링에 대한 OpenTelemetry 스팬을 수집합니다.

​

opentelemetry_trace_processors

processor의 OpenTelemetry 스팬을 수집합니다.

​

optimize_aggregation_in_order

MergeTree 테이블에서 데이터가 정렬된 순서에 맞춰 집계될 때 SELECT 쿼리의 GROUP BY 최적화를 활성화합니다.

가능한 값:

• 0 — GROUP BY 최적화가 비활성화됩니다.
• 1 — GROUP BY 최적화가 활성화됩니다.

관련 항목

• GROUP BY optimization

​

optimize_aggregators_of_group_by_keys

SELECT 절에서 GROUP BY 키에 대한 min/max/any/anyLast 집계 함수를 제거합니다

​

optimize_and_compare_chain

필터링 성능을 높이기 위해 AND 체인에 상수 비교를 추가합니다. <, <=, >, >=, = 연산자와 이들의 혼합을 지원합니다. 예를 들어 (a < b) AND (b < c) AND (c < 5)는 (a < b) AND (b < c) AND (c < 5) AND (b < 5) AND (a < 5)가 됩니다.

​

optimize_append_index

인덱스 조건을 추가하는 데 constraints를 사용합니다. 기본값은 false입니다.

가능한 값:

• true, false

​

optimize_arithmetic_operations_in_aggregate_functions

집계 함수의 산술 연산을 함수 밖으로 이동합니다

​

optimize_const_name_size

큰 상수를 스칼라로 대체하고 이름으로는 hash를 사용합니다(크기는 이름 길이를 기준으로 추정).

가능한 값:

• 양의 정수 - 이름의 최대 길이
• 0 — 항상
• 음의 정수 - 사용하지 않음

​

optimize_count_from_files

서로 다른 입력 형식의 파일에서 행 수를 계산하는 최적화를 활성화하거나 비활성화합니다. 이 설정은 테이블 함수/엔진 file/s3/url/hdfs/azureBlobStorage에 적용됩니다.

가능한 값:

• 0 — 최적화가 비활성화됩니다.
• 1 — 최적화가 활성화됩니다.

​

optimize_dictget_tuple_element

불필요한 딕셔너리 속성 조회를 피하기 위해 tupleElement(dictGet('dict', ('a', 'b', 'c'), key), 2)를 dictGet('dict', 'b', key)로 재작성합니다. 위치 기반(.1, .2, …) 및 이름 기반(.b) 접근을 지원하며, 기본 인수가 상수 튜플 또는 상수로 구성된 tuple(...)인 경우 dictGetOrDefault에도 적용됩니다.

​

optimize_distinct_in_order

DISTINCT에 포함된 일부 컬럼이 정렬 순서의 접두사를 이루는 경우 DISTINCT 최적화를 활성화합니다. 예를 들어 MergeTree의 정렬 키(sorting key) 접두사나 ORDER BY 구문의 접두사인 경우입니다.

​

optimize_distributed_group_by_sharding_key

비용이 많이 드는 initiator server의 집계를 피하여 GROUP BY sharding_key 쿼리를 최적화합니다(이에 따라 initiator server에서 해당 쿼리의 메모리 사용량이 줄어듭니다).

다음 유형의 쿼리가 지원됩니다(이들의 모든 조합도 포함):

• SELECT DISTINCT [..., ]sharding_key[, ...] FROM dist
• SELECT ... FROM dist GROUP BY sharding_key[, ...]
• SELECT ... FROM dist GROUP BY sharding_key[, ...] ORDER BY x
• SELECT ... FROM dist GROUP BY sharding_key[, ...] LIMIT 1
• SELECT ... FROM dist GROUP BY sharding_key[, ...] LIMIT 1 BY x

다음 유형의 쿼리는 지원되지 않습니다(일부는 추후 지원될 수 있습니다):

• SELECT ... GROUP BY sharding_key[, ...] WITH TOTALS
• SELECT ... GROUP BY sharding_key[, ...] WITH ROLLUP
• SELECT ... GROUP BY sharding_key[, ...] WITH CUBE
• SELECT ... GROUP BY sharding_key[, ...] SETTINGS extremes=1

가능한 값:

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

관련 항목:

• distributed_group_by_no_merge
• distributed_push_down_limit
• optimize_skip_unused_shards

현재는 optimize_skip_unused_shards가 필요합니다. 이는 향후 기본적으로 활성화될 수 있기 때문이며, 이 경우 데이터가 분산 테이블(Distributed table)을 통해 삽입되어 sharding_key에 따라 분산된 경우에만 올바르게 동작합니다.

​

optimize_dry_run_check_part

활성화되면 OPTIMIZE ... DRY RUN은 checkDataPart를 사용해 최종적으로 병합된 파트를 검증합니다. 검증에 실패하면 예외가 발생합니다.

​

optimize_empty_string_comparisons

col = '' 또는 '' = col 같은 표현식을 empty(col)로, col != '' 또는 '' != col 같은 표현식을 notEmpty(col)로 변환합니다. 이 동작은 col이 String 또는 FixedString 타입인 경우에만 적용됩니다.

​

optimize_extract_common_expressions

WHERE, PREWHERE, ON, HAVING 및 QUALIFY 표현식에서 OR 조건으로 연결된 식들로부터 공통 표현식을 추출할 수 있도록 합니다. (A AND B) OR (A AND C)와 같은 논리 표현식은 A AND (B OR C)로 다시 작성할 수 있으며, 다음 최적화에 도움이 될 수 있습니다:

• 단순 필터링 표현식에서 인덱스 활용
• cross를 inner join으로 최적화

​

optimize_functions_to_subcolumns

일부 함수를 서브컬럼을 읽는 방식으로 변환하는 최적화 기능을 활성화하거나 비활성화합니다. 이를 통해 읽어야 하는 데이터 양을 줄일 수 있습니다.

다음 함수가 변환될 수 있습니다:

• length를 size0 서브컬럼을 읽는 방식으로 변환합니다.
• empty를 size0 서브컬럼을 읽는 방식으로 변환합니다.
• notEmpty를 size0 서브컬럼을 읽는 방식으로 변환합니다.
• isNull을 null 서브컬럼을 읽는 방식으로 변환합니다.
• isNotNull을 null 서브컬럼을 읽는 방식으로 변환합니다.
• count를 null 서브컬럼을 읽는 방식으로 변환합니다.
• mapKeys를 keys 서브컬럼을 읽는 방식으로 변환합니다.
• mapValues를 values 서브컬럼을 읽는 방식으로 변환합니다.

Possible values:

• 0 — 최적화가 비활성화됩니다.
• 1 — 최적화가 활성화됩니다.

​

optimize_group_by_constant_keys

block 내의 모든 키가 상수일 때 GROUP BY를 최적화합니다

​

optimize_group_by_function_keys

GROUP BY 절에서 다른 키에 적용된 함수를 제거합니다

​

optimize_if_chain_to_multiif

if(cond1, then1, if(cond2, …)) 체인을 multiIf로 대체합니다. 현재 숫자 타입에는 유리하지 않습니다.

​

optimize_if_transform_strings_to_enum

If와 Transform의 문자열 유형 인수를 enum으로 대체합니다. 분산 쿼리에서 일관되지 않은 변경이 발생하여 쿼리가 실패할 수 있으므로 기본적으로 비활성화되어 있습니다.

​

optimize_injective_functions_in_group_by

GROUP BY 절의 단사 함수를 인수로 대체합니

​

optimize_injective_functions_inside_uniq

uniq*() 함수 내부에서 인수가 하나인 단사 함수를 제거합니다.

​

optimize_inverse_dictionary_lookup

미리 계산된 가능한 키 값 집합을 더 빠르게 조회하여 반복적인 역방향 딕셔너리 조회를 방지합니다.

​

optimize_min_equality_disjunction_chain_length

표현식 expr = x1 OR ... expr = xN에 최적화가 적용되기 위한 최소 길이

​

optimize_min_inequality_conjunction_chain_length

최적화 대상이 되는 표현식 expr <> x1 AND ... expr <> xN의 최소 길이

​

optimize_move_to_prewhere

SELECT 쿼리에서 PREWHERE 자동 최적화 사용 여부를 설정합니다.

*MergeTree 테이블에서만 작동합니다.

가능한 값:

• 0 — PREWHERE 자동 최적화가 비활성화됩니다.
• 1 — PREWHERE 자동 최적화가 활성화됩니다.

​

optimize_move_to_prewhere_if_final

FINAL 수정자가 있는 SELECT 쿼리에서 PREWHERE 자동 최적화의 사용 여부를 설정합니다.

*MergeTree 테이블에서만 동작합니다.

가능한 값:

• 0 — FINAL 수정자가 있는 SELECT 쿼리에서 PREWHERE 자동 최적화가 비활성화됩니다.
• 1 — FINAL 수정자가 있는 SELECT 쿼리에서 PREWHERE 자동 최적화가 활성화됩니다.

관련 항목

• optimize_move_to_prewhere 설정

​

optimize_multiif_to_if

조건이 하나만 있는 ‘multiIf’를 ‘if’로 대체합니다.

​

optimize_normalize_count_variants

의미적으로 count()와 동일한 집계 함수를 count()로 재작성합니다.

​

optimize_on_insert

삽입 전에 데이터 변환을 활성화하거나 비활성화합니다. 이는 해당 블록에서 머지가 수행된 것처럼 동작합니다(테이블 엔진에 따라 다름).

가능한 값:

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

예시

활성화된 경우와 비활성화된 경우의 차이:

쿼리:

SET optimize_on_insert = 1;

CREATE TABLE test1 (`FirstTable` UInt32) ENGINE = ReplacingMergeTree ORDER BY FirstTable;

INSERT INTO test1 SELECT number % 2 FROM numbers(5);

SELECT * FROM test1;

SET optimize_on_insert = 0;

CREATE TABLE test2 (`SecondTable` UInt32) ENGINE = ReplacingMergeTree ORDER BY SecondTable;

INSERT INTO test2 SELECT number % 2 FROM numbers(5);

SELECT * FROM test2;

결과:

┌─FirstTable─┐
│          0 │
│          1 │
└────────────┘

┌─SecondTable─┐
│           0 │
│           0 │
│           0 │
│           1 │
│           1 │
└─────────────┘

이 설정은 Materialized view의 동작에도 영향을 미치므로 유의하십시오.

​

optimize_or_like_chain

여러 OR LIKE 조건을 multiMatchAny로 최적화합니다. 이 최적화는 일부 경우 인덱스 분석을 저해하므로 기본적으로 활성화하지 않는 것이 좋습니다.

​

optimize_qbit_distance_function_reads

QBit 데이터 타입의 거리 함수를, 저장소에서 계산에 필요한 컬럼만 읽는 동등한 함수로 대체합니다.

​

optimize_read_in_order

MergeTree 테이블의 데이터를 읽는 SELECT 쿼리에서 ORDER BY 최적화를 활성화합니다.

가능한 값:

• 0 — ORDER BY 최적화가 비활성화됩니다.
• 1 — ORDER BY 최적화가 활성화됩니다.

관련 항목

• ORDER BY 절

​

optimize_redundant_functions_in_order_by

해당 함수의 인수도 ORDER BY에 포함되어 있으면 ORDER BY에서 함수를 제거합니다

​

optimize_respect_aliases

true로 설정하면 WHERE/GROUP BY/ORDER BY에서 별칭을 적용하며, 파티션 프루닝, 보조 인덱스, optimize_aggregation_in_order, optimize_read_in_order, optimize_trivial_count에 도움이 됩니다.

​

optimize_rewrite_aggregate_function_with_if

논리적으로 동등한 경우, 인수로 if 표현식을 사용하는 집계 함수를 재작성합니다. 예를 들어 avg(if(cond, col, null))는 avgOrNullIf(cond, col)로 재작성할 수 있습니다. 성능 향상에 도움이 될 수 있습니다.

분석기(enable_analyzer = 1)를 사용할 때만 지원됩니다.

​

optimize_rewrite_array_exists_to_has

논리적으로 동등한 경우 arrayExists() 함수를 has()로 재작성합니다. 예를 들어, arrayExists(x -> x = 1, arr)는 has(arr, 1)로 재작성할 수 있습니다.

​

optimize_rewrite_like_perfect_affix

정확한 접두사 또는 접미사를 사용하는 LIKE 표현식(예: col LIKE 'ClickHouse%')을 startsWith 또는 endsWith 함수(예: startsWith(col, 'ClickHouse'))로 재작성합니다.

​

optimize_rewrite_regexp_functions

정규식 관련 함수를 더 단순하고 효율적인 형태로 재작성합니다

​

optimize_rewrite_sum_if_to_count_if

논리적으로 동일한 경우 sumIf() 및 sum(if()) 함수를 countIf() 함수로 재작성합니다

​

optimize_skip_merged_partitions

level > 0인 part가 하나뿐이고 만료된 TTL도 없는 경우, OPTIMIZE TABLE … FINAL 쿼리에 대한 최적화를 활성화하거나 비활성화합니다.

• OPTIMIZE TABLE ... FINAL SETTINGS optimize_skip_merged_partitions=1

기본적으로 OPTIMIZE TABLE ... FINAL 쿼리는 part가 하나만 있는 경우에도 해당 part를 재작성합니다.

Possible values:

• 1 - 최적화를 활성화합니다.
• 0 - 최적화를 비활성화합니다.

​

optimize_skip_unused_shards

WHERE/PREWHERE에 세그먼트 분할 키 조건이 있는 SELECT 쿼리에서 사용되지 않는 세그먼트를 스키핑할지 여부를 설정하며, 분산 쿼리 관련 최적화(예: 세그먼트 분할 키 기준 집계)도 활성화합니다.

데이터가 세그먼트 분할 키를 기준으로 분산되어 있다고 가정합니다. 그렇지 않으면 쿼리 결과가 올바르지 않을 수 있습니다.

가능한 값:

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

​

optimize_skip_unused_shards_limit

세그먼트 분할 키 값 개수의 제한입니다. 이 한도에 도달하면 optimize_skip_unused_shards가 비활성화됩니다.

값이 너무 많으면 처리에 상당한 비용이 들 수 있으며, 얻을 수 있는 이점도 크지 않습니다. IN (...)에 값이 매우 많이 포함되어 있으면, 쿼리는 어차피 모든 세그먼트로 전송될 가능성이 높기 때문입니다.

​

optimize_skip_unused_shards_nesting

분산 쿼리의 중첩 수준에 따라 optimize_skip_unused_shards의 동작을 제어합니다. 따라서 이 설정을 사용하려면 optimize_skip_unused_shards도 여전히 필요합니다. 이는 Distributed 테이블이 다른 Distributed 테이블을 조회하는 경우에 해당합니다.

가능한 값:

• 0 — 비활성화됩니다. optimize_skip_unused_shards가 항상 동작합니다.
• 1 — 첫 번째 수준에서만 optimize_skip_unused_shards를 활성화합니다.
• 2 — 두 번째 수준까지 optimize_skip_unused_shards를 활성화합니다.

​

optimize_skip_unused_shards_rewrite_in

원격 세그먼트에 대한 쿼리에서 IN을 재작성하여 해당 세그먼트에 속하지 않는 값을 제외합니다. (optimize_skip_unused_shards가 필요합니다.)

가능한 값:

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

​

optimize_sorting_by_input_stream_properties

입력 스트림의 정렬 특성을 활용해 정렬을 최적화합니다

​

optimize_substitute_columns

컬럼 치환에 제약 조건을 사용합니다. 기본값은 false입니다.

가능한 값:

• true, false

​

optimize_syntax_fuse_functions

동일한 인수를 사용하는 집계 함수를 결합하도록 합니다. 동일한 인수를 사용하는 sum, count, 또는 avg 집계 함수가 2개 이상 포함된 쿼리를 sumCount로 재작성합니다.

가능한 값:

• 0 — 동일한 인수를 사용하는 함수는 결합되지 않습니다.
• 1 — 동일한 인수를 사용하는 함수는 결합됩니다.

예시

쿼리:

CREATE TABLE fuse_tbl(a Int8, b Int8) Engine = Log;
SET optimize_syntax_fuse_functions = 1;
EXPLAIN SYNTAX run_query_tree_passes = 1 SELECT sum(a), sum(b), count(b), avg(b) from fuse_tbl FORMAT TSV;

결과:

SELECT
    sum(__table1.a) AS `sum(a)`,
    tupleElement(sumCount(__table1.b), 1) AS `sum(b)`,
    tupleElement(sumCount(__table1.b), 2) AS `count(b)`,
    divide(tupleElement(sumCount(__table1.b), 1), toFloat64(tupleElement(sumCount(__table1.b), 2))) AS `avg(b)`
FROM default.fuse_tbl AS __table1

​

optimize_throw_if_noop

OPTIMIZE 쿼리가 머지를 수행하지 않았을 때 예외를 발생시킬지 여부를 설정합니다.

기본적으로 OPTIMIZE는 아무 작업도 수행하지 않았더라도 성공으로 반환됩니다. 이 설정을 사용하면 이러한 상황을 구분하고 예외 메시지를 통해 원인을 확인할 수 있습니다.

가능한 값:

• 1 — 예외 발생이 활성화됩니다.
• 0 — 예외 발생이 비활성화됩니다.

​

optimize_time_filter_with_preimage

함수를 변환이 필요 없는 동등한 비교식으로 바꾸어 Date 및 DateTime 프레디케이트를 최적화합니다(예: toYear(col) = 2023 -> col >= '2023-01-01' AND col <= '2023-12-31')

​

optimize_trivial_approximate_count_query

이러한 추정을 지원하는 스토리지에서 단순 count 최적화를 위해 근사값을 사용합니다. 예를 들어 EmbeddedRocksDB가 있습니다.

가능한 값:

• 0 — 최적화가 비활성화됩니다.
  • 1 — 최적화가 활성화됩니다.

​

optimize_trivial_count_query

MergeTree 메타데이터를 사용해 단순 쿼리 SELECT count() FROM table를 최적화할지 여부를 설정합니다. 행 수준 보안을 사용해야 한다면 이 설정을 비활성화하십시오.

가능한 값:

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

관련 항목:

• optimize_functions_to_subcolumns

​

optimize_trivial_group_by_limit_query

max_rows_to_group_by = n + offset 및 group_by_overflow_mode = 'any'를 설정해 단순 쿼리 SELECT key_expr FROM table GROUP BY key_expr LIMIT n(SELECT 목록에 집계 함수가 없고, HAVING/ORDER BY/LIMIT BY/윈도우 절이 없으며, GROUP BY 수정자도 없는 경우)의 최적화를 활성화하거나 비활성화합니다. n + offset개의 고유 키가 생성되면 집계가 중지됩니다.

사용자가 group_by_overflow_mode를 any가 아닌 값으로 명시적으로 설정한 경우(명시적으로 지정한 throw/break 동작을 보존하기 위해), 또는 이미 더 엄격한 max_rows_to_group_by를 설정한 경우(이 최적화가 아무 효과가 없으므로)에는 이 최적화가 적용되지 않습니다.

가능한 값:

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

​

optimize_trivial_insert_select

단순한 ‘INSERT INTO table SELECT … FROM TABLES’ 쿼리를 최적화합니다

​

optimize_truncate_order_by_after_group_by_keys

ORDER BY 접두사에서 모든 GROUP BY 키가 포함되면 뒤쪽의 ORDER BY 요소를 제거합니다.

​

optimize_uniq_to_count

하위 쿼리에 distinct 또는 group by 절이 있는 경우, uniqUpTo를 제외한 uniq 및 그 변형을 count로 재작성합니다.

​

optimize_use_implicit_projections

SELECT 쿼리 수행에 사용할 암시적 프로젝션을 자동으로 선택합니다

​

optimize_use_projection_filtering

SELECT 쿼리를 수행할 프로젝션이 선택되지 않은 경우에도, part 범위를 필터링하는 데 프로젝션을 사용할 수 있도록 합니다.

​

optimize_use_projections

별칭: allow_experimental_projection_optimization

SELECT 쿼리 처리 시 프로젝션 최적화를 활성화할지 여부를 설정합니다.

가능한 값:

• 0 — 프로젝션 최적화가 비활성화됩니다.
• 1 — 프로젝션 최적화가 활성화됩니다.

​

optimize_using_constraints

쿼리 최적화를 위해 제약 조건을 사용합니다. 기본값은 false입니다.

가능한 값:

• true, false

​

os_threads_nice_value_materialized_view

materialized view 스레드의 Linux nice 값입니다. 값이 낮을수록 CPU 우선순위가 높아집니다.

CAP_SYS_NICE capability가 필요하며, 없으면 아무 동작도 하지 않습니다.

가능한 값: -20~19.

​

os_threads_nice_value_query

별칭: os_thread_priority

쿼리 처리 스레드의 Linux nice 값입니다. 값이 낮을수록 CPU 우선순위가 높습니다.

CAP_SYS_NICE capability가 필요하며, 없으면 동작하지 않습니다.

가능한 값: -20~19입니다.

​

page_cache_block_size

사용자 공간 페이지 캐시에 저장할 파일 청크의 크기(바이트)입니다. 캐시를 통해 수행되는 모든 읽기는 이 크기의 배수로 올림됩니다.

이 설정은 쿼리 단위로 조정할 수 있지만, 블록 크기가 다른 캐시 엔트리는 재사용할 수 없습니다. 이 설정을 변경하면 사실상 캐시에 있는 기존 엔트리가 무효화됩니다.

1 MiB와 같은 큰 값은 처리량이 높은 쿼리에 적합하고, 64 KiB와 같은 작은 값은 지연 시간이 낮은 포인트 조회 쿼리에 적합합니다.

​

page_cache_inject_eviction

사용자 공간 페이지 캐시가 때때로 일부 페이지를 무작위로 무효화합니다. 테스트용으로 사용됩니다.

​

page_cache_lookahead_blocks

사용자 공간 페이지 캐시에서 캐시 미스가 발생하면, 해당 블록들도 캐시에 없는 경우 하위 저장소에서 연속된 블록을 최대 이 수만큼 한 번에 읽어 옵니다. 각 블록의 크기는 page_cache_block_size바이트입니다.

값이 클수록 처리량이 높은 쿼리에 유리하며, 지연 시간이 낮아야 하는 포인트 쿼리는 미리 읽기 없이 더 잘 작동합니다.

​

page_cache_max_coalesced_bytes

readBigAt가 사용자 공간 페이지 캐시를 채울 때는 연속된 캐시 미스를 기반 스토리지에서 수행하는 하나의 읽기로 병합합니다. 이 설정은 병합 읽기 1회의 크기를 바이트 단위로 제한하며, 더 긴 미스 구간은 여러 번의 읽기로 나뉩니다. 병렬 콜드 읽기 중 임시 버퍼의 일시적인 메모리 사용량을 제한합니다.

값이 클수록 객체 스토리지에서 콜드 스캔을 수행할 때 HTTP 요청 수가 줄어들고, 값이 작을수록 일시적인 최대 메모리 사용량이 줄어듭니다.

​

paimon_target_snapshot_id

Paimon incremental 모드에서 쿼리 수준으로 대상 snapshot을 읽기 위한 설정입니다. 값이 0보다 크면 리더는 committed watermark를 진행시키지 않고 지정된 snapshot_id의 delta만 가져옵니다. 기본값: -1(비활성화)

​

parallel_distributed_insert_select

병렬 분산 INSERT ... SELECT 쿼리를 활성화합니다.

INSERT INTO distributed_table_a SELECT ... FROM distributed_table_b 쿼리를 실행할 때 두 테이블이 동일한 클러스터를 사용하고, 두 테이블이 모두 복제된 테이블이거나 비복제 테이블이면, 이 쿼리는 각 세그먼트에서 로컬로 처리됩니다.

가능한 값:

• 0 — 비활성화됩니다.
• 1 — SELECT는 Distributed 엔진의 기반 테이블(underlying table)에서 각 세그먼트별로 실행됩니다.
• 2 — SELECT와 INSERT는 Distributed 엔진의 기반 테이블(underlying table)에서 각 세그먼트별로 실행됩니다.

v25.4부터는 ReplicatedMergeTree 또는 SharedMergeTree 소스의 INSERT ... SELECT도 여러 레플리카에 걸쳐 병렬화할 수 있습니다. 이를 활성화하려면 다음을 설정하십시오:

• parallel_distributed_insert_select = 2
• enable_parallel_replicas = 1

​

parallel_hash_join_threshold

해시 기반 조인 알고리즘이 적용될 때, 이 임계값은 hash와 parallel_hash 중 어떤 것을 사용할지 결정하는 데 도움이 됩니다(오른쪽 테이블 크기를 추정할 수 있는 경우에만 해당). 오른쪽 테이블의 크기가 임계값보다 작다는 것을 알고 있으면 전자를 사용합니다.

​

parallel_non_joined_rows_processing

RIGHT 및 FULL JOIN 중에 오른쪽 테이블의 조인되지 않은 행을 여러 스레드가 병렬로 처리할 수 있도록 합니다. 큰 테이블에 parallel_hash 조인 알고리즘을 사용할 때 조인되지 않은 행 처리 단계의 속도를 높일 수 있습니다. 비활성화하면 조인되지 않은 행은 단일 스레드로 처리됩니다.

​

parallel_replica_offset

이 설정은 직접 사용해서는 안 되는 내부 설정이며, ‘병렬 레플리카’ 모드 구현의 세부 사항입니다. 분산 쿼리에서 이 설정은 병렬 레플리카 중 쿼리 처리에 참여하는 레플리카의 인덱스로 initiator server가 자동 설정합니다.

​

parallel_replicas_allow_in_with_subquery

true이면 IN의 서브쿼리가 모든 팔로워 레플리카에서 실행됩니다.

​

parallel_replicas_allow_materialized_views

병렬 레플리카에서 materialized view를 사용할 수 있도록 허용합니다

​

parallel_replicas_allow_view_over_mergetree

MergeTree 테이블 기반 단순 뷰에서 병렬 레플리카가 뷰의 내부 쿼리 대신 외부 쿼리를 실행할 수 있도록 하여, 노드 간 병렬화를 개선합니다. 모든 분기가 서로 다른 MergeTree 테이블을 읽는 UNION ALL 뷰에도 적용됩니다.

​

parallel_replicas_connect_timeout_ms

병렬 레플리카를 사용한 쿼리 실행 중 원격 레플리카에 연결할 때 적용되는 밀리초 단위의 타임아웃입니다. 타임아웃이 만료되면 해당 레플리카는 쿼리 실행에 사용되지 않습니다.

​

parallel_replicas_count

이 설정은 내부 설정으로, 직접 사용해서는 안 되며 ‘병렬 레플리카’ 모드의 구현 세부 사항을 나타냅니다. 분산 쿼리에서는 쿼리 처리에 참여하는 병렬 레플리카 수에 맞춰 initiator server가 이 설정을 자동으로 지정합니다.

​

parallel_replicas_custom_key

특정 테이블에서 레플리카 간 작업을 분할하는 데 사용할 수 있는 임의의 정수 표현식입니다. 값으로는 임의의 정수 표현식을 사용할 수 있습니다.

기본 키(primary key)를 사용하는 단순한 표현식을 권장합니다.

이 설정을 여러 레플리카를 가진 단일 세그먼트로 구성된 클러스터에서 사용하면, 해당 레플리카는 가상 세그먼트로 변환됩니다. 그렇지 않으면 SAMPLE 키와 동일하게 동작하여, 각 세그먼트의 여러 레플리카를 사용합니다.

​

parallel_replicas_custom_key_range_lower

필터 유형 range가 사용자 지정 범위 [parallel_replicas_custom_key_range_lower, INT_MAX]를 기준으로 작업을 레플리카 간에 균등하게 분할할 수 있도록 합니다.

parallel_replicas_custom_key_range_upper와 함께 사용하면 필터가 범위 [parallel_replicas_custom_key_range_lower, parallel_replicas_custom_key_range_upper]에서 작업을 레플리카 간에 균등하게 분할할 수 있습니다.

참고: 이 설정은 쿼리 처리 중 추가 데이터를 필터링하지 않습니다. 대신 병렬 처리를 위해 범위 필터가 [0, INT_MAX] 범위를 분할하는 지점을 변경합니다.

​

parallel_replicas_custom_key_range_upper

필터 유형 range가 사용자 지정 범위 [0, parallel_replicas_custom_key_range_upper]를 기준으로 작업을 레플리카 간에 균등하게 분할할 수 있도록 합니다. 값이 0이면 상한이 비활성화되며, 이 경우 사용자 지정 키 표현식의 최댓값이 사용됩니다.

parallel_replicas_custom_key_range_lower와 함께 사용하면 필터가 범위 [parallel_replicas_custom_key_range_lower, parallel_replicas_custom_key_range_upper]에서 작업을 레플리카 간에 균등하게 분할할 수 있습니다.

참고: 이 설정으로 인해 쿼리 처리 중 추가 데이터가 필터링되지는 않습니다. 대신 병렬 처리를 위해 범위 필터가 [0, INT_MAX] 범위를 나누는 지점만 변경됩니다.

​

parallel_replicas_filter_pushdown

병렬 레플리카가 실행할 쿼리 부분으로 필터를 푸시다운할 수 있도록 허용합니다

​

parallel_replicas_for_cluster_engines

테이블 함수 엔진을 대응하는 -Cluster 대안으로 대체합니다

​

parallel_replicas_for_non_replicated_merge_tree

true로 설정하면 ClickHouse는 복제되지 않은 MergeTree 테이블에도 병렬 레플리카 알고리즘을 사용합니다

​

parallel_replicas_index_analysis_only_on_coordinator

인덱스 분석은 replica-coordinator에서만 수행되며, 다른 레플리카에서는 수행하지 않습니다. parallel_replicas_local_pla가 활성화된 경우에만 적용됩니다

​

parallel_replicas_insert_select_local_pipeline

병렬 레플리카를 사용하는 분산 INSERT SELECT 중에 로컬 파이프라인을 사용합니다

​

parallel_replicas_local_plan

로컬 레플리카에 대한 로컬 계획을 생성합니다

​

parallel_replicas_mark_segment_size

파트는 병렬 읽기를 위해 레플리카 간에 분배할 수 있도록 세그먼트로 논리적으로 분할됩니다. 이 설정은 이러한 세그먼트의 크기를 제어합니다. 수행 중인 작업을 정확히 이해하고 있다고 확신하기 전에는 변경하지 않는 것이 좋습니다. 값은 [128; 16384] 범위여야 합니다.

​

parallel_replicas_min_number_of_rows_per_replica

쿼리에서 사용할 레플리카 수를 (읽을 것으로 예상되는 행 수 / 레플리카당 최소 행 수)로 제한합니다. 최대값은 여전히 ‘max_parallel_replicas’에 의해 제한됩니다.

​

parallel_replicas_mode

병렬 레플리카에서 사용자 지정 키와 함께 사용할 필터 유형입니다. default - 사용자 지정 키에 모듈로 연산을 사용합니다. range - 사용자 지정 키의 값 유형에서 가능한 모든 값을 사용해 사용자 지정 키에 범위 필터를 적용합니다.

​

parallel_replicas_only_with_analyzer

병렬 레플리카를 사용하려면 분석기를 활성화해야 합니다. 분석기가 비활성화되어 있으면 레플리카의 병렬 읽기가 활성화되어 있어도 쿼리는 로컬 실행으로 폴백됩니다. 분석기를 활성화하지 않은 상태에서 병렬 레플리카를 사용하는 것은 지원되지 않습니다.

​

parallel_replicas_prefer_local_join

값이 true이고 JOIN을 병렬 레플리카 알고리즘으로 실행할 수 있으며, 오른쪽 JOIN 부분의 모든 스토리지가 *MergeTree인 경우 GLOBAL JOIN 대신 로컬 JOIN을 사용합니다.

​

parallel_replicas_prefer_local_replica

활성화된 경우(기본값) 병렬 읽기에 사용되는 레플리카 집합에는 항상 로컬 레플리카가 포함됩니다. 비활성화된 경우 로컬 레플리카는 우선적으로 고려되지 않으며, 레플리카는 오직 로드 밸런싱 알고리즘에 따라 선택됩니다. 따라서 max_parallel_replicas = 1인 쿼리를 다른 호스트로 라우팅할 수 있으므로, 클러스터 전반에 많은 짧은 쿼리가 분산되는 경우 캐시 지역성이 향상될 수 있습니다.

​

parallel_replicas_support_projection

프로젝션 최적화는 병렬 레플리카에서 적용할 수 있습니다. parallel_replicas_local_plan이 활성화되어 있고 aggregation_in_order가 비활성화된 경우에만 유효합니다.

​

parallel_view_processing

attached 상태인 뷰로 데이터를 순차적으로 푸시하는 대신 동시에 푸시하도록 설정합니다.

​

parallelize_output_from_storages

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

​

parsedatetime_e_requires_space_padding

parseDateTime 함수의 Formatter ‘%e’는 한 자릿수 날짜가 공백으로 패딩되어 있어야 합니다. 예를 들어 ’ 2’는 허용되지만 ‘2’는 오류를 발생시킵니다.

​

parsedatetime_parse_without_leading_zeros

함수 parseDateTime에서 포매터 ‘%c’, ‘%l’, ‘%k’는 앞의 0 없이 월과 시간을 파싱합니다.

​

partial_merge_join_left_table_buffer_bytes

0이 아니면 부분 병합 조인에서 왼쪽 테이블의 블록을 더 큰 블록으로 묶습니다. 조인 스레드당 지정된 메모리의 최대 2배를 사용합니다.

​

partial_merge_join_rows_in_right_blocks

JOIN 쿼리에서 부분 병합 조인 알고리즘이 오른쪽 조인 데이터 블록의 크기를 제한합니다.

ClickHouse 서버:

1. 오른쪽 조인 데이터를 지정된 행 수 이하의 블록으로 분할합니다.
2. 각 블록에 최소값과 최대값을 기준으로 인덱스를 생성합니다.
3. 가능하면 준비된 블록을 디스크로 언로드합니다.

가능한 값:

• 양의 정수라면 모두 가능합니다. 권장 범위는 [1000, 100000]입니다.

​

partial_result_on_first_cancel

취소 후에도 쿼리가 부분 결과를 반환할 수 있도록 합니다.

​

parts_to_delay_insert

대상 테이블의 단일 파티션에 활성 파트가 이 수 이상 있으면, 해당 테이블에 대한 삽입을 인위적으로 지연시킵니다.

​

parts_to_throw_insert

대상 테이블의 단일 파티션에 활성 파트 수가 이 값보다 많으면 ‘Too many parts …’ 예외를 발생시킵니다.

​

per_part_index_stats

각 파트의 인덱스 통계를 로그에 기록합니다

​

poll_interval

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

​

polyglot_dialect

polyglot transpiler에서 사용할 원본 SQL 방언입니다(예: ‘sqlite’, ‘mysql’, ‘postgresql’, ‘snowflake’, ‘duckdb’).

​

postgresql_connection_attempt_timeout

PostgreSQL 엔드포인트에 한 번 연결을 시도할 때의 연결 타임아웃(초)입니다. 이 값은 연결 URL의 connect_timeout 매개변수로 전달됩니다.

​

postgresql_connection_pool_auto_close_connection

connection을 pool에 반환하기 전에 닫습니다.

​

postgresql_connection_pool_retries

PostgreSQL 테이블 엔진과 데이터베이스 엔진에서 연결 풀의 push/pop 재시도 횟수입니다.

​

postgresql_connection_pool_size

PostgreSQL 테이블 엔진과 데이터베이스 엔진의 연결 풀 크기입니다.

​

postgresql_connection_pool_wait_timeout

PostgreSQL 테이블 엔진 및 데이터베이스 엔진에서 풀이 비어 있을 때 연결 풀의 push/pop 제한 시간입니다. 기본값으로는 풀이 비어 있으면 대기하며 차단됩니다.

​

postgresql_fault_injection_probability

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

​

predicate_statistics_sample_rate

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

​

prefer_column_name_to_alias

쿼리 표현식과 절에서 별칭 대신 원래 컬럼 이름을 사용할지 여부를 설정합니다. 특히 별칭이 컬럼 이름과 동일한 경우에 중요합니다. 자세한 내용은 Expression Aliases를 참조하십시오. 이 설정을 활성화하면 ClickHouse의 별칭 구문 규칙이 대부분의 다른 데이터베이스 엔진과 더 잘 호환됩니다.

가능한 값:

• 0 — 컬럼 이름이 별칭으로 대체됩니다.
• 1 — 컬럼 이름이 별칭으로 대체되지 않습니다.

예시

활성화했을 때와 비활성화했을 때의 차이:

쿼리:

SET prefer_column_name_to_alias = 0;
SELECT avg(number) AS number, max(number) FROM numbers(10);

결과:

Received exception from server (version 21.5.1):
Code: 184. DB::Exception: Received from localhost:9000. DB::Exception: Aggregate function avg(number) is found inside another aggregate function in query: While processing avg(number) AS number.

쿼리:

SET prefer_column_name_to_alias = 1;
SELECT avg(number) AS number, max(number) FROM numbers(10);

결과:

┌─number─┬─max(number)─┐
│    4.5 │           9 │
└────────┴─────────────┘

​

prefer_external_sort_block_bytes

외부 정렬 시 최대 블록 바이트를 우선하여 병합 중 메모리 사용량을 줄입니다.

​

prefer_global_in_and_join

IN/JOIN 연산자를 GLOBAL IN/GLOBAL JOIN으로 대체할 수 있도록 합니다.

가능한 값:

• 0 — 비활성화됨. IN/JOIN 연산자가 GLOBAL IN/GLOBAL JOIN으로 대체되지 않습니다.
• 1 — 활성화됨. IN/JOIN 연산자가 GLOBAL IN/GLOBAL JOIN으로 대체됩니다.

사용법

SET distributed_product_mode=global은 분산 테이블의 쿼리 동작을 변경할 수 있지만, 로컬 테이블이나 외부 리소스의 테이블에는 적합하지 않습니다. 이런 경우 prefer_global_in_and_join 설정이 유용합니다.

예를 들어, 분산에 적합하지 않은 로컬 테이블을 포함한 쿼리 처리 노드가 있다고 가정해 보겠습니다. 이런 경우 GLOBAL 키워드(GLOBAL IN/GLOBAL JOIN)를 사용해 분산 처리 중에 해당 데이터를 즉시 분산시켜야 합니다.

prefer_global_in_and_join의 또 다른 사용 사례는 외부 엔진으로 생성된 테이블에 액세스하는 경우입니다. 이 설정을 사용하면 이러한 테이블을 조인할 때 외부 소스 호출 횟수를 줄일 수 있으며, 쿼리당 한 번만 호출하면 됩니다.

관련 항목:

• GLOBAL IN/GLOBAL JOIN 사용 방법에 대한 자세한 내용은 분산 서브쿼리를 참조하십시오.

​

prefer_localhost_replica

분산 쿼리를 처리할 때 localhost 레플리카를 우선적으로 사용하도록 설정하거나 해제합니다.

가능한 값:

• 1 — localhost 레플리카가 있으면 ClickHouse는 항상 해당 레플리카로 쿼리를 보냅니다.
• 0 — ClickHouse는 load_balancing 설정에 지정된 밸런싱 전략을 사용합니다.

parallel_replicas_custom_key 없이 max_parallel_replicas를 사용하는 경우 이 설정을 비활성화하십시오. parallel_replicas_custom_key가 설정된 경우에는 여러 세그먼트에 여러 레플리카가 포함된 클러스터에서 사용할 때만 이 설정을 비활성화하십시오. 단일 세그먼트와 여러 레플리카가 있는 클러스터에서 사용하는 경우 이 설정을 비활성화하면 부정적인 영향이 있습니다.

​

prefer_warmed_unmerged_parts_seconds

ClickHouse Cloud에서만 적용됩니다. 병합된 파트가 이 값으로 지정된 초 수보다 최근에 생성되었고 사전 워밍되지 않았지만(cache_populated_by_fetch 참조), 해당 파트의 모든 소스 파트가 사용 가능하며 사전 워밍된 상태라면 SELECT 쿼리는 대신 그 소스 파트들에서 읽습니다. Replicated-/SharedMergeTree에서만 사용할 수 있습니다. 이 설정은 CacheWarmer가 해당 파트를 처리했는지만 확인합니다. 따라서 파트가 다른 방법으로 캐시에 fetch되었더라도 CacheWarmer가 이를 처리할 때까지는 계속 콜드 상태로 간주되며, 한 번 워밍된 뒤 캐시에서 제거되었더라도 계속 웜 상태로 간주됩니다.

​

preferred_block_size_bytes

이 설정은 쿼리 처리에 사용되는 데이터 블록 크기를 조정하며, 보다 거친 max_block_size 설정을 추가로 세밀하게 조정하는 데 사용됩니다. 컬럼이 크고 max_block_size 행을 기준으로 할 때 블록 크기가 지정된 바이트 수를 초과할 가능성이 있으면, CPU 캐시 지역성을 높이기 위해 블록 크기를 줄입니다.

​

preferred_max_column_in_block_size_bytes

읽는 동안 block 내 최대 컬럼 크기를 제한합니다. 캐시 미스 횟수를 줄이는 데 도움이 됩니다. L2 캐시 크기에 가까워야 합니다.

​

preferred_optimize_projection_name

비어 있지 않은 문자열로 설정하면 ClickHouse는 쿼리에 지정된 프로젝션을 적용하려고 시도합니다.

가능한 값:

• string: 선호하는 프로젝션의 이름

​

prefetch_buffer_size

파일 시스템에서 읽을 때 사용하는 프리페치 버퍼의 최대 크기입니다.

​

print_pretty_type_names

DESCRIBE 쿼리와 toTypeName() 함수에서 깊게 중첩된 타입 이름을 들여쓰기로 가독성 좋게 출력할 수 있습니다.

예시:

CREATE TABLE test (a Tuple(b String, c Tuple(d Nullable(UInt64), e Array(UInt32), f Array(Tuple(g String, h Map(String, Array(Tuple(i String, j UInt64))))), k Date), l Nullable(String))) ENGINE=Memory;
DESCRIBE TABLE test FORMAT TSVRaw SETTINGS print_pretty_type_names=1;

a   Tuple(
    b String,
    c Tuple(
        d Nullable(UInt64),
        e Array(UInt32),
        f Array(Tuple(
            g String,
            h Map(
                String,
                Array(Tuple(
                    i String,
                    j UInt64
                ))
            )
        )),
        k Date
    ),
    l Nullable(String)
)

​

priority

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

​

promql_database

‘promql’ 방언에서 사용할 데이터베이스 이름을 지정합니다. 빈 문자열은 현재 데이터베이스를 의미합니다.

​

promql_evaluation_time

별칭: evaluation_time

promql 방언에서 사용할 평가 시간을 설정합니다. ‘auto’는 현재 시간을 의미합니다.

​

promql_table

‘promql’ 방언에서 사용하는 TimeSeries 테이블 이름을 지정합니다.

​

push_external_roles_in_interserver_queries

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

​

query_cache_compress_entries

쿼리 캐시의 항목을 압축합니다. 쿼리 캐시에 대한 삽입 및 읽기 속도가 느려지는 대신, 쿼리 캐시의 메모리 사용량을 줄입니다.

가능한 값:

• 0 - 비활성화
• 1 - 활성화

​

query_cache_for_subqueries

활성화하면 서브쿼리 결과를 쿼리 캐시에 저장하고 여기서 읽을 수 있습니다. 이렇게 하면 use_query_cache가 모든 서브쿼리에 전파됩니다.

가능한 값:

• 0 - 비활성화
• 1 - 활성화

​

query_cache_max_entries

현재 사용자가 쿼리 캐시에 저장할 수 있는 쿼리 결과의 최대 개수입니다. 0은 무제한을 의미합니다.

가능한 값:

• 0 이상의 정수.

​

query_cache_max_size_in_bytes

현재 사용자가 쿼리 캐시에 할당할 수 있는 최대 메모리 크기(바이트)입니다. 0은 무제한을 의미합니다.

가능한 값:

• 0 이상인 정수.

​

query_cache_min_query_duration

쿼리 결과가 쿼리 캐시에 저장되기 위해 필요한 최소 실행 시간(밀리초)입니다.

가능한 값:

• 0 이상인 정수.

​

query_cache_min_query_runs

결과가 쿼리 캐시에 저장되기 전에 SELECT 쿼리가 최소 몇 번 실행되어야 하는지를 지정합니다.

가능한 값:

• 0 이상의 정수.

​

query_cache_nondeterministic_function_handling

쿼리 캐시가 rand() 또는 now()와 같은 비결정적 함수가 포함된 SELECT 쿼리를 처리하는 방식을 제어합니다.

Possible values:

• 'throw' - 예외를 발생시키고 쿼리 결과를 캐시하지 않습니다.
• 'save' - 쿼리 결과를 캐시합니다.
• 'ignore' - 쿼리 결과를 캐시하지 않으며 예외도 발생시키지 않습니다.

​

query_cache_share_between_users

활성화하면 쿼리 캐시에 캐시된 SELECT 쿼리 결과를 다른 사용자도 읽을 수 있습니다. 보안상의 이유로 이 설정은 활성화하지 않는 것이 좋습니다.

Possible values:

• 0 - 비활성화됨
• 1 - 활성화됨

​

query_cache_squash_partial_results

부분 결과 블록을 max_block_size 크기의 블록으로 합칩니다. 쿼리 캐시에 대한 삽입 성능은 저하되지만, 캐시 엔트리의 압축 효율은 향상됩니다(query_cache_compress-entries 참조).

가능한 값:

• 0 - 비활성화
• 1 - 활성화

​

query_cache_system_table_handling

쿼리 캐시가 시스템 테이블, 즉 system.* 및 information_schema.* 데이터베이스의 테이블에 대한 SELECT 쿼리를 어떻게 처리할지 제어합니다.

가능한 값:

• 'throw' - 예외를 발생시키고 쿼리 결과를 캐시하지 않습니다.
• 'save' - 쿼리 결과를 캐시합니다.
• 'ignore' - 쿼리 결과를 캐시하지 않으며 예외도 발생시키지 않습니다.

​

query_cache_tag

쿼리 캐시 엔트리의 레이블로 사용되는 문자열입니다. 태그가 서로 다른 동일한 쿼리는 쿼리 캐시에서 서로 다른 것으로 간주됩니다.

가능한 값:

• 임의의 문자열

​

query_cache_ttl

초 단위로 이 시간이 지나면 쿼리 캐시의 항목은 오래된 상태가 됩니다.

Possible values:

• 0 이상의 정수.

​

query_metric_log_interval

개별 쿼리에 대한 query_metric_log를 수집하는 밀리초 단위 간격입니다.

음수 값으로 설정하면 query_metric_log 설정의 collect_interval_milliseconds 값을 사용하고, 해당 값이 없으면 기본값인 1000을 사용합니다.

단일 쿼리에 대한 수집을 비활성화하려면 query_metric_log_interval을 0으로 설정하십시오.

기본값: -1

​

query_plan_aggregation_in_order

순서 기반 집계에 대한 쿼리 계획 수준 최적화를 켜거나 끕니다. 설정 query_plan_enable_optimizations이 1인 경우에만 적용됩니다.

이 설정은 전문가 수준의 설정으로, 개발자가 디버깅할 때만 사용해야 합니다. 이 설정은 향후 하위 호환되지 않는 방식으로 변경되거나 제거될 수 있습니다.

가능한 값:

• 0 - 비활성화
• 1 - 활성화

​

query_plan_convert_any_join_to_semi_or_anti_join

JOIN 이후의 필터가 일치하지 않은 행 또는 일치한 행에 대해 항상 false로 평가되는 경우, ANY JOIN을 SEMI JOIN 또는 ANTI JOIN으로 변환하도록 허용합니다.

​

query_plan_convert_join_to_in

출력 컬럼이 왼쪽 테이블에만 속하는 경우 JOIN을 IN을 사용하는 서브쿼리로 변환하도록 허용합니다. ANY가 아닌 JOIN(예: 기본값인 ALL JOIN)에서는 잘못된 결과가 발생할 수 있습니다.

​

query_plan_convert_outer_join_to_inner_join

JOIN 이후의 필터가 항상 기본값을 제외하는 경우 OUTER JOIN을 INNER JOIN으로 변환할 수 있도록 허용합니다

​

query_plan_direct_read_from_text_index

쿼리 계획에서 역텍스트 인덱스만 사용해 전문 검색 필터링을 수행하도록 허용합니다.

​

query_plan_display_internal_aliases

원본 쿼리에 지정된 별칭 대신 EXPLAIN PLAN에 내부 별칭(예: __table1)을 표시합니다.

​

query_plan_enable_multithreading_after_window_functions

윈도우 함수를 평가한 후 병렬 스트림 처리가 가능하도록 멀티스레딩을 활성화합니다.

​

query_plan_enable_optimizations

쿼리 계획(query plan) 수준의 쿼리 최적화를 켜거나 끕니다.

이 설정은 개발자가 디버깅할 때만 사용해야 하는 전문가용 설정입니다. 향후 하위 호환되지 않는 방식으로 변경되거나 제거될 수 있습니다.

가능한 값:

• 0 - 쿼리 계획 수준의 모든 최적화를 비활성화합니다
• 1 - 쿼리 계획 수준의 최적화를 활성화합니다(단, 개별 최적화는 각 설정을 통해 여전히 비활성화할 수 있습니다)

​

query_plan_execute_functions_after_sorting

정렬 단계 뒤로 표현식을 이동하는 쿼리 계획 수준 최적화를 켜거나 끕니다. 설정 query_plan_enable_optimizations의 값이 1일 때만 적용됩니다.

이 설정은 개발자가 디버깅할 때만 사용해야 하는 전문가 수준의 설정입니다. 이 설정은 향후 하위 호환되지 않는 방식으로 변경되거나 제거될 수 있습니다.

가능한 값:

• 0 - 비활성화
• 1 - 활성화

​

query_plan_filter_push_down

실행 계획에서 필터를 더 아래 단계로 내리는 쿼리 계획 수준의 최적화 기능을 켜거나 끕니다. 이 설정은 query_plan_enable_optimizations 값이 1일 때만 적용됩니다.

이 설정은 개발자가 디버깅할 때만 사용해야 하는 전문가 수준의 설정입니다. 향후 하위 호환되지 않는 방식으로 변경되거나 제거될 수 있습니다.

가능한 값:

• 0 - 비활성화
• 1 - 활성화

​

query_plan_join_shard_by_pk_ranges

두 테이블 모두에서 join key에 PRIMARY KEY의 앞부분이 포함된 경우 JOIN에 세그먼트 분할을 적용합니다. hash, parallel_hash, full_sorting_merge 알고리즘에서 지원됩니다. 일반적으로 쿼리 속도를 높이지는 않지만 메모리 사용량을 줄일 수 있습니다.

​

query_plan_join_swap_table

쿼리 계획에서 조인의 어느 쪽을 빌드 테이블(build table, 내부 테이블이라고도 하며 해시 조인용 해시 테이블에 삽입되는 테이블)로 사용할지 결정합니다. 이 설정은 JOIN ON 절을 사용하는 ALL 조인 엄격성에서만 지원됩니다. 가능한 값은 다음과 같습니다:

• ‘auto’: 플래너가 빌드 테이블로 사용할 테이블을 결정합니다.
  • ‘false’: 테이블을 스왑하지 않습니다(오른쪽 테이블이 빌드 테이블입니다).
  • ‘true’: 항상 테이블을 스왑합니다(왼쪽 테이블이 빌드 테이블입니다).

​

query_plan_lift_up_array_join

실행 계획에서 ARRAY JOIN을 상위로 끌어올리는 쿼리 계획 수준의 최적화를 켜거나 끕니다. query_plan_enable_optimizations 설정이 1일 때만 적용됩니다.

이 설정은 개발자가 디버깅할 때만 사용해야 하는 전문가 수준의 설정입니다. 이 설정은 향후 하위 호환되지 않는 방식으로 변경되거나 제거될 수 있습니다.

가능한 값:

• 0 - 비활성화
• 1 - 활성화

​

query_plan_lift_up_union

추가 최적화를 가능하게 하기 위해 쿼리 계획의 더 큰 하위 트리를 union으로 이동하는 쿼리 계획 수준 최적화를 켜거나 끕니다. 이 설정은 query_plan_enable_optimizations이 1일 때만 적용됩니다.

이 설정은 전문가 수준의 설정으로, 개발자가 디버깅 목적으로만 사용해야 합니다. 이 설정은 향후 하위 호환되지 않는 방식으로 변경되거나 제거될 수 있습니다.

가능한 값:

• 0 - 비활성화
• 1 - 활성화

​

query_plan_max_limit_for_lazy_materialization

지연 머티리얼라이즈 최적화에 쿼리 계획을 사용할 수 있는 최대 제한값을 제어합니다. 0이면 제한이 없습니다.

​

query_plan_max_limit_for_top_k_optimization

minmax 스킵 인덱스와 동적 임계값 필터링을 사용한 TopK 최적화에서 쿼리 계획을 평가할 수 있는 최대 LIMIT 값을 제어합니다. 0이면 제한이 없습니다.

​

query_plan_max_optimizations_to_apply

쿼리 계획(query plan)에 적용되는 최적화의 총 개수를 제한합니다. query_plan_enable_optimizations 설정을 참조하십시오. 복잡한 쿼리에서 최적화 시간이 지나치게 길어지는 것을 방지하는 데 유용합니다. EXPLAIN PLAN 쿼리에서는 이 한도에 도달하면 최적화 적용을 중지하고 계획을 있는 그대로 반환합니다. 일반 쿼리 실행에서 실제 최적화 횟수가 이 설정을 초과하면 예외가 발생합니다.

이 설정은 전문가 수준의 설정이므로 개발자가 debugging 목적으로만 사용해야 합니다. 이 설정은 향후 하위 호환되지 않는 방식으로 변경되거나 제거될 수 있습니다.

​

query_plan_max_step_description_length

EXPLAIN PLAN에서 단계 설명의 최대 길이입니다.

​

query_plan_merge_expressions

연속된 필터를 머지하는 쿼리 계획 수준의 최적화를 켜거나 끕니다. 설정 query_plan_enable_optimizations의 값이 1일 때만 적용됩니다.

이 설정은 전문가 수준의 설정으로, 개발자가 디버깅 목적으로만 사용해야 합니다. 이 설정은 향후 하위 호환되지 않는 방식으로 변경되거나 제거될 수 있습니다.

가능한 값:

• 0 - 비활성화
• 1 - 활성화

​

query_plan_merge_filter_into_join_condition

필터를 JOIN 조건에 머지하고 CROSS JOIN을 INNER로 변환할 수 있습니다.

​

query_plan_merge_filters

쿼리 계획에서 필터를 머지할 수 있게 합니다.

​

query_plan_optimize_join_order_algorithm

쿼리 계획 최적화 중에 시도할 JOIN 순서 알고리즘을 지정합니다. 사용할 수 있는 알고리즘은 다음과 같습니다.

• ‘greedy’ - 기본 그리디 알고리즘으로, 빠르게 동작하지만 최적의 조인 순서를 찾지 못할 수 있습니다
• ‘dpsize’ - 현재는 Inner 조인에 대해서만 DPsize 알고리즘을 구현하며, 가능한 모든 조인 순서를 고려해 가장 최적인 순서를 찾지만 테이블과 조인 프레디케이트가 많은 쿼리에서는 느릴 수 있습니다. 예를 들어 ‘dpsize,greedy’와 같이 여러 알고리즘을 지정할 수 있습니다.

​

query_plan_optimize_join_order_limit

동일한 서브쿼리 내에서 조인 순서를 최적화합니다. 현재는 매우 제한적인 경우에만 지원됩니다. 값은 최적화할 테이블의 최대 개수입니다.

​

query_plan_optimize_join_order_randomize

0이 아닌 경우, join order 최적화기는 실제 통계 대신 무작위로 생성된 카디널리티와 NDV를 사용합니다. 1로 설정하면 랜덤 시드가 생성되고, 1보다 큰 값으로 설정하면 해당 값을 시드로 직접 사용합니다. 이 설정은 서로 다른 join order로 인해 발생하는 오류를 찾기 위한 테스트용입니다.

​

query_plan_optimize_lazy_final

기본 키 집합을 구성하고 이를 인덱스 분석에 사용해 ReplacingMergeTree에서 FINAL로 읽기를 최적화합니다.

​

query_plan_optimize_lazy_materialization

lazy materialization 최적화에 쿼리 계획을 사용합니다.

​

query_plan_optimize_prewhere

지원되는 스토리지에서 필터를 PREWHERE 표현식으로 push down할 수 있도록 허용합니다

​

query_plan_push_down_limit

실행 계획에서 LIMIT를 더 아래 단계로 내리는 쿼리 계획 수준 최적화를 켜거나 끕니다. 이 설정은 query_plan_enable_optimizations 값이 1일 때만 적용됩니다.

이 설정은 전문가 수준의 설정이며, 개발자가 디버깅 용도로만 사용해야 합니다. 이 설정은 향후 하위 호환되지 않는 방식으로 변경되거나 제거될 수 있습니다.

Possible values:

• 0 - 비활성화
• 1 - 활성화

​

query_plan_read_in_order

읽기 순서 유지 최적화에 대한 쿼리 계획 수준 최적화를 켜거나 끕니다. 설정 query_plan_enable_optimizations의 값이 1일 때만 적용됩니다.

이 설정은 개발자가 디버깅 용도로만 사용해야 하는 전문가 수준 설정입니다. 이 설정은 향후 하위 호환되지 않는 방식으로 변경되거나 제거될 수 있습니다.

가능한 값:

• 0 - 비활성화
• 1 - 활성화

​

query_plan_read_in_order_through_join

후속 단계에서 활용할 수 있도록 JOIN 연산에서 왼쪽 테이블의 읽기 순서를 유지합니다.

​

query_plan_remove_redundant_distinct

불필요한 DISTINCT 단계를 제거하는 쿼리 계획 수준 최적화를 켜거나 끕니다. 이 설정은 query_plan_enable_optimizations 값이 1일 때만 적용됩니다.

이 설정은 전문가 수준의 설정으로, 개발자가 디버깅 용도로만 사용해야 합니다. 이 설정은 향후 하위 호환되지 않는 방식으로 변경되거나 제거될 수 있습니다.

가능한 값:

• 0 - 비활성화
• 1 - 활성화

​

query_plan_remove_redundant_sorting

중복된 정렬 단계를 제거하는 쿼리 계획 수준의 최적화를 활성화하거나 비활성화합니다. 예를 들어 서브쿼리에서 사용됩니다. 설정 query_plan_enable_optimizations이 1인 경우에만 적용됩니다.

이 설정은 개발자가 디버깅할 때만 사용해야 하는 전문가 수준의 설정입니다. 이 설정은 향후 하위 호환되지 않는 방식으로 변경되거나 제거될 수 있습니다.

가능한 값:

• 0 - 비활성화
• 1 - 활성화

​

query_plan_remove_unused_columns

쿼리 계획 단계에서 사용되지 않는 컬럼(입력 컬럼과 출력 컬럼 모두)을 제거하려는 쿼리 계획 수준 최적화를 켜거나 끕니다. 이 설정은 query_plan_enable_optimizations가 1일 때만 적용됩니다.

이 설정은 전문가 수준의 설정이므로 개발자가 디버깅할 때만 사용해야 합니다. 이 설정은 향후 하위 호환되지 않는 방식으로 변경되거나 제거될 수 있습니다.

가능한 값:

• 0 - 비활성화
• 1 - 활성화

​

query_plan_reuse_storage_ordering_for_window_functions

별칭: optimize_read_in_window_order

윈도우 함수 정렬 시 스토리지 정렬을 사용하는 쿼리 계획 수준 최적화를 켜거나 끕니다. 이 설정은 query_plan_enable_optimizations이 1일 때만 적용됩니다.

이 설정은 개발자가 디버깅 용도로만 사용해야 하는 전문가 수준의 설정입니다. 이 설정은 향후 하위 호환되지 않는 방식으로 변경되거나 제거될 수 있습니다.

가능한 값:

• 0 - 비활성화
• 1 - 활성화

​

query_plan_split_filter

이 설정은 전문가 수준의 설정으로, 개발자가 디버깅 목적으로만 사용해야 합니다. 이 설정은 향후 하위 호환되지 않는 방식으로 변경되거나 제거될 수 있습니다.

필터를 표현식으로 분할하는 쿼리 계획 수준의 최적화를 켜거나 끕니다. 설정 query_plan_enable_optimizations의 값이 1일 때만 적용됩니다.

가능한 값:

• 0 - 비활성화
• 1 - 활성화

​

query_plan_text_index_add_hint

쿼리 계획에서 역텍스트 인덱스를 기반으로 필터링 힌트(추가 프레디케이트)를 추가할 수 있도록 합니다.

​

query_plan_top_k_through_join

정렬 키가 조인에서 유지되는 쪽(LEFT/RIGHT)의 컬럼만 참조할 때 ORDER BY ... LIMIT n을 조인 아래로 푸시다운하는 쿼리 계획 수준 최적화를 활성화하거나 비활성화합니다. 조인 전에 유지되는 쪽 입력이 생성해야 하는 행 수를 제한합니다. 이 설정은 query_plan_enable_optimizations 설정이 1일 때만 적용됩니다.

가능한 값:

• 0 - 비활성화
• 1 - 활성화

​

query_plan_try_use_vector_search

벡터 유사성 인덱스를 사용하도록 시도하는 쿼리 계획 수준 최적화를 켜거나 끕니다. 이 설정은 query_plan_enable_optimizations이 1일 때만 적용됩니다.

이 설정은 개발자가 디버깅할 때만 사용해야 하는 전문가 수준의 설정입니다. 향후 하위 호환되지 않는 방식으로 변경되거나 제거될 수 있습니다.

가능한 값:

• 0 - 비활성화
• 1 - 활성화

​

query_profiler_cpu_time_period_ns

쿼리 프로파일러의 CPU 클록 타이머 주기를 설정합니다. 이 타이머는 CPU 시간만 측정합니다.

가능한 값:

• 나노초 단위의 양의 정수입니다.

  권장 값:

  • 단일 쿼리의 경우 10000000(초당 100회)나노초 이상
  • cluster 전체 프로파일링의 경우 1000000000(초당 1회)

• 타이머를 끄려면 0으로 설정합니다.

관련 항목:

• 시스템 테이블(system table) trace_log

​

query_profiler_real_time_period_ns

쿼리 프로파일러의 실시간 클록 타이머 주기를 설정합니다. 실시간 클록 타이머는 벽시계 시간(wall-clock time)을 기준으로 계산합니다.

가능한 값:

• 나노초 단위의 양의 정수입니다.

  권장 값:

  • 단일 쿼리에는 10000000(초당 100회)나노초 이하입니다.
  • 클러스터 전체 프로파일링에는 1000000000(초당 1회)입니다.

• 타이머를 끄려면 0입니다.

관련 항목:

• 시스템 테이블(system table) trace_log

Cloud 기본값: 3000000000.

​

queue_max_wait_ms

동시 요청 수가 최대치를 초과할 경우 요청 큐에서 대기하는 시간입니다.

​

rabbitmq_max_wait_ms

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

​

read_backoff_max_throughput

읽기 속도가 느릴 때 스레드 수를 줄이기 위한 설정입니다. 읽기 대역폭이 초당 지정된 바이트 수보다 낮으면 이벤트를 집계합니다.

​

read_backoff_min_concurrency

읽기 속도가 느릴 때 최소 스레드 수를 유지하도록 하는 설정입니다.

​

read_backoff_min_events

읽기가 느릴 때 스레드 수를 줄이기 위한 설정입니다. 지정한 횟수만큼 이벤트가 발생하면 스레드 수를 줄입니다.

​

read_backoff_min_interval_between_events_ms

느린 읽기가 발생할 때 스레드 수를 줄이기 위한 설정입니다. 이전 이벤트가 발생한 지 지정된 시간보다 덜 지났다면 해당 이벤트는 무시합니다.

​

read_backoff_min_latency_ms

읽기 속도가 느릴 때 스레드 수를 줄이기 위한 설정입니다. 이 값 이상의 시간이 걸린 읽기만 대상으로 합니다.

​

read_from_distributed_cache_if_exists_otherwise_bypass_cache

ClickHouse Cloud에서만 적용됩니다. read_from_filesystem_cache_if_exists_otherwise_bypass_cache와 동일하지만, Distributed Cache에 적용됩니다.

​

read_from_filesystem_cache_if_exists_otherwise_bypass_cache

파일 시스템 캐시를 패시브 모드로 사용할 수 있도록 합니다. 즉, 기존 캐시 엔트리는 활용하되, 새로운 엔트리를 캐시에 추가하지는 않습니다. 이 설정을 무거운 애드혹 쿼리에는 적용하고 짧은 실시간 쿼리에는 비활성화해 두면, 과도하게 무거운 쿼리로 인한 캐시 스래싱을 방지하여 전체 시스템 효율을 높일 수 있습니다.

​

read_from_page_cache_if_exists_otherwise_bypass_cache

read_from_filesystem_cache_if_exists_otherwise_bypass_cache와 유사하게 패시브 모드에서 사용자 공간 페이지 캐시를 사용합니다.

​

read_in_order_two_level_merge_threshold

프라이머리 키 순서의 멀티스레드 읽기 중 사전 병합 단계를 실행하기 위해 읽어야 하는 최소 파트 수입니다.

​

read_in_order_use_buffering

기본 키 순서로 읽을 때 병합 전에 버퍼링을 사용합니다. 쿼리 실행의 병렬성이 향상됩니다

​

read_in_order_use_virtual_row

기본 키(primary key) 또는 그 단조 함수의 순서로 읽을 때 가상 행을 사용합니다. 여러 파트에서 검색할 때 관련된 파트만 읽으므로 유용합니다.

​

read_in_order_use_virtual_row_per_block

read_in_order_use_virtual_row와 함께 활성화하면, 각 파트의 시작 시점뿐 아니라 각 block을 읽은 뒤에도 가상 행을 생성합니다. 이렇게 하면 MergingSortedTransform가 소스 우선순위를 더 자주 다시 지정할 수 있으므로, 다운스트림 필터가 많은 행을 걸러내고 데이터가 파트별로 고르지 않게 분산되어 있을 때 유용합니다. 이 설정을 사용하면 읽기 시 read_in_order_use_buffering 최적화와 사전 병합(read_in_order_two_level_merge_threshold)이 비활성화된다는 점에 유의하십시오.

​

read_overflow_mode

제한을 초과했을 때의 처리 방식입니다.

​

read_overflow_mode_leaf

읽는 데이터 양이 leaf 제한 중 하나를 초과할 때의 동작을 설정합니다.

가능한 옵션:

• throw: 예외를 발생시킵니다(기본값).
• break: 쿼리 실행을 중단하고 부분 결과를 반환합니다.

​

read_priority

로컬 파일 시스템 또는 원격 파일 시스템에서 데이터를 읽을 때의 우선순위입니다. 로컬 파일 시스템에서는 ‘pread_threadpool’ 메서드에서만, 원격 파일 시스템에서는 threadpool 메서드에서만 지원됩니다.

​

read_through_distributed_cache

ClickHouse Cloud에서만 효과가 있습니다. Distributed Cache에서 읽기를 허용합니다

​

readonly

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

​

receive_data_timeout_ms

레플리카로부터 첫 번째 데이터 패킷 또는 진행 정보가 포함된 패킷을 수신할 때의 연결 타임아웃

​

receive_timeout

네트워크에서 데이터를 수신하는 제한 시간으로, 초 단위입니다. 이 시간 동안 바이트를 하나도 수신하지 못하면 예외가 발생합니다. 클라이언트에서 이 설정을 지정하면 서버의 해당 연결 끝점에 있는 socket에도 send_timeout이 설정됩니다.

​

recursive_cte_max_steps_in_type_inference

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

​

regexp_dict_allow_hyperscan

Hyperscan 라이브러리를 사용하는 regexp_tree 딕셔너리의 사용을 허용합니다.

​

regexp_dict_flag_case_insensitive

regexp_tree 딕셔너리에서 대소문자를 구분하지 않는 매칭을 사용합니다. 개별 표현식에서는 (?i) 및 (?-i)로 재정의할 수 있습니다.

​

regexp_dict_flag_dotall

regexp_tree 딕셔너리에서 ’.’이 개행 문자와도 일치하도록 허용합니다.

​

regexp_max_matches_per_row

각 행에서 단일 정규식에 대해 허용되는 최대 일치 횟수를 설정합니다. extractAllGroupsHorizontal 함수에서 탐욕적 정규식을 사용할 때 메모리 과부하를 방지하는 데 사용합니다.

가능한 값:

• 양의 정수.

​

reject_expensive_hyperscan_regexps

hyperscan으로 평가할 때 비용이 많이 들 것으로 예상되는 패턴을 거부합니다(NFA 상태 폭증으로 인해).

​

remerge_sort_lowered_memory_bytes_ratio

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

​

remote_filesystem_read_method

원격 파일 시스템에서 데이터를 읽는 메서드입니다. 사용할 수 있는 값은 다음과 같습니다: read, threadpool.

​

remote_filesystem_read_prefetch

원격 파일 시스템에서 데이터를 읽을 때 프리페치를 사용해야 합니다.

​

remote_fs_read_backoff_max_tries

백오프를 적용한 읽기의 최대 재시도 횟수

​

remote_fs_read_max_backoff_ms

원격 디스크에서 데이터를 읽으려고 시도할 때의 최대 대기 시간

​

remote_read_min_bytes_for_seek

원격 읽기(url, S3)에서 데이터를 무시하며 읽는 대신 seek을 수행하는 데 필요한 최소 바이트 수입니다.

​

rename_files_after_processing

• 유형: String

• 기본값: 빈 문자열

이 설정을 사용하면 file 테이블 함수로 처리한 파일의 이름 변경 패턴을 지정할 수 있습니다. 이 옵션을 설정하면 file 테이블 함수가 읽은 모든 파일은 파일 처리가 성공했을 때에만 placeholder가 포함된 지정된 패턴에 따라 이름이 변경됩니다.

​

자리 표시자

• %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로 변경됩니다.

​

replace_running_query

HTTP 인터페이스를 사용할 때 query_id 매개변수를 전달할 수 있습니다. 이는 쿼리 식별자로 사용되는 임의의 문자열입니다. 이 시점에 동일한 사용자의 동일한 query_id를 가진 쿼리가 이미 존재하면 동작은 replace_running_query 매개변수에 따라 달라집니다.

0 (기본값) – 예외를 발생시킵니다(동일한 query_id를 가진 쿼리가 이미 실행 중이면 해당 쿼리의 실행을 허용하지 않습니다).

1 – 기존 쿼리를 취소하고 새 쿼리 실행을 시작합니다.

세그먼트 조건에 대한 제안 기능을 구현하려면 이 매개변수를 1로 설정하십시오. 다음 문자를 입력한 후 기존 쿼리가 아직 끝나지 않았다면 취소해야 합니다.

​

replace_running_query_max_wait_ms

replace_running_query 설정이 활성화되어 있을 때, 동일한 query_id를 가진 쿼리의 실행이 끝날 때까지 기다리는 시간입니다.

Possible values:

• 양의 정수입니다.
• 0 — 서버에서 이미 동일한 query_id를 가진 쿼리를 실행 중인 경우, 새 쿼리를 실행하지 못하도록 예외를 발생시킵니다.

​

replication_wait_for_inactive_replica_timeout

비활성 레플리카가 ALTER, OPTIMIZE 또는 TRUNCATE 쿼리를 실행할 때까지 기다리는 시간을 초 단위로 지정합니다.

가능한 값:

• 0 — 기다리지 않습니다.
• 음의 정수 — 무제한으로 기다립니다.
• 양의 정수 — 기다릴 시간(초)입니다.

​

restore_replace_external_dictionary_source_to_null

복원 시 외부 딕셔너리 소스를 Null로 대체합니다. 테스트용으로 유용합니다.

​

restore_replace_external_engines_to_null

테스트 목적으로 사용합니다. 외부 연결이 시작되지 않도록 모든 외부 엔진을 Null로 대체합니다.

​

restore_replace_external_table_functions_to_null

테스트용입니다. 외부 연결을 시작하지 않도록 모든 외부 테이블 함수를 Null로 대체합니다.

​

restore_replicated_merge_tree_to_shared_merge_tree

RESTORE 시 테이블 엔진을 ReplicatedMergeTree에서 SharedMergeTree로 대체합니다.

Cloud 기본값: 1.

​

result_overflow_mode

Cloud 기본값: throw

결과의 크기가 제한 중 하나를 초과할 경우 수행할 동작을 설정합니다.

가능한 값:

• throw: 예외를 발생시킵니다(기본값).
• break: 쿼리 실행을 중단하고 부분 결과를 반환합니다. 마치 소스 데이터가 모두 소진된 것처럼 동작합니다.

‘break’를 사용하는 것은 LIMIT를 사용하는 것과 유사합니다. Break는 실행을 블록 수준에서만 중단합니다. 즉, 반환되는 행 수는 max_result_rows보다 많을 수 있고, max_block_size의 배수이며, max_threads에 따라 달라집니다.

예시

Query

SET max_threads = 3, max_block_size = 3333;
SET max_result_rows = 3334, result_overflow_mode = 'break';

SELECT *
FROM numbers_mt(100000)
FORMAT Null;

Result

6666 rows in set. ...

​

rewrite_count_distinct_if_with_count_distinct_implementation

count_distinct_implementation 설정을 사용해 countDistcintIf를 재작성할 수 있도록 합니다.

Possible values:

• true — 허용합니다.
• false — 허용하지 않습니다.

​

rewrite_in_to_join

‘x IN subquery’와 같은 표현식을 JOIN으로 재작성합니다. 이는 JOIN 재정렬을 통해 전체 쿼리를 최적화하는 데 유용할 수 있습니다.

​

rows_before_aggregation

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

​

s3_allow_multipart_copy

S3에서 multipart copy를 허용합니다.

​

s3_allow_parallel_part_upload

S3 멀티파트 업로드에 여러 스레드를 사용합니다. 이로 인해 메모리 사용량이 다소 증가할 수 있습니다.

​

s3_check_objects_after_upload

업로드된 각 객체에 대해 S3에 HEAD 요청을 보내 업로드가 성공했는지 확인합니다

​

s3_connect_timeout_ms

s3 디스크에 사용되는 호스트의 연결 타임아웃입니다.

​

s3_create_new_file_on_insert

s3 engine tables에서 각 삽입 시 새 파일을 생성할지 여부를 설정합니다. 활성화하면 삽입할 때마다 다음 패턴과 유사하게 키를 사용한 새 S3 객체가 생성됩니다.

초기: data.Parquet.gz -> data.1.Parquet.gz -> data.2.Parquet.gz 등입니다.

가능한 값:

• 0 — INSERT 쿼리는 새 파일을 생성하며, 파일이 이미 존재하고 s3_truncate_on_insert가 설정되지 않은 경우 실패합니다.
• 1 — INSERT 쿼리는 s3_truncate_on_insert가 설정되지 않은 경우 각 삽입 시 접미사(두 번째 파일부터)를 사용해 새 파일을 생성합니다.

자세한 내용은 여기를 참조하십시오.

​

s3_disable_checksum

파일을 S3로 전송할 때 체크섬을 계산하지 않습니다. 이렇게 하면 파일에 대해 과도한 처리 단계를 반복하지 않아 쓰기 속도가 빨라집니다. 일반적으로는 안전합니다. 어차피 MergeTree 테이블의 데이터는 ClickHouse가 체크섬을 계산하며, HTTPS를 통해 S3에 접근하는 경우에는 TLS 계층이 네트워크 전송 중 무결성을 이미 제공합니다. 다만 S3에서 추가 체크섬을 사용하면 심층 방어 효과를 얻을 수 있습니다.

​

s3_ignore_file_doesnt_exist

특정 키를 읽을 때 파일이 존재하지 않으면 해당 파일의 부재를 무시합니다.

가능한 값:

• 1 — SELECT는 빈 결과를 반환합니다.
• 0 — SELECT는 예외를 발생시킵니다.

​

s3_list_object_keys_size

ListObject 요청에서 한 번에 반환할 수 있는 최대 파일 수

​

s3_max_connections

서버당 최대 연결 수입니다.

​

s3_max_get_burst

초당 요청 수 제한에 도달하기 전에 동시에 보낼 수 있는 최대 요청 수입니다. 기본값(0)은 s3_max_get_rps와 같습니다.

​

s3_max_get_rps

스로틀링이 적용되기 전, 초당 S3 GET 요청 수의 상한입니다. 0은 무제한을 의미합니다.

​

s3_max_inflight_parts_for_one_file

멀티파트 업로드 요청에서 동시에 업로드할 수 있는 파트의 최대 개수입니다. 0은 무제한을 의미합니다.

​

s3_max_part_number

S3 업로드 파트의 최대 파트 번호입니다.

​

s3_max_put_burst

초당 요청 수 제한에 도달하기 전에 동시에 발행할 수 있는 최대 요청 수입니다. 기본값은 0이며, s3_max_put_rps와 같습니다.

​

s3_max_put_rps

스로틀링이 시작되기 전의 초당 S3 PUT 요청 수 제한입니다. 0은 무제한을 의미합니다.

​

s3_max_single_operation_copy_size

s3에서 단일 복사 작업의 최대 크기입니다. 이 설정은 s3_allow_multipart_copy가 true일 때만 사용됩니다.

​

s3_max_single_part_upload_size

S3에 단일 파트 업로드(singlepart upload) 방식으로 업로드할 수 있는 객체의 최대 크기입니다.

​

s3_max_single_read_retries

단일 S3 읽기 작업 중 허용되는 최대 재시도 횟수입니다.

​

s3_max_unexpected_write_error_retries

S3에 쓰는 중 예기치 않은 오류가 발생했을 때의 최대 재시도 횟수입니다.

​

s3_max_upload_part_size

S3로 멀티파트 업로드를 수행할 때 각 업로드 파트의 최대 크기입니다.

​

s3_min_upload_part_size

S3로 멀티파트 업로드를 수행할 때 각 파트의 최소 크기입니다.

​

s3_path_filter_limit

glob listing 대신 파일을 순회할 때 사용하기 위해 쿼리 필터에서 추출할 수 있는 _path 값의 최대 개수입니다. 0은 비활성화됨을 의미합니다.

​

s3_request_timeout_ms

S3로 데이터를 송수신할 때의 유휴 timeout입니다. 단일 TCP 읽기 또는 쓰기 호출이 이 시간 동안 블로킹되면 실패합니다.

​

s3_skip_empty_files

S3 엔진 테이블에서 빈 파일을 스킵할지 여부를 설정합니다.

가능한 값:

• 0 — 빈 파일이 요청된 포맷과 호환되지 않으면 SELECT가 예외를 발생시킵니다.
• 1 — 빈 파일이면 SELECT가 빈 결과를 반환합니다.

​

s3_slow_all_threads_after_network_error

true로 설정하면 동일한 백업 엔드포인트로 S3 요청을 실행하는 스레드 중 하나라도 socket timeout과 같은 재시도 가능한 네트워크 오류를 만나면, 해당 엔드포인트로 요청을 보내는 모든 스레드의 속도가 느려집니다. false로 설정하면 각 스레드는 다른 스레드와 관계없이 S3 요청의 백오프를 개별적으로 처리합니다.

​

s3_strict_upload_part_size

S3에 멀티파트 업로드를 수행할 때 업로드할 파트의 정확한 크기입니다(일부 구현은 가변 크기의 파트를 지원하지 않습니다).

​

s3_throw_on_zero_files_match

ListObjects 요청과 일치하는 파일이 하나도 없으면 오류를 발생시킵니다

​

s3_truncate_on_insert

S3 엔진 테이블에서 삽입 전에 truncate를 수행할지 설정합니다. 비활성화하면 S3 객체가 이미 존재하는 경우 삽입을 시도할 때 예외가 발생합니다.

가능한 값:

• 0 — INSERT 쿼리는 새 파일을 생성하거나, 파일이 이미 존재하고 s3_create_new_file_on_insert가 설정되지 않은 경우 실패합니다.
• 1 — INSERT 쿼리는 파일의 기존 내용을 새 데이터로 대체합니다.

자세한 내용은 여기에서 확인하십시오.

​

s3_upload_part_size_multiply_factor

단일 쓰기에서 S3로 s3_multiply_parts_count_threshold개의 파트가 업로드될 때마다 s3_min_upload_part_size에 이 계수를 곱합니다.

​

s3_upload_part_size_multiply_parts_count_threshold

이 수만큼의 파트가 S3에 업로드될 때마다 s3_min_upload_part_size에 s3_upload_part_size_multiply_factor가 곱해집니다.

​

s3_uri_style

S3 endpoint 스타일을 강제로 설정합니다. 가능한 값: auto, virtual_hosted, path.

​

s3_use_adaptive_timeouts

true로 설정하면 모든 s3 요청에서 처음 두 번의 시도에는 더 짧은 송신 및 수신 timeout이 적용됩니다. false로 설정하면 모든 시도에 동일한 timeout이 적용됩니다.

​

s3_validate_request_settings

S3 요청 설정 검증을 활성화합니다. 가능한 값:

• 1 — 설정을 검증합니다.
• 0 — 설정을 검증하지 않습니다.

​

s3queue_default_zookeeper_path

S3Queue 엔진의 기본 ZooKeeper 경로 접두사

​

s3queue_enable_logging_to_s3queue_log

system.s3queue_log에 기록하도록 활성화합니다. 이 값은 테이블 설정을 통해 테이블별로 재정의할 수 있습니다

​

s3queue_keeper_fault_injection_probability

S3Queue용 Keeper 결함 주입 확률입니다.

​

s3queue_migrate_old_metadata_to_buckets

S3Queue 테이블의 기존 메타데이터 구조를 새 구조로 마이그레이션합니다

​

schema_inference_cache_require_modification_time_for_url

마지막 수정 시간 검증을 수행하는 URL에 대해 캐시된 스키마를 사용합니다(Last-Modified 헤더가 있는 URL).

​

schema_inference_use_cache_for_azure

Azure 테이블 함수를 사용할 때 스키마 추론에 캐시를 사용합니다

​

schema_inference_use_cache_for_file

file 테이블 함수를 사용할 때 스키마 추론에 캐시를 사용합니다

​

schema_inference_use_cache_for_hdfs

hdfs 테이블 함수 사용 시 스키마 추론에 캐시를 사용합니다

​

schema_inference_use_cache_for_s3

S3 테이블 함수 사용 시 스키마 추론에 캐시를 사용합니다

​

schema_inference_use_cache_for_url

URL 테이블 함수를 사용할 때 스키마 추론 시 캐시를 사용합니다

​

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 쿼리가 서로 다른 쿼럼 레플리카 집합에 기록될 수 있으므로, 단일 레플리카가 모든 쓰기를 수신했다고 보장할 수 없기 때문입니다.

관련 항목:

• insert_quorum
• insert_quorum_timeout
• insert_quorum_parallel

​

send_logs_level

지정된 최소 수준 이상의 서버 텍스트 로그를 클라이언트에 전송합니다. 유효한 값은 ‘trace’, ‘debug’, ‘information’, ‘warning’, ‘error’, ‘fatal’, ‘none’입니다.

​

send_logs_source_regexp

지정한 정규식과 일치하는 로그 source 이름의 server 텍스트 logs를 전송합니다. 비어 있으면 모든 source를 의미합니다.

​

send_profile_events

ProfileEvents 패킷을 클라이언트에 전송할지 설정합니다.

프로파일 이벤트가 필요하지 않은 클라이언트의 네트워크 트래픽을 줄이기 위해 이 설정을 비활성화할 수 있습니다.

가능한 값:

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

​

send_progress_in_http_headers

clickhouse-server 응답에서 X-ClickHouse-Progress HTTP 응답 헤더를 사용하거나 사용하지 않도록 설정합니다.

자세한 내용은 HTTP 인터페이스 설명을 참조하십시오.

가능한 값:

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

​

send_table_structure_on_insert_with_inline_data

비활성화되어 있고 INSERT 쿼리에 인라인 데이터가 포함된 경우, 서버는 네이티브 프로토콜을 통해 테이블 구조와 컬럼 기본값을 클라이언트에 다시 전송하지 않습니다. 대신 서버가 인라인 데이터를 직접 파싱합니다. 이렇게 하면 네이티브 프로토콜을 통한 소규모 삽입이 많은 경우 성능이 향상될 수 있습니다.

​

send_timeout

네트워크로 데이터를 전송하는 시간 제한으로, 초 단위입니다. 클라이언트가 데이터를 전송해야 하지만 이 인터벌 동안 바이트를 전혀 보낼 수 없으면 예외가 발생합니다. 클라이언트에서 이 설정을 지정하면 소켓의 ‘receive_timeout’도 서버의 해당 연결 종단에 설정됩니다.

​

serialize_query_plan

분산 처리를 위해 쿼리 계획을 직렬화합니다

​

serialize_string_in_memory_with_zero_byte

집계 중 String 값을 끝에 0바이트를 추가해 직렬화합니다. 호환되지 않는 버전으로 구성된 클러스터에 쿼리할 때 호환성을 유지하려면 이 설정을 활성화하십시오.

​

session_timezone

현재 세션 또는 쿼리의 암시적 시간대를 설정합니다. 암시적 시간대는 명시적으로 시간대가 지정되지 않은 DateTime/DateTime64 유형 값에 적용되는 시간대입니다. 이 설정은 전역으로 구성된(서버 수준) 암시적 시간대보다 우선합니다. 값이 ” (빈 문자열)이면 현재 세션 또는 쿼리의 암시적 시간대는 서버 시간대와 같습니다.

함수 timeZone() 및 serverTimeZone()를 사용하여 세션 시간대와 서버 시간대를 확인할 수 있습니다.

가능한 값:

• system.time_zones에 있는 모든 시간대 이름(예: Europe/Berlin, UTC, Zulu)

예시:

SELECT timeZone(), serverTimeZone() FORMAT CSV

"Europe/Berlin","Europe/Berlin"

SELECT timeZone(), serverTimeZone() SETTINGS session_timezone = 'Asia/Novosibirsk' FORMAT CSV

"Asia/Novosibirsk","Europe/Berlin"

시간대가 명시적으로 지정되지 않은 내부 DateTime에 세션 시간대 ‘America/Denver’를 할당합니다:

SELECT toDateTime64(toDateTime64('1999-12-12 23:23:23.123', 3), 3, 'Europe/Zurich') SETTINGS session_timezone = 'America/Denver' FORMAT TSV

1999-12-13 07:23:23.123

DateTime/DateTime64를 parse하는 모든 함수가 session_timezone를 따르는 것은 아닙니다. 이로 인해 미묘한 오류가 발생할 수 있습니다. 다음 예시와 설명을 참조하십시오.

CREATE TABLE test_tz (`d` DateTime('UTC')) ENGINE = Memory AS SELECT toDateTime('2000-01-01 00:00:00', 'UTC');

SELECT *, timeZone() FROM test_tz WHERE d = toDateTime('2000-01-01 00:00:00') SETTINGS session_timezone = 'Asia/Novosibirsk'
0 rows in set.

SELECT *, timeZone() FROM test_tz WHERE d = '2000-01-01 00:00:00' SETTINGS session_timezone = 'Asia/Novosibirsk'
┌───────────────────d─┬─timeZone()───────┐
│ 2000-01-01 00:00:00 │ Asia/Novosibirsk │
└─────────────────────┴──────────────────┘

이는 파싱 파이프라인이 서로 다르기 때문에 발생합니다:

• 첫 번째 SELECT 쿼리에서 시간대를 명시하지 않고 사용한 toDateTime()은 session_timezone 설정과 전역 시간대를 따릅니다.
• 두 번째 쿼리에서는 DateTime이 String으로부터 파싱되며, 기존 컬럼 d의 유형과 시간대를 상속합니다. 따라서 session_timezone 설정과 전역 시간대는 반영되지 않습니다.

관련 항목

• 시간대

​

set_overflow_mode

데이터 양이 제한값 중 하나를 초과할 때 어떻게 처리할지 설정합니다.

가능한 값:

• throw: 예외를 발생시킵니다(기본값).
• break: 쿼리 실행을 중지하고 부분 결과를 반환합니다. 이는 원본 데이터가 소진된 것처럼 동작합니다.

​

shared_merge_tree_sequential_consistency_initial_parts_update_backoff_ms

select_sequential_consistency를 SharedMergeTree와 함께 사용할 때 파트 업데이트에 적용되는 초기 백오프 시간(밀리초)입니다. ClickHouse Cloud에서만 사용할 수 있습니다.

​

shared_merge_tree_sequential_consistency_max_parts_update_backoff_ms

SharedMergeTree에서 select_sequential_consistency를 사용할 때 파트 업데이트에 대한 최대 백오프 시간(밀리초)입니다. ClickHouse Cloud에서만 사용할 수 있습니다.

​

shared_merge_tree_sequential_consistency_parts_update_max_retries

SharedMergeTree에서 select_sequential_consistency를 사용할 때 파트 업데이트의 최대 재시도 횟수입니다. ClickHouse Cloud에서만 사용할 수 있습니다.

​

shared_merge_tree_sync_parts_on_partition_operations

SMT 테이블에서 MOVE|REPLACE|ATTACH 파티션 작업 후 데이터 파트 집합을 자동으로 동기화합니다. Cloud에서만 사용할 수 있습니다.

​

short_circuit_function_evaluation

단락 평가 방식에 따라 if, multiIf, and, or 함수를 계산할 수 있도록 합니다. 이를 통해 이러한 함수의 복잡한 표현식 실행을 최적화하고, 발생할 수 있는 예외(예: 예상하지 않은 상황에서 0으로 나누는 경우)를 방지하는 데 도움이 됩니다.

가능한 값:

• enable — 단락 평가에 적합한 함수(예외를 발생시킬 수 있거나 계산 비용이 큰 함수)에 대해 단락 함수 평가를 활성화합니다.
• force_enable — 모든 함수에 대해 단락 함수 평가를 활성화합니다.
• disable — 단락 함수 평가를 비활성화합니다.

​

short_circuit_function_evaluation_for_nulls

인수 중 하나라도 NULL이면 NULL을 반환하는 함수의 평가를 최적화합니다. 함수 인수에서 NULL 값의 비율이 short_circuit_function_evaluation_for_nulls_threshold를 초과하면 시스템은 함수를 각 행별로 평가하지 않습니다. 대신 모든 행에 대해 즉시 NULL을 반환하여 불필요한 계산을 방지합니다.

​

short_circuit_function_evaluation_for_nulls_threshold

NULL 값 비율의 임계값으로, 널 허용 인수가 있는 함수를 모든 인수가 NULL이 아닌 행에서만 실행합니다. 이 설정은 short_circuit_function_evaluation_for_nulls가 활성화된 경우에 적용됩니다. NULL 값을 포함한 행의 비율이 전체 행 수 대비 이 임계값을 초과하면, 해당 NULL 값을 포함한 행은 평가되지 않습니다.

​

show_data_lake_catalogs_in_system_tables

시스템 테이블에 데이터 레이크 카탈로그가 표시되도록 합니다.

​

show_processlist_include_internal

SHOW PROCESSLIST 쿼리 출력에 내부 보조 프로세스를 표시합니다.

내부 프로세스에는 딕셔너리 재로드, 갱신 가능 구체화 뷰 재로드, SHOW ... 쿼리에서 실행되는 보조 SELECT, 손상된 테이블에 대응하기 위해 내부적으로 실행되는 보조 CREATE DATABASE ... 쿼리 등이 포함됩니다.

​

show_table_uuid_in_table_create_query_if_not_nil

SHOW TABLE 쿼리의 표시 방식을 설정합니다.

가능한 값:

• 0 — 테이블 UUID 없이 쿼리가 표시됩니다.
• 1 — 테이블 UUID와 함께 쿼리가 표시됩니다.

​

single_join_prefer_left_table

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

​

skip_redundant_aliases_in_udf

사용자 정의 함수의 사용을 단순화하기 위해 중복 별칭은 사용자 정의 함수에서 사용(치환)되지 않습니다.

Possible values:

• 1 — UDF에서 별칭을 건너뜁니다(치환합니다).
• 0 — UDF에서 별칭을 건너뛰지 않습니다(치환하지 않습니다).

예시

활성화 여부에 따른 차이:

쿼리:

SET skip_redundant_aliases_in_udf = 0;
CREATE FUNCTION IF NOT EXISTS test_03274 AS ( x ) -> ((x + 1 as y, y + 2));

EXPLAIN SYNTAX SELECT test_03274(4 + 2);

결과:

SELECT ((4 + 2) + 1 AS y, y + 2)

쿼리:

SET skip_redundant_aliases_in_udf = 1;
CREATE FUNCTION IF NOT EXISTS test_03274 AS ( x ) -> ((x + 1 as y, y + 2));

EXPLAIN SYNTAX SELECT test_03274(4 + 2);

결과:

SELECT ((4 + 2) + 1, ((4 + 2) + 1) + 2)

​

skip_unavailable_shards

사용할 수 없는 세그먼트를 오류 없이 건너뛸지 여부를 설정합니다.

세그먼트의 모든 레플리카를 사용할 수 없으면 해당 세그먼트는 사용할 수 없는 것으로 간주됩니다. 레플리카를 사용할 수 없는 경우는 다음과 같습니다.

• 어떤 이유로든 ClickHouse가 레플리카에 연결할 수 없습니다.

  레플리카에 연결할 때 ClickHouse는 여러 차례 연결을 시도합니다. 이 시도가 모두 실패하면 해당 레플리카는 사용할 수 없는 것으로 간주됩니다.

• DNS를 통해 레플리카를 확인할 수 없습니다.

  DNS를 통해 레플리카의 호스트명을 확인할 수 없다면 다음과 같은 상황일 수 있습니다.

  • 레플리카 호스트에 DNS 레코드가 없습니다. 이는 예를 들어 Kubernetes와 같이 동적 DNS를 사용하는 시스템에서 발생할 수 있으며, 다운타임 중에는 노드의 이름을 확인할 수 없을 수 있지만 이는 오류가 아닙니다.

  • 구성 오류입니다. ClickHouse 설정 파일에 잘못된 호스트명이 포함되어 있습니다.

가능한 값:

• 1 — 스키핑이 활성화됩니다.

  세그먼트를 사용할 수 없으면 ClickHouse는 부분 데이터에 기반한 결과를 반환하며, 노드 가용성 문제는 보고하지 않습니다.

• 0 — 스키핑이 비활성화됩니다.

  세그먼트를 사용할 수 없으면 ClickHouse는 예외를 발생시킵니다.

​

sleep_after_receiving_query_ms

TCPHandler에서 쿼리를 수신한 후 대기할 시간

​

sleep_in_send_data_ms

TCPHandler에서 데이터를 전송할 때 잠시 대기하는 시간

​

sleep_in_send_tables_status_ms

TCPHandler에서 테이블 상태 응답을 전송할 때 대기하는 시간

​

sort_overflow_mode

정렬 전에 수신된 행 수가 제한 중 하나를 초과할 때의 동작을 설정합니다.

가능한 값:

• throw: 예외를 발생시킵니다.
• break: 쿼리 실행을 중지하고 부분 결과를 반환합니다.

​

split_intersecting_parts_ranges_into_layers_final

FINAL 최적화 중에 겹치는 파트 범위를 레이어로 나눔

​

split_parts_ranges_into_intersecting_and_non_intersecting_final

FINAL 최적화 중 파트 범위를 서로 겹치는 범위와 겹치지 않는 범위로 나눕니다

​

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에는 영향을 주지 않습니다.

​

storage_file_read_method

스토리지 파일에서 데이터를 읽는 메서드이며, 다음 중 하나입니다: read, pread, mmap. mmap 메서드는 clickhouse-server에는 적용되지 않으며, clickhouse-local용입니다.

​

storage_system_stack_trace_pipe_read_timeout_ms

system.stack_trace 테이블을 쿼리할 때 스레드로부터 정보를 받기 위해 파이프에서 읽기를 수행할 수 있는 최대 시간입니다. 이 설정은 테스트 목적으로만 사용되며, 사용자가 변경하도록 설계되지 않았습니다.

​

stream_flush_interval_ms

스트리밍을 사용하는 테이블에서 timeout이 발생했거나 스레드가 max_insert_block_size개의 행을 생성한 경우에 적용됩니다.

기본값은 7500입니다.

값이 작을수록 데이터가 테이블로 더 자주 플러시됩니다. 값을 너무 낮게 설정하면 성능이 저하됩니다.

​

stream_like_engine_allow_direct_select

Kafka, RabbitMQ, FileLog, Redis Streams, S3Queue, AzureQueue, NATS 엔진에 대한 직접 SELECT 쿼리를 허용합니다. attached 상태인 materialized view가 있으면 이 설정을 활성화해도 SELECT 쿼리는 허용되지 않습니다. attached 상태인 materialized view가 없으면 이 설정을 활성화하여 데이터를 읽을 수 있습니다. 일반적으로 읽은 데이터는 큐에서 제거되므로 유의하십시오. 읽은 데이터가 제거되지 않도록 하려면 관련 엔진 설정을 올바르게 구성해야 합니다.

​

stream_like_engine_insert_queue

stream과 유사한 engine이 여러 큐에서 읽는 경우, 쓰기 시에는 삽입할 큐를 하나 선택해야 합니다. Redis Streams와 NATS에서 사용됩니다.

​

stream_poll_timeout_ms

스트리밍 스토리지에서/로 데이터를 폴링할 때 적용되는 시간 초과입니다.

​

system_events_show_zero_values

system.events에서 값이 0인 이벤트도 선택할 수 있습니다.

일부 모니터링 시스템에서는 메트릭 값이 0이더라도 각 체크포인트마다 모든 메트릭 값을 전달해야 합니다.

가능한 값:

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

예시

쿼리

SELECT * FROM system.events WHERE event='QueryMemoryLimitExceeded';

결과

Ok.

쿼리

SET system_events_show_zero_values = 1;
SELECT * FROM system.events WHERE event='QueryMemoryLimitExceeded';

결과

┌─event────────────────────┬─value─┬─description───────────────────────────────────────────┐
│ QueryMemoryLimitExceeded │     0 │ Number of times when memory limit exceeded for query. │
└──────────────────────────┴───────┴───────────────────────────────────────────────────────┘

​

system_metric_log_show_zero_values_in_histograms

값이 0인 히스토그램 데이터가 system.metric_log의 histograms 중첩 컬럼에 기록되는지 여부를 제어합니다.

기본적으로 전체 관측 count가 0인 히스토그램은 기록하지 않습니다. 또한 출력되는 각 히스토그램에서도 관측값이 없는 버킷 항목은 histogram 맵에서 생략됩니다. 이 설정을 활성화하면 count와 관계없이 모든 히스토그램과 모든 버킷을 기록합니다. 이는 모든 체크포인트에서 모든 메트릭이 표시되어야 하는 모니터링 시스템에 유용합니다.

Possible values:

• 0 — 비활성화됨. count = 0인 히스토그램은 출력되지 않으며, 출력되는 히스토그램에는 하나 이상의 관측값이 있는 버킷만 포함됩니다.
• 1 — 활성화됨. 모든 히스토그램이 기록되며, 모든 버킷 경계가 histogram에 표시됩니다.

​

table_engine_read_through_distributed_cache

ClickHouse Cloud에서만 적용됩니다. 테이블 엔진 / 테이블 함수(s3, azure 등)를 통해 Distributed Cache에서 읽을 수 있도록 허용합니다.

​

table_function_remote_max_addresses

remote 함수에 대해 패턴으로 생성되는 주소의 최대 수를 설정합니다.

가능한 값:

• 양의 정수.

​

tcp_keep_alive_timeout

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

​

temporary_data_in_cache_reserve_space_wait_lock_timeout_milliseconds

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

​

temporary_files_buffer_size

temporary files 쓰기 작업에 사용되는 버퍼 크기입니다. 버퍼 크기가 클수록 시스템 호출은 줄어들지만 메모리 사용량은 늘어납니다.

​

temporary_files_codec

디스크에서 수행되는 정렬 및 조인 작업에 사용되는 임시 파일의 압축 코덱을 설정합니다.

가능한 값:

• LZ4 — LZ4 압축이 적용됩니다.
• NONE — 압축이 적용되지 않습니다.

​

text_index_hint_max_selectivity

역텍스트 인덱스에서 생성된 힌트를 사용할 수 있는 필터의 최대 선택도입니다.

​

text_index_like_max_postings_to_read

딕셔너리 스캔을 사용하는 텍스트 인덱스 LIKE 평가가 활성화된 경우 읽을 큰 posting의 최대 개수입니다.

use_text_index_like_evaluation_by_dictionary_scan이 활성화되어 있어야 합니다.

​

text_index_like_min_pattern_length

딕셔너리 스캔을 통한 text index LIKE 평가를 사용하려면 LIKE/ILIKE 패턴 내 영숫자 needle의 길이가 이 최소값 이상이어야 합니다. 이 임계값보다 짧은 패턴은 너무 많은 딕셔너리 토큰과 일치하므로, 비용이 큰 스캔을 피하기 위해 건너뜁니다.

use_text_index_like_evaluation_by_dictionary_scan이 활성화되어 있어야 합니다.

​

throw_if_no_data_to_insert

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

​

throw_on_error_from_cache_on_write_operations

쓰기 작업(INSERT, 머지)에서 쓰기 시 캐싱을 수행할 때 캐시 오류를 무시합니다

​

throw_on_max_partitions_per_insert_block

max_partitions_per_insert_block에 도달했을 때의 동작을 제어합니다.

가능한 값:

• true - 삽입 블록이 max_partitions_per_insert_block에 도달하면 예외가 발생합니다.
• false - max_partitions_per_insert_block에 도달하면 경고를 로그에 기록합니다.

max_partitions_per_insert_block을 변경할 때 사용자에게 어떤 영향이 있는지 파악하는 데 유용할 수 있습니다.

​

throw_on_unsupported_query_inside_transaction

지원되지 않는 쿼리를 트랜잭션(transaction) 내부에서 사용하면 예외를 발생시킵니다

​

timeout_before_checking_execution_speed

지정된 시간(초)이 지난 후 실행 속도가 너무 느리지 않은지, 즉 min_execution_speed 이상인지 확인합니다.

​

timeout_overflow_mode

쿼리 실행 시간이 max_execution_time을 초과하거나 예상 실행 시간이 max_estimated_execution_time을 초과할 때 어떻게 처리할지 설정합니다.

가능한 값:

• throw: 예외를 발생시킵니다(기본값).
• break: 쿼리 실행을 중지하고 부분 결과를 반환합니다. 이는 원본 데이터가 모두 소진된 것처럼 동작합니다.

​

timeout_overflow_mode_leaf

리프 노드(leaf node)에서 실행되는 쿼리가 max_execution_time_leaf를 초과해 실행될 때의 동작을 설정합니다.

가능한 값:

• throw: 예외를 발생시킵니다(기본값).
• break: 쿼리 실행을 중지하고 부분 결과를 반환합니다. 이는 소스 데이터가 모두 소진된 것처럼 동작합니다.

​

totals_auto_threshold

totals_mode = 'auto'에 대한 임계값입니다. “WITH TOTALS 수정자” 섹션을 참조하십시오.

​

totals_mode

HAVING이 있을 때, 그리고 max_rows_to_group_by 및 group_by_overflow_mode = 'any'가 설정되어 있을 때 TOTALS를 계산하는 방법입니다. 「WITH TOTALS」 수정자 섹션을 참조하십시오.

​

trace_profile_events

프로파일 이벤트가 업데이트될 때마다 프로파일 이벤트 이름, 증가값, 스택트레이스를 함께 수집하여 trace_log로 전송할지 여부를 설정합니다.

가능한 값:

• 1 — 프로파일 이벤트 tracing이 활성화됩니다.
• 0 — 프로파일 이벤트 tracing이 비활성화됩니다.

​

trace_profile_events_list

설정 trace_profile_events가 활성화되면, 추적할 이벤트를 지정한 쉼표로 구분된 이름 목록으로 제한합니다. trace_profile_events_list가 빈 문자열(기본값)이면 모든 프로파일 이벤트를 추적합니다.

예시 값: ‘DiskS3ReadMicroseconds,DiskS3ReadRequestsCount,SelectQueryTimeMicroseconds,ReadBufferFromS3Bytes’

이 설정을 사용하면 많은 수의 쿼리에 대한 데이터를 더 정밀하게 수집할 수 있습니다. 그렇지 않으면 이벤트가 지나치게 많아 내부 시스템 로그 큐에서 오버플로우가 발생해 일부 이벤트가 유실될 수 있습니다.

​

transfer_overflow_mode

데이터 양이 제한값 중 하나를 초과할 때의 동작을 설정합니다.

가능한 값:

• throw: 예외를 발생시킵니다(기본값).
• break: 쿼리 실행을 중지하고 부분 결과를 반환합니다. 소스 데이터가 소진된 것처럼 동작합니다.

​

transform_null_in

IN 연산자에서 NULL 값의 동등 비교를 활성화합니다.

기본적으로 NULL 값은 비교할 수 없습니다. NULL은 정의되지 않은 값을 의미하기 때문입니다. 따라서 expr = NULL 비교는 항상 false를 반환해야 합니다. 이 설정을 사용하면 IN 연산자에서 NULL = NULL이 true를 반환합니다.

가능한 값:

• 0 — IN 연산자에서 NULL 값 비교는 false를 반환합니다.
• 1 — IN 연산자에서 NULL 값 비교는 true를 반환합니다.

예시

null_in 테이블을 예로 들어 보겠습니다:

┌──idx─┬─────i─┐
│    1 │     1 │
│    2 │  NULL │
│    3 │     3 │
└──────┴───────┘

쿼리:

SELECT idx, i FROM null_in WHERE i IN (1, NULL) SETTINGS transform_null_in = 0;

결과:

┌──idx─┬────i─┐
│    1 │    1 │
└──────┴──────┘

쿼리:

SELECT idx, i FROM null_in WHERE i IN (1, NULL) SETTINGS transform_null_in = 1;

결과:

┌──idx─┬─────i─┐
│    1 │     1 │
│    2 │  NULL │
└──────┴───────┘

관련 항목

• IN 연산자의 NULL 처리

​

traverse_shadow_remote_data_paths

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

​

union_default_mode

SELECT 쿼리 결과를 결합하는 방식을 설정합니다. 이 설정은 UNION ALL 또는 UNION DISTINCT를 명시적으로 지정하지 않고 UNION을 사용할 때만 적용됩니다.

가능한 값:

• 'DISTINCT' — ClickHouse는 중복 행을 제거한 쿼리 결합 결과를 반환합니다.
• 'ALL' — ClickHouse는 중복 행을 포함한 쿼리 결합 결과를 모두 반환합니다.
• '' — UNION과 함께 사용하면 ClickHouse에서 예외가 발생합니다.

예시는 UNION을 참조하십시오.

​

unknown_packet_in_send_data

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

​

update_parallel_mode

동시에 실행되는 UPDATE 쿼리의 동작 방식을 결정합니다.

가능한 값:

• sync - 모든 UPDATE 쿼리를 순차적으로 실행합니다.
• auto - 한 쿼리에서 업데이트되는 컬럼과 다른 쿼리의 표현식에서 사용되는 컬럼 사이에 의존성이 있는 UPDATE 쿼리만 순차적으로 실행합니다.
• async - UPDATE 쿼리를 동기화하지 않습니다.

​

update_sequential_consistency

true이면 update를 실행하기 전에 파트 집합이 최신 버전으로 갱신됩니다.

​

url_base

url 테이블 함수와 URL 테이블 엔진에서 상대 URL을 해석할 때 사용하는 기준 URL입니다.

설정하면 상대 URL은 다음과 같이 해석됩니다.

• 경로 상대 URL(예: data.csv): RFC 3986에 따라 기준 URL의 경로와 병합됩니다. 기준 경로에서 마지막 / 뒤의 모든 내용이 상대 URL로 대체되므로 후행 슬래시의 유무가 중요합니다. https://example.com/dir/ + data.csv = https://example.com/dir/data.csv이지만, https://example.com/dir + data.csv = https://example.com/data.csv입니다. 기준 URL에 경로가 없으면(예: https://example.com) /가 삽입되어 https://example.com/data.csv가 됩니다. 상대 URL의 점 세그먼트(./ 및 ../)는 정규화됩니다. 예: https://example.com/dir/ + ../a.csv = https://example.com/a.csv.
• 호스트 상대 URL(예: /test/data.csv): 기준 URL의 스킴과 호스트를 기준으로 해석됩니다.
• 스킴 상대 URL(예: //other.com/test/data.csv): 기준 URL의 스킴을 사용해 해석됩니다.
• 쿼리만 있는 참조(예: ?x=1): 기준 URL 경로에 추가됩니다(기존 쿼리/프래그먼트는 대체됨).
• 프래그먼트만 있는 참조(예: #frag): 기준 URL에 추가되며 기존 쿼리 문자열은 유지됩니다(기존 프래그먼트는 대체됨).
• 빈 참조: 프래그먼트가 없는 기준 URL을 반환합니다.

예를 들어 url_base가 https://example.com/def/이면 다음과 같습니다.

• data.csv는 https://example.com/def/data.csv로 해석됩니다
• /test/data.csv는 https://example.com/test/data.csv로 해석됩니다
• //other.com/test/data.csv는 https://other.com/test/data.csv로 해석됩니다

​

use_async_executor_for_materialized_views

materialized view 쿼리를 비동기적으로, 경우에 따라 멀티스레드로 실행합니다. INSERT 시 뷰 처리 속도를 높일 수 있지만, 메모리를 더 많이 사용할 수도 있습니다.

​

use_cache_for_count_from_files

테이블 함수 file/s3/url/hdfs/azureBlobStorage에서 파일의 행 수를 count할 때 캐싱을 활성화합니다.

기본적으로 활성화되어 있습니다.

​

use_client_time_zone

DateTime 문자열 값을 해석할 때 server 시간대를 따르는 대신 클라이언트 시간대를 사용합니다.

​

use_compact_format_in_distributed_parts_names

Distributed 엔진을 사용하는 테이블에 대해 백그라운드(distributed_foreground_insert) INSERT용 블록을 저장할 때 compact 포맷을 사용합니다.

가능한 값:

• 0 — user[:password]@host:port#default_database 디렉터리 포맷을 사용합니다.
• 1 — [shard{shard_index}[_replica{replica_index}]] 디렉터리 포맷을 사용합니다.

• use_compact_format_in_distributed_parts_names=0을 사용하면 클러스터 정의의 변경 사항이 백그라운드 INSERT에 적용되지 않습니다.
• use_compact_format_in_distributed_parts_names=1을 사용하면 클러스터 정의에서 노드 순서를 변경할 경우 shard_index/replica_index가 바뀌므로 주의하십시오.

​

use_concurrency_control

서버의 동시성 제어를 준수합니다(concurrent_threads_soft_limit_num 및 concurrent_threads_soft_limit_ratio_to_cores 전역 서버 설정 참고). 비활성화하면 서버에 과부하가 걸린 경우에도 더 많은 스레드를 사용할 수 있습니다(일반적인 사용에는 권장되지 않으며, 주로 테스트에 필요합니다).

Cloud 기본값: 0.

​

use_hash_table_stats_for_join_reordering

조인 재정렬 시 카디널리티를 추정할 때 수집된 해시 테이블 통계를 사용하도록 설정합니다

​

use_hedged_requests

원격 쿼리에 대한 hedged requests 로직을 활성화합니다. 이 기능을 사용하면 쿼리 실행을 위해 서로 다른 레플리카에 여러 연결을 설정할 수 있습니다. 기존 레플리카 연결이 hedged_connection_timeout 내에 설정되지 않았거나 receive_data_timeout 내에 데이터를 받지 못한 경우 새 연결이 활성화됩니다. 쿼리는 비어 있지 않은 Progress 패킷(또는 allow_changing_replica_until_first_data_packet가 설정된 경우 Data 패킷)을 가장 먼저 보내는 연결을 사용하며, 다른 연결은 취소됩니다. max_parallel_replicas > 1인 쿼리도 지원합니다.

기본적으로 활성화되어 있습니다.

Cloud 기본값: 0.

​

use_hive_partitioning

활성화되면 ClickHouse는 파일 계열 테이블 엔진 File/S3/URL/HDFS/AzureBlobStorage의 경로(/name=value/)에서 Hive 스타일 파티셔닝을 감지하고, 쿼리에서 파티션 컬럼을 가상 컬럼으로 사용할 수 있도록 합니다. 이러한 가상 컬럼의 이름은 파티션 경로의 이름과 같지만, 앞에 _가 붙습니다.

​

use_iceberg_metadata_files_cache

활성화하면 Iceberg 테이블 함수와 Iceberg 스토리지가 Iceberg 메타데이터 파일 캐시를 사용할 수 있습니다.

가능한 값:

• 0 - 비활성화됨
• 1 - 활성화됨

​

use_iceberg_partition_pruning

Iceberg 테이블에 Iceberg 파티션 프루닝을 사용합니다

​

use_index_for_in_with_subqueries

IN 연산자의 오른쪽에 서브쿼리 또는 테이블 표현식이 있는 경우 인덱스 사용을 시도합니다.

​

use_index_for_in_with_subqueries_max_values

필터링에 테이블 인덱스를 사용하기 위해 IN 연산자 오른쪽에 오는 집합의 최대 크기입니다. 큰 쿼리에서 추가 데이터 구조를 준비하느라 발생할 수 있는 성능 저하와 메모리 사용량 증가를 방지할 수 있습니다. 0은 제한이 없음을 의미합니다.

​

use_join_disjunctions_push_down

JOIN 조건에서 OR로 연결된 부분을 해당 입력 측으로 푸시다운(“부분 푸시다운”)할지 설정합니다. 이렇게 하면 스토리지 엔진이 더 이른 단계에서 필터링할 수 있으므로 읽는 데이터 양을 줄일 수 있습니다. 이 최적화는 의미를 유지하며, 각 최상위 OR 분기가 대상 측에 대해 최소 1개의 결정적 프레디케이트를 제공하는 경우에만 적용됩니다.

​

use_legacy_to_time

활성화하면 기존 toTime 함수를 사용할 수 있습니다. 이 함수는 시간을 유지하면서 시간이 포함된 날짜 값을 특정 고정 날짜로 변환합니다. 활성화하지 않으면 서로 다른 유형의 데이터를 Time 유형으로 변환하는 새로운 toTime 함수를 사용합니다. 기존 레거시 함수는 toTimeWithFixedDate로도 항상 사용할 수 있습니다.

​

use_page_cache_for_disks_without_file_cache

파일 시스템 캐시가 활성화되지 않은 원격 디스크에 사용자 공간 페이지 캐시를 사용하도록 합니다.

​

use_page_cache_for_local_disks

로컬 디스크에서 읽을 때 사용자 공간 페이지 캐시를 사용합니다. 테스트용으로 사용되며, 실제 환경에서는 성능 향상에 도움이 될 가능성이 낮습니다. 사용하려면 local_filesystem_read_method = 'pread' 또는 'read'가 필요합니다. OS 페이지 캐시를 비활성화하지는 않으며, 이를 위해 min_bytes_to_use_direct_io를 사용할 수 있습니다. 일반 테이블에만 영향을 주며, file() 테이블 함수 또는 File() 테이블 엔진에는 영향을 주지 않습니다.

​

use_page_cache_for_object_storage

객체 스토리지 테이블 함수(s3, azure, hdfs)와 테이블 엔진(S3, Azure, HDFS)에서 읽을 때 사용자 공간 페이지 캐시를 사용합니다.

​

use_page_cache_with_distributed_cache

Distributed Cache를 사용하는 경우 사용자 공간 페이지 캐시를 사용합니다.

​

use_paimon_partition_pruning

Paimon 테이블 함수에 Paimon 파티션 프루닝을 적용합니다

​

use_parquet_metadata_cache

활성화하면 Parquet 포맷에서 Parquet 메타데이터 캐시를 사용할 수 있습니다.

가능한 값:

• 0 - 비활성화
• 1 - 활성화

​

use_partition_pruning

별칭: use_partition_key

MergeTree 테이블에서 쿼리 실행 중 파티션 키를 사용해 파티션 프루닝을 수행합니다.

가능한 값:

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

​

use_primary_key

MergeTree 테이블에서 쿼리를 실행할 때 그래뉼을 프루닝하는 데 프라이머리 키(primary key)를 사용합니다.

가능한 값:

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

​

use_query_cache

활성화하면 SELECT 쿼리에서 쿼리 캐시를 사용할 수 있습니다. 매개변수 enable_reads_from_query_cache 및 enable_writes_to_query_cache로 캐시 사용 방식을 더 세부적으로 제어할 수 있습니다.

가능한 값:

• 0 - 비활성화
• 1 - 활성화

​

use_query_condition_cache

쿼리 조건 캐시를 활성화합니다. 이 캐시는 WHERE 절의 조건을 만족하지 않는 데이터 파트 내 그래뉼 범위를 저장하고, 이 정보를 이후 쿼리에서 임시 인덱스로 재사용합니다.

가능한 값:

• 0 - 비활성화
• 1 - 활성화

​

use_roaring_bitmap_iceberg_positional_deletes

Iceberg의 위치 기반 삭제에 roaring 비트맵을 사용합니다.

​

use_skip_indexes

쿼리 실행 중 데이터 스키핑 인덱스를 사용합니다.

가능한 값:

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

​

use_skip_indexes_for_disjunctions

스킵 인덱스를 사용하여 AND와 OR가 혼합된 WHERE 필터 조건을 평가합니다. 예시: WHERE A = 5 AND (B = 5 OR C = 5). 비활성화된 경우에도 WHERE 조건 평가에는 계속 스킵 인덱스가 사용되지만, 조건에는 AND로 연결된 절만 포함될 수 있습니다.

가능한 값:

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

​

use_skip_indexes_for_top_k

TopK 필터링에 데이터 스키핑 인덱스를 사용합니다.

활성화되면 ORDER BY <column> LIMIT n 쿼리에서 해당 컬럼에 minmax 스킵 인덱스가 있는 경우, 옵티마이저는 최종 결과와 관련 없는 그래뉼을 건너뛰기 위해 minmax 인덱스를 사용하려고 시도합니다. 이렇게 하면 쿼리 지연 시간을 줄일 수 있습니다.

가능한 값:

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

​

use_skip_indexes_if_final

FINAL 수정자와 함께 쿼리를 실행할 때 스킵 인덱스를 사용할지 여부를 제어합니다.

스킵 인덱스는 최신 데이터가 포함된 행(그래뉼)을 제외할 수 있으므로 FINAL 수정자가 있는 쿼리에서 잘못된 결과가 발생할 수 있습니다. 이 설정을 활성화하면 FINAL 수정자를 사용하는 경우에도 스킵 인덱스가 적용되어 성능이 향상될 수 있지만, 최근 업데이트를 놓칠 위험이 있습니다. 이 설정은 use_skip_indexes_if_final_exact_mode 설정과 함께 활성화하는 것이 좋습니다(기본값은 활성화됨).

가능한 값:

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

​

use_skip_indexes_if_final_exact_mode

이 설정은 FINAL 수정자를 사용한 쿼리를 실행할 때 올바른 결과를 반환할 수 있도록, 스키핑 인덱스가 반환한 그래뉼의 범위를 더 새로운 파트까지 확장할지 여부를 제어합니다.

스킵 인덱스를 사용하면 최신 데이터가 포함된 행(그래뉼)이 제외되어 잘못된 결과가 나올 수 있습니다. 이 설정을 사용하면 스킵 인덱스가 반환한 범위와 겹치는 더 새로운 파트를 스캔하여 올바른 결과를 보장할 수 있습니다. 애플리케이션에서 스킵 인덱스 조회를 기반으로 한 근사 결과로도 충분한 경우에만 이 설정을 비활성화해야 합니다.

가능한 값:

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

​

use_skip_indexes_on_data_read

데이터를 읽는 동안 데이터 스키핑 인덱스 사용을 활성화합니다.

활성화하면 쿼리 실행이 시작되기 전에 미리 분석하는 대신, 각 데이터 granule을 읽는 시점에 스킵 인덱스를 동적으로 평가합니다. 이렇게 하면 쿼리 시작 지연 시간을 줄일 수 있습니다.

가능한 값:

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

​

use_statistics

/// ‘use_primary_key’ 및 ‘use_skip_indexes’와의 일관성을 위해 ‘allow_statistics_optimize’보다 이 이름을 더 선호합니다 통계를 사용해 쿼리 최적화를 수행할 수 있습니다

​

use_statistics_cache

각 파트의 통계를 로드하는 오버헤드를 피하기 위해 쿼리에서 통계 캐시를 사용합니다

​

use_statistics_for_part_pruning

쿼리 실행 중 파트를 필터링하는 데 통계를 사용합니다.

활성화하면 SELECT 쿼리의 프루닝에서 데이터를 읽기 전에 일치하는 데이터를 포함할 수 없는 파트를 제외하기 위해 컬럼 통계(예: MinMax 통계)를 사용합니다.

가능한 값:

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

​

use_strict_insert_block_limits

활성화하면 최소 및 최대 삽입 블록 크기 제한이 모두 엄격하게 적용됩니다.

다음 경우 블록이 생성됩니다.

• 최소 임계값(AND): min_insert_block_size_rows와 min_insert_block_size_bytes에 모두 도달한 경우
• 최대 임계값(OR): max_insert_block_size_rows 또는 max_insert_block_size_bytes 중 하나에 도달한 경우

비활성화하면 다음 경우 블록이 생성됩니다.

• 최소 임계값(OR): min_insert_block_size_rows 또는 min_insert_block_size_bytes 중 하나에 도달한 경우

참고: max 설정이 min 설정보다 작으면 max 제한이 우선 적용되며, min 임계값에 도달하기 전에 블록이 생성됩니다.

참고: 이 설정은 async inserts에서는 자동으로 비활성화됩니다. async inserts는 항목별 중복 제거 token을 연결하는데, 이는 엄격한 제한 적용에 필요한 블록 분할과 호환되지 않기 때문입니다.

기본적으로 비활성화되어 있습니다.

​

테이블 함수에서 삽입 테이블의 구조 사용

데이터로 스키마를 추론하는 대신 삽입 테이블의 구조를 사용합니다. 가능한 값: 0 - 비활성화, 1 - 활성화, 2 - 자동

​

use_text_index_header_cache

역직렬화된 text index header 캐시를 사용할지 여부입니다. text index header cache를 사용하면 많은 수의 text index 쿼리를 처리할 때 지연 시간을 크게 줄이고 처리량을 높일 수 있습니다.

​

use_text_index_like_evaluation_by_dictionary_scan

역텍스트 인덱스 딕셔너리를 스캔해 LIKE/ILIKE 쿼리를 평가하도록 설정합니다.

​

use_text_index_postings_cache

역직렬화된 텍스트 인덱스 포스팅 리스트 캐시 사용 여부입니다. 텍스트 인덱스 포스팅 캐시를 사용하면 다수의 텍스트 인덱스 쿼리를 처리할 때 지연 시간을 크게 줄이고 처리량을 높일 수 있습니다.

​

use_text_index_tokens_cache

역직렬화된 text index token info 캐시를 사용할지 여부입니다. text index tokens cache를 사용하면 다수의 text index 쿼리를 처리할 때 지연 시간을 크게 줄이고 처리량을 높일 수 있습니다.

​

use_top_k_dynamic_filtering

ORDER BY <column> LIMIT n 쿼리를 실행할 때 동적 필터링 최적화를 활성화합니다.

활성화하면 쿼리 실행기는 결과 세트의 최종 top N 행에 포함되지 않을 그래뉼과 행을 건너뛰려고 시도합니다. 이 최적화는 동적으로 적용되며, 지연 시간 개선 효과는 데이터 분포와 쿼리에 다른 프레디케이트가 있는지에 따라 달라집니다.

가능한 값:

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

​

use_top_k_dynamic_filtering_for_variable_length_types

정렬 컬럼이 가변 길이 데이터 타입(예: String, Array, Map, 가변 길이 요소를 포함하는 Tuple)인 경우에도 use_top_k_dynamic_filtering을 적용할 수 있도록 허용합니다.

이러한 타입에서는 동적 필터가 수행하는 행별 임계값 비교 비용이, 컬럼의 사전식 최소값이 우세하고(예: 대부분이 빈 문자열) 건너뛸 수 있는 그래뉼이 거의 없을 때, 그로 인해 얻는 절감 효과보다 더 커질 수 있습니다. 이런 경우 동적 필터는 쿼리 지연 시간을 개선하기는커녕 오히려 악화시킬 수 있습니다.

이 설정이 0이면 동적 필터링은 메모리에서 값의 최대 크기가 고정된 컬럼(숫자, Date, DateTime, FixedString, Enum, 이러한 타입의 Nullable, 이러한 타입의 Tuple)으로 제한됩니다. 1로 설정하면 동적 필터링이 가변 길이 타입에도 적용됩니다.

가능한 값:

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

​

use_uncompressed_cache

비압축 블록 캐시를 사용할지 여부를 지정합니다. 0 또는 1을 허용합니다. 기본값은 0(비활성화)입니다. 비압축 캐시( MergeTree 엔진 계열 테이블에만 해당)를 사용하면 짧은 쿼리를 대량으로 처리할 때 지연 시간을 크게 줄이고 처리량을 높일 수 있습니다. 짧은 요청을 자주 보내는 사용자에게는 이 설정을 활성화하세요. 또한 uncompressed_cache_size 구성 매개변수(구성 파일에서만 설정 가능)도 확인하세요. 이 매개변수는 비압축 캐시 블록의 크기를 지정합니다. 기본값은 8 GiB입니다. 비압축 캐시는 필요에 따라 채워지며, 가장 적게 사용된 데이터는 자동으로 삭제됩니다.

어느 정도 큰 양의 데이터(100만 행 이상)를 읽는 쿼리의 경우, 실제로 작은 쿼리를 위한 공간을 확보하기 위해 비압축 캐시가 자동으로 비활성화됩니다. 즉, ‘use_uncompressed_cache’ 설정은 항상 1로 설정해 두어도 됩니다.

​

use_variant_as_common_type

인수 타입에 공통 타입이 없을 때 if/multiIf/array/map 함수의 결과 타입으로 Variant를 사용할 수 있습니다.

예시:

SET use_variant_as_common_type = 1;
SELECT toTypeName(if(number % 2, number, range(number))) as variant_type FROM numbers(1);
SELECT if(number % 2, number, range(number)) as variant FROM numbers(5);

┌─variant_type───────────────────┐
│ Variant(Array(UInt64), UInt64) │
└────────────────────────────────┘
┌─variant───┐
│ []        │
│ 1         │
│ [0,1]     │
│ 3         │
│ [0,1,2,3] │
└───────────┘

SET use_variant_as_common_type = 1;
SELECT toTypeName(multiIf((number % 4) = 0, 42, (number % 4) = 1, [1, 2, 3], (number % 4) = 2, 'Hello, World!', NULL)) AS variant_type FROM numbers(1);
SELECT multiIf((number % 4) = 0, 42, (number % 4) = 1, [1, 2, 3], (number % 4) = 2, 'Hello, World!', NULL) AS variant FROM numbers(4);

─variant_type─────────────────────────┐
│ Variant(Array(UInt8), String, UInt8) │
└──────────────────────────────────────┘

┌─variant───────┐
│ 42            │
│ [1,2,3]       │
│ Hello, World! │
│ ᴺᵁᴸᴸ          │
└───────────────┘

SET use_variant_as_common_type = 1;
SELECT toTypeName(array(range(number), number, 'str_' || toString(number))) as array_of_variants_type from numbers(1);
SELECT array(range(number), number, 'str_' || toString(number)) as array_of_variants FROM numbers(3);

┌─array_of_variants_type────────────────────────┐
│ Array(Variant(Array(UInt64), String, UInt64)) │
└───────────────────────────────────────────────┘

┌─array_of_variants─┐
│ [[],0,'str_0']    │
│ [[0],1,'str_1']   │
│ [[0,1],2,'str_2'] │
└───────────────────┘

SET use_variant_as_common_type = 1;
SELECT toTypeName(map('a', range(number), 'b', number, 'c', 'str_' || toString(number))) as map_of_variants_type from numbers(1);
SELECT map('a', range(number), 'b', number, 'c', 'str_' || toString(number)) as map_of_variants FROM numbers(3);

┌─map_of_variants_type────────────────────────────────┐
│ Map(String, Variant(Array(UInt64), String, UInt64)) │
└─────────────────────────────────────────────────────┘

┌─map_of_variants───────────────┐
│ {'a':[],'b':0,'c':'str_0'}    │
│ {'a':[0],'b':1,'c':'str_1'}   │
│ {'a':[0,1],'b':2,'c':'str_2'} │
└───────────────────────────────┘

​

use_variant_default_implementation_for_comparisons

비교 함수에서 Variant 타입에 기본 구현을 사용할지 여부를 설정합니다.

​

use_with_fill_by_sorting_prefix

ORDER BY 절에서 WITH FILL 컬럼 앞에 오는 컬럼들이 정렬 접두어를 이룹니다. 정렬 접두어 값이 다른 행은 각각 독립적으로 채워집니다

​

validate_enum_literals_in_operators

활성화하면 IN, NOT IN, ==, != 같은 연산자에서 enum 리터럴을 enum 유형에 대해 검증하며, 리터럴이 유효한 enum 값이 아니면 예외를 발생시킵니다.

​

validate_mutation_query

뮤테이션 쿼리를 수락하기 전에 검증합니다. 뮤테이션은 백그라운드에서 실행되므로, 잘못된 쿼리를 실행하면 뮤테이션이 중단된 상태가 되어 수동 조치가 필요합니다.

하위 호환되지 않는 버그가 발생한 경우에만 이 설정을 변경하십시오.

​

validate_polygons

폴리곤이 자기 교차하거나 자기 접하는 경우 pointInPolygon 함수에서 예외를 발생시킬지 여부를 설정합니다.

가능한 값:

• 0 — 예외 발생이 비활성화됩니다. pointInPolygon은 유효하지 않은 폴리곤도 허용하며, 이에 대해 잘못된 결과를 반환할 수 있습니다.
• 1 — 예외 발생이 활성화됩니다.

​

variant_throw_on_type_mismatch

기본 구현을 사용해 Variant 컬럼에 함수를 적용할 때, 실제 타입이 함수와 호환되지 않는 행을 어떻게 처리할지 제어합니다:

• true (기본값) — 예외를 발생시킵니다.
• false — 대신 해당 행에 NULL을 반환합니다.

​

vector_search_filter_strategy

벡터 검색 쿼리에 WHERE 절이 있는 경우, 이 설정은 해당 절을 먼저 평가할지(프리필터링), 아니면 벡터 유사성 인덱스를 먼저 검사할지(포스트필터링)를 결정합니다. 가능한 값은 다음과 같습니다.

• ‘auto’ - 포스트필터링(정확한 동작 방식은 향후 변경될 수 있습니다).
• ‘postfilter’ - 벡터 유사성 인덱스를 사용해 최근접 이웃을 식별한 다음, 다른 필터를 적용합니다.
• ‘prefilter’ - 다른 필터를 먼저 평가한 다음, 브루트포스 검색을 수행해 이웃을 식별합니다.

​

vector_search_index_fetch_multiplier

별칭: vector_search_postfilter_multiplier

벡터 유사성 인덱스에서 가져올 최근접 이웃 수를 이 값만큼 곱합니다. 다른 프레디케이트와 함께 포스트필터링을 수행할 때 또는 설정 vector_search_with_rescoring = 1인 경우에만 적용됩니다.

​

vector_search_with_rescoring

ClickHouse가 벡터 유사도 인덱스를 사용하는 쿼리에 대해 rescoring을 수행할지 여부입니다. rescoring을 사용하지 않으면 벡터 유사도 인덱스가 최적의 일치 항목을 포함하는 행을 직접 반환합니다. rescoring을 사용하면 행 범위가 granule 수준으로 확장되며, 해당 granule의 모든 행을 다시 검사합니다. 대부분의 경우 rescoring은 정확도 향상에 거의 도움이 되지 않지만, 벡터 검색 쿼리 성능은 크게 저하시킵니다. 참고: rescoring 없이 실행되고 병렬 레플리카가 활성화된 쿼리는 rescoring으로 대체될 수 있습니다.

​

wait_changes_become_visible_after_commit_mode

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

​

wait_for_async_insert

true이면 비동기 삽입이 처리될 때까지 기다립니다

​

wait_for_async_insert_timeout

비동기 삽입 처리를 기다리는 시간 제한

​

wait_for_window_view_fire_signal_timeout

이벤트 시간 처리에서 window view의 fire signal을 기다리는 시간 제한

​

webassembly_udf_max_fuel

WebAssembly UDF 인스턴스를 실행할 때 적용되는 연료 한도입니다. 각 WebAssembly 명령어는 일정량의 연료를 소비합니다. 제한을 두지 않으려면 0으로 설정하십시오.

​

webassembly_udf_max_input_block_size

단일 블록에서 WebAssembly UDF에 전달되는 최대 행 수입니다. 0으로 설정하면 모든 행을 한 번에 처리합니다.

​

webassembly_udf_max_instances

함수별로 병렬 실행할 수 있는 WebAssembly UDF 인스턴스의 최대 개수입니다.

​

webassembly_udf_max_memory

각 WebAssembly UDF 인스턴스에 적용되는 바이트 단위 메모리 한도입니다.

​

window_view_clean_interval

window view의 오래된 데이터를 정리하는 주기(초)입니다.

​

window_view_heartbeat_interval

watch 쿼리가 활성 상태임을 나타내는 하트비트 인터벌(초)입니다.

​

workload

리소스 액세스에 사용할 workload 이름

​

write_full_path_in_iceberg_metadata

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

​

write_through_distributed_cache

ClickHouse Cloud에서만 적용됩니다. 분산 캐시에 쓰기 작업을 허용합니다(S3에 대한 쓰기 작업도 분산 캐시를 통해 수행됩니다).

​

write_through_distributed_cache_buffer_size

ClickHouse Cloud에서만 적용됩니다. write-through Distributed Cache에 사용할 버퍼 크기를 설정합니다. 0이면 Distributed Cache가 없을 때 사용되는 버퍼 크기를 사용합니다.

​

zstd_window_log_max

ZSTD의 최대 윈도우 로그를 설정할 수 있습니다(MergeTree 엔진 계열에는 사용되지 않습니다)