> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-vortex-format.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# group_by_* 세션 설정

> group_by_* 그룹에 속한 ClickHouse 세션 설정입니다.

export const ExperimentalBadge = () => {
  return <a href="https://clickhouse.com/docs/reference/settings/beta-and-experimental-features#experimental-features" className="experimentalBadge">
            <div className="experimentalIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.25" d="M5.5 2H10.5" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M9.50015 2V6.19625L13.4283 12.7425C13.4738 12.8183 13.4985 12.9049 13.4996 12.9934C13.5008 13.0818 13.4785 13.169 13.435 13.246C13.3914 13.323 13.3283 13.3871 13.2519 13.4317C13.1755 13.4764 13.0886 13.4999 13.0002 13.5H3.00015C2.91164 13.5 2.8247 13.4766 2.74822 13.432C2.67174 13.3874 2.60847 13.3233 2.56487 13.2463C2.52126 13.1693 2.49889 13.082 2.50004 12.9935C2.50119 12.905 2.52582 12.8184 2.5714 12.7425L6.50015 6.19625V2" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M4.47656 9.56754C5.30344 9.41254 6.47656 9.47942 7.99969 10.25C10.0153 11.2707 11.4216 11.0569 12.2184 10.7282" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            실험 기능
        </a>;
};

export const VersionHistory = ({rows = []}) => {
  if (rows.length === 0) {
    return null;
  }
  const headers = ["버전", "기본값", "설명"];
  const border = "1px solid rgba(128, 128, 128, 0.3)";
  const cell = {
    border,
    padding: "0.25rem 0.5rem",
    textAlign: "start",
    verticalAlign: "top"
  };
  return <details className="not-prose" style={{
    border,
    borderRadius: "0.5rem",
    margin: "0.5rem 0",
    padding: "0.5rem 0.75rem",
    fontSize: "0.8125rem",
    lineHeight: "1.125rem"
  }}>
      <summary style={{
    cursor: "pointer",
    fontWeight: 600,
    opacity: 0.72
  }}>
        버전 이력
      </summary>
      <table style={{
    borderCollapse: "collapse",
    width: "100%",
    margin: "0.5rem 0 0"
  }}>
        <thead>
          <tr>
            {headers.map(header => <th key={header} style={{
    ...cell,
    fontWeight: 600,
    opacity: 0.72
  }}>
                {header}
              </th>)}
          </tr>
        </thead>
        <tbody>
          {rows.map((row, row_index) => <tr key={row.id ?? row_index}>
              {(row.items ?? []).map((item, item_index) => <td key={item_index} style={{
    ...cell,
    overflowWrap: "anywhere"
  }}>
                  {item?.label}
                </td>)}
            </tr>)}
        </tbody>
      </table>
    </details>;
};

export const SettingsInfoBlock = ({type, default_value, changeable_without_restart}) => {
  return <div className="not-prose" style={{
    display: "flex",
    flexWrap: "wrap",
    alignItems: "baseline",
    columnGap: "0.5rem",
    rowGap: "0.125rem",
    margin: "0.375rem 0",
    fontSize: "0.8125rem",
    lineHeight: "1.125rem"
  }}>
      <div style={{
    fontWeight: 600,
    opacity: 0.72
  }}>유형</div>
      <div style={{
    overflowWrap: "anywhere"
  }}>{type}</div>
      <div style={{
    fontWeight: 600,
    opacity: 0.72,
    marginInlineStart: "0.5rem"
  }}>기본값</div>
      <div style={{
    overflowWrap: "anywhere"
  }}>{default_value}</div>
      {changeable_without_restart && <div style={{
    fontWeight: 600,
    opacity: 0.72,
    marginInlineStart: "0.5rem"
  }}>
          재시작 없이 변경 가능
        </div>}
      {changeable_without_restart && <div style={{
    overflowWrap: "anywhere"
  }}>
          {changeable_without_restart}
        </div>}
    </div>;
};

