max(최대) 관련 설정

쿼리 실행의 다양한 측면을 제한하는 max_* 설정들을 모아둔 문서예요. 블록 크기, 읽을 컬럼·행·바이트 수, 스레드 수, 파싱 깊이, 세션 수 등 쿼리 처리 전반의 여러 한도를 다룬답니다. 이 설정들은 system.settings 테이블에서 확인할 수 있고 소스 코드에서 자동 생성된 값들이에요.

출처: 문서

본문

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

max_analyze_depth

인터프리터가 수행하는 분석의 최대 횟수예요.

max_autoincrement_series

generateSerialID 함수가 만드는 시리즈 수의 제한이에요. 각 시리즈는 Keeper의 노드를 나타내므로 보통 수백만 개 이하로 유지하는 것이 권장돼요.

max_backup_bandwidth

서버에서 특정 백업의 초당 최대 읽기 속도(바이트)예요. 0은 무제한을 의미해요.

max_block_size

ClickHouse에서 데이터는 컬럼 파트의 집합인 블록으로 처리돼요. 단일 블록의 내부 처리 주기는 효율적이지만 각 블록을 처리할 때 눈에 띄는 비용이 있어요.

max_block_size 설정은 테이블에서 데이터를 로드할 때 단일 블록에 포함할 권장 최대 행 수를 나타내요. max_block_size 크기의 블록이 항상 테이블에서 로드되지는 않아요. ClickHouse가 검색할 데이터가 더 적다고 판단하면 더 작은 블록이 처리돼요.

블록 크기는 각 블록을 처리할 때의 눈에 띄는 비용을 피하기 위해 너무 작지 않아야 하고, LIMIT 절이 있는 쿼리가 첫 번째 블록을 처리한 후 빠르게 실행되도록 너무 크지도 않아야 해요. max_block_size를 설정할 때 목표는 여러 스레드에서 많은 수의 컬럼을 추출할 때 너무 많은 메모리를 소비하지 않고 최소한의 캐시 지역성을 보존하는 것이어야 해요.

max_columns_to_read

단일 쿼리에서 테이블에서 읽을 수 있는 최대 컬럼 수예요. 쿼리가 지정된 수보다 많은 컬럼을 읽어야 하면 예외가 발생해요.

이 설정은 과도하게 복잡한 쿼리를 방지하는 데 유용해요.

0 값은 무제한을 의미해요.

max_compress_block_size

테이블에 쓰기 전 압축되는 무압축 데이터 블록의 최대 크기예요. 기본값은 1,048,576(1 MiB)이에요. 더 작은 블록 크기를 지정하면 일반적으로 압축 비율이 약간 낮아지고, 캐시 지역성 덕분에 압축 및 압축 해제 속도가 약간 빨라지며 메모리 소비가 줄어들어요.

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

압축용 블록(바이트로 구성된 메모리 청크)과 쿼리 처리용 블록(테이블의 행 집합)을 혼동하지 마세요.

max_consume_snapshots

증분 읽기당 소비할 Paimon 스냅샷의 최대 수예요. 0은 제한 없음을 의미해요.

max_estimated_execution_time

최대 쿼리 추정 실행 시간(초)이에요. timeout_before_checking_execution_speed가 만료될 때 모든 데이터 블록에서 확인돼요.

max_expanded_ast_elements

별칭과 별표의 확장 후 쿼리 구문 트리의 노드 수로 본 최대 크기예요.

max_fetch_partition_retries_count

다른 호스트에서 파티션을 가져오는 동안의 재시도 횟수예요.

max_final_threads

FINAL 수정자가 있는 SELECT 쿼리의 데이터 읽기 단계를 위한 최대 병렬 스레드 수를 설정해요.

가능한 값:

양의 정수.
0 또는 1 — 비활성화. SELECT 쿼리가 단일 스레드로 실행돼요.

max_http_get_redirects

허용되는 HTTP GET 리디렉션 홉의 최대 수예요. 악의적인 서버가 요청을 예상치 못한 서비스로 리디렉션하는 것을 방지하는 추가 보안 조치를 보장해요.

외부 서버가 다른 주소로 리디렉션하는데 그 주소가 회사 인프라의 내부 주소로 보이고, 내부 서버에 HTTP 요청을 보냄으로써 인증을 우회하고 내부 네트워크에서 내부 API를 요청하거나 Redis나 Memcached 같은 다른 서비스를 쿼리할 수 있는 경우가 그렇죠. 내부 인프라(로컬호스트에서 실행되는 것을 포함)가 없거나 서버를 신뢰한다면 리디렉션을 허용해도 안전해요. 단, URL이 HTTPS 대신 HTTP를 사용하면 원격 서버뿐 아니라 ISP와 중간의 모든 네트워크도 신뢰해야 한다는 점을 명심하세요.

클라우드 기본값: 10.

max_limit_for_vector_search_queries

이 설정보다 큰 LIMIT가 있는 SELECT 쿼리는 벡터 유사도 인덱스를 사용할 수 없어요. 벡터 유사도 인덱스에서 메모리 오버플로를 방지하는 데 도움이 돼요.

max_os_cpu_wait_time_ratio_to_throw

쿼리를 거부할지 고려하는 OS CPU 대기(OSCPUWaitMicroseconds 메트릭)와 사용 중(OSCPUVirtualTimeMicroseconds 메트릭) 시간 사이의 최대 비율이에요. 최소·최대 비율 사이의 선형 보간을 사용해 확률을 계산하며, 이 지점에서 확률은 1이에요.

