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

max_analyze_depth

解释器执行分析的最大次数。

max_autoincrement_series

generateSerialID 函数可创建的序列数量上限。 由于每个序列都对应 Keeper 中的一个节点,建议其数量不要超过几百万个。

max_backup_bandwidth

服务器上特定备份的最大读取速度 (以每秒字节数计) 。0 表示不受限制。

max_block_size

在 ClickHouse 中,数据以块为单位进行处理,块由各列的数据片段组成。单个块的内部处理过程效率很高,但处理每个块时仍会产生明显的额外开销。 max_block_size 设置表示从表中加载数据时,单个块建议包含的最大行数。但从表中读取的块并不一定总是达到 max_block_size:如果 ClickHouse 判断只需检索较少的数据,就会处理更小的块。 块大小不应过小,以免处理每个块时的额外开销过于明显;也不应过大,以确保带有 LIMIT 子句的查询在处理完第一个块后能够快速返回结果。设置 max_block_size 时,目标应是避免在多线程提取大量列时占用过多内存,同时尽可能保持一定的缓存局部性。

max_columns_to_read

单次查询可从表中读取的最大列数。 如果查询需要读取的列数超过指定数量, 将抛出异常。
此设置可用于防止查询过于复杂。
0 表示不受限制。

max_compress_block_size

写入表时,压缩前未压缩数据块的最大大小。默认值为 1,048,576 (1 MiB) 。指定较小的块大小通常会使压缩率略有下降;由于缓存局部性,压缩和解压速度会略有提升,同时还能减少内存消耗。
这是一个专家级设置;如果你刚开始使用 ClickHouse,不建议更改它。
不要将用于压缩的块 (由字节组成的一段内存) 与用于查询处理的块 (表中的一组行) 混淆。

max_consume_snapshots

每次增量读取最多可消费的 Paimon 快照数量。0 表示不限制。

max_estimated_execution_time

查询预计的最大执行时间 (秒) 。当 timeout_before_checking_execution_speed 超时后,会对每个数据块进行检查。

max_expanded_ast_elements

别名和星号展开后,查询语法树可包含的最大节点数。

max_fetch_partition_retries_count

从另一台主机拉取分区时的重试次数。

max_final_threads

设置带有 FINAL 修饰符的 SELECT 查询在数据读取阶段可使用的最大并行线程数。 可能的值:
  • 正整数。
  • 0 或 1 — 禁用。SELECT 查询将以单线程执行。

max_http_get_redirects

允许的 HTTP GET 重定向跳转最大次数。该设置可提供额外的安全保护,防止恶意服务器将你的请求重定向到意外的服务。\n\n这种情况会发生在:某个外部服务器重定向到另一个地址,而该地址看起来像是公司基础设施内部的地址。此时,如果向内部服务器发送 HTTP 请求,你可能会从内部网络访问内部 API,绕过身份验证,甚至查询其他服务,例如 Redis 或 Memcached。如果你没有内部基础设施 (包括在 localhost 上运行的内容) ,或者你信任该服务器,那么允许重定向是安全的。不过请记住,如果 URL 使用的是 HTTP 而不是 HTTPS,那么你不仅需要信任远程服务器,还需要信任你的 ISP 以及中间经过的每一层网络。 Cloud 默认值:10

max_limit_for_vector_search_queries

LIMIT 大于此设置值的 SELECT 查询将无法使用向量相似性索引。这有助于防止向量相似性索引出现内存溢出。

max_number_of_partitions_for_independent_aggregation

应用此优化时,表中允许的最大分区数

max_os_cpu_wait_time_ratio_to_throw

用于判定是否拒绝查询的最大比率,即 OS CPU 等待时间 (OSCPUWaitMicroseconds 指标) 与忙碌时间 (OSCPUVirtualTimeMicroseconds 指标) 之间的比率上限。概率通过最小比率与最大比率之间的线性插值计算;在该点处,概率为 1。

