enable(활성화) 관련 설정

ClickHouse의 다양한 기능을 켜고 끄는 enable_* 계열 세션 설정들을 모아둔 문서예요. 압축 코덱, 집계 최적화, 분산 쿼리, JSON 처리, 스트리밍 쿼리 등 기능의 범위가 아주 넓답니다. 이 설정들은 system.settings 테이블에서 확인할 수 있고 소스 코드에서 자동 생성된 값들이에요.

출처: 문서

본문

이 설정들은 system.settings에서 확인할 수 있고, 소스 코드에서 자동 생성된 값들이에요.

enable_adaptive_aggregator

적응형 GROUP BY 알고리즘을 활성화해요. 각 스레드는 키 수가 adaptive_aggregator_freeze_threshold(또는 메모리가 adaptive_aggregator_freeze_threshold_bytes)에 도달할 때까지 자기 로컬 해시 테이블에 집계하다가, 테이블이 freeze되면서 이미 본(자주 등장하는) 키의 행들은 그 자리에서 계속 갱신되고, 새로운(드문) 키들은 해시에 따라 버킷별 backlog로 라우팅되어 버킷-병렬 병합 안에서 정확히 한 번 집계된답니다. 자주 등장하는 키는 작은 캐시-상주 테이블에 남고, 드문 키는 스레드마다 한 번씩이 아니라 한 번만 저장되고 처리돼요.

외부 집계 설정(max_bytes_before_external_group_by, max_bytes_ratio_before_external_group_by)도 그대로 적용돼요. 임계값을 넘으면 backlog는 공유 테이블로 일찍 비워지고, 그래도 충분하지 않으면 공유 테이블이 일반 외부 집계를 통해 디스크로 spill된답니다.

enable_adaptive_memory_spill_scheduler

프로세서가 데이터를 적응형으로 외부 스토리지에 spill하도록 트리거해요. 현재는 spill이 가능한 해시 조인(grace_hash 및 적응형 hash / parallel_hash 경로)이 지원된답니다.

enable_add_distinct_to_in_subqueries

IN 서브쿼리에 DISTINCT를 활성화해요. 이는 트레이드오프가 있는 설정으로, 켜면 분산 IN 서브쿼리에 전송되는 임시 테이블의 크기를 크게 줄이고 고유한 값만 전송되도록 해서 샤드 간 데이터 전송을 크게 가속화할 수 있어요.

하지만 이 설정을 켜면 각 노드에서 중복 제거(DISTINCT)를 수행해야 하므로 추가적인 병합 작업이 발생해요. 네트워크 전송이 병목인 경우에 이 설정을 사용하고, 추가 병합 비용이 허용 가능한지 확인해 보세요.

enable_alp_codec

ALP 압축 코덱을 활성화해요.

enable_automatic_decision_for_merging_across_partitions_for_final

설정하면 파티션 키 표현식이 결정적이고 파티션 키 표현식에 사용된 모든 컬럼이 프라이머리 키에 포함되어 있을 때 ClickHouse가 이 최적화를 자동으로 활성화해요.

이 자동 유도는 같은 프라이머리 키 값을 가진 행이 항상 같은 파티션에 속하게 해서 크로스-파티션 병합을 안전하게 피할 수 있게 해줘요. 부동소수점 키 컬럼은 이 유도에서 제외된답니다. FINAL 비교자는 Float32, Float64, BFloat16의 값 동일성보다 거친데, -0.0은 0.0과 같게 비교되고 모든 NaN 비트 패턴은 서로 같게 비교되거든요. 파티션 표현식은 그 값들을 정확히 구분할 수 있어서, 비교자가 하나의 키로 취급하는 행들이 다른 파티션에 들어갈 수 있고 크로스-파티션 병합을 건너뛰면 그 모든 행이 반환된답니다.

이 제외는 키 컬럼 안에 부동소수점이 중첩된 경우, 예를 들어 Tuple(Float64, UInt8) 또는 Array(Float64)에도 적용돼요.

enable_cascades_optimizer

분산 쿼리 계획을 위한 Cascades 비용 기반 옵티마이저를 활성화해요. make_distributed_plan = 1과 함께만 적용되며, 이 설정만으로는 단일 노드 쿼리 계획을 변경하지 않아요.

enable_early_constant_folding

함수와 서브쿼리 결과를 분석하고 상수가 있으면 쿼리를 재작성하는 쿼리 최적화를 활성화해요.

enable_extended_results_for_datetime_functions

Date 타입과 비교해 확장된 범위를 가진 Date32 타입, DateTime과 비교해 확장된 범위를 가진 DateTime64 타입의 결과를 반환할지 여부를 활성화/비활성화해요.

