Skip to main content
这些设置可在 system.settings 中找到,并由 源代码 自动生成。

max_bytes_before_external_distinct

将 DISTINCT 数据落盘的查询内存阈值,以字节为单位。实际内存使用量可能超过该阈值。 0 表示禁用该阈值。如果 max_bytes_ratio_before_external_distinct 也指定了阈值,则取两者中较小的一个。将两个设置均设为 0 即可禁用落盘。 参见 外部内存中的 DISTINCT。

max_bytes_before_external_group_by

Cloud 默认值:每个副本内存总量的一半。 控制是否在外部内存中执行 GROUP BY 子句。 (参见 外部内存中的 GROUP BY) 可能的值:
  • 单次 GROUP BY 操作可使用的最大 RAM 容量 (以字节为单位) 。
  • 0 — 禁用外部内存中的 GROUP BY。
如果 GROUP BY 操作期间的内存使用量超过此阈值 (以字节为单位) , 则会启用“外部聚合”模式 (将数据落盘) 。建议值为可用系统内存的一半。

max_bytes_before_external_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

Cloud 默认值:每个副本内存的一半。 启用或禁用使用外部内存执行 ORDER BY 子句。参见 ORDER BY 实现细节 如果 ORDER BY 操作期间的内存使用量超过此阈值 (以字节为单位) ,就会启用“外部排序”模式 (将数据落盘到磁盘) 。 可能的值:
  • 单次 ORDER BY 操作可使用的最大 RAM 量 (以字节为单位) 。 建议值为可用系统内存的一半
  • 0 — 禁用使用外部内存执行 ORDER BY。

max_bytes_before_remerge_sort

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

max_bytes_for_lazy_final

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

max_bytes_in_distinct

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

max_bytes_in_join

用于表连接时右侧数据结构 (通常是哈希表) 的最大字节数。 此设置适用于 SELECT … JOIN 操作以及 Join table engine。 如果一个查询包含多个 JOIN,ClickHouse 会对每个中间结果检查此设置。对于所有基于哈希的 join_algorithm,它都是一个硬性上限:达到该限制时,查询会根据 join_overflow_mode 抛出异常或中断。它绝不会促使 join 落盘——落盘与否由 max_bytes_before_external_join 和 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

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

max_bytes_ratio_before_external_distinct

在执行开始时,用于计算外部 DISTINCT 阈值的可用服务器或用户内存的比例。例如,0.5 表示使用可用内存的一半。 取值必须不小于 0 且小于 1。0 表示禁用该阈值。如果不存在适用的服务器或用户内存限制,该比例不会生效。 max_memory_usage 不参与此计算。若要基于该限制配置落盘行为,请使用 max_bytes_before_external_distinct,并为额外的内存使用量预留空间。

max_bytes_ratio_before_external_group_by

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

max_bytes_ratio_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

可供 ORDER BY 使用的可用内存比例。达到该比例后,将使用外部排序。 例如,如果设置为 0.6,则在执行开始时,ORDER BY 可使用 60% 的可用内存 (对 server/user/merges 而言) ;超过该比例后,将开始使用外部排序。 请注意,max_bytes_before_external_sort 仍然有效,只有当排序块大于 max_bytes_before_external_sort 时才会落盘。

max_bytes_to_read

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

max_bytes_to_read_leaf

运行分布式查询时,在叶节点上从本地表中可读取的最大字节数 (未压缩数据) 。虽然分布式查询可以向每个分片 (叶) 发出多个子查询,但此限制只会在叶节点的读取阶段进行检查,在根节点的结果合并阶段会被忽略。 例如,一个集群由 2 个分片组成,每个分片都包含一张有 100 字节数据的表。对于一个需要从这两张表中读取全部数据的分布式查询,如果设置 max_bytes_to_read=150,则会失败,因为总共需要读取 200 字节。而设置 max_bytes_to_read_leaf=150 的查询则会成功,因为叶节点最多只会读取 100 字节。 该限制会对每个已处理的数据块进行检查。
当 prefer_localhost_replica=1 时,此设置不稳定。

max_bytes_to_sort

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

max_bytes_to_transfer

在执行 GLOBAL IN/JOIN 部分时,可传输到远程服务器或保存到临时表的最大字节数 (未压缩数据) 。
最后修改于 2026年9月26日