use_* 세션 설정

use_* 세션 설정 (기타 사용 최적화)

이 페이지에서는 use_로 시작하는 다양한 세션 설정들을 다뤄요. 머티리얼라이즈드 뷰 실행, 캐시 사용, 동시성 제어, 인덱스 분석, 조인 재정렬, 헤지드 요청, 파티션 감지 등 다양한 동작을 제어해요. 이 설정들은 system.settings 테이블에서 확인할 수 있으며 ClickHouse 소스에서 자동 생성돼요.

출처: 문서

본문

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

use_async_executor_for_materialized_views

머티리얼라이즈드 뷰 쿼리의 비동기 및 잠재적으로 멀티스레드 실행을 사용해요. INSERT 중 뷰 처리를 빠르게 할 수 있지만 메모리를 더 소비해요.

use_cache_for_count_from_files

file/s3/url/hdfs/azureBlobStorage 테이블 함수에서 파일의 행 수를 세는 동안 행 수를 캐시하는 것을 활성화해요. 기본적으로 활성화돼요.

use_client_time_zone

서버 시간대를 채택하는 대신 DateTime 문자열 값을 해석할 때 클라이언트 시간대를 사용해요.

use_compact_format_in_distributed_parts_names

Distributed 엔진의 테이블에 대한 백그라운드(distributed_foreground_insert) INSERT에서 블록 저장에 컴팩트 형식을 사용해요. 가능한 값:

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 글로벌 서버 설정 참고). 비활성화하면 서버가 과부하된 경우에도 더 많은 수의 스레드를 사용할 수 있게 해요(일반 사용에는 권장되지 않으며 주로 테스트에 필요).

use_constant_folding_in_index_analysis

파트별 기본 키와 스킵 인덱스를 분석할 때 필터 조건에 파티션 수준 상수를 대입해요. 파티션 키가 기본 키 또는 스킵 인덱스 컬럼과 함께 필터에 나타나면, 인덱스 분석이 각 파트 내에서 파티션 값을 별도로 접을 수 있게 해줘요. 서로 다른 파티션을 대상으로 하는 분기의 접속(disjunctive) 필터에 가장 유용해요. 예를 들어 PARTITION BY a와 ORDER BY b가 있으면:

SELECT * FROM t WHERE (a = 1 AND b >= 1) OR (a = 2 AND b > 10) OR (a = 3 AND b > 10)

파티션 a = 1의 파트에서는 조건이 b >= 1로 접히고, 파티션 a = 2와 a = 3에서는 b > 10으로 접히므로, 각 파트는 실제로 적용되는 조건으로 분석돼요. 가능한 값:

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

use_hash_table_stats_for_join_reordering

조인 재정렬 중 기수 추정에 수집된 해시 테이블 통계를 사용할 수 있게 해요.

use_hedged_requests

원격 쿼리에 대한 hedged requests 로직을 활성화해요. 쿼리에 대해 서로 다른 레플리카와의 여러 연결을 수립할 수 있게 해줘요. 기존 레플리카 연결이 hedged_connection_timeout 내에 수립되지 않았거나 receive_data_timeout 내에 데이터가 수신되지 않으면 새 연결이 활성화돼요. 쿼리는 첫 번째로 비어 있지 않은 진행 상황 패킷(또는 allow_changing_replica_until_first_data_packet이면 데이터 패킷)을 보내는 연결을 사용하고, 다른 연결은 취소돼요. max_parallel_replicas > 1인 쿼리가 지원돼요. 기본적으로 활성화돼요. Cloud 기본값: 0.

use_hive_partitioning

활성화하면 ClickHouse가 File/S3/URL/HDFS/AzureBlobStorage 파일형 테이블 엔진의 경로(/name=value/)에서 Hive 스타일 파티셔닝을 감지하고, 파티션 컬럼을 쿼리의 가상 컬럼으로 사용할 수 있게 해요. 이 가상 컬럼은 파티션 경로와 같은 이름을 가지며 _로 시작해요.

use_indexes_refiner_in_read_pools

데이터 읽기 시 평가된 인덱스를 MergeTree 읽기 풀 내부에서 이미 적용해요: 스킵 인덱스(use_skip_indexes_on_data_read 참고) 또는 프로젝션 인덱스(optimize_use_projection_filtering 참고)에 의해 완전히 필터링된 마크 범위는 읽는 동안 granule별로 건너뛰는 대신 읽기 태스크가 생성되기 전에 버려져요. 프리페치된 읽기 풀에서는 버려진 범위가 결코 프리페치되지 않지만, 태스크 경계와 filesystem_prefetch_max_memory_usage/filesystem_prefetches_limit의 프리페치 허용은 필터링 전에 결정되므로, 선택성이 매우 높은 필터 아래에서는 살아남는 태스크가 의도된 태스크 크기보다 작아지고 허용이 보수적일 수 있어요.

use_join_disjunctions_push_down