가능한 값:

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_full_text_index

별칭: allow_experimental_full_text_index

true로 설정하면 텍스트 인덱스를 사용할 수 있게 돼요.

enable_function_early_short_circuit

쿼리 분석 중 and와 or에 대한 조기 단락(early short-circuit) 상수 폴딩을 활성화해요.

켜면 적격한 죽은 스칼라-서브쿼리 분기를 분석해 타입을 보존하고 쿼리 의미를 검증하지만, 실행하지는 않아요. 스칼라 카디널리티나 런타임 값이 필요한 경우에는 이 최적화가 일반 분석으로 되돌아간답니다.

enable_funnel_functions

별칭: allow_experimental_funnel_functions

퍼널 분석을 위한 함수들을 활성화해요.

enable_global_with_statement

WITH 문장을 UNION 쿼리와 모든 서브쿼리로 전파해요.

enable_group_by_top_k_optimization

GROUP BY keys ORDER BY <prefix of keys> LIMIT K 쿼리와, ORDER BY 없이 GROUP BY keys LIMIT K 쿼리(거기선 아무 K개 그룹이나 유효한 결과이므로 전체 키에 대한 정렬이 합성됨)에서 집계 중 TopK 필터링 최적화를 활성화해요.

켜면 집계기가 지금까지 본 상위 K개 키의 경계 있는 힙을 유지하고, 그룹핑 키가 최종 결과에 들어갈 수 없을 때 새 행을 해시 테이블에 삽입하지 않아요. 이를 통해 이후 ORDER BY ... LIMIT에서 버려질 행의 집계를 피할 수 있고, 힙이 전체 GROUP BY 키를 순위화하면 중간 해시 테이블에서 퇴출된 그룹을 잘라내 그 크기를 고유 키 수 대신 LIMIT로 제한해요. ORDER BY가 GROUP BY 키의 진짜 일부 전위(prefix)만 다루는 경우에는 순위화가 전체 그룹을 식별할 수 없으므로 행 건너뛰기만 적용돼요. 해시 테이블은 허용된 모든 그룹을 유지하고 나머지 키 컬럼의 카디널리티에 따라 계속 커질 수 있어요.

요청한 LIMIT가 query_plan_max_limit_for_top_k_optimization 또는 하드 캡인 100000보다 높으면 힙의 메모리·CPU 비용이 요청 LIMIT에 따라 커지므로 이 최적화는 비활성화돼요.

그룹 가지치기가 결과를 바꿀 수 있는 쿼리 형태에서는 이 최적화를 건너뛰어요. 여기에는 WITH TOTALS, HAVING, QUALIFY, 윈도우 함수, ROLLUP/CUBE/GROUPING SETS, LIMIT WITH TIES, 일치하는 GROUP BY 키 중 하나에 대한 COLLATE(전체 키 전위를 지나친 이후 ORDER BY 컬럼의 COLLATE는 어떤 그룹이 적격인지에 영향을 줄 수 없으므로 최적화를 비활성화하지 않음), 집계 또는 GROUP BY 키의 선행 전위가 아닌 ORDER BY, 그리고 max_rows_to_group_by나 exact_rows_before_limit가 설정된 경우가 포함돼요.

가능한 값:

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

enable_hash_join_row_store

해시 조인의 페이로드를 행-우선(row-major) 레이아웃으로 변환하는 것을 활성화해요.

enable_hdfs_pread

HDFS 파일에 대한 pread를 활성화하거나 비활성화해요. 기본적으로는 hdfsPread가 사용된답니다. 비활성화하면 hdfsRead와 hdfsSeek를 사용해 hdfs 파일을 읽어요.

enable_http_compression

HTTP 요청에 대한 응답의 데이터 압축을 활성화하거나 비활성화해요. 자세한 내용은 HTTP 인터페이스 설명을 읽어 보세요.

가능한 값:

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

enable_identifier_resolve_cache

쿼리 분석기의 식별자 해석 캐시를 활성화해요. 이 캐시는 같은 별칭이 여러 번 참조될 때 AST 폭발을 막기 위해 해석된 별칭 노드를 공유해요. 잘못된 결과가 의심되면 false로 설정해 캐싱을 비활성화하세요.

enable_job_stack_trace

job이 예외로 끝날 때 job 생성자의 스택 트레이스를 출력해요. 성능 오버헤드를 피하기 위해 기본적으로는 비활성화되어 있답니다.

enable_json_ast_dialect

