query_plan_* 세션 설정

이 페이지에서는 쿼리 플랜 수준 최적화와 관련된 다양한 query_plan_* 세션 설정들을 다뤄요. 집계, 조인, 필터, LIMIT, 정렬, DISTINCT, 서브컬럼, 텍스트 인덱스 등 여러 최적화를 쿼리 플랜 레벨에서 개별적으로 켜고 끌 수 있어요. 이 설정들은 system.settings 테이블에서 확인할 수 있으며 ClickHouse 소스에서 자동 생성돼요.

출처: 문서

본문

이 설정들은 system.settings에서 확인할 수 있으며 소스에서 자동 생성돼요.

query_plan_aggregation_bucket_top_k

쿼리 플랜 수준 최적화를 토글해요. 최종 집계가 집계 출력에 대한 ORDER BY와 LIMIT n을 공급하고 플랜이 버킷별 선택이 정확함을 증명할 때, 집계의 최종 변환 동안 각 2단계 버킷의 최고 n개 그룹만 그 순서대로 구체화해요. 결과는 정확해요: 자신의 버킷의 최고 n개 밖의 그룹은 전역적으로 그 앞에 최소 n개의 그룹이 있으므로 전역 상위 n개에 들어갈 수 없어요. query_plan_enable_optimizations 설정이 1일 때만 효과가 있어요. 가능한 값:

0 - 비활성화
1 - 활성화

query_plan_aggregation_in_order

쿼리 플랜 수준의 순서대로 집계(aggregation in-order) 최적화를 토글해요. query_plan_enable_optimizations 설정이 1일 때만 효과가 있어요. 이것은 개발자가 디버깅 목적으로만 사용해야 하는 전문가용 설정이에요. 이 설정은 향후 하위 호환되지 않는 방식으로 바뀌거나 제거될 수 있어요. 가능한 값:

0 - 비활성화
1 - 활성화

query_plan_convert_any_join_to_semi_or_anti_join

조인 후 필터가 불일치 행이나 일치 행에 대해 항상 false로 평가되면 ANY JOIN을 SEMI 또는 ANTI JOIN으로 변환할 수 있게 해요.

query_plan_convert_join_to_in

출력 컬럼이 왼쪽 테이블에만 묶여 있으면 JOIN을 IN이 있는 서브쿼리로 변환할 수 있게 해요. 비-ANY JOIN(예: 기본값인 ALL JOIN)에서는 잘못된 결과를 초래할 수 있어요.

query_plan_convert_outer_join_to_inner_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

쿼리 플랜 수준에서 쿼리 최적화를 토글해요. 이것은 개발자가 디버깅 목적으로만 사용해야 하는 전문가용 설정이에요. 이 설정은 향후 하위 호환되지 않는 방식으로 바뀌거나 제거될 수 있어요. 가능한 값:

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_fuse_filter_into_array_join

ARRAY JOIN된 요소 컬럼에 대한 필터를 ARRAY JOIN 단계로 융합하는 쿼리 플랜 수준 최적화를 토글해요. 확장 전에 요소 공간에서 배열을 필터링하여, 필터링된 요소가 확장되거나 복제되지 않도록 해요. query_plan_enable_optimizations 설정이 1일 때만 효과가 있어요. 이것은 개발자가 디버깅 목적으로만 사용해야 하는 전문가용 설정이에요. 이 설정은 향후 하위 호환되지 않는 방식으로 바뀌거나 제거될 수 있어요.

query_plan_join_shard_by_pk_ranges

조인 키가 두 테이블 모두의 PRIMARY KEY 접두사를 포함하면 JOIN에 샤딩을 적용해요. hash, parallel_hash, full_sorting_merge, parallel_full_sorting_merge 알고리즘에서 지원돼요. 보통 쿼리를 빠르게 하지는 않지만 메모리 소비를 낮출 수 있어요.

query_plan_join_swap_table

쿼리 플랜에서 조인의 어느 쪽이 빌드 테이블(해시 조인의 경우 해시 테이블에 삽입되는 쪽, inner라고도 함)이 되어야 할지 결정해요. 이 설정은 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_lower_array_join_function

