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

# max_bytes_* 会话设置

> ClickHouse 中 max_bytes_* 自动生成分组的会话设置。

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) 自动生成。

## max\_bytes\_before\_external\_distinct

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.9"},{"label": "0"},{"label": "新增设置，用于在内存使用量超过指定阈值（以字节为单位）时将 `DISTINCT` 落盘。若为 0，则仅 `max_bytes_ratio_before_external_distinct` 生效。"}]}]} />

将 `DISTINCT` 数据落盘的查询内存阈值，以字节为单位。实际内存使用量可能超过该阈值。

`0` 表示禁用该阈值。如果 `max_bytes_ratio_before_external_distinct` 也指定了阈值，则取两者中较小的一个。将两个设置均设为 `0` 即可禁用落盘。

参见 [外部内存中的 DISTINCT](/zh/reference/statements/select/distinct#distinct-in-external-memory)。

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

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

Cloud 默认值：每个副本内存总量的一半。

控制是否在外部内存中执行 `GROUP BY` 子句。
(参见 [外部内存中的 GROUP BY](/zh/reference/statements/select/group-by#group-by-in-external-memory))

可能的值：

* 单次 [GROUP BY](/zh/reference/statements/select/group-by) 操作可使用的最大 RAM 容量 (以字节为单位) 。
* `0` — 禁用外部内存中的 `GROUP BY`。

<Note>
  如果 GROUP BY 操作期间的内存使用量超过此阈值 (以字节为单位) ，
  则会启用“外部聚合”模式 (将数据落盘) 。

  建议值为可用系统内存的一半。
</Note>

## max\_bytes\_before\_external\_join

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.4"},{"label": "0"},{"label": "用于控制哈希 JOIN 自动落盘的新设置。非零值会启用落盘并设置字节阈值。"}]}]} />

如果设置为非零值，当右侧数据超过该字节数时，哈希 JOIN 会自动转换为 grace hash join，以支持落盘。它与 `max_bytes_ratio_before_external_join` 一起，构成所有基于哈希的 `join_algorithm` 的基于阈值的落盘触发条件，其中包括 `grace_hash`，后者要求两者之一必须为非零值。一旦非零阈值使 JOIN 具备落盘能力，`enable_adaptive_memory_spill_scheduler` 就可以在内存压力下强制其在达到阈值之前落盘；若两项设置均为 `0`，则该 JOIN 永不落盘，调度器也就无从触发。例外情况是 `legacy_join_size_limits_trigger_spilling`：启用该设置后，独立使用的 `grace_hash` 会忽略这两项设置，改为依据 `max_rows_in_join` / `max_bytes_in_join` 落盘。设置为 `0` (默认值) 时，此绝对字节阈值将被禁用，但仍可能通过 `max_bytes_ratio_before_external_join` (其默认值为 `0.5`) 自动落盘；将两者都设为 `0` 可完全禁用自动落盘。它会阻止通过 JOIN 优化实现的 read in order。

## max\_bytes\_before\_external\_sort

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

Cloud 默认值：每个副本内存的一半。

启用或禁用使用外部内存执行 `ORDER BY` 子句。参见 [ORDER BY 实现细节](/zh/reference/statements/select/order-by#implementation-details)
如果 ORDER BY 操作期间的内存使用量超过此阈值 (以字节为单位) ，就会启用“外部排序”模式 (将数据落盘到磁盘) 。

可能的值：

* 单次 [ORDER BY](/zh/reference/statements/select/order-by) 操作可使用的最大 RAM 量 (以字节为单位) 。
  建议值为可用系统内存的一半
* `0` — 禁用使用外部内存执行 `ORDER BY`。

## max\_bytes\_before\_remerge\_sort

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

对于带有 LIMIT 的 ORDER BY，当内存使用量超过指定阈值时，会在最终合并前额外执行几步块合并，以便只保留前 LIMIT 行。

## max\_bytes\_for\_lazy\_final

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.4"},{"label": "256000000"},{"label": "新增设置：用于限制 lazy FINAL 优化中集合的最大字节数"}]}]} />

lazy FINAL 优化中集合的最大字节数。超过该值时，将回退到普通 FINAL。

## max\_bytes\_in\_distinct

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

使用 DISTINCT 时，哈希表在内存中使用的状态的最大字节数
(按未压缩字节计算) 。

## max\_bytes\_in\_join

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

用于表连接时右侧数据结构 (通常是哈希表) 的最大字节数。

此设置适用于 [SELECT ... JOIN](/zh/reference/statements/select/join) 操作以及 [Join table engine](/zh/reference/engines/table-engines/special/join)。

如果一个查询包含多个 JOIN，ClickHouse 会对每个中间结果检查此设置。对于所有基于哈希的 `join_algorithm`，它都是一个硬性上限：达到该限制时，查询会根据 [`join_overflow_mode`](/zh/reference/settings/session-settings/join#join_overflow_mode) 抛出异常或中断。它绝不会促使 join 落盘——落盘与否由 [`max_bytes_before_external_join`](/zh/reference/settings/session-settings/max-bytes#max_bytes_before_external_join) 和 [`max_bytes_ratio_before_external_join`](/zh/reference/settings/session-settings/max-bytes#max_bytes_ratio_before_external_join) 决定。由于它是上限而非触发条件，将其设置为等于或低于落盘阈值通常会导致查询在 join 尚未落盘之前就失败——除非该 join 支持落盘且 `enable_adaptive_memory_spill_scheduler` 先强制触发了落盘，或者 `legacy_join_size_limits_trigger_spilling` 将此限制重新变为已在磁盘上运行的那部分 join 的落盘触发条件。

该限制统计的是哈希表所持有的数据量，因此已落盘的 join 是在逐个加载各 bucket 时达到该限制，而不是在读取右侧数据的过程中达到：与内存中的哈希 JOIN相比，它在停止之前可以读取更多的右侧数据。

可能的值：

* 正整数。
* 0 — 禁用内存控制。

## max\_bytes\_in\_set

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

由子查询创建的 IN 子句中的 Set 所使用的最大字节数 (按未压缩数据计算) 。

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

<SettingsInfoBlock type="Double" default_value="0.5" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.9"},{"label": "0.5"},{"label": "新增设置：当内存使用量超过可用内存的指定比例时，允许 `DISTINCT` 落盘。若为 0，则仅 `max_bytes_before_external_distinct` 生效。"}]}]} />

在执行开始时，用于计算外部 `DISTINCT` 阈值的可用服务器或用户内存的比例。例如，`0.5` 表示使用可用内存的一半。

取值必须不小于 `0` 且小于 `1`。`0` 表示禁用该阈值。如果不存在适用的服务器或用户内存限制，该比例不会生效。

`max_memory_usage` 不参与此计算。若要基于该限制配置落盘行为，请使用 `max_bytes_before_external_distinct`，并为额外的内存使用量预留空间。

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

<SettingsInfoBlock type="Double" default_value="0.5" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "25.1"},{"label": "0.5"},{"label": "默认启用自动落盘。"}]}, {"id": "row-2","items": [{"label": "24.12"},{"label": "0"},{"label": "新设置。"}]}]} />