JOIN 조건의 OR로 연결된 부분을 대응하는 입력 쪽으로 내리는 것("부분 푸시다운")을 활성화해요. 이를 통해 스토리지 엔진이 더 일찍 필터링할 수 있어 데이터 읽기가 줄어들 수 있어요. 이 최적화는 의미를 보존하며, 각 최상위 OR 분기가 대상 쪽에 최소 하나의 결정적 조건을 기여할 때만 적용돼요.

use_legacy_to_time

활성화하면 toTime 이름이 기존 toTime 함수를 가리키며, 이 함수는 날짜가 있는 시간을 특정 고정 날짜로 변환하면서 시간은 보존해요. 그렇지 않으면 이름이 서로 다른 타입의 값을 Time 타입으로 변환하는 새 toTime 함수를 가리켜요. 기존 함수는 이 설정과 무관하게 toTimeWithFixedDate로도 무조건 접근할 수 있어요. 이 설정이 활성화된 동안에는 CAST(x AS Time) 또는 x::Time을 사용해 Time 타입으로 변환해요.

use_lightweight_primary_key_index_analysis

긴 기본 키를 가진 MergeTree 테이블의 기본 키 인덱스 분석을 최적화해요. 활성화하면 인덱스 분석의 실행 시간은 주로 쿼리 필터의 복잡성(실제로 사용하는 키 컬럼)에 의존하며 기본 키의 길이에는 의존하지 않아요 — 따라서 정렬 키를 확장하는 것은 몇 개의 컬럼만 필터링하는 쿼리에 대해 인덱스 분석에 무시할 만한 추가 오버헤드만 발생시켜요. 가능한 값:

0 — 비활성화. 모든 기본 키 컬럼이 인덱스 분석 중 처리돼요.
1 — 활성화.

use_parquet_metadata_cache

켜면 parquet 형식이 parquet 메타데이터 캐시를 활용할 수 있어요. 가능한 값:

0 - 비활성화.
1 - 활성화.

use_primary_key

MergeTree 테이블의 쿼리 실행 중 granule을 프루닝하기 위해 기본 키를 사용해요. 가능한 값:

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

use_reader_executor

실험적. 읽기를 기존의 읽기 버퍼 matryoshka 대신 새 파이프라인 ReaderExecutor를 통해 라우팅해요. 실행자가 아직 지원하지 않는 구성에 대해서는 기존 경로로 폴백해요.

use_roaring_bitmap_iceberg_positional_deletes

iceberg 위치 삭제에 roaring bitmap을 사용해요.

use_streaming_marks_compression

MergeTree 파츠의 마크를 로드할 때, 전체 일반 마크 배열을 먼저 구체화하는 대신 한 번에 한 블록씩(스트리밍) 압축해 메모리 표현으로 만들어요. 이는 많은 서브스트림이 있는 컴팩트 파츠(예: JSON 컬럼과 write_marks_for_substreams_in_compact_parts가 활성화된 테이블)에 대해 마크 로딩 중 최고 메모리 사용량을 크게 줄여줘요.

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 중 하나 도달.

비활성화하면 블록은 다음 때 내보내져요:

최소 임계값(OR): min_insert_block_size_rows OR min_insert_block_size_bytes 중 하나 도달.

참고: 최대 설정이 최소 설정보다 작으면 최대 제한이 우선하며, 최소 임계값에 도달하기 전에 블록이 내보내져요. 참고: 비동기 삽입의 경우 엄격한 제한 적용에 필요한 블록 분할과 호환되지 않는 항목별 중복 제거 토큰이 붙기 때문에 이 설정은 자동으로 비활성화돼요. 기본적으로 비활성화돼요.

use_structure_from_insertion_table_in_table_functions

데이터에서 스키마 추론 대신 삽입 테이블의 구조를 사용해요. 가능한 값: 0 - 비활성화, 1 - 활성화, 2 - 자동.

use_uncompressed_cache

압축되지 않은 블록 캐시를 사용할지 여부예요. 0 또는 1을 받아요. 기본값은 0(비활성화)이에요. 압축되지 않은 캐시(MergeTree 계열 테이블에만 해당)를 사용하면 많은 수의 짧은 쿼리를 처리할 때 지연을 크게 줄이고 처리량을 높일 수 있어요. 빈번한 짧은 요청을 보내는 사용자에 대해 이 설정을 활성화해요. 또한 config 파일에만 설정되는 uncompressed_cache_size 구성 매개변수(압축되지 않은 캐시 블록의 크기)에 주의하세요. 기본값은 8 GiB예요. 압축되지 않은 캐시는 필요에 따라 채워지고 가장 적게 사용된 데이터는 자동으로 삭제돼요. 상당히 많은 양의 데이터(백만 행 이상)를 읽는 쿼리의 경우, 진짜 작은 쿼리를 위한 공간을 절약하기 위해 압축되지 않은 캐시가 자동으로 비활성화돼요. 따라서 use_uncompressed_cache 설정을 항상 1로 유지할 수 있어요.

use_with_fill_by_sorting_prefix

ORDER BY 절에서 WITH FILL 컬럼 앞에 오는 컬럼이 정렬 접두사를 이뤄요. 정렬 접두사 값이 서로 다른 행은 독립적으로 채워져요.

use_* 세션 설정