표현식 내부의 arrayJoin 함수를 실제 ARRAY JOIN 단계로 낮추는 쿼리 플랜 수준 최적화를 토글해요. 그래서 ARRAY JOIN 절과 같은 실행 메커니즘(지연 복제 및 필터 융합)을 통과해요. query_plan_enable_optimizations 설정이 1일 때만 효과가 있어요. 이것은 개발자가 디버깅 목적으로만 사용해야 하는 전문가용 설정이에요. 이 설정은 향후 하위 호환되지 않는 방식으로 바뀌거나 제거될 수 있어요.

query_plan_max_limit_for_join_lazy_indexing

JOIN에서 지연 인덱싱 최적화에 쿼리 플랜을 사용할 수 있게 하는 최대 제한 값을 제어해요. 0이면 제한이 없어요.

query_plan_max_limit_for_lazy_materialization

지연 구체화(lazy materialization) 최적화에 쿼리 플랜을 사용할 수 있게 하는 최대 제한 값을 제어해요. 0이면 제한이 없어요.

query_plan_max_limit_for_top_k_optimization

minmax 스킵 인덱스와 동적 임계값 필터링으로 TopK 최적화를 위해 쿼리 플랜을 평가할 수 있게 하는 최대 제한 값을 제어해요. 0이면 제한이 없어요. 이 설정은 enable_group_by_top_k_optimization의 동작도 제어해요.

query_plan_max_optimizations_to_apply

쿼리 플랜에 적용되는 총 최적화 수를 제한해요. query_plan_enable_optimizations 설정 참고. 복잡한 쿼리의 긴 최적화 시간을 피하는 데 유용해요. EXPLAIN PLAN 쿼리에서는 이 제한에 도달하면 최적화 적용을 중단하고 플랜을 그대로 반환해요. 일반 쿼리 실행에서는 실제 최적화 수가 이 설정을 초과하면 예외가 발생해요. 이것은 개발자가 디버깅 목적으로만 사용해야 하는 전문가용 설정이에요. 이 설정은 향후 하위 호환되지 않는 방식으로 바뀌거나 제거될 수 있어요.

query_plan_max_set_size_for_projection_match

두 집합이 같은지 결정할 때 프로젝션 매처가 콘텐츠 해시를 계산하고 비교하는 IN-절 집합의 최대 행 수예요. 이보다 큰 집합은 일치하지 않는 것으로 취급되고 프로젝션을 건너뛰어요. 0은 콘텐츠 해시 비교를 완전히 비활성화해요: IN-절 집합을 포함한 노드에 대해 프로젝션 일치는 절대 성공하지 않아요. 집계 프로젝션 매처(그리고 IN-절 집합을 비교해야 하는 미래의 프로젝션 매처)에서 사용돼요. 콘텐츠 해시 계산은 집합 요소 수에 대해 O(N log N)이므로, 이 설정은 쿼리나 프로젝션에 많은 IN-절이 나타날 때 플래닝 동안 지불되는 비용을 제한해요.

query_plan_max_step_description_length

EXPLAIN PLAN의 단계 설명 최대 길이예요.

query_plan_merge_expression_into_join

조인 재정렬 최적화 중 표현식을 JOIN 단계로 병합할 수 있게 해요.

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_min_columns_for_join_lazy_indexing

JOIN에서 지연 인덱싱 최적화를 활성화하는 데 필요한 왼쪽의 최소 페이로드 컬럼 수를 제어해요. 0은 최적화가 비활성화됨을 의미해요.

query_plan_optimize_count_from_text_index

SELECT count() ... WHERE <text search predicate>를 일치 행을 구체화하지 않고 텍스트 인덱스 posting-list 카디널리티에서 직접 답할 수 있게 해요. query_plan_direct_read_from_text_index가 활성화된 경우에만 효과가 있어요.

query_plan_optimize_join_order_algorithm

쿼리 플랜 최적화 중 시도할 JOIN 순서 알고리즘을 지정해요. 다음 알고리즘을 사용할 수 있어요:

