其他会话设置

位于自动生成的“其他”分组中的 ClickHouse 会话设置。

这些设置可在 system.settings 中查看，由 源代码 自动生成。

​

adaptive_aggregator_freeze_threshold

自适应聚合器冻结线程本地哈希表时的键数量 (参见 enable_adaptive_aggregator) 。较小的值可使冻结后的表保持在缓存中，较大的值则可让其吸收更多高频键。值为 0 时，表会在首次有机会时冻结，这会使该算法的行为类似于按键哈希进行的纯分片：每个键都根据其哈希进行路由，并由单个所有者聚合；区别仅在于，聚合会延后到合并阶段，而不是在扫描期间在线程之间交换。

​

adaptive_aggregator_freeze_threshold_bytes

自适应聚合器冻结线程本地哈希表时对应的内存大小 (请参阅 enable_adaptive_aggregator) 。此设置与 adaptive_aggregator_freeze_threshold 中任一阈值先达到时，表即会被冻结。该大小指本地表自身已分配的字节数 (包括其哈希表缓冲区和 Arena) ，在块之间进行检查。当键或聚合状态较宽时，字节限制尤为重要：仅使用键数量阈值会使这类表增长到超出 CPU 缓存容量。使用默认值时，键和状态宽度常规的表仍会按键数量冻结。0 将禁用字节限制，因此仅由键数量阈值决定。

​

add_http_cors_header

写入 HTTP CORS 请求头。

​

analyze_index_with_space_filling_curves

如果表的索引中使用了空间填充曲线，例如 ORDER BY mortonEncode(x, y) 或 ORDER BY hilbertEncode(x, y)，并且查询对其参数指定了条件，例如 x >= 10 AND x <= 20 AND y >= 20 AND y <= 30，则会使用空间填充曲线进行索引分析。目前，二维分析会跳过带有 UInt64 参数的曲线，因为曲线实现对每个参数仅使用 32 位。

​

analyzer_inline_views

启用后，analyzer 会用定义这些普通 (非物化、非参数化) 视图的子查询替换它们，从而实现跨边界优化，例如谓词下推和列裁剪。

​

any_join_distinct_right_table_keys

启用 ANY INNER|LEFT JOIN 操作中的旧版 ClickHouse server 行为。

仅当你的用例依赖旧版 JOIN 行为时，才应出于向后兼容目的使用此设置。

启用旧版行为时：

• t1 ANY LEFT JOIN t2 和 t2 ANY RIGHT JOIN t1 操作的结果不相同，因为 ClickHouse 使用的是从左表到右表键的多对一映射逻辑。
• ANY INNER JOIN 操作的结果会像 SEMI LEFT JOIN 操作一样，包含左表中的所有行。

禁用旧版行为时：

• t1 ANY LEFT JOIN t2 和 t2 ANY RIGHT JOIN t1 操作的结果相同，因为 ClickHouse 在 ANY RIGHT JOIN 操作中使用的是可提供一对多键映射的逻辑。
• ANY INNER JOIN 操作的结果中，每个键在左表和右表中各包含一行。

可选值：

• 0 — 旧版行为已禁用。
• 1 — 旧版行为已启用。

另请参见：

• JOIN strictness

​

archive_adaptive_buffer_max_size_bytes