dialect 설정의 clickhouse_json 값을 활성화해요. dialect가 clickhouse_json으로 설정되면 쿼리가 SQL 텍스트 대신 JSON AST(parseQueryToJSON의 출력)로 해석된답니다. SET 쿼리는 여전히 일반 SQL로 파싱되어 dialect를 다시 전환할 수 있어요.

예시:

SET enable_json_ast_dialect = 1;
SET dialect = 'clickhouse_json';

-- 이후 쿼리는 JSON AST로 파싱됩니다:
{"type":"SelectWithUnionQuery", ...}

enable_json_lazy_type_hints

별칭: allow_experimental_json_lazy_type_hints

JSON 타입에 대한 지연(lazy) 타입 힌트를 활성화해요. 이 설정을 켜면 타입 힌트만 추가하거나 변경하는 ALTER TABLE ... MODIFY COLUMN json JSON(path TypeName)은 메타데이터 전용 작업이 돼요. 타입 힌트는 기존 파트에 대해 쿼리 시점에 적용되고, 히스토리 데이터를 다시 쓰는 대신 삽입과 백그라운드 병합 중에 구체화된답니다.

enable_lazy_columns_replication

JOIN, ARRAY JOIN, 그리고 고차 함수(예: arrayMap)의 람다 캡처에서 지연 컬럼 복제를 활성화해요. 메모리에서 같은 행을 불필요하게 여러 번 복사하는 것을 피할 수 있게 해주죠.

enable_materialized_cte

구체화된 공통 테이블 표현식(WITH <name> AS MATERIALIZED (<subquery>))을 활성화해요.

켜면 MATERIALIZED로 선언되고 한 번 이상 참조되는 CTE는 한 번 실행되어 임시 테이블에 저장되고, 모든 참조는 그 테이블에서 읽어요. 한 번만 참조되는 CTE는 오버헤드를 피하기 위해 일반 CTE처럼 인라인된답니다.

끄면 MATERIALIZED 키워드는 무시되고, CTE는 일반 CTE처럼 각 참조에서 인라인되며 경고가 로그로 기록돼요.

enable_materialized_postgresql_table

별칭: allow_experimental_materialized_postgresql_table

MaterializedPostgreSQL 테이블 엔진을 사용할 수 있게 해요.

enable_memory_bound_merging_of_aggregation_results

집계를 위한 메모리 바운드 병합 전략을 활성화해요.

enable_multiple_prewhere_read_steps

WHERE의 더 많은 조건을 PREWHERE로 옮기고, AND로 결합된 조건이 여러 개일 때 디스크 읽기와 필터링을 여러 단계로 수행해요.

enable_named_columns_in_function_tuple

모든 이름이 고유하고 따옴표 없는 식별자로 취급될 수 있을 때 함수 tuple()에서 이름 있는 튜플을 생성해요.

enable_nullable_tuple_type

별칭: allow_experimental_nullable_tuple_type

테이블에 NullableTuple 컬럼 생성이 가능하게 해요. 이 설정은 추출된 튜플 서브컬럼이 Nullable이 될 수 있는지(예: Dynamic, Variant, JSON, Tuple 컬럼)를 제어하지 않아요. 추출된 튜플 서브컬럼이 Nullable이 될 수 있는지 제어하려면 allow_nullable_tuple_in_extracted_subcolumns을 사용하세요.

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_packed_string_keys_in_aggregation

단일 non-nullable String 키를 가진 GROUP BY에 대해 16바이트 packed 문자열 참조(PackedStringRef)를 키로 하는 해시 테이블을 사용해요. 최대 11바이트의 키는 packed 참조에 인라인으로 저장되고, 더 긴 키는 arena에서 참조된답니다.

대부분의 워크로드에서 더 빠르지만, 11바이트보다 긴 고유 키가 아주 적은 GROUP BY(특히 12..24바이트)에서는 레거시 방식보다 느릴 수 있어요. 레거시 해시 테이블은 키를 셀에 인라인으로 유지하는 반면 packed 방식은 매 프로브마다 arena 포인터를 역참조하기 때문이에요.

비활성화하면 레거시 StringHashTable 기반 방식(26.8 이전 기본값)이 사용돼요. 분산 쿼리에 참여하는 모든 서버는 이 값에 동의해야 해요. distributed_aggregation_memory_efficient를 사용하면 2단계 버킷 번호가 키 해시에 의존하는데, 두 방식 사이에 해시가 다르므로 이 설정에 동의하지 않는 서버는 같은 키를 다른 버킷으로 나눠 잘못 병합된 결과를 만들 수 있거든요. 동의를 보장하기 위해 initiator는 항상 자신의 유효 값을 보조 쿼리와 함께 전송해(서버/프로필 기본값에서만 오더라도) 원격 서버의 자체 기본값을 덮어써요.

