> ## 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>
            Experimental 功能
        </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](/zh/reference/system-tables/settings) 中查看，并由 [源代码](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`：继续对已进入集合的键进行聚合，但不再向集合中添加新键。

使用 `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 堆只会带来额外开销并将其冻结之前，每个聚合 stream 观察的行数。"}]}]} />

对于 `enable_group_by_top_k_optimization`：在冻结一个完整 top-K 堆之前，每个聚合 stream 观察的行数；该堆跳过的输入行不足 10%，且驱逐的键数少于其容量。堆被冻结后，聚合会像禁用该优化一样继续执行。

有效窗口至少是堆预留大小的两倍，因此堆在接受评估前始终有机会填满。`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" />

键的数量达到多少时开始启用两级聚合。0 表示未设置该阈值。

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

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

当聚合状态的大小达到多少字节时，开始使用两级聚合。0 表示未设置阈值。当至少一个阈值达到条件时，将使用两级聚合。

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

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

更改 [GROUP BY clause](/zh/reference/statements/select/group-by) 处理聚合键类型的方式。
使用 `ROLLUP`、`CUBE` 或 `GROUPING SETS` 说明符时，某些聚合键可能不会用于生成某些结果行。
这些键对应的列会根据此设置，在相应行中填入默认值或 `NULL`。

Possible values:

* 0 — 使用聚合键类型的默认值来填补缺失值。
* 1 — ClickHouse 会按照 SQL 标准的方式执行 `GROUP BY`。聚合键的类型会转换为 [Nullable](/zh/reference/data-types/nullable)。对于未使用相应聚合键的行，其对应列会填充为 [NULL](/zh/reference/syntax#null)。

See also:

* [GROUP BY clause](/zh/reference/statements/select/group-by)