이 설정은 [system.settings](/ko/reference/system-tables/settings)에서 사용할 수 있으며 [source](https://github.com/ClickHouse/ClickHouse/blob/master/src/Core/Settings.cpp)로부터 자동 생성됩니다.

<div id="group_by_overflow_mode">
  ## group\_by\_overflow\_mode
</div>

<SettingsInfoBlock type="OverflowModeGroupBy" default_value="throw" />

집계 시 고유 키 수가 한도를 초과하면 어떻게 처리할지 설정합니다.

* `throw`: 예외를 발생시킵니다
* `break`: 쿼리 실행을 중지하고 부분 결과를 반환합니다
* `any`: Set에 포함된 키에 대해서는 집계를 계속하지만, 새로운 키는 Set에 추가하지 않습니다.

`any` 값을 사용하면 GROUP BY의 근사치를 계산할 수 있습니다. 이 근사의 품질은
데이터의 통계적 특성에 따라 달라집니다.

<div id="group_by_top_k_optimization_observation_rows">
  ## group\_by\_top\_k\_optimization\_observation\_rows
</div>

<ExperimentalBadge />

<SettingsInfoBlock type="UInt64" default_value="65536" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.8"},{"label": "65536"},{"label": "새 실험적 설정: 각 집계 스트림이 어떤 항목도 제외하지 않은 가득 찬 top-K 힙을 순수한 오버헤드로 간주해 고정하기 전에 관찰하는 행 수입니다."}]}]} />

`enable_group_by_top_k_optimization`의 설정입니다. 각 집계 스트림이 입력 행의 10% 미만을 건너뛰고 용량보다 적은 수의 키를 제거한 가득 찬 top-K 힙을 고정하기 전에 관찰하는 행 수입니다. 힙이 고정되면 최적화가 비활성화된 것처럼 집계가 계속됩니다.

유효 윈도우는 힙의 예약 크기보다 최소 2배이므로, 평가 전에 힙이 채워질 기회가 항상 보장됩니다. `0`은 이 고정을 비활성화합니다(경계 동률 집합이 힙보다 커지면 힙은 계속 고정됩니다).

`ORDER BY` 없이 사용하는 `GROUP BY keys LIMIT K` 쿼리에서는 고정이 항상 비활성화되므로 이 설정은 영향을 주지 않습니다. 이 형태의 계획에는 힙이 해시 테이블의 크기를 제한하는 동안에만 이점이 있는 합성 정렬이 포함되므로, 힙을 고정하면 최적화되지 않은 계획보다 느린 계획이 됩니다.

<div id="group_by_two_level_threshold">
  ## group\_by\_two\_level\_threshold
</div>

<SettingsInfoBlock type="UInt64" default_value="100000" />

키 개수가 이 수에 도달하면 2단계 집계가 시작됩니다. 0이면 임계값이 설정되지 않습니다.

<div id="group_by_two_level_threshold_bytes">
  ## group\_by\_two\_level\_threshold\_bytes
</div>

<SettingsInfoBlock type="UInt64" default_value="50000000" />

집계 상태의 크기가 몇 바이트부터 2단계 집계를 사용하기 시작할지 지정합니다. 0은 임계값이 설정되지 않았음을 의미합니다. 임계값 중 하나 이상이 충족되면 2단계 집계가 사용됩니다.

<div id="group_by_use_nulls">
  ## group\_by\_use\_nulls
</div>

<SettingsInfoBlock type="Bool" default_value="0" />

[GROUP BY 절](/ko/reference/statements/select/group-by)이 집계 키의 타입을 처리하는 방식을 변경합니다.
`ROLLUP`, `CUBE`, 또는 `GROUPING SETS` 지정자를 사용하면 일부 집계 키가 일부 결과 행을 생성하는 데 사용되지 않을 수 있습니다.
이러한 키의 컬럼은 이 설정에 따라 해당 행에서 기본값 또는 `NULL`로 채워집니다.

Possible values:

* 0 — 누락된 값을 생성할 때 집계 키 타입의 기본값을 사용합니다.
* 1 — ClickHouse는 SQL 표준에 정의된 방식과 동일하게 `GROUP BY`를 실행합니다. 집계 키의 타입은 [널 허용](/ko/reference/data-types/nullable)으로 변환됩니다. 해당 집계 키의 컬럼은 이 키가 사용되지 않은 행에서 [NULL](/ko/reference/syntax#null)로 채워집니다.

관련 항목:

* [GROUP BY 절](/ko/reference/statements/select/group-by)