max_memory_usage — 쿼리 하나가 메모리를 얼마나 쓸 수 있는가
ClickHouse ARRAY JOIN 절 및 max_memory_usage/KILL QUERY 공식 문서 종합 (웹 리서치, 2026) — ClickHouse 공식 문서(sql-reference/statements/select/array-join, knowledgebase/memory-limit-exceeded-for-query) ClickHouse 공식문서 Memory limit exceeded for query
이 모듈을 다 읽으면
- max_memory_usage 초과 시 쿼리가 어떻게 종료되는지, 그리고 clickhouse-learn-35의 system.query_log와 어떻게 함께 진단하는지 설명할 수 있다
- External Aggregation(디스크 스필)이 메모리 초과를 피하는 대안이라는 것을 설명할 수 있다
clickhouse-learn-35에서 다룬 system.query_log(이미 끝난 쿼리의 사후 이력)와 대비해, 지금 실행 '중인' 쿼리의 메모리 사용량을 감시·제한하고 필요하면 강제 종료하는 런타임 자원 통제 메커니즘을 정리한다.
max_memory_usage — 쿼리 하나의 메모리 상한(기본 10GB)
max_memory_usage는 쿼리 하나가 쓸 수 있는 최대 메모리를 제한하는 설정으로, 기본값은 10GB다(사용자 전체 기준으로는 max_memory_usage_for_user로 별도 제한 가능). 이 한도를 넘으면 ClickHouse는 예외를 던지고 그 쿼리를 즉시 취소한다 — 서버 전체가 메모리 부족(OOM)으로 죽는 것보다, 문제가 된 쿼리 하나만 깔끔하게 실패시키는 게 낫다는 설계 철학이다.
핵심 포인트
- max_memory_usage(기본 10GB): 쿼리 하나의 최대 메모리 사용량 — 넘으면 예외를 던지고 그 쿼리를 즉시 취소
- max_memory_usage_for_user로 사용자 전체 기준 별도 상한도 설정 가능 — 서버 전체 OOM보다 문제 쿼리 하나만 깔끔히 실패시키는 설계
실행 중인 쿼리 감시와 강제 종료 — system.processes와 KILL QUERY
clickhouse-learn-35의 system.query_log가 이미 끝난 쿼리의 사후 기록이라면, system.processes는 지금 실행 '중인' 쿼리의 실시간 상태(memory_usage, elapsed 등)를 보여준다 — 예를 들어 memory_usage가 5GB를 넘는 쿼리를 실시간으로 찾아낼 수 있다. 특정 쿼리를 강제로 끝내고 싶으면 KILL QUERY WHERE query_id = '...' 로 개별 종료할 수도 있고, KILL QUERY WHERE user = '...' 로 특정 사용자의 모든 쿼리를 한 번에 종료할 수도 있다.
핵심 포인트
- system.query_log(module35, 사후 이력)와 대비되는 system.processes(실행 중인 쿼리의 실시간 memory_usage·elapsed 등)
- KILL QUERY WHERE query_id='...'(개별 종료) 또는 WHERE user='...'(특정 사용자의 모든 쿼리 종료)로 실행 중인 쿼리를 강제로 끝낼 수 있음
메모리 초과를 피하는 대안 — External Aggregation으로 디스크에 스필
메모리 한도에 자주 부딪히는 무거운 집계·정렬 쿼리라면, max_bytes_before_external_group_by/max_bytes_before_external_sort 설정으로 대응할 수 있다 — 이 임계값을 넘으면 ClickHouse가 그 연산을 메모리 대신 디스크로 흘려보내(spill) 처리를 계속한다. 즉 쿼리가 실패하는 대신 느려지는 쪽을 택하는 트레이드오프다. 이 외에도 memory_overcommit_ratio_denominator를 0이 아닌 값으로 설정하면(실험적 기능) 쿼리가 일시적으로 한도를 넘는 걸 허용하되, 전체 서버 메모리 압박이 심해지면 초과 비율이 가장 큰 쿼리부터 죽이는 방식으로 동작한다.
핵심 포인트
- max_bytes_before_external_group_by/max_bytes_before_external_sort: 임계값 초과 시 집계·정렬을 메모리 대신 디스크로 스필 — 실패 대신 느려지는 트레이드오프
- memory_overcommit_ratio_denominator(실험적): 일시적 한도 초과를 허용하되 전체 메모리 압박 시 초과 비율이 가장 큰 쿼리부터 종료