Skip to main content
이 설정은 system.settings에서 확인할 수 있으며, 소스 코드에서 자동으로 생성됩니다.

max_analyze_depth

인터프리터가 수행할 수 있는 최대 분석 횟수입니다.

max_autoincrement_series

generateSerialID 함수로 생성할 수 있는 series 수의 한도입니다. 각 series는 Keeper의 node를 나타내므로, 그 수는 최대 수백만 개를 넘지 않도록 유지하는 것이 좋습니다.

max_backup_bandwidth

server의 특정 Backup에 대한 초당 최대 읽기 속도(바이트 단위)입니다. 0은 무제한을 의미합니다.

max_block_size

ClickHouse에서는 데이터를 블록 단위로 처리하며, 블록은 컬럼 파트의 집합입니다. 단일 블록에 대한 내부 처리 과정은 효율적이지만, 각 블록을 처리할 때마다 무시할 수 없는 비용이 발생합니다. max_block_size 설정은 테이블에서 데이터를 로드할 때 단일 블록에 포함할 권장 최대 행 수를 나타냅니다. 항상 max_block_size 크기의 블록을 테이블에서 로드하는 것은 아닙니다. ClickHouse가 더 적은 데이터만 가져오면 된다고 판단하면 더 작은 블록을 처리합니다. 블록 크기는 각 블록 처리 시 발생하는 비용이 두드러지지 않도록 너무 작아서는 안 됩니다. 또한 LIMIT 절이 있는 쿼리가 첫 번째 블록을 처리한 후 빠르게 실행될 수 있도록 너무 커서도 안 됩니다. max_block_size를 설정할 때는 여러 스레드에서 많은 컬럼을 추출할 때 메모리를 과도하게 사용하지 않도록 하고, 최소한의 캐시 지역성(cache locality)은 유지하는 것을 목표로 해야 합니다.

max_columns_to_read

단일 쿼리에서 테이블로부터 읽을 수 있는 최대 컬럼 수입니다. 쿼리가 지정된 수보다 많은 컬럼을 읽어야 하면 예외가 발생합니다.
이 설정은 지나치게 복잡한 쿼리를 방지하는 데 유용합니다.
0은 제한 없음을 의미합니다.

max_compress_block_size

테이블에 쓰기 위해 압축하기 전에, 압축되지 않은 데이터 블록의 최대 크기입니다. 기본값은 1,048,576(1 MiB)입니다. 더 작은 블록 크기를 지정하면 일반적으로 압축률은 약간 낮아지지만, 캐시 지역성(cache locality) 덕분에 압축 및 압축 해제 속도는 약간 향상되고 메모리 사용량은 줄어듭니다.
이 설정은 전문가 수준의 설정이므로 ClickHouse를 이제 막 시작하는 단계라면 변경하지 않는 것이 좋습니다.
압축용 블록(바이트로 구성된 메모리 청크)과 쿼리 처리용 블록(테이블의 행 집합)을 혼동하지 마십시오.

max_consume_snapshots

증분 읽기에서 소비할 Paimon 스냅샷의 최대 개수입니다. 0은 제한이 없음을 의미합니다.

max_estimated_execution_time

초 단위의 최대 쿼리 예상 실행 시간입니다. timeout_before_checking_execution_speed 만료 시마다 각 데이터 블록에서 확인합니다.

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이는 외부 서버가 다른 주소로 리디렉션했는데, 그 주소가 회사 내부 인프라에 속한 것처럼 보이는 경우를 말합니다. 이때 내부 서버로 HTTP 요청을 보내면 인증을 우회해 내부 네트워크의 내부 API를 요청하거나 Redis 또는 Memcached 같은 다른 서비스에 쿼리를 보낼 수도 있습니다. 내부 인프라(localhost에서 실행 중인 항목 포함)가 없거나 해당 서버를 신뢰할 수 있다면 리디렉션을 허용해도 안전합니다. 다만 URL이 HTTPS 대신 HTTP를 사용한다면 원격 서버뿐 아니라 ISP와 그 사이의 모든 네트워크도 신뢰해야 한다는 점에 유의해야 합니다. Cloud 기본값: 10.

max_limit_for_vector_search_queries

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

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를 사용한 병렬 처리

이 설정은 모든 복제된 테이블에 유용합니다.

max_parsing_threads

병렬 파싱을 지원하는 입력 형식에서 데이터를 파싱하는 데 사용할 수 있는 최대 스레드 수입니다. 기본적으로 자동으로 결정됩니다.

max_partition_size_to_drop

쿼리 시점에 파티션을 삭제할 때 적용되는 제한입니다. 값 0은 제한 없이 파티션을 삭제할 수 있음을 의미합니다. Cloud 기본값: 1 TB.
이 쿼리 설정은 해당 서버 설정을 재정의합니다. max_partition_size_to_drop를 참조하십시오.

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 사용)로 처리되므로 이 제한의 영향을 받지 않습니다.
ClickHouse는 쿼리를 구문 분석하기 위해 buffer를 할당해야 하며, 이 buffer 크기는 max_query_size 설정으로 결정됩니다. 따라서 이 설정은 쿼리가 실행되기 전에 미리 구성되어 있어야 하므로 max_query_size는 SQL 쿼리 내에서 설정할 수 없습니다(예: SELECT now() SETTINGS max_query_size=10000).

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 서버에서 인증된 사용자 1명당 동시에 사용할 수 있는 최대 session 수입니다. 예시:
가능한 값:
  • 양의 정수
  • 0 - 동시 세션 수가 무제한(기본값)

max_subquery_depth

쿼리에 지정된 개수를 초과하는 중첩된 서브쿼리가 있으면 예외가 발생합니다.
이 설정을 사용하면 클러스터 사용자로부터 지나치게 복잡한 쿼리가 작성되는 것을 방지하는 안전 점검 장치로 활용할 수 있습니다.

max_table_size_to_drop

쿼리 시점에 테이블을 삭제할 때 적용되는 제한입니다. 값 0은 아무런 제한 없이 모든 테이블을 삭제할 수 있음을 의미합니다. Cloud 기본값: 1 TB.
이 쿼리 설정은 해당 서버 설정 값을 덮어씁니다. 자세한 내용은 max_table_size_to_drop를 참조하십시오.

max_untracked_memory

작은 메모리 할당 및 해제는 스레드 로컬 변수에 묶여 저장되며, 그 크기(절댓값 기준)가 지정된 값보다 커질 때만 추적되거나 프로파일링됩니다. 이 값이 ‘memory_profiler_step’보다 크면 실제로는 ‘memory_profiler_step’으로 낮춰집니다.

max_wkb_geometry_elements

readWKB 및 관련 함수가 파싱하는 동안 단일 WKB geometry 원소에 허용되는 Point, Ring 또는 다각형의 최대 개수입니다. 이 설정은 잘못된 WKB 데이터로 인한 과도한 메모리 할당을 방지합니다. 하드코딩된 제한값(1억)을 사용하려면 0으로 설정하십시오.
마지막 수정일 2026년 7월 24일