可用于 `GROUP BY` 的可用内存占比。达到该比例后，
将使用外部内存进行聚合。

例如，如果设置为 `0.6`，`GROUP BY` 在执行开始时将允许使用 60% 的可用内存
(相对于 server/user/merges 可用的内存) ，之后将
开始使用外部聚合。

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

<SettingsInfoBlock type="Double" default_value="0.5" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.5"},{"label": "0.5"},{"label": "新增设置：可用内存中用作 哈希 JOIN 落盘阈值的比例。默认启用，值为 `0.5`，与 `max_bytes_ratio_before_external_group_by` 和 `max_bytes_ratio_before_external_sort` 保持一致。与绝对值设置 `max_bytes_before_external_join` 结合使用时，取两者中较小者。"}]}]} />

允许 `JOIN` 使用的可用内存比例。达到该比例后，哈希 JOIN 会转换为 grace hash join，并将右侧数据落盘到磁盘。

例如，如果设置为 `0.6`，则在执行开始时，`JOIN` 允许右侧哈希表使用可用内存 (对 server/user/merges 可用) 的 `60%`；之后将开始落盘到磁盘。

如果同时设置了 `max_bytes_before_external_join` 和 `max_bytes_ratio_before_external_join`，则使用较小的结果阈值。如果该比例为 `0`，则仅应用绝对值设置。

只要已配置临时数据路径，此设置对每一种基于哈希的 `join_algorithm` 都生效，包括 `grace_hash`。

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

<SettingsInfoBlock type="Double" default_value="0.5" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "25.1"},{"label": "0.5"},{"label": "默认启用自动落盘。"}]}, {"id": "row-2","items": [{"label": "24.12"},{"label": "0"},{"label": "新设置。"}]}]} />

可供 `ORDER BY` 使用的可用内存比例。达到该比例后，将使用外部排序。

例如，如果设置为 `0.6`，则在执行开始时，`ORDER BY` 可使用 `60%` 的可用内存 (对 server/user/merges 而言) ；超过该比例后，将开始使用外部排序。

请注意，`max_bytes_before_external_sort` 仍然有效，只有当排序块大于 `max_bytes_before_external_sort` 时才会落盘。

## max\_bytes\_to\_read

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

运行查询时，从表中可读取的最大字节数 (未压缩数据) 。
该限制会对每个已处理的数据块检查一次，仅适用于最内层的表表达式；从远程服务器读取时，则只在远程服务器上检查。

## max\_bytes\_to\_read\_leaf

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

运行分布式查询时，在叶节点上从本地表中可读取的最大字节数 (未压缩数据) 。虽然分布式查询可以向每个分片 (叶) 发出多个子查询，但此限制只会在叶节点的读取阶段进行检查，在根节点的结果合并阶段会被忽略。

例如，一个集群由 2 个分片组成，每个分片都包含一张有 100 字节数据的表。对于一个需要从这两张表中读取全部数据的分布式查询，如果设置 `max_bytes_to_read=150`，则会失败，因为总共需要读取 200 字节。而设置 `max_bytes_to_read_leaf=150` 的查询则会成功，因为叶节点最多只会读取 100 字节。

该限制会对每个已处理的数据块进行检查。

<Note>
  当 `prefer_localhost_replica=1` 时，此设置不稳定。
</Note>

## max\_bytes\_to\_sort

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

进行排序前允许处理的最大字节数。如果 ORDER BY 操作需要处理的未压缩字节数
超过指定数量，则其行为由 `sort_overflow_mode` 决定；该参数默认设置为 `throw`。

## max\_bytes\_to\_transfer

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

在执行 GLOBAL IN/JOIN 部分时，可传输到远程服务器或保存到临时表的最大字节数 (未压缩数据) 。