max_parallel_replicas

执行查询时,每个分片可使用的最大副本数。 可能的值:
  • 正整数。
附加信息 此选项在不同设置下会产生不同的结果。

使用 SAMPLE 采样键进行并行处理

如果一个查询在多台服务器上并行执行,处理速度可能会更快。但在以下情况下,查询性能可能会下降:
  • 采样键在分区键中的位置不利于高效的范围扫描。
  • 向表中添加采样键会降低按其他列进行过滤的效率。
  • 采样键是一个计算成本较高的表达式。
  • 集群的延迟分布存在长尾,因此查询更多服务器会增加查询的整体延迟。

使用 parallel_replicas_custom_key 实现并行处理

此设置适用于任何启用了复制的表。

max_parsing_threads

在支持并行解析的输入格式中,用于解析数据的最大线程数。默认会自动确定。

max_partition_size_to_drop

对在查询时删除分区操作的限制。值 0 表示删除分区时不受任何限制。 Cloud 默认值:1 TB。
此查询设置会覆盖对应的服务器级设置,参见 max_partition_size_to_drop

max_parts_to_move

限制单个查询中可移动的 parts 数量。0 表示不受限制。

max_projection_rows_to_use_projection_index

如果需要从投影索引读取的行数小于或等于此阈值,ClickHouse 将在查询执行期间尝试使用该投影索引。

max_query_size

由 SQL 解析器解析的查询字符串的最大字节数。 INSERT 查询中 VALUES 子句里的数据由单独的 stream 解析器处理 (占用 O(1) RAM) ,不受此限制影响。
max_query_size 不能在 SQL 查询内部设置 (例如 SELECT now() SETTINGS max_query_size=10000) ,因为 ClickHouse 需要先分配一个缓冲区来解析查询,而该缓冲区的大小由 max_query_size 设置决定,因此必须在查询执行前完成配置。

max_recursive_cte_evaluation_depth

递归 CTE 求值深度的最大限制

max_replica_delay_for_distributed_queries

在分布式查询中禁用存在延迟的副本。参见 复制 设置一个以秒为单位的时间阈值。如果某个副本的延迟大于或等于该值,则不使用该副本。 可选值:
  • 正整数。
  • 0 — 不检查副本延迟。
要避免使用任何延迟非零的副本,请将此参数设为 1。 在对指向复制表的分布式表执行 SELECT 时使用。

max_reverse_dictionary_lookup_cache_size_bytes

函数 dictGetKeys 使用的每个查询反向字典查找缓存的最大字节数。该缓存会按每个属性值存储序列化后的键 Tuple,以避免在同一查询中重复扫描字典。达到限制后,缓存条目将按 LRU 策略被逐出。设置为 0 可禁用缓存。

max_sessions_for_user

每个已通过身份验证的用户在 ClickHouse server 上允许的最大并发会话数。 示例:
可能的值:
  • 正整数
  • 0 - 并发会话数量无限 (默认)

max_subquery_depth

如果查询中的嵌套子查询数量超过指定值,则会抛出异常。
可用它进行合理性检查,防止集群用户编写过于复杂的查询。

max_table_size_to_drop

对在查询时删除表的限制。值 0 表示可以不受任何限制地删除所有表。 Cloud 默认值:1 TB。
此查询设置会覆盖对应的服务器级设置,参见 max_table_size_to_drop

max_untracked_memory

较小的内存分配和释放会在线程局部变量中归组,只有当其数量 (按绝对值计算) 大于指定值时,才会被跟踪或分析。如果该值高于 memory_profiler_step,则实际上会被下调为 memory_profiler_step

max_wkb_geometry_elements

readWKB 及相关函数在解析时,单个 WKB 几何元素中允许包含的 Point、Ring 或 Polygon 的最大数量。这可防止格式错误的 WKB 数据导致过多内存分配。设为 0 可使用硬编码限制 (1 亿) 。
最后修改于 2026年7月24日