max_* 서버 설정

max_* 서버 설정

이 페이지에서는, 데이터 파트 로딩 스레드, 연결 수, 백업/병합/mutation 대역폭, 메모리 한도 등 다양한 최대값을 제어하는 max_* 계열 서버 설정을 설명할게요.

출처: 문서

본문

이 설정들은 ClickHouse 서버를 구성하며, ClickHouse 소스에서 자동으로 생성돼요.

max_active_parts_loading_thread_pool_size

시작 시 활성(Active) 데이터 파트 집합을 로드하는 데 사용되는 스레드 수예요.

max_authentication_methods_per_user

사용자를 만들거나 수정할 때 가질 수 있는 최대 인증 방법 수예요. 이 설정을 변경해도 기존 사용자에게는 영향을 주지 않아요. 인증 관련 create/alter 쿼리는 이 설정에 지정된 한도를 초과하면 실패해요. 인증과 무관한 create/alter 쿼리는 성공해요. 값 0은 무제한을 의미해요.

max_backup_bandwidth_for_server

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

max_build_vector_similarity_index_thread_pool_size

벡터 인덱스를 구축하는 데 사용되는 최대 스레드 수예요. 값 0은 모든 코어를 의미해요.

max_connections

최대 서버 연결 수예요.

max_entries_for_hash_table_stats

집계 중 수집되는 해시 테이블 통계가 가질 수 있는 엔트리 수예요.

max_fetch_partition_thread_pool_size

ALTER TABLE FETCH PARTITION용 스레드 수예요.

max_held_snapshots

동시에 보유할 수 있는 최대 경량 스냅샷 수예요. 0은 무제한을 의미해요. 스냅샷 수가 이 한도에 도달하면 새 스냅샷을 만들려고 할 때 예외가 발생해요.

max_http_index_page_size

HTTP를 통한 디렉터리 목록에 사용되는 HTTP 인덱스 페이지 응답의 최대 크기예요. 응답이 이 한도를 초과하면 쿼리가 오류로 실패해요. 기본값: 10485760 (10 MiB).

max_iceberg_manifest_decode_thread_pool_free_size

Iceberg 데이터 manifest 파일을 디코딩하는 스레드풀에 유지할 유휴 대기 스레드의 최대 수예요.

max_iceberg_manifest_decode_thread_pool_size

Iceberg 데이터 manifest 파일을 디코딩하는 데 사용되는 최대 총 스레드 수예요. 이 풀은 의도적으로 IO 풀과 분리되어 있어요: 디코드 작업은 쿼리가 생성한 엔트리를 소비할 때까지 블로킹할 수 있는 반면, delete manifest 디코드는 어떤 엔트리도 소비되기 전에 IO 풀에서 자체 작업을 기다리므로, 풀을 공유하면 교착 상태(deadlock)가 발생할 수 있어요.

max_keep_alive_requests

ClickHouse 서버가 닫을 때까지 단일 keep-alive 연결을 통해 처리되는 최대 요청 수예요.

예시

<max_keep_alive_requests>10</max_keep_alive_requests>

max_materialized_views_count_for_table

테이블에 연결된 materialized view 수의 한도예요. 여기서는 직접 의존하는 뷰만 고려하며, 다른 뷰 위에 뷰를 만드는 것은 고려하지 않아요.

max_merges_bandwidth_for_server

서버의 모든 병합의 최대 읽기 속도(초당 바이트)예요. 0은 무제한을 의미해요.

max_mutations_bandwidth_for_server

서버의 모든 mutation의 최대 읽기 속도(초당 바이트)예요. 0은 무제한을 의미해요.

max_open_files

최대 열린 파일 수예요. getrlimit() 함수가 잘못된 값을 반환하므로 macOS에서는 이 옵션을 사용하는 것을 권장해요.

max_os_cpu_wait_time_ratio_to_drop_connection