greedy - 기본 탐욕 알고리즘 - 빠르게 동작하지만 최적의 조인 순서를 만들지 못할 수 있어요.
dpsize - 현재 내부 조인에 대해서만 DPsize 알고리즘을 구현 - 가능한 모든 조인 순서를 고려해 가장 최적의 것을 찾지만, 테이블과 조인 조건이 많은 쿼리에서는 느릴 수 있어요.
dpsub - 내부 및 비내부 조인을 모두 지원하는 DPsub 알고리즘 구현 - 가능한 모든 조인 순서를 고려해 가장 최적의 것을 찾지만, 테이블과 조인 조건이 많은 쿼리에서는 느릴 수 있어요.
dphyp - 현재 내부 조인에 대해서만 DPhyp(Hypergraph Partitioning을 통한 동적 프로그래밍) 알고리즘을 구현 - dpsize와 같은 검색 공간을 탐색하지만 연결된 부분 그래프 쌍만 열거하므로 희소한 조인 그래프에서 중간 조인이 더 적게 생성되지만, 교차 곱(cross product)을 고려하지 않는 비용이 있어요.

여러 알고리즘을 쉼표로 구분된 목록으로 지정할 수 있어요(예: dphyp,greedy). 그것들은 순서대로 시도되며, 알고리즘이 쿼리를 처리할 수 없으면(예: 외부 조인이나 끊어진 구성 요소 때문에) 다음 것이 폴백으로 사용돼요.

query_plan_optimize_join_order_conflict_detector

dpsub 조인 순서 알고리즘에만 영향을 줘요. DPsub가 어떤 조인 재정렬이 유효한지 결정하는 데 사용하는 충돌 감지기를 선택해요. 다음 값을 사용할 수 있어요:

''(기본값) - 충돌 감지기 없음, DPsub는 관계별 ON 절 제한을 사용해요.
'a' - CD-A 충돌 감지기, 정확하지만 불완전해요.
'c' - CD-C 충돌 감지기, 정확하고 완전해요.

query_plan_optimize_join_order_limit

같은 서브쿼리 내에서 조인의 순서를 최적화해요. 현재 매우 제한된 경우에만 지원돼요. 값은 최적화할 최대 테이블 수예요.

query_plan_optimize_join_order_max_searched_plans

조인 순서 최적화기가 포기하고 query_plan_optimize_join_order_algorithm의 다음 알고리즘으로 폴백하기 전에 열거할 수 있는 부분 플랜의 최대 수예요. 이것은 검색 공간이 지수적으로 커지는 밀집 조인 그래프(클릭이나 스타 같은)에서 최적화 시간을 결정적으로(벽시계와 무관하게) 제한해요. 제한을 비활성화하려면 0으로 설정해요. 기본 query_plan_optimize_join_order_limit에는 효과가 없는데, 그 경우 검색이 항상 이 경계 훨씬 아래에 머물기 때문이에요.

query_plan_optimize_join_order_randomize

0이 아닐 때 조인 순서 최적화기가 실제 통계 대신 무작위로 생성된 카디널리티와 NDV를 사용해요. 1로 설정하면 무작위 시드가 생성되고, 1보다 큰 값으로 설정하면 그 값이 시드로 직접 사용돼요. 다른 조인 순서로 인한 오류를 찾기 위한 테스트용으로 사용돼요.

query_plan_optimize_lazy_final

기본 키 집합을 만들고 그것을 인덱스 분석에 사용하여 ReplacingMergeTree에서 FINAL로 읽는 것을 최적화해요.

query_plan_optimize_lazy_materialization

지연 구체화 최적화에 쿼리 플랜을 사용해요.

query_plan_optimize_lazy_materialization_for_file

file 테이블 함수와 File 테이블 엔진으로 로컬 Parquet 파일을 읽을 때 지연 구체화 최적화를 사용해요: ORDER BY ... LIMIT n 쿼리의 경우 정렬과 필터링에 필요하지 않은 컬럼은 LIMIT를 통과하는 n개 행에 대해서만 읽혀요. query_plan_optimize_lazy_materialization이 활성화된 경우에만 효과가 있어요.