限制写入归档文件时使用的自适应缓冲区的最大大小 (例如，tar 归档

​

arrow_flight_request_descriptor_type

用于 Arrow Flight 请求的描述符类型。‘path’ 会将数据集名称作为路径描述符发送。‘command’ 会将 SQL 查询作为命令描述符发送 (Dremio 需要这种方式) 。

可能的值：

• ‘path’ — 使用 FlightDescriptor::Path (默认值，适用于大多数 Arrow Flight 服务器)
• ‘command’ — 使用包含 SELECT 查询的 FlightDescriptor::Command (Dremio 需要这种方式)

​

backup_slow_all_threads_after_retryable_s3_error

当设置为 true 时，只要有任意一个 S3 请求遇到可重试的 S3 错误 (例如 ‘Slow Down’) ， 所有向同一备份端点发起 S3 请求的线程都会被放慢。 当设置为 false 时，每个线程都会独立处理 S3 请求的退避，而不受其他线程影响。

​

cache_warmer_threads

仅在 ClickHouse Cloud 中生效。启用 cache_populated_by_fetch 时，用于将新的数据分区片段预下载到文件系统缓存中的后台线程数。设为 0 可禁用。

​

calculate_text_stack_trace

在查询执行期间发生异常时，计算文本堆栈跟踪。这是默认设置。该功能需要进行符号查找，因此在执行大量错误查询时，可能会降低模糊测试的速度。一般情况下，不应禁用此选项。

​

cancel_http_readonly_queries_on_client_close

当客户端在未等待响应的情况下关闭连接时，会取消 HTTP 只读查询 (例如 SELECT) 。

Cloud 默认值：1。

​

cascades_aggregation_pushdown

在 Cascades 优化器中，将部分聚合下推到 join 之下 (立即聚合) 作为一种基于代价的备选方案纳入考虑。 仅在同时设置 enable_cascades_optimizer = 1 和 make_distributed_plan = 1 时生效。

​

checksum_on_read

在读取时验证校验和。此设置默认启用，并且在生产环境中应始终保持启用。不要期望禁用此设置会带来任何好处。它仅可用于实验和基准测试。该设置仅适用于 MergeTree 家族的表。对于其他表引擎，以及通过网络接收数据时，始终都会验证校验和。

​

compression

对响应正文应用通用压缩，例如 compression=gz。请注意，此设置独立于 Content-Encoding (HTTP 压缩) 和旧版 compress 参数 (ClickHouse 原生压缩) 。在 URL 路径中指定压缩文件扩展名也可达到相同效果。

这是一个用于调整 HTTP 接口响应的设置：它会在查询执行前被处理 (响应缓冲区会预先设置) ，因此必须通过 HTTP URL 参数、URL 路径中的文件扩展名或用户 profile 提供，不能通过查询内的 SETTINGS 子句提供 (在该子句中无效，并且会被拒绝) 。

​

connection_pool_max_wait_ms

连接池已满时等待连接的时间，单位为毫秒。

该等待时间按副本生效，因为每个副本各有一个连接池。等待超时后，本次尝试会以 NO_FREE_CONNECTION 失败。在分布式 SELECT 所使用的故障转移路径上，这与其他不可用副本的处理方式相同：查询会继续尝试其余副本，只有在所有副本都尝试过之后才会以 ALL_CONNECTION_TRIES_FAILED 失败。因此该设置并不限制整个查询的耗时；在有 N 个副本、每个副本尝试 T 次的情况下，总等待时间可能达到 connection_pool_max_wait_ms 乘以 N 再乘以 T，其中 T 为 connections_with_failover_max_tries，但不会小于 1，因为在放弃某个副本之前总会先尝试一次。若要限制查询本身的耗时，请使用 max_execution_time。

skip_unavailable_shards 无法屏蔽该错误：发起服务器因没有空闲连接槽而未能连接的副本，实际上从未被访问过，因此该分片不会被视为不可用。

可能的值：

• 正整数。
• 0 — 无限超时。该等待仍可被 KILL QUERY 中断；在默认的 timeout_overflow_mode throw 下，也会被 max_execution_time 中断。 在 break 模式下，时间限制不会取消查询，因此等待会一直持续到有连接被释放为止；此时 KILL QUERY 仍可将其中断。

​

connections_with_failover_max_tries

Distributed 表引擎针对每个副本的最大连接尝试次数。

​

convert_query_to_cnf

设置为 true 时，SELECT 查询会被转换为合取范式 (CNF) 。在某些情况下，将查询重写为 CNF 可能会执行得更快 (说明请参见这个 Github issue) 。

例如，请注意下面这个 SELECT 查询不会被修改 (这是默认行为) ：

EXPLAIN SYNTAX
SELECT *
FROM
(
    SELECT number AS x
    FROM numbers(20)
) AS a
WHERE ((x >= 1) AND (x <= 5)) OR ((x >= 10) AND (x <= 15))
SETTINGS convert_query_to_cnf = false;

结果如下：

┌─explain────────────────────────────────────────────────────────┐
│ SELECT x                                                       │
│ FROM                                                           │
│ (                                                              │
│     SELECT number AS x                                         │
│     FROM numbers(20)                                           │
│     WHERE ((x >= 1) AND (x <= 5)) OR ((x >= 10) AND (x <= 15)) │
│ ) AS a                                                         │
│ WHERE ((x >= 1) AND (x <= 5)) OR ((x >= 10) AND (x <= 15))     │
│ SETTINGS convert_query_to_cnf = 0                              │
└────────────────────────────────────────────────────────────────┘

我们将 convert_query_to_cnf 设为 true，看看会有哪些变化：

EXPLAIN SYNTAX
SELECT *
FROM
(
    SELECT number AS x
    FROM numbers(20)
) AS a
WHERE ((x >= 1) AND (x <= 5)) OR ((x >= 10) AND (x <= 15))
SETTINGS convert_query_to_cnf = true;

请注意，WHERE 子句虽已重写为 CNF，但结果集完全相同——布尔逻辑并未改变：

┌─explain───────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ SELECT x                                                                                                              │
│ FROM                                                                                                                  │
│ (                                                                                                                     │
│     SELECT number AS x                                                                                                │
│     FROM numbers(20)                                                                                                  │
│     WHERE ((x <= 15) OR (x <= 5)) AND ((x <= 15) OR (x >= 1)) AND ((x >= 10) OR (x <= 5)) AND ((x >= 10) OR (x >= 1)) │
│ ) AS a                                                                                                                │
│ WHERE ((x >= 10) OR (x >= 1)) AND ((x >= 10) OR (x <= 5)) AND ((x <= 15) OR (x >= 1)) AND ((x <= 15) OR (x <= 5))     │
│ SETTINGS convert_query_to_cnf = 1                                                                                     │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

可选值：true、false

​

count_matches_stop_at_empty_match

在 countMatches 函数中，一旦模式匹配到零长度内容，就停止计数。

​

cross_to_inner_join_rewrite

如果 WHERE 子句中存在连接表达式，则使用 INNER JOIN 代替逗号/CROSS JOIN。取值：0 - 不重写，1 - 如果可能，则对逗号/CROSS 应用此重写，2 - 强制重写所有逗号 join，cross - 如果可能

​

data_type_default_nullable

允许将列定义中未显式使用修饰符 NULL or NOT NULL 的数据类型设为 Nullable。

可能的值：

• 1 — 列定义中的数据类型默认设置为 Nullable。
• 0 — 列定义中的数据类型默认不设置为 Nullable。

​

decimal_check_overflow

检查 Decimal 算术/比较操作是否溢出

​

deduplicate_blocks_in_dependent_materialized_views

启用或禁用对接收来自 Replicated* 表数据的 materialized view 的去重检查。

可能的值：

• 0 — 禁用。
• 1 — 启用。

启用后，ClickHouse 会对依赖于 Replicated* 表的 materialized view 中的块执行去重。 当插入操作因故障而重试时，此设置有助于确保 materialized view 中不会包含重复数据。

另请参阅

• IN 运算符中的 NULL 处理

​

defer_partition_pruning_after_final

启用时 (默认) ，对于分区键列不属于 sorting key 的表，FINAL 查询会跳过分区裁剪。这是 26.3 引入的、可确保正确性的行为：FINAL 可能需要对主键相同但位于不同分区的行进行去重，而分区裁剪会在不提示的情况下将这些行排除在去重输入之外。

禁用时，即使使用 FINAL 也会应用分区裁剪，从而恢复 26.3 之前的行为。对于在分区列上带有 WHERE 条件的查询，这种方式可能会显著更快，但只有在不同分区中不可能存在主键相同的行时才是正确的——例如事件日志表，其分区列在 insert 时设定，之后永不更改。

此设置仅影响分区键列未包含在 sorting key 中的分区表；对于其他表，始终会应用分区裁剪。

可能的值：

• 0 — 在 FINAL 之前应用分区裁剪 (26.3 之前的行为，更快，但一般情况下不安全) 。
• 1 — 将分区裁剪延后到 FINAL 之后 (默认，确保正确性) 。

​

describe_compact_output

如果为 true，则 DESCRIBE 查询结果中仅包含列名和类型

​

dialect

用于解析查询的方言。

支持的值：

• clickhouse (默认) — 标准 ClickHouse SQL。
• kusto — Kusto 查询语言。需要启用 Experimental 设置 allow_experimental_kusto_dialect。
• prql — PRQL。需要启用 Experimental 设置 allow_experimental_prql_dialect。
• polyglot — 将其他方言 (MySQL、PostgreSQL 等) 的 SQL 转译为 ClickHouse SQL。需要启用 Experimental 设置 allow_experimental_polyglot_dialect。
• promql — PromQL (Prometheus 查询语言) ，基于由 promql_database、promql_table 和 promql_evaluation_time 设置指定的 TimeSeries 表进行计算。
• clickhouse_json — 查询将不作为 SQL 文本处理，而是解释为 JSON AST (parseQueryToJSON 的输出) 。仍可使用普通形式的 SET 查询，以便切换回其他方言。需要启用 Experimental 设置 enable_json_ast_dialect。
• trino — Trino SQL：转换 Trino 语法 (ARRAY[...]、TRY_CAST、UNNEST 等) ，并将 Trino 函数名映射为对应的 ClickHouse 函数。需要启用 Experimental 设置 enable_trino_dialect。

​

discard_query_data

启用后，服务器会跳过向客户端发送查询结果行。查询仍会执行，并在服务器上完整记录，客户端仍会接收其余数据包。

用于影子流量、基准测试和模糊测试。

对次级查询无影响。

仅影响原生 TCP 协议。

​

distinct_overflow_mode

设置当数据量超过某一限制时的处理方式。

可能的值：

• throw：抛出异常 (默认) 。
• break：停止执行查询并返回部分结果，就像源数据已耗尽一样。

​

do_not_merge_across_partitions_select_final

通过避免跨不同分区合并来提升 FINAL 查询的性能。

启用后，在 SELECT FINAL 查询期间，来自不同分区的 parts 不会被合并到一起，而是只会在各个分区内分别进行合并。这在处理分区表时可以显著提升查询性能。

​

dynamic_throw_on_type_mismatch

当使用默认实现对 Dynamic 列应用函数时， 该设置用于控制那些实际类型与函数不兼容的行的处理方式：

• true (默认) — 抛出异常。
• false — 对这些行返回 NULL。

​

enforce_strict_identifier_format

启用后，将只允许包含字母、数字和下划线的标识符。

​

engine_url_skip_empty_files

启用或禁用在 URL 引擎表中跳过空文件。

可能的值：

• 0 — 如果空文件与所请求的格式不兼容，SELECT 会抛出异常。
• 1 — 对于空文件，SELECT 返回空结果。

​

exact_rows_before_limit

启用后，ClickHouse 会为 rows_before_limit_at_least 统计信息提供精确值，但代价是必须将 limit 之前的数据全部读取完毕

​

except_default_mode

设置 EXCEPT 查询的默认模式。可能的值：空字符串、‘ALL’、‘DISTINCT’。如果为空，则未指定模式的查询会抛出异常。

​

exclude_materialize_skip_indexes_on_insert

指定在 INSERT 期间不构建和存储某些跳过索引。被排除的跳过索引仍会在合并期间构建并存储，或通过显式执行 MATERIALIZE INDEX查询来构建并存储。

如果 materialize_skip_indexes_on_insert 为 false，则此设置无效。

示例：

CREATE TABLE tab
(
    a UInt64,
    b UInt64,
    INDEX idx_a a TYPE minmax,
    INDEX idx_b b TYPE set(3)
)
ENGINE = MergeTree ORDER BY tuple();

SET exclude_materialize_skip_indexes_on_insert='idx_a'; -- idx_a will be not be updated upon insert
--SET exclude_materialize_skip_indexes_on_insert='idx_a, idx_b'; -- neither index would be updated on insert

INSERT INTO tab SELECT number, number / 50 FROM numbers(100); -- only idx_b is updated

-- since it is a session setting it can be set on a per-query level
INSERT INTO tab SELECT number, number / 50 FROM numbers(100, 100) SETTINGS exclude_materialize_skip_indexes_on_insert='idx_b';

ALTER TABLE tab MATERIALIZE INDEX idx_a; -- this query can be used to explicitly materialize the index

SET exclude_materialize_skip_indexes_on_insert = DEFAULT; -- reset setting to default

​

execute_exists_as_scalar_subquery

将非关联的 EXISTS 子查询按标量子查询执行。与标量子查询一样，会使用缓存，并对结果进行常量折叠。

Cloud 默认值：0。

​

explain_query_plan_default

EXPLAIN PLAN 使用的默认输出格式。

可能的值：

• pretty (自 26.7 起为默认值) — actions、compact 和 pretty 默认均为 true，生成紧凑、美观且带有 action 注释的计划。
• legacy — 26.7 之前的输出。

在 EXPLAIN 语句中显式指定 actions、compact 或 pretty 选项 (例如，EXPLAIN actions = 0, compact = 0, pretty = 0 SELECT ...) 始终会覆盖此设置。

带有 json = 1 或 distributed = 1 的 EXPLAIN PLAN 无论此设置如何，都会保留 legacy (26.7 之前) 的默认值，除非显式设置了 actions、compact 或 pretty。pretty 输出无法表示 JSON 结果或按分片划分的分布式查询计划，因此这些模式只有以 legacy 形式呈现时才能正确显示。

​

explain_syntax_single_record

将 EXPLAIN SYNTAX 的输出作为单条记录 (包含嵌入的换行符) 返回，而非每行一条记录，从而使结果成为单个可恢复的行 (例如，SELECT count() FROM (EXPLAIN SYNTAX ...) 返回 1) 。

在 EXPLAIN SYNTAX 语句中显式指定 single_record 选项 (例如，EXPLAIN SYNTAX single_record = 0 SELECT ...) 将始终覆盖此设置。

将此设置为 false 可恢复 26.8 之前每行一条记录的输出；或者将 compatibility 设置为任何早于 26.8 的版本。

​

extract_key_value_pairs_max_pairs_per_row

别名: extract_kvp_max_pairs_per_row

extractKeyValuePairs 函数可生成的键值对的最大数量。用于防止占用过多内存。

​

extremes

是否统计极值 (即查询结果各列中的最小值和最大值) 。接受 0 或 1。默认值为 0 (已禁用) 。 更多信息，请参见“极值”一节。

​

fallback_to_stale_replicas_for_distributed_queries

如果最新数据不可用，则强制将查询发送到过时的副本。参见 Replication。

ClickHouse 会从该表的过时副本中选择最合适的一个。

用于从指向复制表的分布式表执行 SELECT 时。

默认值为 1 (已启用) 。

​

file_like_engine_default_partition_strategy

类文件表引擎的默认分区策略。仅适用于路径中不含 glob 或 {_partition_id} 占位符的 CREATE 查询。包含 {_partition_id} 的路径始终使用 wildcard。包含其他 glob 的路径不使用分区策略，并忽略 PARTITION BY。如果此设置为 wildcard，但路径中没有 {_partition_id}，则不使用分区策略；无法将此选择持久化到引擎参数中的表引擎 (例如 HDFS) 将拒绝此类 CREATE。

​

filesystem_prefetches_limit

最大预取数量。零表示不受限制。如果你想限制预取数量，更推荐使用设置 filesystem_prefetches_max_memory_usage

​

filter

以包装子查询的方式为查询添加 WHERE 子句。多个过滤器会使用 AND 组合。HTTP 接口支持多个 filter URL 参数，这些参数会按顺序使用 AND 相互组合，并与此设置的值组合。

这是一项由引擎应用于已解析查询的查询构造设置 (将查询包装为派生表) ，因此可与现有查询组合使用，并适用于所有协议：可通过 HTTP URL 参数、查询内的 SETTINGS 子句或用户 profile 提供。

它会影响产生结果的 SELECT / UNION 查询。对于写入查询 (INSERT … SELECT、CREATE … AS SELECT) ，仅当源 SELECT 在自身的 SETTINGS 子句中指定此设置时才会生效；从 profile 或 session 继承的值，或在 INSERT / CREATE 语句本身中设置的值，不会传播到源 SELECT——这与其他所有设置的非传播规则相同。

filter 不是访问控制机制，不得用作 行级安全策略 或 additional_table_filters 设置的替代方案。它只会在包装子查询的外层添加 WHERE，因此在应用过滤器前，底层数据仍会被读取和处理——查询在处理过程中仍可能观察到被过滤掉的行 (例如，使用 throwIf 通过错误路径泄露信息) 。如需限制用户可访问的行，请使用行级安全或 additional_table_filters。

​

final

自动将 FINAL 修饰符应用到查询中的所有表，以及所有可应用 FINAL 的表，包括连接表、子查询中的表和 分布式表。

可能的值：

• 0 - 已禁用
• 1 - 已启用

示例：

CREATE TABLE test
(
    key Int64,
    some String
)
ENGINE = ReplacingMergeTree
ORDER BY key;

INSERT INTO test FORMAT Values (1, 'first');
INSERT INTO test FORMAT Values (1, 'second');

SELECT * FROM test;
┌─key─┬─some───┐
│   1 │ second │
└─────┴────────┘
┌─key─┬─some──┐
│   1 │ first │
└─────┴───────┘

SELECT * FROM test SETTINGS final = 1;
┌─key─┬─some───┐
│   1 │ second │
└─────┴────────┘

SET final = 1;
SELECT * FROM test;
┌─key─┬─some───┐
│   1 │ second │
└─────┴────────┘

​

finalize_projection_parts_synchronously

启用后，projection parts 会在 INSERT 期间同步完成，从而降低峰值内存占用，但代价是 S3 上传并行度会下降。默认情况下，每个 projection 的输出流都会一直保持打开，直到整个 part (包括所有 projections) 都完成，这样可以让 S3 上传相互重叠，但也会使峰值内存随着 projections 的数量成比例增加。此设置仅影响 INSERT 路径；merge 和变更已经会同步完成 projections。

​

flatten_nested

设置 Nested 列的数据格式。

可能的值：

• 1 — Nested 列会被展平为单独的数组。
• 0 — Nested 列保持为单个元组数组。

用法

如果将此设置设为 0，则可以使用任意层级的嵌套。

示例

查询：

SET flatten_nested = 1;
CREATE TABLE t_nest (`n` Nested(a UInt32, b UInt32)) ENGINE = MergeTree ORDER BY tuple();

SHOW CREATE TABLE t_nest;

结果：

┌─statement───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ CREATE TABLE default.t_nest
(
    `n.a` Array(UInt32),
    `n.b` Array(UInt32)
)
ENGINE = MergeTree
ORDER BY tuple()
SETTINGS index_granularity = 8192 │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

查询：

SET flatten_nested = 0;

CREATE TABLE t_nest (`n` Nested(a UInt32, b UInt32)) ENGINE = MergeTree ORDER BY tuple();

SHOW CREATE TABLE t_nest;

结果：

┌─statement──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ CREATE TABLE default.t_nest
(
    `n` Nested(a UInt32, b UInt32)
)
ENGINE = MergeTree
ORDER BY tuple()
SETTINGS index_granularity = 8192 │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

​

format

覆盖查询的输入和输出 FORMAT。其优先级高于查询中指定的 format 和文件扩展名。对于各自的方向，更具体的 input_format 和 output_format 设置优先于通用的 format 设置。

​

framing_output_format

允许在单个 stream 中复用查询响应的不同部分：数据 chunks、totals 和 extremes、Progress 信息数据包、profile events (指标) 以及 server logs，即 native protocol 支持的所有内容。

帧格式独立于输出格式：它们通过分隔并可能编码这些字节 chunks，来封装任意输出格式生成的字节。所有 data、totals 和 extremes 数据包的载荷拼接后，与不使用 framing 时输出格式生成的内容完全一致。辅助数据包 (Progress 信息、日志、profile events、exceptions) 以 JSON 表示。

有一个特意设计的例外：某些输出格式因无法表示 totals 和 extremes 而在普通输出中省略它们 (JSONCompactEachRow 系列) ，但在 framing 下会将它们写入 totals 和 extremes 数据包。对于此类 formats，仅拼接 data 数据包即可得到与未分帧输出完全相同的结果，而 totals 和 extremes 数据包则携带未分帧输出中没有的额外行。

设置了 send_logs_level 时会包含 server logs；启用 send_profile_events 时会包含 profile events (它们最多每 interactive_delay 微秒发送一次，Progress 信息数据包同样受 interactive_delay 限流) 。

成功的 stream 会以最终的 progress 数据包结束。该数据包携带最终计数器 (result_rows、result_bytes、memory_usage) ，在查询完成日志记录产生的尾随 log 和 profile_events 数据包之后写入，类似于 native protocol 中的最终 Progress 信息数据包。失败时，exception 数据包会成为最后一个数据包；但有一个例外：如果在响应中已生成部分数据包 stream、无法再丢弃时发生失败 (例如数据包写入中途失败、exception 数据包本身发送失败，或响应 stream 在刷新或关闭时失败) ，framing 会以失败关闭的方式处理：stream 会在没有终止 exception 数据包的情况下结束，客户端看到的是截断的响应和中止的 HTTP connection，而不是可解析的终止数据包。部分数据包 stream 之后绝不会追加任何内容，因此普通 HTTP 错误正文绝不会混入其中。

查询仅通过自身的 SETTINGS clause 启用的内容——帧格式、send_logs_level 或 send_profile_events——在查询解析完成前无法得知，因此相应的日志和 profile events 只能从查询执行开始后捕获。只有当设置来自 session 或 URL 时，才能捕获 parse、plan 和 analysis 阶段的日志和 profile events。例如，某个查询在 analysis 期间失败 (如引用未知表) ，且仅在其 SETTINGS clause 中启用 send_logs_level，则只会传递 exception 数据包，不会传递 analysis 阶段的日志；请在 session 或 URL 中设置 send_logs_level 以捕获这些日志。

同样的延迟发现限制也适用于 send_logs_source_regexp：日志队列会在捕获每个条目时按 source 过滤，因此仅在查询自身的 SETTINGS clause 中设置的 regexp 会从查询执行开始后生效。parse、plan 和 analysis 阶段的 log 数据包会按该设置的 session 或 URL 值过滤 (如果未在其中设置，则不过滤) ，因此其中可能包含不匹配查询级别 regexp 的 sources；反之，被更严格的 session 或 URL regexp 丢弃的条目，也无法通过更宽泛的查询级别 regexp 恢复。请在 session 或 URL 中设置 send_logs_source_regexp，以过滤整个查询生命周期。

该设置目前仅适用于 HTTP protocol，其他 interfaces 会忽略它。

可能的值：

• None - 将所有适用内容 (数据、totals、extremes、Progress 信息) 透明地传递给输出格式，并忽略所有不适用内容 (指标、日志) ，因此默认情况下即可正常工作。
• EventStream - 将数据包封装为 HTTP 服务器发送事件 (text/event-stream) 。每个数据包都会作为具有相应名称的事件发送：data、totals、extremes、progress、log、profile_events、exception。Progress 信息和其他辅助数据包以 JSON 格式发送。由于服务器发送事件是一种将换行符 (包括回车符 \r) 视为分隔符的文本协议，格式化数据块会经过 base64 编码并置于事件的单个 data 字段中；解码后即可得到包含所有换行符的完整格式化载荷。Content-Type 包含 payload=base64 参数以表明这一点。通过这种方式，任何输出格式都可进行字节精确传输，无论是文本还是二进制格式。
• JSONEachPacketBase64 - 每个数据包都是单独一行中的 JSON 对象，格式化数据经过 base64 编码，例如 {"packet":"data","data":"eyJ4IjoxfQo="}。适用于二进制输出格式。
• JSONEachPacketString - 每个数据包都是单独一行中的 JSON 对象，格式化数据会放入字符串中，例如 {"packet":"data","data":"{\"x\":1}\n"}。

JSONEachPacketString 会将载荷字节放入 JSON 字符串中，而不对其进行验证或重新编码。String 和 FixedString 列可存储任意字节，因此文本输出格式 (如 JSONEachRow、TSV 或 CSV) 可能会为此类值输出无效的 UTF-8——正如 ClickHouse’ 自身的 JSONEachRow 在默认 output_format_json_validate_utf8 = 0 时所做的一样——因此生成的 NDJSON 流不保证是有效的 UTF-8。若要以字节精确方式传输任意字节，请使用 JSONEachPacketBase64。

示例：

curl "http://localhost:8123/?framing_output_format=JSONEachPacketString" -d "SELECT number FROM numbers(3) FORMAT JSONEachRow"

结果：

{"packet":"data","data":"{\"number\":\"0\"}\n{\"number\":\"1\"}\n{\"number\":\"2\"}\n"}
{"packet":"profile_events","profile_events":[{"host_name":"localhost","current_time":"2026-07-11 00:00:00","thread_id":"0","type":"increment","name":"SelectedRows","value":"3"}]}
{"packet":"progress","progress":{"read_rows":"3","read_bytes":"24","total_rows_to_read":"3","result_rows":"3","result_bytes":"24","elapsed_ns":"1265958"}}

​

fsync_metadata

控制在写入 .sql 文件时是否启用 fsync。默认启用。

如果 server 中有数百万个持续创建和删除的小表，禁用此项是合理的。

​

functions_h3_default_if_invalid

如果为 false，h3 函数 (例如 h3CellAreaM2) 在输入无效时会抛出异常。如果为 true，则返回 0 或默认值。

​

geo_distance_returns_float64_on_float64_arguments

如果 geoDistance、greatCircleDistance 和 greatCircleAngle 这三个函数的四个参数均为 Float64，则返回 Float64，并在内部计算中使用双精度。在此前的 ClickHouse 版本中，这些函数始终返回 Float32。

​

geotoh3_argument_order

函数 geoToH3 在设置为 lon_lat 时接受 (lon, lat)，在设置为 lat_lon 时接受 (lat, lon)。

​

glob_expansion_max_elements

允许的地址最大数量 (适用于外部存储、表函数等) 。

​

h3togeo_lon_lat_result_order

如果为 true，函数 h3ToGeo 返回 (lon, lat)；否则返回 (lat, lon)。

​

handshake_timeout_ms

握手过程中，从副本接收 Hello 数据包的超时时间 (毫秒) 。

​

hedged_connection_timeout_ms

对冲请求中与副本建立连接时的连接超时时间

​

highlight_max_matches_per_row

设置 highlight 函数中每行高亮匹配的最大数量。可用于在大型文本中高亮高度重复的模式时，防止内存占用过高。

可能的值：

• 正整数。

​

hnsw_candidate_list_size_for_search

搜索向量相似度索引时使用的动态候选列表大小，也称为“ef_search”。

​

hsts_max_age

HSTS 的过期时长。0 表示禁用 HSTS。

​

idle_connection_timeout

空闲 TCP 连接在达到指定秒数后自动关闭的超时时间。

可能的值：

• 正整数 (0 表示立即关闭，即 0 秒后关闭) 。

​

inject_random_order_for_select_without_order_by

如果启用，会为不带 ORDER BY 子句的 SELECT 查询注入 ‘ORDER BY rand()’。 仅在子查询深度 = 0 时生效。子查询和 INSERT INTO … SELECT 不受影响。 如果顶层结构是 UNION，则会分别为其所有子项独立注入 ‘ORDER BY rand()’。 仅对测试和开发有用 (缺少 ORDER BY 是非确定性查询结果的一个来源) 。

​

input_format

覆盖查询的输入格式，其优先级高于查询中指定的格式。

​

interactive_delay

以微秒为单位的时间间隔，用于检查请求执行是否已取消，并发送 Progress 信息。

​

intersect_default_mode

设置 INTERSECT 查询的默认 mode。可能的值：空字符串、‘ALL’、‘DISTINCT’。如果为空，未指定 mode 的查询将抛出异常。

​

least_greatest_legacy_null_behavior

如果启用，当函数 least 和 greatest 的任一参数为 NULL 时，将返回 NULL。

​

legacy_column_name_of_tuple_literal

对于大型 Tuple 字面量，在其列名中列出所有元素名称，而不是使用哈希。此设置仅为兼容性而存在。在将集群从低于 21.7 的版本滚动更新到更高版本时，建议将其设为 ‘true’。

​

legacy_join_size_limits_trigger_spilling

针对连接中在磁盘上执行的那部分，恢复 max_rows_in_join 和 max_bytes_in_join 在落盘阈值成为触发条件之前的行为：达到其中任意一项会让连接继续落盘，而不是中止查询。 此时 join_algorithm = 'grace_hash' 仅依据这两项落盘，并完全忽略 max_bytes_before_external_join (取值为零时也一样) 。hash / parallel_hash 仍在达到落盘阈值时转入磁盘，之后只要触及这两项中的任意一项即落盘；其内存阶段则与以往一样，仍将这两项视为硬性上限。

适用于按这两项设置的旧含义编写的查询；compatibility 会自动启用该行为。

早于该设置的服务器只会采用旧含义，且无法更改，因此当 serialize_query_plan = 1 时，落盘行为依赖新含义的连接根本不会被发送到这类服务器：查询会直接失败，而不是在另一套契约下悄然运行。启用该设置可让这些查询在两个版本之间都正常工作，且两端都使用旧含义。

​

limit

设置从查询结果中获取的最大行数。它会调整 LIMIT 子句指定的值。该值会透传给 LIMIT，并接受 LIMIT 支持的所有值，包括负值 (从结果末尾开始计数) 和 (0, 1) 范围内的小数 (表示结果的占比) 。

可能的值：

• 0 — 不限制行数。
• 正整数 — 精确的行数。
• 负整数 — 返回最后 N 行。
• 开区间 (0, 1) 内的实数 — 返回结果中相应比例的数据。

此设置会影响产生结果的 SELECT / UNION 查询。对于写入查询 (INSERT … SELECT、CREATE … AS SELECT) ，只有当源 SELECT 在其自身的 SETTINGS 子句中指定此设置时才会生效；从 profile 或 session 继承的值，或在 INSERT / CREATE 语句本身设置的值，都不会传播到源 SELECT。这与其他所有设置适用的“不传播”规则相同。

​

load_marks_asynchronously

在后台线程池中异步加载 MergeTree 标记 (参见服务器设置 load_marks_threadpool_pool_size) ，从而并行加载所有流的标记。否则，标记会按流依次同步加载；对于具有多个子流的列 (如 JSON) ，在远程磁盘上这样做速度较慢。

​

lock_acquire_timeout

定义锁请求在失败前等待的秒数。

锁超时用于防止对表执行读/写操作时发生死锁。当超时时间到期且锁请求失败时，ClickHouse server 会抛出异常 “Locking attempt timed out! Possible deadlock avoided. Client should retry.”，错误代码为 DEADLOCK_AVOIDED。

Possible values:

• 正整数 (单位：秒) 。
• 0 — 不设置锁超时。

​

low_priority_query_wait_time_ms

在采用查询优先级机制时 (参见设置 priority) ，低优先级查询会等待高优先级查询完成。此设置指定等待时长。

​

make_distributed_plan

生成分布式查询计划。

启用后，会自动调整控制分布式查询计划暂不支持功能的相关设置：

• enable_parallel_replicas = 0 和 automatic_parallel_replicas_mode = 0 — 分布式计划自行分配工作；
• correlated_subqueries_use_in_memory_buffer = 0；
• compile_expressions = 0；
• query_plan_direct_read_from_text_index = 0。

​

merge_table_max_tables_to_look_for_schema_inference

创建未显式指定 schema 的 Merge 表，或使用 merge 表函数时，会将 schema 推断为匹配表的并集，数量不超过指定值。 如果表的数量更多，则只会基于前面指定数量的表来推断 schema。

​

mongodb_throw_on_unsupported_query

如果启用，当无法构建 MongoDB 查询时，MongoDB 表会报错。否则，ClickHouse 会读取整个表并在本地处理。

​

multiple_joins_try_to_keep_original_names

在多个 JOIN 重写时，不向顶层表达式列表添加别名

​

normalize_function_names

将函数名称规范化为其标准名称

​

offset

设置查询返回行之前要跳过的行数。它会调整由 OFFSET 子句设置的偏移量。该值会直接传递给 OFFSET，可接受 OFFSET 支持的所有值，包括负值和 (0, 1) 区间内的小数。

可能的值：

• 0 — 不跳过任何行。
• 正整数。
• 负整数。
• 开区间 (0, 1) 内的实数 — 跳过结果中相应比例的行。

示例

输入表：

CREATE TABLE test (i UInt64) ENGINE = MergeTree() ORDER BY i;
INSERT INTO test SELECT number FROM numbers(500);

查询：

SET limit = 5;
SET offset = 7;
SELECT * FROM test LIMIT 10 OFFSET 100;

结果：

┌───i─┐
│ 107 │
│ 108 │
│ 109 │
└─────┘

此设置会影响产生结果的 SELECT / UNION 查询。对于写入查询 (INSERT … SELECT、CREATE … AS SELECT) ，只有当源 SELECT 在自身的 SETTINGS 子句中指定了该设置时才会生效；从 profile 或会话继承的值，或在 INSERT / CREATE 语句本身中设置的值，都不会传播到源 SELECT——这与其他任何设置的非传播规则相同。

​

order

将 ORDER BY 子句作为外层子查询添加到查询中。接受任意表达式列表。

这是引擎在已解析的查询上应用的查询构造设置 (将查询包装为派生表) ，因此可与现有查询组合使用，并适用于所有协议：可通过 HTTP URL 参数、查询内的 SETTINGS 子句或用户 profile 提供。

它会作用于产生结果的 SELECT / UNION 查询。对于写入查询 (INSERT … SELECT、CREATE … AS SELECT) ，只有源 SELECT 在自身的 SETTINGS 子句中包含该设置时才会生效；从 profile 或 会话 继承的值，或在 INSERT / CREATE 语句本身中设置的值，不会传播到源 SELECT——这与其他所有设置遵循相同的非传播规则。

​

output_format

覆盖查询的输出格式。其优先级高于查询中指定的格式、文件扩展名指定的格式或通过 default_format 指定的格式。

​

页码

设置分页结果的页码。等同于 offset = limit * (page - 1)。仅当设置了 limit 且未设置 offset 时才能指定。页码从 1 开始计数。与 limit 和 offset 一样，支持负值和小数值。

这是引擎应用于已解析查询的查询构造设置 (会将查询包装为派生表) ，因此可与现有查询组合，并适用于所有协议：可通过 HTTP URL 参数、查询内的 SETTINGS 子句或用户 profile 提供。

它会影响产生结果的 SELECT / UNION 查询。对于写入查询 (INSERT … SELECT、CREATE … AS SELECT) ，仅当源 SELECT 在其自身的 SETTINGS 子句中包含此设置时才会生效；从 profile 或会话继承的值，或在 INSERT / CREATE 语句本身中设置的值，都不会传播到源 SELECT——这与任何其他设置适用的非传播规则相同。

​

paimon_target_snapshot_id

用于 Paimon 增量模式的查询级定向快照读取。当 >0 时，读取器只会拉取指定 snapshot_id 的增量， 而不会推进已提交的水位线。 默认值：-1 (禁用)

​

parallelize_output_from_storages

对存储读取步骤的输出进行并行化。如果条件允许，可在从存储读取后立即并行执行查询处理

​

partial_result_on_first_cancel

允许查询在被取消后返回部分结果。

​

per_part_index_stats

记录各个 part 的索引统计信息

​

poll_interval

在服务器端的查询等待循环中阻塞指定秒数。

​

polyglot_dialect

polyglot 转译器的源 SQL 方言 (例如 ‘sqlite’、‘mysql’、‘postgresql’、‘snowflake’、‘duckdb’) 。

​

postgresql_fault_injection_probability

使内部 (用于复制) 的 PostgreSQL 查询失败的近似概率。有效值范围为区间 [0.0f, 1.0f]

​

predicate_statistics_sample_rate

将谓词选择性统计信息收集到 system.predicate_statistics_log。设置为 N > 0 时，将按查询 ID 对约 1/N 的查询进行采样。0 表示禁用。

​

prefetch_buffer_size

用于从文件系统读取数据的预取缓冲区最大大小。超过 256 MiB 的值会被限制为 256 MiB，因为读取缓冲区不需要更大。

​

print_pretty_type_names

允许在 DESCRIBE 查询和 toTypeName() 函数中，以带缩进的美观格式输出深层嵌套的类型名称。

示例：

CREATE TABLE test (a Tuple(b String, c Tuple(d Nullable(UInt64), e Array(UInt32), f Array(Tuple(g String, h Map(String, Array(Tuple(i String, j UInt64))))), k Date), l Nullable(String))) ENGINE=Memory;
DESCRIBE TABLE test FORMAT TSVRaw SETTINGS print_pretty_type_names=1;

a   Tuple(
    b String,
    c Tuple(
        d Nullable(UInt64),
        e Array(UInt32),
        f Array(Tuple(
            g String,
            h Map(
                String,
                Array(Tuple(
                    i String,
                    j UInt64
                ))
            )
        )),
        k Date
    ),
    l Nullable(String)
)

​

priority

查询的priority。1 表示最高priority，值越大priority越低；0 表示不使用priority。

​

push_external_roles_in_interserver_queries

启用在执行查询时将用户角色从发起节点推送到其他节点。

​

query_metric_log_interval

用于收集单个查询的 query_metric_log 的时间间隔 (以毫秒为单位) 。

如果设置为任意负值，则会采用 query_metric_log 设置 中的 collect_interval_milliseconds 值；如果未设置，则默认使用 1000。

要禁用单个查询的收集，请将 query_metric_log_interval 设置为 0。

默认值：-1

​

queue_max_wait_ms

如果并发请求数超过最大值，请求在队列中的等待时间。

​

rabbitmq_max_wait_ms

重试前，从 RabbitMQ 读取的等待时间。

​

readonly

0 - 无只读限制。1 - 仅允许读取请求，以及修改明确允许更改的设置。2 - 仅允许读取请求，以及修改除 readonly 设置外的其他设置。

​

recursive_cte_max_steps_in_type_inference

在递归 CTE 中推断列类型时允许的最大迭代次数。列类型的确定方式是：在 UNION ALL 的非递归部分和递归部分之间反复应用 getLeastSupertype，直到结果收敛。设为 0 可禁用类型拓宽，仅使用非递归部分的类型。

​

regexp_max_matches_per_row

设置单个正则表达式在每行中的最大匹配次数。使用 extractAllGroupsHorizontal 函数中的贪婪正则表达式时，可用此设置防止内存占用过高。

可能的值：

• 正整数。

​

reject_expensive_hyperscan_regexps

拒绝那些在使用 hyperscan 进行求值时可能导致较高开销的模式 (由于 NFA 状态爆炸)

​

remerge_sort_lowered_memory_bytes_ratio

如果 remerge 后内存使用量未按该比率降低，则会禁用 remerge。

​

remote_read_min_bytes_for_seek

远程读取 (URL、S3) 执行寻道而非以 ignore 方式读取时所需的最小字节数。

​

rename_files_after_processing

• 类型： String

• 默认值： 空字符串

此设置用于为由 file 表函数处理的文件指定重命名模式。设置此选项后，file 表函数读取的所有文件都会在处理成功后，按照包含占位符的指定模式重命名。

重命名会写入源文件，因此，使用此选项读取文件的查询除需要 READ ON FILE 外，还需要 WRITE ON FILE 授权。DESCRIBE 不会构建用于重命名的数据读取管道，因此只需要 READ ON FILE。

​

占位符

• %a — 原始文件的完整文件名 (例如 "sample.csv") 。
• %f — 不含扩展名的原始文件名 (例如 "sample") 。
• %e — 带点号的原始文件扩展名 (例如 ".csv") 。
• %t — 时间戳 (以微秒为单位) 。
• %% — 百分号 ("%") 。

​

示例

• 选项：--rename_files_after_processing="processed_%f_%t%e"

• 查询：SELECT * FROM file('sample.csv')

如果 sample.csv 读取成功，文件将重命名为 processed_sample_1683473210851438.csv

​

replication_wait_for_inactive_replica_timeout

指定等待非活动副本执行 ALTER、OPTIMIZE 或 TRUNCATE 查询的时间 (以秒为单位) 。

可能的值：

• 0 — 不等待。
• 负整数 — 无限期等待。
• 正整数 — 要等待的秒数。

​

reserve_memory

用于工作负载调度。该设置指定在单台服务器上运行查询时预留的最小 RAM 量。预留通过 WORKLOAD 层级，基于查询设置 workload 的值进行。 如果该工作负载没有足够的可用内存，查询将无法启动，并会保持在待处理状态，直到能够满足预留要求。 值为 0 表示不预留内存。 仅当创建了 MEMORY RESERVATION 资源时，此设置才会生效。

​

restore_replicated_merge_tree_to_shared_merge_tree

在 RESTORE 时，将表引擎从 ReplicatedMergeTree 替换为 SharedMergeTree。

Cloud 默认值：1。

​

result_overflow_mode

设置当结果量超过某个限制时的处理方式。

可能的值：

• throw：抛出异常 (默认) 。
• break：停止执行查询并返回部分结果，就像 源数据已经耗尽一样。

使用 ‘break’ 与使用 LIMIT 类似。Break 只会在 块级别中断执行。这意味着返回的行数会大于 max_result_rows，且是 max_block_size 的倍数，并且取决于 max_threads。

示例

Query

SET max_threads = 3, max_block_size = 3333;
SET max_result_rows = 3334, result_overflow_mode = 'break';

SELECT *
FROM numbers_mt(100000)
FORMAT Null;

Result

6666 rows in set. ...

​

resumable_backup_from_snapshot

启用可恢复的 BACKUP FROM SNAPSHOT：失败后可重新执行，而无需重新复制已完成批次中的 条目。仅适用于 ClickHouse Cloud 中目录形式的 S3 和 AzureBlobStorage 目标端。在不支持 BACKUP FROM SNAPSHOT 的 ClickHouse 开源构建中启用此设置， 会使 BACKUP 因 WRONG_BACKUP_SETTINGS 而失败。

​

rows_before_aggregation

启用后，ClickHouse 将提供 rows_before_aggregation 统计信息的精确值，表示聚合前读取的行数

​

run_query_in_background

启用后，服务器会在后台调度查询，立即返回一个空的成功结果，并继续运行查询直至完成，不受连接状态影响。

后台查询不会在服务器重启后保留。关闭服务器时，它遵循与前台查询相同的服务器设置：shutdown_wait_unfinished_queries 决定取消查询还是等待其完成 (无论哪种情况，队列中的条目都会被丢弃，且不会写入 system.query_log) ，shutdown_wait_unfinished 则限制服务器的最长等待时间。

可通过其 query_id 跟踪查询：运行期间可在 system.processes 中查看；查询完成且查询日志条目已刷新后，可在 system.query_log 中查看。

适用于通过原生 TCP 和 HTTP 协议接收的查询。通过 HTTP 时，将该设置作为 URL 参数传递。无法通过 SET 更改；可按查询启用，或在用户或 profile 级别启用。

主要用例是长时间运行的 INSERT ... SELECT，以确保客户端连接断开时查询不会丢失。

​

secondary_indices_enable_bulk_filtering

为索引启用批量过滤算法。通常它的效果会更好，但我们保留此设置以便进行兼容性控制。

​

select

将查询包装为带有显式 SELECT 表达式列表的子查询。非空时，会将产生结果的查询包装为 SELECT <expr_list> FROM (<query>)。

这是引擎应用于已解析查询的查询构造设置 (将其包装为派生表) ，因此可与现有查询组合使用，并适用于所有协议：可通过 HTTP URL 参数、查询内的 SETTINGS 子句或用户 profile 提供。

它会影响产生结果的 SELECT / UNION 查询。对于写入查询 (INSERT … SELECT、CREATE … AS SELECT) ，仅当源 SELECT 在其自身的 SETTINGS 子句中指定该设置时才会生效；从 profile 或 会话 继承的值，或在 INSERT / CREATE 语句本身上设置的值，不会传播到源 SELECT——这与其他任何设置均适用的不传播规则相同。

​

select_sequential_consistency

此设置在 SharedMergeTree 和 ReplicatedMergeTree 中的行为不同。有关 select_sequential_consistency 在 SharedMergeTree 中的行为的更多信息，请参阅 SharedMergeTree 一致性。

为 SELECT 查询启用或禁用顺序一致性。要求禁用 insert_quorum_parallel (默认情况下启用) 。

Possible values:

• 0 — 禁用。
• 1 — 启用。

Usage

启用顺序一致性后，ClickHouse 只允许客户端在包含此前所有使用 insert_quorum 执行的 INSERT 查询数据的副本上执行 SELECT 查询。如果客户端访问的是不完整的副本，ClickHouse 将抛出异常。SELECT 查询不会包含尚未写入到法定数量副本中的数据。

启用 insert_quorum_parallel (默认值) 时，select_sequential_consistency 将不起作用。这是因为并行 INSERT 查询可能会写入不同的法定数量副本集合，因此无法保证某一个副本已接收到所有写入。

See also:

• insert_quorum
• insert_quorum_timeout
• insert_quorum_parallel

​

session_query_ids_history_size

通过 system.session_query_ids 系统表暴露的会话本地历史记录中最多保留的查询 ID 数量。 会话中执行的每个非内部查询，其查询 ID 都会在查询开始时记录其中；当历史记录超出该大小时，最早的记录会被优先淘汰。

该值在查询开始时、查询被解析之前读取，因此查询自身的 SETTINGS 子句不会影响该查询是否被记录；请改用 SET、HTTP URL 参数或 settings profile。

可能的值：

• 正整数。
• 0 — 禁用记录；此前已记录的条目仍保留在表中。

​

session_timezone

设置当前 session 或查询的隐式时区。 隐式时区是应用于未显式指定时区的 DateTime/DateTime64 类型值的时区。 此设置的优先次序高于全局配置的 (server 级别) 隐式时区。 值为 ” (空字符串) 表示当前 session 或查询的隐式时区与server 时区相同。

你可以使用函数 timeZone() 和 serverTimeZone() 获取会话时区和 server 时区。

可能的值：

• system.time_zones 中的任意时区名称，例如 Europe/Berlin、UTC 或 Zulu

示例：

SELECT timeZone(), serverTimeZone() FORMAT CSV

"Europe/Berlin","Europe/Berlin"

SELECT timeZone(), serverTimeZone() SETTINGS session_timezone = 'Asia/Novosibirsk' FORMAT CSV

"Asia/Novosibirsk","Europe/Berlin"

将会话时区 ‘America/Denver’ 赋给内部未显式指定时区的日期时间：

SELECT toDateTime64(toDateTime64('1999-12-12 23:23:23.123', 3), 3, 'Europe/Zurich') SETTINGS session_timezone = 'America/Denver' FORMAT TSV

1999-12-13 07:23:23.123

并非所有解析 DateTime/DateTime64 的函数都会遵循 session_timezone。这可能会导致一些难以察觉的错误。 请参见下面的示例和说明。

CREATE TABLE test_tz (`d` DateTime('UTC')) ENGINE = Memory AS SELECT toDateTime('2000-01-01 00:00:00', 'UTC');

SELECT *, timeZone() FROM test_tz WHERE d = toDateTime('2000-01-01 00:00:00') SETTINGS session_timezone = 'Asia/Novosibirsk'
0 rows in set.

SELECT *, timeZone() FROM test_tz WHERE d = '2000-01-01 00:00:00' SETTINGS session_timezone = 'Asia/Novosibirsk'
┌───────────────────d─┬─timeZone()───────┐
│ 2000-01-01 00:00:00 │ Asia/Novosibirsk │
└─────────────────────┴──────────────────┘

这是由于解析流程不同所致：

• 第一个 SELECT 查询中，未显式指定 time zone 的 toDateTime() 会遵循 session_timezone 设置和全局 time zone。
• 在第二个查询中，日期时间是从 String 解析而来，并继承现有列 d 的类型和 time zone。因此，session_timezone 设置和全局 time zone 都不会生效。

另请参见

• timezone

​

set_overflow_mode

设置当数据量超过某个限制时的处理方式。

可能的值：

• throw：抛出异常 (默认值) 。
• break：停止执行查询并返回部分结果，就像 源数据已经耗尽一样。

​

single_join_prefer_left_table

对于单个 JOIN，标识符存在歧义时优先使用左表

​

skip_redundant_aliases_in_udf

为简化用户自定义函数的使用，冗余别名不会在其中使用，而是会被替换。

可能的值：

• 1 — 在 UDFs 中跳过 (替换) 这些别名。
• 0 — 在 UDFs 中不跳过 (替换) 这些别名。

示例

启用和禁用的区别：

查询：

SET skip_redundant_aliases_in_udf = 0;
CREATE FUNCTION IF NOT EXISTS test_03274 AS ( x ) -> ((x + 1 as y, y + 2));

EXPLAIN SYNTAX SELECT test_03274(4 + 2);

结果：

SELECT ((4 + 2) + 1 AS y, y + 2)

查询：

SET skip_redundant_aliases_in_udf = 1;
CREATE FUNCTION IF NOT EXISTS test_03274 AS ( x ) -> ((x + 1 as y, y + 2));

EXPLAIN SYNTAX SELECT test_03274(4 + 2);

结果：

SELECT ((4 + 2) + 1, ((4 + 2) + 1) + 2)

​

sleep_after_receiving_query_ms

TCPHandler 收到查询后休眠的时长

​

snappy_mode

控制在通用文件 I/O 路径 (如 file 和 url) 中，snappy 压缩所使用的传输格式。HTTP Content-Encoding: snappy 始终使用 framing 格式，并会忽略此设置。

请注意，单次调用 snappy::Compress 生成的原始 snappy 块格式 (例如由 SnappyBasicReadBuffer 处理的 Prometheus 远程协议载荷) 属于另一种特定于协议的传输格式，不受此设置控制。

可能的值：

• basic — Hadoop snappy 块格式。兼容 Hadoop 读写的文件。支持读取和写入。
• framed — Snappy framing 格式，即 Google 定义的标准流式格式。支持读取和写入。

​

sort

将简单的 ORDER BY 子句作为外层子查询添加到查询中。接受以逗号分隔的标识符列表或按位置引用的列 (正整数) ，并可带有可选的 + (ASC) 或 - (DESC) 前缀。示例：sort=a,-b 按 a 升序、b 降序排序；sort=1,-2 按第一列升序、第二列降序排序。不能与 order 一起使用。

这是引擎作用于已解析查询的查询构造设置 (将其包装为派生表) ，因此可与现有查询组合使用，并适用于所有协议：可通过 HTTP URL 参数、查询内的 SETTINGS 子句或用户 profile 提供。

它会影响产生结果的 SELECT / UNION 查询。对于写入查询 (INSERT … SELECT、CREATE … AS SELECT) ，仅当源 SELECT 在其自身的 SETTINGS 子句中指定该设置时才会生效；从 profile 或会话继承的值，或在 INSERT / CREATE 语句本身中设置的值，都不会传播到源 SELECT——这与其他任何设置适用的非传播规则相同。

​

sort_overflow_mode

设置在排序前接收的行数超过某个限制时的处理方式。

可能的值：

• throw：抛出异常。
• break：停止执行查询并返回部分结果。

​

splitby_max_substrings_includes_remaining_string

控制带有参数 max_substrings > 0 的 splitBy*() 函数是否会将剩余字符串包含在结果数组的最后一个元素中。

可能的值：

• 0 - 剩余字符串不会包含在结果数组的最后一个元素中。
• 1 - 剩余字符串会包含在结果数组的最后一个元素中。这是 Spark 的 split() 函数和 Python 的 string.split() 方法的行为。

​

statistics_max_set_size_for_exact_selectivity_estimation

IN 运算符右侧集合的最大大小。对于不超过该大小的集合，选择性估算器会推导出该集合覆盖的精确范围。推导这些范围需要为每个元素分配一个 Field、进行一次排序，并对每个元素执行一次统计信息探测；对于大型集合，这些操作会成为查询计划的主要开销。超过此限制后，估算器会改为根据集合大小及其边界范围推导选择性，只需对集合进行一次线性遍历，无需排序或逐元素执行统计信息探测。零表示无限制。

​

stop_refreshable_materialized_views_on_startup

在服务器启动时，阻止调度可刷新materialized view，效果等同于执行 SYSTEM STOP VIEWS。之后，你可以手动使用 SYSTEM START VIEWS 或 SYSTEM START VIEW <name> 启动它们。此设置也适用于新创建的视图。对不可刷新的 materialized view 无效。

​

tcp_keep_alive_timeout

连接在 TCP 开始发送 keepalive 探测之前，需保持空闲的时间 (以秒为单位)

​

temporary_data_in_cache_reserve_space_wait_lock_timeout_milliseconds

为文件系统缓存中的临时数据预留空间时，锁定缓存的等待时间

​

throw_if_no_data_to_insert

允许或禁止空 INSERT，默认启用 (空插入时会抛出错误) 。仅适用于通过 ClickHouse 客户端 或 gRPC 接口 执行的 INSERT。

​

time_series_prefer_recent_samples_table

当请求的整个时间范围完全落在近期样本表的生存时间 (TTL) 窗口内时，从 TimeSeries 表的近期样本表而非主样本表读取数据 (请参阅 TimeSeries 表引擎的 recent_samples_ttl_seconds 设置) 。

​

timeout_before_checking_execution_speed

在指定的秒数过去后，检查执行速度是否过慢 (不低于 min_execution_speed) 。

​

transfer_overflow_mode

设置当数据量超过某个限制时的处理方式。

可能的值：

• throw：抛出异常 (默认) 。
• break：停止执行查询并返回部分结果，仿佛 源数据已经耗尽。

​

transform_null_in

为 IN 运算符启用 NULL 值之间的相等比较。

默认情况下，NULL 值不能参与比较，因为 NULL 表示未定义的值。因此，比较 expr = NULL 必须始终返回 false。启用此设置后，对于 IN 运算符，NULL = NULL 会返回 true。

可能的值：

• 0 — IN 运算符中对 NULL 值的比较返回 false。
• 1 — IN 运算符中对 NULL 值的比较返回 true。

示例

以 null_in 表为例：

┌──idx─┬─────i─┐
│    1 │     1 │
│    2 │  NULL │
│    3 │     3 │
└──────┴───────┘

查询：

SELECT idx, i FROM null_in WHERE i IN (1, NULL) SETTINGS transform_null_in = 0;

结果：

┌──idx─┬────i─┐
│    1 │    1 │
└──────┴──────┘

查询：

SELECT idx, i FROM null_in WHERE i IN (1, NULL) SETTINGS transform_null_in = 1;

结果：

┌──idx─┬─────i─┐
│    1 │     1 │
│    2 │  NULL │
└──────┴───────┘

另请参见

• IN 运算符中的 NULL 处理

​

traverse_shadow_remote_data_paths

查询 system.remote_data_paths 时，除实际表数据外，也遍历冻结数据 (shadow 目录)

​

union_default_mode

设置用于合并 SELECT 查询结果的模式。只有在使用 UNION 且未显式指定 UNION ALL 或 UNION DISTINCT 时，此设置才会生效。

可能的值：

• 'DISTINCT' — ClickHouse 在合并查询结果时会去除重复行。
• 'ALL' — ClickHouse 在合并查询结果时会保留所有行，包括重复行。
• '' — 与 UNION 一起使用时，ClickHouse 会引发异常。

示例请参见 UNION。

​

unknown_packet_in_send_data

在第 N 个数据包处发送未知数据包，而不是发送数据

​

variant_throw_on_type_mismatch

当使用默认实现对 Variant 列应用函数时， 控制实际类型与该函数不兼容的行应如何处理：

• true (默认) — 抛出异常。
• false — 改为对这些行返回 NULL。

​

wait_changes_become_visible_after_commit_mode

等待已提交的更改在最新快照中变为可见

​

workload

访问资源时使用的 workload 名称

​

workload_admission_timeout_ms

查询等待 workload 调度准入的最长时间，超过该时间查询将直接失败而不会开始执行。 该时间涵盖获取 query slot (来自 CREATE RESOURCE ... (QUERY) resource，受该 workload 的 max_concurrent_queries 限制) 与获取 memory reservation (来自 CREATE RESOURCE ... (MEMORY RESERVATION) resource，并配合 reserve_memory 设置) 两部分的合计等待时长。二者均在查询开始运行前完成获取，因此这是限制该执行前等待时间的唯一方式：此时 max_execution_time 尚未生效，因为查询还未开始。

超时后，查询会根据其所等待的资源返回两种不同错误之一：等待 query slot 时为 QUERY_SLOT_ACQUISITION_TIMEOUT，等待 memory reservation 时为 MEMORY_RESERVATION_ACQUISITION_TIMEOUT。

可能的值：

• 正整数 — 超时时间，单位为毫秒。
• 0 — 无限超时：查询将无限期等待准入 (默认值) 。但当达到该 workload 的 max_waiting_queries 限制时，查询仍会被立即拒绝。

​

write_full_path_in_iceberg_metadata

将完整路径 (包括 S3://) 写入 Iceberg 元数据文件。

​

zstd_window_log_max

允许选择 ZSTD 的最大 window log (不适用于 MergeTree 家族)