연결을 끊을지 고려하는 OS CPU 대기(OSCPUWaitMicroseconds 메트릭)와 사용 중(OSCPUVirtualTimeMicroseconds 메트릭) 시간 사이의 최대 비율이에요. 최소 비율과 최대 비율 사이의 선형 보간으로 확률을 계산하며, 이 시점에서 확률은 1이에요. 자세한 내용은 Controlling behavior on server CPU overload를 참고하세요.

max_outdated_parts_loading_thread_pool_size

시작 시 비활성 데이터 파트 집합(Outdated)을 로드하는 데 사용되는 스레드 수예요.

max_part_num_to_warn

활성 파트 수가 지정된 값을 초과하면 clickhouse 서버가 system.warnings 테이블에 경고 메시지를 추가해요.

예시

<max_part_num_to_warn>400</max_part_num_to_warn>

max_partition_size_to_drop

파티션 드롭에 대한 제한이에요. MergeTree 테이블의 크기가 max_partition_size_to_drop(바이트)를 초과하면 DROP PARTITION 쿼리로 파티션을 드롭할 수 없어요. 이 설정은 ClickHouse 서버 재시작 없이 적용돼요. 제한을 비활성화하는 또 다른 방법은 <clickhouse-path>/flags/force_drop_table 파일을 만드는 것이에요. 값 0은 제한 없이 파티션을 드롭할 수 있다는 뜻이에요. 이 제한은 drop table과 truncate table은 제한하지 않아요 (max_table_size_to_drop 참고).

예시

<max_partition_size_to_drop>0</max_partition_size_to_drop>

max_parts_cleaning_thread_pool_size

비활성 데이터 파트의 동시 제거용 스레드 수예요.

max_per_cpu_untracked_memory

한 CPU에서 실행되는 모든 스레드가 메모리 트래커로 플러시되기 전에 동시에 보유할 수 있는 미추적(untracked) 메모리의 상한(바이트)이에요. max_untracked_memory가 단일 스레드를 제한하는 반면, 이 설정은 CPU별 총합을 제한하므로 많은 스레드가 자신의 스레드당 허용량을 곱해서 서버 전체에 큰 과다 약정(overcommit)을 만들 수 없어요. 따라서 총 미추적 메모리는 대략 number_of_cpus * max_per_cpu_untracked_memory로 제한돼요. 값 0은 CPU별 제한을 비활성화해요 (스레드당 max_untracked_memory만 적용돼요). Linux 전용이에요.

max_session_timeout

최대 세션 타임아웃(초)이에요.

예시:

<max_session_timeout>3600</max_session_timeout>

max_temporary_data_on_disk_size

외부 집계, 조인 또는 정렬에 사용할 수 있는 스토리지의 최대 양이에요. 이 한도를 초과하는 쿼리는 예외로 실패해요. 값 0은 무제한을 의미해요.

참고:

max_unexpected_parts_loading_thread_pool_size

시작 시 비활성 데이터 파트 집합(Unexpected)을 로드하는 데 사용되는 스레드 수예요.

max_waiting_queries

동시에 대기 중인 쿼리의 총 개수에 대한 한도예요. 대기 중인 쿼리는 필요한 테이블이 비동기적으로 로드되는 동안(```async_load_databases`](/docs/reference/settings/server-settings/settings/async-load#async_load_databases 참고) 실행이 차단돼요. 대기 중인 쿼리는 다음 설정이 제어하는 한도를 확인할 때 집계되지 않아요:

이 보정은 서버 시작 직후에 이러한 한도에 도달하는 것을 피하기 위한 것이에요. 값 0(기본값)은 무제한을 의미해요. 이 설정은 런타임에 수정할 수 있으며 즉시 적용돼요. 이미 실행 중인 쿼리는 변경되지 않고 유지돼요.

max_zookeeper_pooled_connections

공유 풀의 ZooKeeper 클러스터당 지연 초기화되는 ZooKeeper 세션의 최대 수예요. 값 0은 풀링된 연결을 비활성화하고 단일 세션을 계속 사용해요.

더 알아보기 (Learn more)