query_plan_optimize_lazy_materialization_for_object_storage

객체 스토리지(Iceberg 테이블 포함)에서 Parquet 파일을 읽을 때 지연 구체화 최적화를 사용해요: ORDER BY ... LIMIT n 쿼리의 경우 정렬과 필터링에 필요하지 않은 컬럼은 LIMIT를 통과하는 n개 행에 대해서만 읽혀요. query_plan_optimize_lazy_materialization이 활성화된 경우에만 효과가 있어요.

query_plan_optimize_prewhere

지원되는 스토리지에 대해 필터를 PREWHERE 표현식으로 내릴 수 있게 해요.

query_plan_propagate_predicate_across_join

equi-조인의 한 쪽에서 필터 분리를 equi-키 대체를 통해 다른 쪽으로 복사하여, 다른 쪽의 기본 키/인덱스 프루닝이 그것을 사용할 수 있게 하는 쿼리 플랜 수준 최적화를 토글해요. 필터와 MergeTree 읽기가 조인에서 표현식 및 필터 단계로만 분리되어 있고, 복사된 분리가 기본 키 컬럼을 상수와 비교할 때(상수 집합이 있는 IN 포함) 적용돼요. 중첩 조인 또는 DISTINCT 아래의 조건이나 두 키 컬럼 사이의 비교는 그대로 둬요: 그것은 다른 쪽의 기본 키 프루닝을 구동할 수 없으므로 복사하는 것이 작업만 추가할 뿐이에요. query_plan_enable_optimizations가 1일 때만 효과가 있어요.

query_plan_push_down_limit

LIMIT를 실행 플랜에서 아래로 이동하는 쿼리 플랜 수준 최적화를 토글해요. query_plan_enable_optimizations 설정이 1일 때만 효과가 있어요. 이것은 개발자가 디버깅 목적으로만 사용해야 하는 전문가용 설정이에요. 이 설정은 향후 하위 호환되지 않는 방식으로 바뀌거나 제거될 수 있어요. 가능한 값:

0 - 비활성화
1 - 활성화

query_plan_push_down_volume_reducing_functions

부피 축소 함수(length, lengthUTF8, empty, notEmpty)를 실행 플랜에서 아래로, Sorting과 Filter 단계 아래로 이동하는 쿼리 플랜 수준 최적화를 토글해요. 고정 크기 결과가 넓은 String/FixedString 인자를 대체하므로 인자가 더 이상 그 단계를 통해 전달되지 않아요. 재작성은 인자 컬럼이 그것이 내려지는 단계 위에서 필요하지 않을 때만 적용돼요. query_plan_enable_optimizations 설정이 1일 때만 효과가 있어요. 가능한 값:

0 - 비활성화
1 - 활성화

query_plan_push_limit_by_into_sort

ORDER BY ... LIMIT BY 쿼리를 위한 쿼리 플랜 수준 최적화를 토글해요. LIMIT BY 컬럼이 ORDER BY 절의 접두사일 때, 각 병렬 정렬 스트림이 하나로 병합되기 전에 LIMIT BY를 적용하여 최종 병합과 이후 파이프라인 단계에서 처리되는 행을 줄여요. LIMIT BY가 행의 큰 비율을 버리는 쿼리를 빠르게 해요. query_plan_enable_optimizations 설정이 1일 때만 효과가 있어요. 가능한 값:

0 - 비활성화
1 - 활성화

query_plan_read_in_order

순서대로 읽기(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_short_circuit_constant_false_join

ON 조건이 상수 false로 접히는 JOIN을 단락 회로 처리해요. 행에 기여할 수 없는 각 입력 쪽(INNER/CROSS/SEMI의 양쪽, LEFT/RIGHT의 보존되지 않은 쪽)을 빈 소스로 대체하여 기여하지 않는 쪽을 읽지 않도록 해요. 비분산 플랜에 적용돼요.

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_plan_* 세션 설정