enable_parsing_to_custom_serialization

true이면 테이블에서 얻은 직렬화 힌트에 따라 데이터가 사용자 지정 직렬화(예: Sparse)를 가진 컬럼으로 직접 파싱될 수 있어요.

enable_producing_buckets_out_of_order_in_aggregation

메모리 효율적 집계( distributed_aggregation_memory_efficient 참조)가 버킷을 순서 없이 생성하도록 허용해요. 집계 버킷 크기가 치우쳐 있을 때, 레플리카가 일부 무거운 낮은 id 버킷을 처리하는 동안 높은 id 버킷을 initiator로 보낼 수 있어 성능이 개선될 수 있어요. 단점은 메모리 사용량이 잠재적으로 높아진다는 것이에요.

enable_quantized_codec

Quantized 압축 코덱을 활성화해요.

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
)

이 설정이 없으면 외부 쿼리와 내부 쿼리가 서로 다른 데이터 스냅샷을 대상으로 동작해 잘못된 결과를 만들 수 있어요.

가능한 값:

0 - 비활성화
1 - 활성화

enable_sharing_sets_for_mutations

같은 뮤테이션의 서로 다른 태스크 간에 IN 서브쿼리용으로 빌드된 set 객체를 공유할 수 있게 해요. 이는 메모리 사용량과 CPU 소비를 줄여준답니다.

enable_streaming_queries

SELECT ... FROM t STREAM [CURSOR '{...}'] 연속 쿼리를 허용해요. 꺼져 있으면 STREAM 수정자를 사용한 모든 테이블 표현식이 plan-build 시점에 거부돼요. 이는 스트리밍-쿼리 기능의 전체 게이트이며, 추가 기능은 자체 설정으로 제한될 수 있어요.

enable_sz3_codec

SZ3 압축 코덱을 활성화해요.

enable_time_series_aggregate_functions

별칭: allow_experimental_ts_to_grid_aggregate_function, allow_experimental_time_series_aggregate_functions

Prometheus 스타일 시계열 리샘플링, 비율, 델타 계산을 위한 timeSeries* 집계 함수를 활성화해요.

enable_time_series_table

별칭: allow_experimental_time_series_table

TimeSeries 테이블 엔진을 사용한 테이블 생성을 허용해요.

가능한 값:

0 — TimeSeries 테이블 엔진 비활성화.
1 — TimeSeries 테이블 엔진 활성화.

enable_time_time64_type

별칭: allow_experimental_time_time64_type

Time과 Time64 데이터 타입 생성을 허용해요.

enable_trino_dialect

dialect 설정의 trino 값을 활성화해요. dialect가 trino로 설정되면 쿼리가 Trino SQL로 작성됩니다. Trino 전용 구문(ARRAY[...] 리터럴, TRY_CAST, UNNEST, ROW 타입, LIMIT 앞의 OFFSET)은 ClickHouse SQL로 변환되고, Trino 함수 이름은 ClickHouse 등가물에 매핑돼요. SET 쿼리는 여전히 일반 SQL로 파싱되어 dialect를 다시 전환할 수 있어요.

이 dialect는 쿼리 의미를 Trino에 맞춰 정렬해요. join_use_nulls가 켜지고 use_variant_as_common_type이 꺼지며 쿼리 분석기가 켜진답니다. 쿼리의 명시적 SETTINGS 절은 여전히 우선권을 가져요.

enable_unaligned_array_join

크기가 다른 여러 배열과의 ARRAY JOIN을 허용해요. 이 설정이 활성화되면 배열이 가장 긴 배열의 크기로 리사이즈된답니다.

enable_unique_key

별칭: allow_experimental_unique_key

MergeTree 계열 엔진에서 UNIQUE KEY 절을 사용한 테이블 생성을 허용해요.

enable_url_encoding

URL 엔진 테이블에서 URI의 디코딩/인코딩 경로를 활성화/비활성화할 수 있게 해요. 기본적으로는 비활성화되어 있답니다.

enable_vertical_final

활성화하면 FINAL 중에 행을 삭제된 것으로 표시하고 나중에 필터링하는 방식으로 중복 행을 제거해서, 행을 병합하지 않아요.

enable_writes_to_query_cache

켜면 SELECT 쿼리의 결과가 쿼리 캐시에 저장돼요.

가능한 값:

0 - 비활성화
1 - 활성화

enable_zxc_codec

ZXC 압축 코덱을 활성화해요.

enable(활성화) 관련 설정