max_parallel_replicas

쿼리 실행 시 각 샤드의 최대 레플리카 수예요.

가능한 값: 양의 정수.

추가 정보

이 옵션은 사용되는 설정에 따라 다른 결과를 만들어요.

SAMPLE 키를 사용한 병렬 처리

쿼리가 여러 서버에서 병렬로 실행되면 더 빠르게 처리될 수 있어요. 하지만 다음 경우에는 쿼리 성능이 저하될 수 있어요:

파티셔닝 키에서 샘플링 키의 위치가 효율적인 범위 스캔을 허용하지 않을 때.
테이블에 샘플링 키를 추가하면 다른 컬럼에 의한 필터링이 덜 효율적일 때.
샘플링 키가 계산 비용이 비싼 표현식일 때.
클러스터 지연 분포의 꼬리가 길어서 더 많은 서버를 조회하면 쿼리 전체 지연이 증가할 때.

parallel_replicas_custom_key를 사용한 병렬 처리

이 설정은 모든 복제 테이블에 유용해요.

max_parsing_threads

병렬 파싱을 지원하는 입력 포맷에서 데이터를 파싱할 최대 스레드 수예요. 기본적으로는 자동으로 결정돼요.

max_partition_size_to_drop

쿼리 시점에 파티션을 내리는 것에 대한 제한이에요. 값 0은 제한 없이 파티션을 내릴 수 있음을 의미해요.

클라우드 기본값: 1 TB.

이 쿼리 설정은 그 서버 설정 등가물을 덮어써요. max_partition_size_to_drop 참조.

max_parts_to_move

한 쿼리에서 이동할 수 있는 파트 수를 제한해요. 0은 무제한을 의미해요.

max_projection_rows_to_use_projection_index

프로젝션 인덱스에서 읽을 행 수가 이 임계값보다 작거나 같으면 ClickHouse가 쿼리 실행 중 프로젝션 인덱스를 적용하려 해요.

max_query_size

SQL 파서가 파싱하는 쿼리 문자열의 최대 바이트 수예요. INSERT 쿼리의 VALUES 절의 데이터는 별도의 스트림 파서로 처리되며(O(1) RAM 소비) 이 제한의 영향을 받지 않아요.

max_query_size는 SQL 쿼리 안(예: SELECT now() SETTINGS max_query_size=10000)에서 설정할 수 없어요. ClickHouse가 쿼리를 파싱할 버퍼를 할당해야 하고 그 버퍼 크기가 max_query_size 설정으로 결정되며 쿼리 실행 전에 구성되어야 하기 때문이에요.

max_recursive_cte_evaluation_depth

재귀 CTE 평가 깊이의 최대 한계예요.

max_replica_delay_for_distributed_queries

분산 쿼리에 대해 지연되는 레플리카를 비활성화해요. 복제 참조. 시간(초)을 설정해요. 레플리카의 지연이 설정된 값보다 크거나 같으면 그 레플리카는 사용되지 않아요.

가능한 값:

양의 정수.
0 — 레플리카 지연이 확인되지 않아요.

0이 아닌 지연이 있는 레플리카의 사용을 방지하려면 이 파라미터를 1로 설정하세요. 복제 테이블을 가리키는 분산 테이블에서 SELECT를 수행할 때 사용돼요.

max_reverse_dictionary_lookup_cache_size_bytes

함수 dictGetKeys가 사용하는 쿼리별 역방향 딕셔너리 조회 캐시의 최대 크기(바이트)예요. 이 캐시는 같은 쿼리 내에서 딕셔너리를 다시 스캔하지 않도록 속성 값당 직렬화된 키 튜플을 저장해요. 한도에 도달하면 LRU로 항목이 퇴출돼요. 캐싱을 비활성화하려면 0으로 설정하세요.

max_sessions_for_user

ClickHouse 서버에 대한 인증된 사용자당 동시 세션의 최대 수예요.

예시:

<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 - 무한한 동시 세션 수(기본값)

max_subquery_depth

쿼리에 지정된 수보다 많은 중첩 서브쿼리가 있으면 예외를 던져요. 이는 클러스터 사용자가 지나치게 복잡한 쿼리를 작성하는 것을 보호하기 위한 안전 검사를 가능하게 해요.

max_table_size_to_drop

쿼리 시점에 테이블을 삭제하는 것에 대한 제한이에요. 값 0은 제한 없이 모든 테이블을 삭제할 수 있음을 의미해요.

클라우드 기본값: 1 TB.

이 쿼리 설정은 그 서버 설정 등가물을 덮어써요. max_table_size_to_drop 참조.

max_untracked_memory

작은 할당과 해제는 스레드 로컬 변수로 그룹화되고, 그 양(절대값)이 지정된 값보다 커질 때만 추적되거나 프로파일링돼요. 값이 'memory_profiler_step'보다 높으면 'memory_profiler_step'으로 실질적으로 낮춰져요.

max_wkb_geometry_elements

readWKB 및 관련 함수로 파싱하는 동안 단일 WKB 지오메트리 요소에 허용되는 최대 점, 링, 또는 폴리곤 수예요. 잘못된 WKB 데이터로 인한 과도한 메모리 할당을 방지해줘요. 하드 코딩된 한도(1억)를 사용하려면 0으로 설정하세요.

max(최대) 관련 설정