> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# max_bytes_* 세션 설정

> max_bytes_* 자동 생성 그룹의 ClickHouse 세션 설정입니다.

이 설정들은 [system.settings](https://clickhouse.com/docs/ko/reference/system-tables/settings.md)에서 확인할 수 있으며 [소스 코드](https://github.com/ClickHouse/ClickHouse/blob/master/src/Core/Settings.cpp)를 바탕으로 자동 생성됩니다.

## max\_bytes\_before\_external\_distinct

유형

UInt64

기본값

0

`DISTINCT` 데이터를 디스크로 스필하는 기준이 되는 쿼리 메모리 임계값(바이트 단위)입니다. 실제 메모리 사용량은 이 임계값을 초과할 수 있습니다.

`0`으로 지정하면 이 임계값이 비활성화됩니다. `max_bytes_ratio_before_external_distinct`에도 임계값이 지정되어 있으면 둘 중 더 작은 값이 사용됩니다. 스필을 비활성화하려면 두 설정을 모두 `0`으로 지정하십시오.

[외부 메모리에서의 DISTINCT](https://clickhouse.com/docs/ko/reference/statements/select/distinct.md#distinct-in-external-memory)를 참고하십시오.

## max\_bytes\_before\_external\_group\_by

유형

UInt64

기본값

0

Cloud 기본값: 레플리카당 메모리 용량의 절반입니다.

외부 메모리에서 `GROUP BY` 절을 실행할지 여부를 설정합니다.
([외부 메모리에서의 GROUP BY](https://clickhouse.com/docs/ko/reference/statements/select/group-by.md#group-by-in-external-memory) 참조)

가능한 값:

* 단일 [GROUP BY](https://clickhouse.com/docs/ko/reference/statements/select/group-by.md) 작업에 사용할 수 있는 최대 RAM 용량(바이트)입니다.
* `0` — 외부 메모리에서 `GROUP BY`를 실행하지 않습니다.

> [!NOTE]
>
> GROUP BY 작업 중 메모리 사용량이 이 바이트 단위 임계값을 초과하면
> '외부 집계(external aggregation)' 모드가 활성화됩니다(중간 데이터를 디스크에 스필).
>
> 권장 값은 사용 가능한 시스템 메모리의 절반입니다.

## max\_bytes\_before\_external\_join

유형

UInt64

기본값

0

0이 아닌 값으로 설정하고 `join_algorithm`이 `hash`, `parallel_hash`, `default` 또는 `auto`이면, 오른쪽 데이터가 이 바이트 수를 초과할 때 디스크로 스필할 수 있도록 해시 조인이 자동으로 grace hash join으로 변환됩니다. `max_bytes_ratio_before_external_join`과 함께, 이 설정은 `grace_hash`를 포함한 모든 해시 기반 `join_algorithm`에 대한 임계값 기반 스필 트리거이며, `grace_hash`는 둘 중 하나가 0이 아니어야 합니다. 0이 아닌 임계값으로 조인이 스필 가능한 상태가 되면, `enable_adaptive_memory_spill_scheduler`가 임계값에 도달하기 전에도 메모리 압박 상황에서 스필을 강제할 수 있습니다. `0`(기본값)으로 설정하면 이 절대 바이트 임계값은 비활성화되지만, `max_bytes_ratio_before_external_join`(기본값 `0.5`)을 통해 자동 스필이 계속 발생할 수 있습니다. 두 설정이 모두 `0`이면 조인은 절대 스필하지 않으므로 스케줄러가 트리거할 대상이 없습니다. 예외는 `legacy_join_size_limits_trigger_spilling`으로, 이 설정이 켜져 있으면 독립형 `grace_hash`는 두 설정을 모두 무시하고 대신 `max_rows_in_join` / `max_bytes_in_join`을 기준으로 스필합니다. 이 설정을 사용하면 조인을 통한 read in order 최적화는 적용되지 않습니다. 이 임계값은 `join_algorithm`의 설정값과 관계없이 [블록 중첩 루프 조인(block nested loop join)](https://clickhouse.com/docs/ko/reference/statements/select/join.md#join-with-an-arbitrary-on-condition)이 구체화하는 오른쪽 데이터의 크기도 제한합니다.

## max\_bytes\_before\_external\_set

유형

UInt64

기본값

0

서브쿼리를 사용하는 `IN`의 집합(set)을 생성하는 동안 또는 쿼리에서 해당 집합을 사용하는 동안 집합을 디스크로 스필하는 기준이 되는
쿼리 메모리 임계값(바이트 단위)입니다. 실제 메모리 사용량(memory usage)은 이 임계값을 초과할 수 있습니다. 이 임계값과 16 MiB 중
더 작은 값보다 메모리를 적게 차지하는 집합은 메모리에 그대로 유지됩니다.

`0`으로 지정하면 이 임계값을 비활성화합니다. `max_bytes_ratio_before_external_set`에서도 임계값이 지정된 경우
둘 중 더 작은 값이 사용됩니다. 스필을 비활성화하려면 두 설정을 모두 `0`으로 지정하십시오.

자세한 내용은 [외부 메모리에서의 IN](https://clickhouse.com/docs/ko/reference/statements/in.md#in-in-external-memory)을 참조하십시오.

## max\_bytes\_before\_external\_sort

유형

UInt64

기본값

0

Cloud 기본값: 레플리카당 메모리 용량의 절반입니다.

`ORDER BY` 절을 외부 메모리를 사용해 실행할지 여부를 설정합니다. [ORDER BY 구현 세부 사항](https://clickhouse.com/docs/ko/reference/statements/select/order-by.md#implementation-details)을 참조하십시오.
`ORDER BY` 작업 중 메모리 사용량이 바이트 단위의 이 임계값을 초과하면 "외부 정렬" 모드(중간 데이터를 디스크에 스필)가 활성화됩니다.

가능한 값:

* 단일 [ORDER BY](https://clickhouse.com/docs/ko/reference/statements/select/order-by.md) 작업에 사용할 수 있는 최대 RAM 용량(바이트)입니다.
  권장 값은 사용 가능한 시스템 메모리의 절반입니다.
* `0` — 외부 메모리를 사용하는 `ORDER BY`가 비활성화됩니다.

## max\_bytes\_before\_remerge\_sort

유형

UInt64

기본값

1000000000

ORDER BY와 LIMIT를 함께 사용하는 경우, 메모리 사용량이 지정된 임계값을 초과하면 상위 LIMIT개 행만 유지하도록 최종 머지 전에 블록을 추가로 머지합니다.

## max\_bytes\_for\_external\_set\_bloom\_filter

유형

UInt64

기본값

134217728

디스크에 기록된 각 `IN` 집합(set)이 메모리에 유지하는 블룸 필터(Bloom filter)의 메모리 예산(바이트 단위)입니다.
이 필터를 사용하면 집합에 없는 값을 조회할 때 디스크 읽기를 건너뛸 수 있습니다. 단, 집합에 있는 값의 조회 속도는
향상되지 않습니다.

각 집합의 필터는 키당 약 1바이트와 예산 중 더 작은 크기만큼 메모리를 사용합니다. 여기서 집합의 키는
고유 값(distinct values)을 의미하며, 여러 컬럼을 사용하는 `IN`에서는 고유 튜플을 의미합니다.

* 예산이 키당 1바이트 이상이면 집합은 완전한 필터를 사용하며, 집합에 없는 값 조회의 약 97%가
  디스크 읽기를 건너뜁니다. 예를 들어 키가 100만 개인 집합은 약 1 MiB를 사용합니다.
* 예산이 이보다 작으면 집합은 예산에 맞춘 더 취약한 필터를 사용하며, 집합에 없는 값 조회 중 디스크 읽기를
  건너뛰는 비율이 줄어듭니다. 예를 들어 키당 1/4바이트이면 이러한 조회 중 97%가 아닌 약 60%만
  디스크 읽기를 건너뜁니다.
* 예산이 키당 약 1/7바이트 미만이면 집합은 필터를 사용하지 않습니다. 이 정도 크기의 필터로는 디스크 읽기를
  건너뛰는 조회가 너무 적어 필터 빌드 비용을 상쇄할 수 없기 때문입니다.

기본 예산인 128 MiB에서는 키가 약 1억 3천만 개 이하인 집합은 완전한 필터를 사용하고, 키가 약 9억 5천만 개를
초과하는 집합은 필터를 사용하지 않습니다. 조회하는 값 대부분이 집합에 없다면 더 큰 집합을 위해 예산을
늘리십시오. 메모리가 부족하거나, 조회하는 값 대부분이 집합에 있어 필터가 도움이 되지 않는다면 예산을
줄이십시오. `0`으로 설정하면 필터가 비활성화됩니다.

필터는 `max_memory_usage`와 같은 쿼리의 메모리 사용량(memory usage)에는 포함되지만,
`max_bytes_in_set`에는 포함되지 않습니다. 예산은 쿼리 단위가 아니라 집합 단위로 적용됩니다.

[외부 메모리에서의 IN](https://clickhouse.com/docs/ko/reference/statements/in.md#in-in-external-memory)을 참조하십시오.

## max\_bytes\_for\_external\_set\_cache

유형

UInt64

기본값

134217728

디스크에 기록된 각 `IN` 집합(set)이 메모리에 유지하는 블록(Block) 캐시의 메모리 예산(바이트 단위)입니다.
조회(lookup) 시 이전 조회에서 이미 읽은 블록(Block)이 필요하면 디스크에서 다시 읽지 않고 캐시에서 가져옵니다.
이 캐시는 자주 등장하는 소수의 값을 조회하거나 캐시에 들어갈 만한 크기의 집합을 여러 번 조회할 때처럼
동일한 블록(Block)이 반복적으로 필요한 경우에 유용합니다. 반면 캐시보다 훨씬 큰 집합 전체에 조회가 고르게 분산되는
경우에는 효과가 거의 없습니다. `0`으로 설정하면 캐시를 비활성화합니다.

이 예산은 집합별로 적용됩니다. 캐시는 `max_memory_usage`와 같은 쿼리의 메모리 사용량(memory usage)에는
포함되지만, `max_bytes_in_set`에는 포함되지 않습니다.

[외부 메모리에서의 IN](https://clickhouse.com/docs/ko/reference/statements/in.md#in-in-external-memory)을 참고하십시오.

## max\_bytes\_for\_lazy\_final

유형

UInt64

기본값

256000000

지연 실행 FINAL 최적화에서 사용하는 집합의 최대 바이트 수입니다. 이 값을 초과하면 일반 FINAL로 되돌아갑니다.

## max\_bytes\_in\_distinct

유형

UInt64

기본값

0

DISTINCT를 사용할 때 해시 테이블이 사용하는 메모리 내 상태의 최대 크기(비압축 바이트 기준)입니다.

## max\_bytes\_in\_join

유형

UInt64

기본값

0

테이블 조인 시 사용되는 오른쪽 데이터 구조(일반적으로 해시
테이블)의 최대 크기(바이트)입니다.

이 설정은 [SELECT ... JOIN](https://clickhouse.com/docs/ko/reference/statements/select/join.md)
연산과 [Join 테이블 엔진](https://clickhouse.com/docs/ko/reference/engines/table-engines/special/join.md)에 적용됩니다.

쿼리에 여러 개의 조인이 포함된 경우 ClickHouse는 모든
중간 결과에 대해 이 설정을 확인합니다. 이 값은 해시 기반의 모든 `join_algorithm`에 적용되는 하드 상한이며, 제한에
도달하면 쿼리는
[`join_overflow_mode`](https://clickhouse.com/docs/ko/reference/settings/session-settings/join#join_overflow_mode)에 따라 throw하거나 중단됩니다.
이 설정 때문에 조인이 디스크로 스필되는 일은 결코 없으며, 스필 여부는
[`max_bytes_before_external_join`](https://clickhouse.com/docs/ko/reference/settings/session-settings/max-bytes#max_bytes_before_external_join)
및
[`max_bytes_ratio_before_external_join`](https://clickhouse.com/docs/ko/reference/settings/session-settings/max-bytes#max_bytes_ratio_before_external_join)이 결정합니다.
이는 트리거가 아니라 상한이므로, 스필 임계값 이하로 설정하면
일반적으로 조인이 스필하기도 전에 쿼리가 실패합니다. 다만 조인이 스필 가능하고
`enable_adaptive_memory_spill_scheduler`가 먼저 스필을 강제하는 경우,
또는 `legacy_join_size_limits_trigger_spilling`이 이미 디스크에서 실행 중인 조인의 해당 파트에 대해
이 제한을 다시 스필 트리거로 되돌리는 경우는 예외입니다.

이 제한은 해시 테이블이 보유한 양을 집계하므로, 스필된 조인은 오른쪽을 읽는 도중이 아니라
각 버킷이 로드될 때 제한에 도달합니다. 즉, 인메모리 해시 조인보다
중단되기 전까지 오른쪽을 더 많이 읽을 수 있습니다.

`ON` 절에서 조인 키를 하나도 결정할 수 없으면 선택할 알고리즘이 없습니다. 이 경우 제한은
[블록 중첩 루프 조인(block nested loop join)](https://clickhouse.com/docs/ko/reference/statements/select/join.md#join-with-an-arbitrary-on-condition)이 구체화한 오른쪽 데이터에
스필된 블록까지 포함하여 적용되며, 오버플로우 시 동작은
[`join_overflow_mode`](https://clickhouse.com/docs/ko/reference/settings/session-settings/join#join_overflow_mode)를 따릅니다.

가능한 값:

* 양의 정수
* 0 — 메모리 제어가 비활성화됩니다.

## max\_bytes\_in\_set

유형

UInt64

기본값

0

서브쿼리로 생성된 IN 절의 집합에서 사용할 수 있는 최대 바이트 수(비압축 데이터 기준)입니다.

## max\_bytes\_ratio\_before\_external\_distinct

유형

Double

기본값

0.5

실행 시작 시점에 외부 `DISTINCT` 임계값을 계산하는 데 사용되는 서버 또는 사용자 가용 메모리의 비율입니다. 예를 들어 `0.5`는 사용 가능한 메모리의 절반을 사용합니다.

값은 `0` 이상 `1` 미만이어야 합니다. `0`이면 이 임계값이 비활성화됩니다. 적용 가능한 서버 또는 사용자 메모리 제한이 없으면 이 비율은 아무런 효과가 없습니다.

`max_memory_usage`는 이 계산에 영향을 주지 않습니다. 해당 제한을 기준으로 스필을 구성하려면 `max_bytes_before_external_distinct`를 사용하여 추가 메모리 사용을 위한 여유를 남겨 두십시오.

## max\_bytes\_ratio\_before\_external\_group\_by

유형

Double

기본값

0.5

가용 메모리 중 `GROUP BY`에 사용할 수 있는 비율입니다. 이 값에 도달하면
집계를 위해 외부 메모리를 사용합니다.

예를 들어 `0.6`으로 설정하면 실행 시작 시 `GROUP BY`는 가용 메모리의 60%
(서버/사용자/머지 기준)까지 사용할 수 있으며, 이후에는
외부 집계를 사용하기 시작합니다.

## max\_bytes\_ratio\_before\_external\_join

유형

Double

기본값

0.5

`JOIN`에 사용할 수 있는 가용 메모리 비율입니다. 이 값에 도달하면 해시 조인이 grace hash join으로 전환되어 오른쪽 데이터를 디스크로 스필합니다.

예를 들어 `0.6`으로 설정하면 실행 시작 시 `JOIN`의 오른쪽 해시 테이블이 가용 메모리(서버/사용자/머지에 할당된 메모리 기준)의 `60%`까지 사용할 수 있으며, 그 이후부터는 디스크로 스필하기 시작합니다.

`max_bytes_before_external_join`과 `max_bytes_ratio_before_external_join`이 모두 설정된 경우 계산된 임계값 중 더 작은 값이 사용됩니다. 비율이 `0`이면 절대값 설정만 적용됩니다.

임시 데이터 경로가 구성되어 있다면 `grace_hash`를 포함한 모든 해시 기반 `join_algorithm`에 적용됩니다.

## max\_bytes\_ratio\_before\_external\_set

유형

Double

기본값

0.5

서브쿼리가 포함된 `IN`의 집합을 디스크로 스필하는 임계값을 실행 시작 시점에 계산할 때 사용하는,
사용 가능한 서버 또는 사용자 메모리의 비율입니다. 예를 들어 `0.5`는 사용 가능한 메모리의 절반을 의미합니다.

값은 `0` 이상 `1` 미만이어야 합니다. `0`으로 설정하면 이 임계값이 비활성화됩니다. 적용할 수 있는
서버 또는 사용자 메모리 제한이 없으면 이 비율은 효과가 없습니다.

`max_memory_usage`는 이 계산에 영향을 주지 않습니다. 해당 제한을 기준으로 스필을 구성하려면
추가 메모리 사용을 고려해 여유를 두고 `max_bytes_before_external_set`을 사용하십시오.

## max\_bytes\_ratio\_before\_external\_sort

유형

Double

기본값

0.5

`ORDER BY`에 사용할 수 있는 가용 메모리의 비율입니다. 이 값에 도달하면 외부 정렬이 사용됩니다.

예를 들어 `0.6`으로 설정하면 실행 시작 시 `ORDER BY`에서 가용 메모리(서버/사용자/머지 기준)의 `60%`까지 사용할 수 있고, 그 이후부터는 외부 정렬을 사용하기 시작합니다.

참고로 `max_bytes_before_external_sort`는 계속 적용되며, 정렬 block이 `max_bytes_before_external_sort`보다 큰 경우에만 디스크로 스필됩니다.

## max\_bytes\_to\_read

유형

UInt64

기본값

0

쿼리 실행 시 테이블에서 읽을 수 있는 최대 바이트 수(압축되지 않은 데이터 기준)입니다.
이 제한은 처리되는 각 데이터 청크마다 확인되며,
가장 안쪽의 테이블 표현식에만 적용됩니다. 원격 서버에서 읽는 경우에는
원격 서버에서만 확인됩니다.

## max\_bytes\_to\_read\_leaf

유형

UInt64

기본값

0

분산 쿼리를 실행할 때 리프 노드의 로컬
테이블에서 읽을 수 있는 최대 바이트 수(비압축 데이터 기준)입니다. 분산 쿼리는
각 세그먼트(리프)에 여러 개의 하위 쿼리를 보낼 수 있지만, 이 제한은
리프 노드의 읽기 단계에서만 검사되며 루트 노드에서 결과를
병합하는 단계에서는 무시됩니다.

예를 들어, 클러스터가 2개의 세그먼트로 구성되어 있고 각 세그먼트에
100바이트의 데이터가 있는 테이블이 있다고 가정합니다. `max_bytes_to_read=150`
설정으로 두 테이블의 모든 데이터를 읽도록 하는 분산 쿼리는 전체 크기가
200바이트가 되므로 실패합니다. `max_bytes_to_read_leaf=150`인 쿼리는
리프 노드가 최대 100바이트만 읽으므로 성공합니다.

이 제한은 처리되는 각 데이터 청크에 대해 검사됩니다.

> [!NOTE]
>
> 이 설정은 `prefer_localhost_replica=1`과 함께 사용할 때 안정적이지 않습니다.

## max\_bytes\_to\_sort

유형

UInt64

기본값

0

정렬 전에 처리할 수 있는 최대 바이트 수입니다. ORDER BY 작업에서 지정된 양보다 많은
비압축 바이트를 처리해야 하는 경우, 동작은 `sort_overflow_mode`에 따라
결정되며 기본값은 `throw`입니다.

## max\_bytes\_to\_transfer

유형

UInt64

기본값

0

GLOBAL IN/JOIN 절이 실행될 때 원격 서버로 전달하거나 임시 테이블에 저장할 수 있는 최대 바이트 수(비압축 데이터)입니다.
