const` 的谓词（以及等价的 `ifNull` 形式，或常量位于左侧的情况）重写为析取表达式，以便使用每个 `a_i` 上的主键和跳过索引。还支持部分常量形式，例如 `coalesce(a, 42, b)` 和 `coalesce(a, b, 42)`。"}]}]} />
允许 MergeTree 主键和跳过索引对涉及 `coalesce` 或 `ifNull` 的 `WHERE`/`PREWHERE` 谓词进行粒度剪枝。若未启用此设置，这类谓词对索引分析来说是“不透明”的，无法用于剪枝，因此即使某些粒度不可能匹配，仍然会被读取。此设置只影响会读取哪些粒度；查询结果不会变化，因为行仍会由原始谓词过滤。
在索引分析之前，会重写两种谓词形态：
* 与 `coalesce`/`ifNull` 比较的谓词，例如 `coalesce(a, b) = 5`，会被重写为析取表达式，以便每个 argument 上的索引都可用于剪枝：`a = 5 OR (a IS NULL AND b = 5)`；如果参数更多，则会继续扩展。
* 直接将带有假值 (零) 常量默认值的 `coalesce`/`ifNull` 用作条件时，例如 `ifNull(a = 5, 0)` 或 `coalesce(a = 5, 0)`，会解包为其内部谓词 `a = 5`。这类 wrapper 会将内部谓词的三值结果折叠为确定的布尔值 (将 `NULL` 映射为 `false`) 。
## allow\_limit\_by\_partitions\_independently
当分区表达式是 `LIMIT BY` 列的确定性函数时，可在单独的线程上按分区独立执行 `LIMIT BY`。
## allow\_materialized\_view\_with\_bad\_select
允许使用引用不存在表或列的 SELECT 查询来 CREATE MATERIALIZED VIEW。该查询在语法上仍必须有效。不适用于可刷新的 MV。如果需要根据 SELECT 查询来 infer MV 的 schema，则也不适用 (即 CREATE 没有列列表，且没有 TO 表时) 。可用于在 source table 创建之前先创建 MV。
## allow\_named\_collection\_override\_by\_default
默认允许覆盖命名集合中的字段。
## allow\_non\_metadata\_alters
允许执行不仅会影响表元数据、还会影响磁盘上数据的 alter 操作
## allow\_nonconst\_timezone\_arguments
允许在某些与时间相关的函数中使用非常量时区参数，例如 toTimeZone()、fromUnixTimestamp\*()、snowflakeToDateTime\*()。
此设置仅为兼容性而保留。在 ClickHouse 中，时区是数据类型的属性，准确地说，也是列的属性。
启用此设置会给人一种错误印象，仿佛同一列中的不同值可以具有不同的时区。
因此，请不要启用此设置。
## allow\_nondeterministic\_mutations
允许在复制表的变更中使用非确定性函数 (如 `dictGet`) 的用户级设置。
例如，字典在各节点之间可能存在不同步的情况，因此默认不允许复制表上的变更从字典中获取值。启用此设置后将允许这种行为，但用户需自行确保所使用的数据在所有节点之间保持同步。
**示例**
```xml theme={null}
1
```
## allow\_nondeterministic\_optimize\_skip\_unused\_shards
允许在分片键中使用非确定性函数 (例如 `rand` 或 `dictGet`；后者在更新时有一些注意事项) 。
可能的值：
* 0 — 不允许。
* 1 — 允许。
## allow\_nullable\_tuple\_in\_extracted\_subcolumns
控制类型为 `Tuple(...)` 的提取子列是否可以具有 `Nullable(Tuple(...))` 类型。
* `false`：返回 `Tuple(...)`，并对缺失该子列的行使用默认 Tuple 值。
* `true`：返回 `Nullable(Tuple(...))`，并对缺失该子列的行使用 `NULL`。
此设置仅控制提取子列的行为。
它不控制是否可以在表中创建 `Nullable(Tuple(...))` 列；这一点由 `enable_nullable_tuple_type` 控制。
ClickHouse 使用服务器启动时加载的此设置值。
通过 `SET` 或查询级 `SETTINGS` 所做的更改不会改变提取子列的行为。
若要更改提取子列的行为，请在启动时加载的 profile 配置 (例如 users.xml) 中更新 `allow_nullable_tuple_in_extracted_subcolumns`，然后重启服务器。
## allow\_prefetched\_read\_pool\_for\_local\_filesystem
如果所有 parts 都在本地文件系统上，则优先使用预取线程池
## allow\_prefetched\_read\_pool\_for\_remote\_filesystem
当所有 parts 均位于远程文件系统上时，优先使用预取线程池
## allow\_push\_predicate\_ast\_for\_distributed\_subqueries
允许在启用分析器的情况下，对分布式子查询在 AST 层级下推谓词
## allow\_push\_predicate\_when\_subquery\_contains\_with
允许在子查询包含 WITH 子句时下推谓词
## allow\_rank\_dense\_rank\_arguments
允许向 `RANK` 和 `DENSE_RANK` 窗口函数传递参数，以保持向后兼容。
按照 SQL 标准，`RANK` 和 `DENSE_RANK` 不接受任何参数——它们仅基于
`OVER (ORDER BY ...)` 窗口对行进行排名。在 26.5 之前的 ClickHouse 版本中，类似
`RANK(x) OVER (...)` 的查询会静默接受并忽略该参数，这容易让用户产生困惑
(显式写出的参数看起来似乎会影响排名，但实际上并不会) 。
当此设置为 `false` (默认值) 时，`RANK` 和 `DENSE_RANK` 会拒绝任何参数，并抛出
`NUMBER_OF_ARGUMENTS_DOESNT_MATCH`。当设为 `true` 时，将恢复旧版的宽松行为——
参数会被静默忽略，与 26.5 之前的行为一致。
## allow\_reorder\_prewhere\_conditions
将条件从 WHERE 移至 PREWHERE 时，允许重新排序这些条件以优化过滤效果
## allow\_settings\_after\_format\_in\_insert
控制是否允许在 `INSERT` 查询中于 `FORMAT` 之后使用 `SETTINGS`。不建议使用此设置，因为这可能会将 `SETTINGS` 的一部分解释为值。
示例：
```sql theme={null}
INSERT INTO FUNCTION null('foo String') SETTINGS max_threads=1 VALUES ('bar');
```
但以下查询只有在启用 `allow_settings_after_format_in_insert` 时才能正常工作：
```sql theme={null}
SET allow_settings_after_format_in_insert=1;
INSERT INTO FUNCTION null('foo String') VALUES ('bar') SETTINGS max_threads=1;
```
可能的值：
* 0 — 不允许。
* 1 — 允许。
仅当您的使用场景依赖旧语法、需要向后兼容时，才使用此设置。
## allow\_simdjson
如果支持 AVX2 指令，则允许在 'JSON\*' 函数中使用 simdjson 库。禁用时将使用 rapidjson。
## allow\_special\_serialization\_kinds\_in\_output\_formats
允许直接输出采用 Sparse 和 Replicated 等特殊序列化类型的列，而无需将其转换为普通列表示。
这有助于避免在格式化过程中发生不必要的数据复制。
## allow\_statistics
**别名**: `allow_experimental_statistics`
允许为列定义[统计信息](/zh/reference/engines/table-engines/mergetree-family/mergetree#table_engine-mergetree-creating-a-table)，并[管理统计信息](/zh/reference/engines/table-engines/mergetree-family/mergetree#column-statistics)。
## allow\_statistics\_optimize
**别名**: `allow_statistic_optimize`
允许使用统计信息优化查询
## allow\_suspicious\_codecs
如果将其设置为 true，则允许指定无实际意义的压缩编解码器。
## allow\_suspicious\_fixed\_string\_types
在 CREATE TABLE 语句中，允许创建类型为 FixedString(n) 且 n > 256 的列。长度 >= 256 的 FixedString 值得警惕，通常说明用法有误
## allow\_suspicious\_indices
拒绝主索引/次级索引和排序键使用相同的表达式
## allow\_suspicious\_low\_cardinality\_types
允许或限制将 [LowCardinality](/zh/reference/data-types/lowcardinality) 用于固定大小为 8 字节或更小的数据类型：数值数据类型和 `FixedString(8_bytes_or_less)`。
对于较小的固定值，使用 `LowCardinality` 通常效率不高，因为 ClickHouse 会为每一行存储一个数值索引。因此：
* 磁盘空间占用可能增加。
* RAM 占用可能更高，具体取决于字典大小。
* 由于额外的编码/解码操作，某些函数的执行速度可能变慢。
由于上述原因，在 [MergeTree](/zh/reference/engines/table-engines/mergetree-family/mergetree) 引擎表中，合并时间也可能增加。
Possible values:
* 1 — 不限制使用 `LowCardinality`。
* 0 — 限制使用 `LowCardinality`。
## allow\_suspicious\_primary\_key
允许在 MergeTree 中使用可疑的 `PRIMARY KEY`/`ORDER BY` (即 SimpleAggregateFunction) 。
## allow\_suspicious\_ttl\_expressions
拒绝不依赖表中任何列的生存时间 (TTL) 表达式。这在大多数情况下表明是用户错误。
## allow\_suspicious\_types\_in\_group\_by
允许或禁止将 [Variant](/zh/reference/data-types/variant) 和 [Dynamic](/zh/reference/data-types/dynamic) 类型用作 GROUP BY 键。
## allow\_suspicious\_types\_in\_order\_by
控制是否允许在 ORDER BY 键中使用 [Variant](/zh/reference/data-types/variant) 和 [Dynamic](/zh/reference/data-types/dynamic) 类型。
## allow\_suspicious\_variant\_types
在 CREATE TABLE statement 中，允许指定包含相近 Variant 类型的 Variant 类型 (例如，不同的数值类型或日期类型) 。启用此设置后，在处理类型相近的值时可能会带来一定的歧义。
## allow\_unrestricted\_reads\_from\_keeper
允许从 system.zookeeper 表进行不受限制的读取 (即不对 path 添加条件) ，这样做虽然方便，但对 ZooKeeper 并不安全
## alter\_move\_to\_space\_execute\_async
以异步方式执行 ALTER TABLE MOVE ... TO \[DISK|VOLUME]
## alter\_partition\_verbose\_result
启用或禁用显示有关分区和 parts 操作已成功应用到哪些 parts 的信息。
适用于 [ATTACH PARTITION|PART](/zh/reference/statements/alter/partition#attach-partitionpart) 和 [FREEZE PARTITION](/zh/reference/statements/alter/partition#freeze-partition)。
可能的值：
* 0 — 禁用详细输出。
* 1 — 启用详细输出。
**示例**
```sql theme={null}
CREATE TABLE test(a Int64, d Date, s String) ENGINE = MergeTree PARTITION BY toYYYYMDECLARE(d) ORDER BY a;
INSERT INTO test VALUES(1, '2021-01-01', '');
INSERT INTO test VALUES(1, '2021-01-01', '');
ALTER TABLE test DETACH PARTITION ID '202101';
ALTER TABLE test ATTACH PARTITION ID '202101' SETTINGS alter_partition_verbose_result = 1;
┌─command_type─────┬─partition_id─┬─part_name────┬─old_part_name─┐
│ ATTACH PARTITION │ 202101 │ 202101_7_7_0 │ 202101_5_5_0 │
│ ATTACH PARTITION │ 202101 │ 202101_8_8_0 │ 202101_6_6_0 │
└──────────────────┴──────────────┴──────────────┴───────────────┘
ALTER TABLE test FREEZE SETTINGS alter_partition_verbose_result = 1;
┌─command_type─┬─partition_id─┬─part_name────┬─backup_name─┬─backup_path───────────────────┬─part_backup_path────────────────────────────────────────────┐
│ FREEZE ALL │ 202101 │ 202101_7_7_0 │ 8 │ /var/lib/clickhouse/shadow/8/ │ /var/lib/clickhouse/shadow/8/data/default/test/202101_7_7_0 │
│ FREEZE ALL │ 202101 │ 202101_8_8_0 │ 8 │ /var/lib/clickhouse/shadow/8/ │ /var/lib/clickhouse/shadow/8/data/default/test/202101_8_8_0 │
└──────────────┴──────────────┴──────────────┴─────────────┴───────────────────────────────┴─────────────────────────────────────────────────────────────┘
```
## alter\_sync
**别名**: `replication_alter_partitions_sync`
用于指定由 [`ALTER`](/zh/reference/statements/alter/index)、[`OPTIMIZE`](/zh/reference/statements/optimize) 或 [`TRUNCATE`](/zh/reference/statements/truncate) 查询触发、需在副本上执行的操作的等待行为。
可能的值：
* `0` — 不等待。
* `1` — 等待本副本执行完成。
* `2` — 等待所有副本执行完成。
* `3` - 仅等待活跃副本。
Cloud 默认值：`0`。
`alter_sync` 仅适用于 `Replicated` 和 `SharedMergeTree` 表，对非 `Replicated` 或 `Shared` 表不起作用。
## alter\_update\_mode
用于包含 `UPDATE` 命令的 `ALTER` 查询的模式。
可能的值：
* `heavy` - 执行常规变更。
* `lightweight` - 如果可以，则执行轻量级更新；否则执行常规变更。
* `lightweight_force` - 如果可以，则执行轻量级更新；否则抛出异常。
## 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`，则使用该空间填充曲线进行索引分析。
## analyzer\_compatibility\_allow\_compound\_identifiers\_in\_unflatten\_nested
允许向 nested 结构添加复合标识符。这是一个兼容性设置，因为它会改变查询结果。禁用时，`SELECT a.b.c FROM table ARRAY JOIN a` 将无法使用，而 `SELECT a FROM table` 的结果中也不会将 `a.b.c` 列包含在 `Nested a` 内。
## analyzer\_compatibility\_join\_using\_top\_level\_identifier
强制在 JOIN USING 中从投影解析标识符 (例如，在 `SELECT a + 1 AS b FROM t1 JOIN t2 USING (b)` 中，join 将按 `t1.a + 1 = t2.b` 执行，而不是按 `t1.b = t2.b` 执行) 。
## analyzer\_compatibility\_prefer\_alias\_over\_subcolumn
当像 `b.id` 这样的多部分标识符既可能表示别名为 `b` 的表的列 `id`，也可能表示另一列的 Tuple 子列 `b.id` 时，优先按别名前缀来解释 (即 `b` 的列 `id`) 。默认情况下，新的 analyzer 会优先解析为子列。启用此设置后，可与旧 analyzer 的解析方式保持一致。
## 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](/zh/reference/statements/select/join#settings)
## apply\_deleted\_mask
启用后，会过滤掉通过轻量级删除标记删除的行。如果禁用，查询仍可读取这些行。这对于调试和“取消删除”场景很有用
## apply\_mutations\_on\_fly
如果为 true，尚未在数据分区片段中 materialized 的变更 (UPDATE 和 DELETE) 会在 SELECT 时生效。
## apply\_patch\_parts
如果为 true，则会在 SELECT 查询时应用补丁分区片段 (用于表示轻量级更新) 。
## apply\_patch\_parts\_join\_cache\_buckets
在 Join 模式下应用补丁分区片段时，临时缓存中的桶数量。
## apply\_prewhere\_after\_final
启用后，对于 ReplacingMergeTree 及类似引擎，会在 FINAL 处理完成后应用 PREWHERE 条件。
当 PREWHERE 引用了在重复行之间可能取值不同的列时，
如果你希望 FINAL 先选出最终保留的行再进行过滤，这个设置会很有用。禁用时，PREWHERE 会在读取期间应用。
注意：如果启用了 apply\_row\_level\_security\_after\_final，且行策略使用了非排序键列，PREWHERE 也会
被延后，以保持正确的执行顺序 (必须先应用行策略，再应用 PREWHERE) 。
## apply\_row\_policy\_after\_final
启用后，行策略和 PREWHERE 会在 \*MergeTree 表完成 FINAL 处理后再应用。 (尤其是对 ReplacingMergeTree)
禁用后，行策略会在 FINAL 之前应用；如果策略
过滤掉了本应在 ReplacingMergeTree 或类似引擎中用于去重的行，则可能导致结果不同。
如果行策略表达式仅依赖于 ORDER BY 中的列，出于优化考虑，它仍会在 FINAL 之前应用，
因为这种过滤不会影响去重结果。
可能的值：
* 0 — 在 FINAL 之前应用行策略和 PREWHERE (默认) 。
* 1 — 在 FINAL 之后应用行策略和 PREWHERE。
## apply\_settings\_from\_server
客户端是否接受来自服务器的设置。
这只会影响在客户端执行的操作，尤其是 INSERT 输入数据的解析和查询结果的格式化。查询执行的大部分工作都发生在服务器端，因此不受此设置影响。
通常，此设置应在用户 profile 中设置 (通过 users.xml 或 `ALTER USER` 这类查询) ，而不是通过客户端进行设置 (客户端命令行参数、`SET` 查询或 `SELECT` 查询中的 `SETTINGS` 部分) 。通过客户端可以将其改为 false，但不能改为 true (因为如果用户 profile 中设置了 `apply_settings_from_server = false`，服务器就不会发送这些设置) 。
请注意，在最初的 24.12 版本中，这里有一个 server setting (`send_settings_to_client`) ，但后来为了提升易用性，它被这个 client setting 取代了。
## 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 必需)
## ast\_fuzzer\_any\_query
当值为 false (默认值) 时，由 `ast_fuzzer_runs` 控制的服务器端 AST fuzzer 仅对只读查询 (SELECT、EXPLAIN、SHOW、DESCRIBE、EXISTS) 进行模糊测试。当值为 true 时，则会对包括 DDL 和 INSERT 在内的所有查询类型进行模糊测试。
## ast\_fuzzer\_runs
启用服务端 AST fuzzer。它会在每次正常查询后运行随机生成的查询，并丢弃其结果。
* 0：禁用 (默认) 。
* 大于 0 且小于 1 的值：运行单个模糊查询的概率。
* 值 >= 1：每次正常查询要运行的模糊查询数量。
该 fuzzer 会从所有会话中的所有查询中累积 AST 片段，随着时间推移产生越来越有意思的变异。执行失败的模糊查询会被静默丢弃；结果也绝不会返回给客户端。
## asterisk\_include\_alias\_columns
在通配符查询 (`SELECT *`) 中包含 [ALIAS](/zh/reference/statements/create/table#alias) 列。
可选值：
* 0 - 已禁用
* 1 - 已启用
## asterisk\_include\_materialized\_columns
在通配符查询 (`SELECT *`) 中包含 [MATERIALIZED](/zh/reference/statements/create/view#materialized-view) 列。
可能的值：
* 0 - 禁用
* 1 - 启用
## asterisk\_include\_virtual\_columns
在通配符查询 (`SELECT *`) 中包含虚拟列。
可选值：
* 0 - 已禁用
* 1 - 已启用
## async\_insert
如果为 true，INSERT 查询中的数据会先存储在队列中，随后在后台写入表中。如果 wait\_for\_async\_insert 为 false，INSERT 查询几乎会立即处理完成；否则，客户端会等待，直到数据被写入表中
## async\_insert\_busy\_timeout\_decrease\_rate
自适应异步插入超时降低时的指数增长率
## async\_insert\_busy\_timeout\_increase\_rate
自适应异步插入超时的指数增长率
## async\_insert\_busy\_timeout\_max\_ms
**别名**: `async_insert_busy_timeout_ms`
自首条数据出现起，每个查询在转储已收集数据前的最长等待时间。
Cloud 默认值：`1000` (1s)。
## async\_insert\_busy\_timeout\_min\_ms
如果通过 async\_insert\_use\_adaptive\_busy\_timeout 启用了自动调整，则该值表示自首次出现数据起，每个查询在转储已收集数据之前的最短等待时间。它也用作自适应算法的初始值
## async\_insert\_deduplicate
对于副本表中的 async INSERT 查询，指定是否对插入块执行去重
## async\_insert\_max\_data\_size
每个查询在插入前可收集的未解析数据的最大字节数
Cloud 默认值：`104857600` (100 MiB) 。
## async\_insert\_max\_query\_number
数据实际写入前可累积的最大 INSERT 查询数。
仅当设置 [`async_insert_deduplicate`](#async_insert_deduplicate) 为 1 时生效。
## async\_insert\_poll\_timeout\_ms
从异步插入队列中轮询数据的超时时间
## async\_insert\_use\_adaptive\_busy\_timeout
如果设置为 true，则异步插入将使用自适应忙碌超时
## async\_query\_sending\_for\_remote
在执行远程查询时，启用异步创建连接和发送查询。
默认启用。
## async\_socket\_for\_remote
执行远程查询时，启用套接字异步读取。
默认启用。
## automatic\_parallel\_replicas\_min\_bytes\_per\_replica
自动启用并行副本所需的每个副本读取字节数阈值 (仅在 `automatic_parallel_replicas_mode`=1 时适用) 。0 表示无阈值。
待读取的总字节数会根据已收集的统计信息进行估算。
## automatic\_parallel\_replicas\_mode
根据已收集的统计信息，启用自动切换为使用并行副本执行。要求 `enable_analyzer = 1`、`enable_parallel_replicas != 0`、`parallel_replicas_local_plan = 1`，并提供 `cluster_for_parallel_replicas`。
0 - 禁用，1 - 启用，2 - 仅启用统计信息收集 (禁用切换为使用并行副本执行) 。
## azure\_allow\_parallel\_part\_upload
使用多个线程执行 Azure 分段上传。
## azure\_check\_objects\_after\_upload
检查 Azure Blob 存储中的每个已上传对象，确认上传是否成功
## azure\_connect\_timeout\_ms
连接到 azure disks 主机时的超时时间。
## azure\_create\_new\_file\_on\_insert
启用或禁用在 Azure engine 表中每次 insert 时创建新文件的功能
## azure\_ignore\_file\_doesnt\_exist
读取某些键时，如果文件不存在，则忽略该文件缺失的情况。
可能的值：
* 1 — `SELECT` 返回空结果。
* 0 — `SELECT` 抛出异常。
## azure\_list\_object\_keys\_size
ListObject 请求单个批次可返回的最大文件数
## azure\_max\_blocks\_in\_multipart\_upload
Azure 分段上传的最大块数。
## azure\_max\_get\_burst
在达到每秒请求数限制前，可同时发出的最大请求数。默认值 (0) 等于 `azure_max_get_rps`
## azure\_max\_get\_rps
Azure 每秒 GET 请求速率在触发限流前的上限。0 表示不限制。
## azure\_max\_inflight\_parts\_for\_one\_file
分段上传请求中可并发上传的分片最大数量。0 表示不受限制。
## azure\_max\_put\_burst
达到每秒请求数限制前，可同时发出的最大请求数。默认值为 0 时，等同于 `azure_max_put_rps`
## azure\_max\_put\_rps
Azure PUT 请求每秒速率的限制，超过后会触发限流。0 表示不限制。
## azure\_max\_redirects
允许的 Azure 重定向跳转次数上限。
## azure\_max\_single\_part\_copy\_size
使用单个分片复制到 Azure Blob 存储时，对象的最大可复制大小。
## azure\_max\_single\_part\_upload\_size
使用单分片上传到 Azure Blob 存储时，对象的最大大小。
## azure\_max\_single\_read\_retries
单次 Azure Blob 存储读取的最大重试次数。
## azure\_max\_unexpected\_write\_error\_retries
Azure Blob 存储写入期间发生意外错误时的最大重试次数
## azure\_max\_upload\_part\_size
向 Azure Blob 存储执行分段上传时，单个上传分段的最大大小。
## azure\_min\_upload\_part\_size
向 Azure Blob 存储进行分段上传时，单个上传分段的最小大小。
## azure\_request\_timeout\_ms
向 Azure 发送和从 Azure 接收数据时的空闲超时时间。如果单次 TCP 读取或写入调用阻塞超过该时长，则会失败。
## azure\_sdk\_max\_retries
Azure SDK 的最大重试次数
## azure\_sdk\_retry\_initial\_backoff\_ms
Azure SDK 中两次重试之间的最小退避时间
## azure\_sdk\_retry\_max\_backoff\_ms
Azure SDK 中两次重试之间的最大退避间隔
## azure\_skip\_empty\_files
启用或禁用在 S3 引擎中跳过空文件。
可选值：
* 0 — 如果空文件与所请求的格式不兼容，`SELECT` 会抛出异常。
* 1 — 对于空文件，`SELECT` 返回空结果。
## azure\_strict\_upload\_part\_size
向 Azure Blob 存储执行分段上传时，每个分段的精确大小。
## azure\_throw\_on\_zero\_files\_match
如果根据 glob 展开规则未匹配到任何文件，则抛出错误。
可能的值：
* 1 — `SELECT` 抛出异常。
* 0 — `SELECT` 返回空结果。
## azure\_truncate\_on\_insert
启用或禁用在 Azure engine 表中 insert 前先执行 truncate。
## azure\_upload\_part\_size\_multiply\_factor
每当单次写入 Azure Blob 存储上传的分片数达到 azure\_multiply\_parts\_count\_threshold 时，就将 azure\_min\_upload\_part\_size 乘以该因子。
## azure\_upload\_part\_size\_multiply\_parts\_count\_threshold
每当上传到 Azure Blob 存储的分片数量达到该值时，azure\_min\_upload\_part\_size 就会乘以 azure\_upload\_part\_size\_multiply\_factor。
## azure\_use\_adaptive\_timeouts
当设置为 `true` 时，所有 azure 请求的前两次尝试都会使用较短的发送和接收超时时间。
当设置为 `false` 时，所有尝试都会使用相同的超时时间。
## backup\_restore\_batch\_size\_for\_keeper\_multi
在备份或恢复期间，向 \[Zoo]Keeper 发起多重请求时的最大批次大小
## backup\_restore\_batch\_size\_for\_keeper\_multiread
在备份或恢复期间，向 \[Zoo]Keeper 发起 multiread 请求时的最大批次大小
## backup\_restore\_failure\_after\_host\_disconnected\_for\_seconds
如果某个主机在执行 BACKUP ON CLUSTER 或 RESTORE ON CLUSTER 期间，持续这段时间都未能在 ZooKeeper 中重新创建其临时 “alive” 节点，则整个 backup 或 restore 会被视为失败。
该值应大于主机发生故障后重新连接到 ZooKeeper 所需的任何合理时长。
0 表示不受限制。
## backup\_restore\_finish\_timeout\_after\_error\_sec
在当前 `BACKUP ON CLUSTER` 或 `RESTORE ON CLUSTER` 操作中，发起节点在 `'error'` 节点出现后，等待其他主机作出响应并停止当前工作的时长。
## backup\_restore\_keeper\_fault\_injection\_probability
在备份或恢复期间，Keeper 请求发生故障的近似概率。有效值范围为 \[0.0f, 1.0f]
## backup\_restore\_keeper\_fault\_injection\_seed
0 - 随机种子，否则为该设置值
## backup\_restore\_keeper\_max\_retries
BACKUP 或 RESTORE 操作过程中，\[Zoo]Keeper 操作的最大重试次数。
该值应足够大，以确保整个操作不会因临时的 \[Zoo]Keeper 故障而失败。
## backup\_restore\_keeper\_max\_retries\_while\_handling\_error
处理 BACKUP ON CLUSTER 或 RESTORE ON CLUSTER 操作期间发生的错误时，\[Zoo]Keeper 操作的最大重试次数。
## backup\_restore\_keeper\_max\_retries\_while\_initializing
初始化 BACKUP ON CLUSTER 或 RESTORE ON CLUSTER 操作时，\[Zoo]Keeper 操作的最大重试次数。
## backup\_restore\_keeper\_retry\_initial\_backoff\_ms
用于备份或恢复期间 \[Zoo]Keeper 操作的初始退避超时时间
## backup\_restore\_keeper\_retry\_max\_backoff\_ms
在备份或恢复期间，\[Zoo]Keeper 操作的最大退避超时时长
Cloud 默认值：`60000`。
## backup\_restore\_keeper\_value\_max\_size
备份期间 \[Zoo]Keeper 节点数据的最大大小
## backup\_restore\_s3\_retry\_attempts
Aws::Client::RetryStrategy 的设置项。Aws::Client 会自行重试，0 表示不重试。仅对备份/恢复生效。
## backup\_restore\_s3\_retry\_initial\_backoff\_ms
在备份和恢复过程中，首次重试前的初始 backoff 延迟，单位为毫秒。此后的每次重试都会按指数方式增加延迟，直到达到 `backup_restore_s3_retry_max_backoff_ms` 指定的最大值
## backup\_restore\_s3\_retry\_jitter\_factor
在备份和恢复操作期间，此项用于为 Aws::Client::RetryStrategy 中的重试退避延迟应用抖动系数。计算出的退避延迟会乘以一个位于 \[1.0, 1.0 + jitter] 范围内的随机系数，且最大不超过 `backup_restore_s3_retry_max_backoff_ms`。其值必须在 \[0.0, 1.0] 区间内
## backup\_restore\_s3\_retry\_max\_backoff\_ms
备份和恢复操作期间，重试之间的最大延迟 (以毫秒为单位) 。
## 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](/zh/reference/settings/merge-tree-settings#cache_populated_by_fetch) 时，用于将新的数据分区片段试探性下载到文件系统缓存中的后台线程数。设为 0 可禁用。
## calculate\_text\_stack\_trace
在查询执行期间发生异常时，计算文本 stack trace。这是默认设置。它需要进行符号查找；在执行大量错误查询时，可能会降低模糊测试的速度。正常情况下，不应禁用此选项。
## cancel\_http\_readonly\_queries\_on\_client\_close
当客户端在未等待响应的情况下关闭连接时，取消 HTTP 只读查询 (例如 `SELECT`) 。
Cloud 默认值：`1`。
## cast\_ipv4\_ipv6\_default\_on\_conversion\_error
将 CAST 运算符转换为 IPv4、将 CAST 运算符转换为 IPv6 类型，以及 toIPv4、toIPv6 函数，在转换错误时会返回默认值，而不是抛出异常。
## cast\_keep\_nullable
启用或禁用在 [CAST](/zh/reference/functions/regular-functions/type-conversion-functions#CAST) 操作中保留 `Nullable` 数据类型。
启用此设置后，如果 `CAST` 函数的参数为 `Nullable`，结果也会转换为 `Nullable` 类型。禁用此设置时，结果始终严格为目标数据类型。
Possible values:
* 0 — `CAST` 结果严格为指定的目标数据类型。
* 1 — 如果参数类型为 `Nullable`，则 `CAST` 结果会转换为 `Nullable(DestinationDataType)`。
**Examples**
以下查询的结果严格为目标数据类型：
```sql theme={null}
SET cast_keep_nullable = 0;
SELECT CAST(toNullable(toInt32(0)) AS Int32) as x, toTypeName(x);
```
结果：
```text theme={null}
┌─x─┬─toTypeName(CAST(toNullable(toInt32(0)), 'Int32'))─┐
│ 0 │ Int32 │
└───┴───────────────────────────────────────────────────┘
```
以下查询会使目标端数据类型变为带有 `Nullable` 修饰的类型：
```sql theme={null}
SET cast_keep_nullable = 1;
SELECT CAST(toNullable(toInt32(0)) AS Int32) as x, toTypeName(x);
```
结果：
```text theme={null}
┌─x─┬─toTypeName(CAST(toNullable(toInt32(0)), 'Int32'))─┐
│ 0 │ Nullable(Int32) │
└───┴───────────────────────────────────────────────────┘
```
**另请参阅**
* [CAST](/zh/reference/functions/regular-functions/type-conversion-functions#CAST) 函数
## cast\_string\_to\_date\_time\_mode
允许在从 String 进行转换时，选择日期和时间文本表示的解析器。
可能的值：
* `'best_effort'` — 启用扩展解析。
ClickHouse 可以解析基础的 `YYYY-MM-DD HH:MM:SS` 格式以及所有 [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) 日期和时间格式。例如，`'2018-06-08T01:02:03.000Z'`。
* `'best_effort_us'` — 与 `best_effort` 类似 (差异请参见 [parseDateTimeBestEffortUS](/zh/reference/functions/regular-functions/type-conversion-functions#parseDateTimeBestEffortUS)
* `'basic'` — 使用基础解析器。
ClickHouse 只能解析基础的 `YYYY-MM-DD HH:MM:SS` 或 `YYYY-MM-DD` 格式。例如，`2019-08-20 10:18:56` 或 `2019-08-20`。
另请参见：
* [DateTime 数据类型。](/zh/reference/data-types/datetime)
* [日期和时间处理函数。](/zh/reference/functions/regular-functions/date-time-functions)
## cast\_string\_to\_dynamic\_use\_inference
在将 String 转换为 Dynamic 时使用类型推断
## cast\_string\_to\_variant\_use\_inference
在从 String 转换为 Variant 时使用类型推断。
## check\_named\_collection\_dependencies
检查 DROP NAMED COLLECTION 不会导致依赖它的表失效
## check\_query\_single\_value\_result
定义 `MergeTree` 家族引擎中 [CHECK TABLE](/zh/reference/statements/check-table) 查询结果的详细程度。
Possible values:
* 0 — 查询会显示表中每个数据分区片段各自的检查状态。
* 1 — 查询会显示表的整体检查状态。
## check\_referential\_table\_dependencies
检查 DDL 查询 (如 DROP TABLE 或 RENAME) 是否会破坏引用依赖关系
## check\_table\_dependencies
检查 DDL 查询 (如 DROP TABLE 或 RENAME) 是否会破坏依赖关系
## checksum\_on\_read
读取时验证校验和。此设置默认启用，并且在生产环境中应始终保持启用。不要指望禁用此设置会带来任何收益。它仅可用于实验和性能测试。该设置仅适用于 MergeTree 家族的表。对于其他表引擎，以及通过网络接收数据时，校验和始终会被验证。
## cloud\_mode
Cloud 模式
Cloud 默认值：`1`。
## cloud\_mode\_database\_engine
Cloud 中允许的数据库引擎。1 - 将 DDL 重写为使用 Replicated 数据库，2 - 将 DDL 重写为使用 Shared 数据库
Cloud 默认值：`2`。
## cloud\_mode\_engine
Cloud 中允许使用的引擎家族。
* 0 - 允许所有引擎
* 1 - 将 DDLs 重写为使用 \*ReplicatedMergeTree
* 2 - 将 DDLs 重写为使用 SharedMergeTree
* 3 - 将 DDLs 重写为使用 SharedMergeTree，但显式指定远程磁盘时除外
* 4 - 与 3 相同，另外使用 Alias 而不是 Distributed (Alias 表将指向 Distributed 表的目标表，因此会使用对应的本地表)
使用 UInt64 以尽量减少公开部分
Cloud 默认值：`2`。
## cluster\_for\_parallel\_replicas
当前服务器所在分片的集群
Cloud 默认值：`default`。
## cluster\_function\_process\_archive\_on\_multiple\_nodes
如果设置为 `true`，可提高 cluster functions 中处理归档的性能。若要保持兼容性，并避免在使用带归档的 cluster functions 从较早版本升级到 25.7+ 时出错，则应将其设置为 `false`。
## cluster\_table\_function\_buckets\_batch\_size
定义在采用 `bucket` 拆分粒度的 cluster 表函数中进行任务分布式处理时所使用的批次近似大小 (以字节为单位) 。系统会持续累积数据，直到至少达到该大小。为与数据边界对齐，实际大小可能会略大一些。
## cluster\_table\_function\_split\_granularity
控制在执行 CLUSTER TABLE FUNCTION 时，如何将数据拆分为任务。
此设置定义了工作在集群中的分发粒度：
* `file` — 每个任务处理整个文件。
* `bucket` — 任务按文件内部的数据块创建 (例如 Parquet 行组) 。
选择更细的粒度 (如 `bucket`) 时，在处理少量大文件的场景下可以提升并行度。
例如，如果一个 Parquet 文件包含多个行组，启用 `bucket` 粒度后，每个行组都可以由不同的工作线程独立处理。
## collect\_hash\_table\_stats\_during\_aggregation
启用哈希表统计信息收集，以优化内存分配
## collect\_hash\_table\_stats\_during\_joins
启用收集哈希表统计信息，以优化内存分配
## compatibility
`compatibility` 设置会使 ClickHouse 使用由该设置指定的 ClickHouse 早期版本的默认设置。
如果某些设置已被设为非默认值，则这些设置会被保留 (只有未修改的设置才会受 `compatibility` 设置影响) 。
此设置接受一个以字符串形式表示的 ClickHouse 版本号，例如 `22.3`、`22.8`。空值表示此设置已禁用。
默认处于禁用状态。
在 ClickHouse Cloud 中，服务级默认的 compatibility 设置必须由 ClickHouse Cloud Support 配置。请[提交工单](https://clickhouse.cloud/support)进行设置。
不过，也可以使用标准的 ClickHouse 设置机制，在用户、Role、profile、查询或 session 级别覆盖 compatibility 设置，例如在 session 中使用 `SET compatibility = '22.3'`，或在查询中使用 `SETTINGS compatibility = '22.3'`。
## compatibility\_ignore\_auto\_increment\_in\_create\_table
如果为 true，则忽略列声明中的 AUTO\_INCREMENT 关键字；否则返回错误。这有助于简化从 MySQL 的迁移
## compatibility\_ignore\_collation\_in\_create\_table
兼容性：在 CREATE TABLE 中忽略排序规则
## compatibility\_s3\_presigned\_url\_query\_in\_path
兼容性：启用后，会将预签名 URL 的查询参数 (如 X-Amz-\*) 并入 S3 键中 (旧版行为) ，
因此路径中的 '?' 会被当作通配符。禁用时 (默认) ，预签名 URL 的查询参数将保留在 URL 查询字符串中，
以避免把 '?' 解释为通配符。
## compile\_aggregate\_expressions
启用或禁用将聚合函数 JIT 编译为原生代码。启用此设置可提升性能。
可能的值：
* 0 — 聚合在不使用 JIT 编译的情况下进行。
* 1 — 聚合使用 JIT 编译进行。
**另请参见**
* [min\_count\_to\_compile\_aggregate\_expression](#min_count_to_compile_aggregate_expression)
## compile\_expressions
将部分标量函数和运算符编译为原生代码。
## compile\_sort\_description
将排序描述编译成原生代码。
## connect\_timeout
没有副本时的连接超时时间。
## connect\_timeout\_with\_failover\_ms
如果在集群定义中使用了 'shard' 和 'replica' 部分，则此参数表示 Distributed 表引擎连接远程服务器时的超时时间 (以毫秒为单位) 。
如果连接失败，系统会尝试连接其他副本多次。
## connect\_timeout\_with\_failover\_secure\_ms
在安全连接中，用于选择第一个健康副本的连接超时时间。
## connection\_pool\_max\_wait\_ms
当连接池已满时，连接可等待的时间 (毫秒) 。
可能的值：
* 正整数。
* 0 — 无限等待。
## connections\_with\_failover\_max\_tries
Distributed 表引擎中，对每个副本进行连接尝试的最大次数。
## convert\_query\_to\_cnf
设置为 `true` 时，`SELECT` 查询会被转换为合取范式 (CNF) 。在某些情况下，将查询重写为 CNF 可能执行得更快 (说明请参见这个 [Github issue](https://github.com/ClickHouse/ClickHouse/issues/11749)) 。
例如，注意以下 `SELECT` 查询不会被修改 (默认行为) ：
```sql theme={null}
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;
```
结果如下：
```response theme={null}
┌─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`，看看会发生什么变化：
```sql theme={null}
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，但结果集完全相同——布尔逻辑并未改变：
```response theme={null}
┌─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
## correlated\_subqueries\_default\_join\_kind
控制去相关查询计划中使用的 JOIN 类型。默认值为 `right`，这意味着去相关后的查询计划将包含 RIGHT JOIN，且子查询输入位于右侧。
可选值：
* `left` - 去相关过程将生成 LEFT JOIN，输入表将出现在左侧。
* `right` - 去相关过程将生成 RIGHT JOIN，输入表将出现在右侧。
## correlated\_subqueries\_substitute\_equivalent\_expressions
使用过滤器表达式推断等价表达式，并用其替代，而不是创建 CROSS JOIN。
## correlated\_subqueries\_use\_in\_memory\_buffer
使用内存缓冲区处理关联子查询的输入，以避免重复求值。
## count\_distinct\_implementation
指定执行 [COUNT(DISTINCT ...)](/zh/reference/functions/aggregate-functions/count) 时应使用哪个 `uniq*` 函数。
可能的值：
* [uniq](/zh/reference/functions/aggregate-functions/uniq)
* [uniqCombined](/zh/reference/functions/aggregate-functions/uniqCombined)
* [uniqCombined64](/zh/reference/functions/aggregate-functions/uniqCombined64)
* [uniqHLL12](/zh/reference/functions/aggregate-functions/uniqHLL12)
* [uniqExact](/zh/reference/functions/aggregate-functions/uniqExact)
## count\_distinct\_optimization
将 count distinct 重写为 group by 子查询
## count\_matches\_stop\_at\_empty\_match
在 `countMatches` 函数中，一旦模式发生零长度匹配，就停止计数。
## create\_if\_not\_exists
默认对 `CREATE` 语句启用 `IF NOT EXISTS`。如果指定了此设置或 `IF NOT EXISTS`，且给定名称的表已存在，则不会抛出异常。
## create\_index\_ignore\_unique
忽略 CREATE UNIQUE INDEX 中的 UNIQUE 关键字。此设置用于 SQL 兼容性测试。
## create\_replicated\_merge\_tree\_fault\_injection\_probability
在 ZooKeeper 中创建元数据后，创建表过程中发生故障注入的概率
## create\_table\_empty\_primary\_key\_by\_default
允许在未指定 ORDER BY 和 PRIMARY KEY 时，为 \*MergeTree 表创建空主键
## cross\_join\_min\_bytes\_to\_compress
在 CROSS JOIN 中，对块进行压缩的最小大小。值为 0 表示禁用此阈值。当达到两个阈值 (按行数或按字节) 中的任意一个时，该块将被压缩。
## cross\_join\_min\_rows\_to\_compress
在 CROSS JOIN 中压缩块的最小行数。值为 0 表示禁用此阈值。当达到两个阈值 (按行数或按字节数) 中的任意一个时，就会压缩该块。
## cross\_to\_inner\_join\_rewrite
如果 WHERE 子句中存在连接表达式，则使用 inner join 而不是逗号/cross join。取值：0 - 不重写，1 - 在可能时对逗号/cross join 应用重写，2 - 强制重写所有逗号 join，cross join 则在可能时重写
## data\_type\_default\_nullable
允许将列定义中未显式使用修饰符 [NULL or NOT NULL](/zh/reference/statements/create/table#null-or-not-null-modifiers) 的数据类型设为 [Nullable](/zh/reference/data-types/nullable)。
可能的值：
* 1 — 列定义中的数据类型默认设为 `Nullable`。
* 0 — 列定义中的数据类型默认不设为 `Nullable`。
## database\_atomic\_wait\_for\_drop\_and\_detach\_synchronously
为所有 `DROP` 和 `DETACH` 查询添加 `SYNC` 修饰符。
可能的值：
* 0 — 查询将延后执行。
* 1 — 查询将立即执行。
## database\_datalake\_require\_metadata\_access
如果没有权限获取数据库引擎 DataLakeCatalog 中表的元数据，是否抛出错误。
## database\_replicated\_allow\_explicit\_uuid
0 - 不允许在 Replicated 数据库中显式指定表 UUID。1 - 允许。2 - 允许，但会忽略指定的 UUID，转而生成一个随机 UUID。
## database\_replicated\_allow\_heavy\_create
允许在 Replicated 数据库引擎中执行耗时较长的 DDL 查询 (CREATE AS SELECT 和 POPULATE) 。请注意，这可能会使 DDL 队列长时间阻塞。
## database\_replicated\_allow\_only\_replicated\_engine
仅允许在使用 Replicated 引擎的数据库中创建 Replicated 表
Cloud 默认值：`1`。
## database\_replicated\_allow\_replicated\_engine\_arguments
0 - 不允许为 Replicated 数据库中的 \*MergeTree 表显式指定 ZooKeeper 路径和副本名称。1 - 允许。2 - 允许，但会忽略指定的路径，改用默认路径。3 - 允许，且不记录警告日志。
## database\_replicated\_always\_detach\_permanently
如果数据库引擎为 Replicated，则以 DETACH TABLE PERMANENTLY 的方式执行 DETACH TABLE
## database\_replicated\_enforce\_synchronous\_settings
对某些查询强制进行同步等待 (另请参见 database\_atomic\_wait\_for\_drop\_and\_detach\_synchronously、mutations\_sync、alter\_sync) 。不建议启用这些设置。
## database\_replicated\_initial\_query\_timeout\_sec
设置初始 DDL 查询等待 `Replicated` 数据库处理之前 DDL 队列条目的时长，单位为秒。
可能的值：
* 正整数。
* 0 — 无限。
## database\_shared\_drop\_table\_delay\_seconds
已删除的表在 Shared 数据库中被实际移除前的延迟时间 (以秒为单位) 。在此期间，可以使用 `UNDROP TABLE` 语句恢复该表。
## decimal\_check\_overflow
检查 Decimal 算术/比较运算是否溢出
## deduplicate\_blocks\_in\_dependent\_materialized\_views
启用或禁用对从 Replicated\* 表接收数据的 materialized view 进行去重检查。
可能的值：
0 — 禁用。
1 — 启用。
启用后，ClickHouse 会对依赖于 Replicated\* 表的 materialized view 中的块执行去重。
当插入操作因故障而重试时，此设置有助于确保 materialized view 中不会包含重复数据。
**另请参见**
* [IN 运算符中的 NULL 处理](/zh/concepts/features/operations/insert/deduplicating-inserts-on-retries#insert-deduplication-with-materialized-views)
## deduplicate\_insert
启用或禁用 `INSERT INTO` 的块去重 (适用于 Replicated\* 表) 。
此设置会覆盖 `insert_deduplicate` 和 `async_insert_deduplicate` 设置。
该设置有三个可能值：
* disable — 对 `INSERT INTO` 查询禁用去重。
* enable — 对 `INSERT INTO` 查询启用去重。
* backward\_compatible\_choice — 如果特定插入类型启用了 `insert_deduplicate` 或 `async_insert_deduplicate`，则启用去重。
## deduplicate\_insert\_select
启用或禁用 `INSERT SELECT` 的块去重 (适用于 Replicated\* 表) 。
对于 `INSERT SELECT` 查询，此设置会覆盖 `insert_deduplicate` 和 `deduplicate_insert`。
该设置有四个可能值：
* disable — 对 `INSERT SELECT` 查询禁用去重。
* force\_enable — 对 `INSERT SELECT` 查询启用去重。如果 SELECT 结果不稳定，则会抛出异常。
* enable\_when\_possible — 如果 `insert_deduplicate` 已启用且 SELECT 结果稳定，则启用去重；否则禁用。
* enable\_even\_for\_bad\_queries - 如果 `insert_deduplicate` 已启用，则启用去重。如果 SELECT 结果不稳定，则会记录警告，但查询仍会在启用去重的情况下执行。此选项用于向后兼容。建议改用其他选项，因为它可能导致意外结果。
## default\_materialized\_view\_sql\_security
允许在创建 materialized view 时，为 SQL SECURITY 选项设置默认值。[更多关于 SQL security 的信息](/zh/reference/statements/create/view#sql_security)。
默认值为 `DEFINER`。
## default\_max\_bytes\_in\_join
当需要施加限制但未设置 `max_bytes_in_join` 时，右侧表允许的最大大小。
## default\_normal\_view\_sql\_security
允许在创建普通视图时设置默认的 `SQL SECURITY` 选项。[了解更多 SQL security](/zh/reference/statements/create/view#sql_security)。
默认值为 `INVOKER`。
## default\_table\_engine
当 `CREATE` statement 中未设置 `ENGINE` 时，使用的默认表引擎。
可能的值：
* 表示任意有效表引擎名称的字符串
Cloud 默认值：`SharedMergeTree`。
**示例**
查询：
```sql theme={null}
SET default_table_engine = 'Log';
SELECT name, value, changed FROM system.settings WHERE name = 'default_table_engine';
```
结果：
```response theme={null}
┌─name─────────────────┬─value─┬─changed─┐
│ default_table_engine │ Log │ 1 │
└──────────────────────┴───────┴─────────┘
```
在本示例中，任何未指定 `Engine` 的新表都将使用 `Log` 表引擎：
查询：
```sql theme={null}
CREATE TABLE my_table (
x UInt32,
y UInt32
);
SHOW CREATE TABLE my_table;
```
结果：
```response theme={null}
┌─statement────────────────────────────────────────────────────────────────┐
│ CREATE TABLE default.my_table
(
`x` UInt32,
`y` UInt32
)
ENGINE = Log
└──────────────────────────────────────────────────────────────────────────┘
```
## default\_temporary\_table\_engine
与 [default\_table\_engine](#default_table_engine) 相同，但适用于临时表。
在此示例中，任何未指定 `Engine` 的新建临时表都会使用 `Log` 表引擎：
查询：
```sql theme={null}
SET default_temporary_table_engine = 'Log';
CREATE TEMPORARY TABLE my_table (
x UInt32,
y UInt32
);
SHOW CREATE TEMPORARY TABLE my_table;
```
结果：
```response theme={null}
┌─statement────────────────────────────────────────────────────────────────┐
│ CREATE TEMPORARY TABLE default.my_table
(
`x` UInt32,
`y` UInt32
)
ENGINE = Log
└──────────────────────────────────────────────────────────────────────────┘
```
## default\_view\_definer
允许在创建视图时设置默认 `DEFINER` 选项。 [有关 SQL security 的更多信息](/zh/reference/statements/create/view#sql_security)。
默认值为 `CURRENT_USER`。
## defer\_partition\_pruning\_after\_final
启用时 (默认) ，对于分区键列不属于排序键的表，`FINAL` 查询会跳过分区裁剪。这是 26.3 中引入的安全正确行为：`FINAL` 可能需要对主键相同但位于不同分区中的行进行去重，而分区裁剪会静默地将这类行排除在
去重输入之外。
禁用时，即使使用 `FINAL` 也会应用分区裁剪，从而恢复 26.3 之前的
行为。对于在分区列上带有 `WHERE` 谓词的查询，这样通常会快得多，
但只有在相同主键的行不可能出现在不同分区中时才是正确的——例如分区列在 `insert`
时设定且之后从不变化的事件日志表。
此设置只影响分区键列未包含在排序键中的分区表；对于其他表，始终会应用分区裁剪。
可能的值：
* 0 — 在 `FINAL` 之前应用分区裁剪 (26.3 之前的行为，速度更快，但一般情况下并不安全) 。
* 1 — 将分区裁剪延后到 `FINAL` 之后 (默认，保证正确性) 。
## delta\_lake\_enable\_engine\_predicate
启用 delta-kernel 的内部数据裁剪。
## delta\_lake\_enable\_expression\_visitor\_logging
启用 DeltaLake 表达式访问器的测试级别日志。即使在测试日志中，这些日志也可能过于冗长。
## delta\_lake\_insert\_max\_bytes\_in\_data\_file
定义 delta lake 中单个插入数据文件的字节数上限。
## delta\_lake\_insert\_max\_rows\_in\_data\_file
定义 Delta Lake 中单个插入数据文件的行数上限。
## delta\_lake\_log\_metadata
启用后，会将 Delta Lake 元数据文件记录到系统表中。
## delta\_lake\_reload\_schema\_for\_consistency
如果启用，则会在每次执行查询前从 DeltaLake 元数据中重新加载 schema，以确保查询分析期间使用的 schema 与执行期间使用的 schema 一致。
## delta\_lake\_snapshot\_end\_version
要读取的 Delta Lake snapshot 的结束版本。值为 -1 表示读取最新版本 (值 0 是有效的 snapshot version) 。
## delta\_lake\_snapshot\_start\_version
要读取的 delta lake snapshot 的起始版本。值为 -1 表示读取最新版本 (值 0 是有效的 snapshot version) 。
## delta\_lake\_snapshot\_version
要读取的 Delta Lake 快照版本号。值为 -1 表示读取最新版本 (值 0 也是有效的快照版本) 。
## delta\_lake\_throw\_on\_engine\_predicate\_error
启用后，如果在 delta-kernel 中分析扫描谓词时出错，则会抛出异常。
## describe\_compact\_output
如果为 true，则 DESCRIBE 查询结果中仅包含列名和类型
## describe\_include\_subcolumns
启用在 [DESCRIBE](/zh/reference/statements/describe-table) 查询中显示子列。例如，[Tuple](/zh/reference/data-types/tuple) 的成员，或 [Map](/zh/reference/data-types/map#reading-subcolumns-of-map)、[Nullable](/zh/reference/data-types/nullable#finding-null) 和 [Array](/zh/reference/data-types/array#array-size) 数据类型的子列。
可能的值：
* 0 — `DESCRIBE` 查询中不包含子列。
* 1 — `DESCRIBE` 查询中包含子列。
**示例**
请参阅 [DESCRIBE](/zh/reference/statements/describe-table) 语句示例。
## describe\_include\_virtual\_columns
如果为 true，则表的虚拟列也会包含在 DESCRIBE 查询结果中
## 方言
用于解析查询的方言
## dictionary\_use\_async\_executor
使用多个线程执行读取字典源的管道。仅支持字典源为本地 CLICKHOUSE 的字典。
## dictionary\_validate\_primary\_key\_type
验证字典的主键类型。默认情况下，简单布局的 id 类型会隐式转换为 UInt64。
## distinct\_overflow\_mode
设置当数据量超过某项限制时的处理方式。
可能的值：
* `throw`：抛出异常 (默认) 。
* `break`：停止执行查询并返回部分结果，就像源数据
已经耗尽一样。
## distributed\_aggregation\_memory\_efficient
是否启用分布式聚合的节省内存模式。
## distributed\_background\_insert\_batch
**别名**: `distributed_directory_monitor_batch_inserts`
启用/禁用按批次发送已插入的数据。
启用批次发送后，[Distributed](/zh/reference/engines/table-engines/special/distributed) 表引擎会尝试在一次操作中发送多个已插入数据文件，而不是分别发送。批次发送能更高效地利用服务器和网络资源，从而提升集群性能。
可能值：
* 1 — 已启用。
* 0 — 已禁用。
## distributed\_background\_insert\_max\_sleep\_time\_ms
**别名**: `distributed_directory_monitor_max_sleep_time_ms`
[Distributed](/zh/reference/engines/table-engines/special/distributed) 表引擎发送数据的最大时间间隔。用于限制 [distributed\_background\_insert\_sleep\_time\_ms](#distributed_background_insert_sleep_time_ms) 设置中所设时间间隔的指数增长。
可能的值：
* 以毫秒为单位的正整数。
## distributed\_background\_insert\_sleep\_time\_ms
**别名**: `distributed_directory_monitor_sleep_time_ms`
[Distributed](/zh/reference/engines/table-engines/special/distributed) 表引擎发送数据时使用的基础时间间隔。发生错误时，实际时间间隔会以指数级增长。
可能的值：
* 以毫秒为单位的正整数。
## distributed\_background\_insert\_split\_batch\_on\_failure
**别名**: `distributed_directory_monitor_split_batch_on_failure`
启用/禁用在发生失败时拆分批次。
有时，向远程分片发送某个批次可能会失败，原因是在后续的复杂管道中 (例如带有 `GROUP BY` 的 `MATERIALIZED VIEW`) 触发了 `Memory limit exceeded` 或类似错误。在这种情况下，重试也无济于事 (而且会导致该表的分布式发送卡住) ；但如果将该批次中的文件逐个发送，则可能成功执行 INSERT。
因此，将此设置设为 `1` 后，会对这类批次禁用批处理 (即临时对失败批次禁用 `distributed_background_insert_batch`) 。
可能的值：
* 1 — 已启用。
* 0 — 已禁用。
此设置也会影响损坏的批次 (这类批次可能是由于服务器 (机器) 异常终止，且 [Distributed](/zh/reference/engines/table-engines/special/distributed) 表引擎未启用 `fsync_after_insert`/`fsync_directories` 而产生的) 。
不应依赖自动批次拆分，因为这可能会影响性能。
## distributed\_background\_insert\_timeout
**别名**: `insert_distributed_timeout`
向 Distributed 表执行插入查询的超时时间。该设置仅在启用 `insert_distributed_sync` 时生效。值为 0 表示不超时。
## distributed\_cache\_alignment
仅在 ClickHouse Cloud 中生效。此设置仅供测试使用，请勿更改
## distributed\_cache\_bypass\_connection\_pool
仅在 ClickHouse Cloud 中生效。允许绕过分布式缓存连接池
## distributed\_cache\_connect\_backoff\_max\_ms
仅在 ClickHouse Cloud 中生效。设置创建分布式缓存连接时的最大退避毫秒数。
## distributed\_cache\_connect\_backoff\_min\_ms
仅在 ClickHouse Cloud 中生效。创建分布式缓存连接时的最小退避时间 (毫秒) 。
## distributed\_cache\_connect\_max\_tries
仅在 ClickHouse Cloud 中生效。连接分布式缓存失败时，允许重试的次数。
## distributed\_cache\_connect\_timeout\_ms
仅在 ClickHouse Cloud 中生效。连接分布式缓存服务器时的连接超时时间。
## distributed\_cache\_credentials\_refresh\_period\_seconds
仅在 ClickHouse Cloud 中生效。凭证刷新周期。
## distributed\_cache\_data\_packet\_ack\_window
仅在 ClickHouse Cloud 中生效。用于在单个分布式缓存读取请求中为 DataPacket 序列发送 ACK 的窗口大小
## distributed\_cache\_discard\_connection\_if\_unread\_data
仅在 ClickHouse Cloud 中生效。如果存在未读取的数据，则丢弃连接。
## distributed\_cache\_fetch\_metrics\_only\_from\_current\_az
仅在 ClickHouse Cloud 中生效。在 system.distributed\_cache\_metrics 和 system.distributed\_cache\_events 中，仅拉取当前可用区的指标。
## distributed\_cache\_file\_cache\_name
仅在 ClickHouse Cloud 中生效。此设置仅用于 CI 测试——指定在分布式缓存中使用的文件系统缓存名称。
## distributed\_cache\_log\_mode
仅在 ClickHouse Cloud 中生效。用于写入 system.distributed\_cache\_log 的模式
## distributed\_cache\_max\_unacked\_inflight\_packets
仅在 ClickHouse Cloud 中生效。单个分布式缓存读取请求中未确认的在途数据包最大数量
## distributed\_cache\_min\_bytes\_for\_seek
仅在 ClickHouse Cloud 中生效。在分布式缓存中执行寻道操作的最小字节数。
## distributed\_cache\_pool\_behaviour\_on\_limit
仅在 ClickHouse Cloud 中生效。指定分布式缓存连接在达到连接池限制时的行为
## distributed\_cache\_prefer\_bigger\_buffer\_size
仅在 ClickHouse Cloud 中有效。与 filesystem\_cache\_prefer\_bigger\_buffer\_size 相同，但适用于分布式缓存。
## distributed\_cache\_read\_only\_from\_current\_az
仅在 ClickHouse Cloud 中生效。只允许从当前可用区读取；如果禁用，则会从所有可用区的所有缓存服务器读取。
## distributed\_cache\_read\_request\_max\_tries
仅在 ClickHouse Cloud 中生效。分布式缓存读取请求失败后的重试次数
## distributed\_cache\_receive\_response\_wait\_milliseconds
仅在 ClickHouse Cloud 中生效。表示从分布式缓存接收请求数据的等待时间，单位为毫秒
## distributed\_cache\_receive\_timeout\_milliseconds
仅在 ClickHouse Cloud 中生效。等待从分布式缓存接收任何类型响应的时间，单位为毫秒
Cloud 默认值：`20000`。
## distributed\_cache\_receive\_timeout\_ms
仅在 ClickHouse Cloud 中生效。表示从分布式缓存服务器接收数据的超时时间，单位为毫秒。如果在此时间间隔内未收到任何字节，则会抛出异常。
## distributed\_cache\_send\_timeout\_ms
仅在 ClickHouse Cloud 中生效。向分布式缓存服务器发送数据的超时时间，单位为毫秒。如果客户端需要发送数据，但在该时间间隔内一个字节都无法发送出去，则会抛出异常。
## distributed\_cache\_tcp\_keep\_alive\_timeout\_ms
仅在 ClickHouse Cloud 中生效。该值表示连接到分布式缓存服务器后，在 TCP 开始发送 keepalive 探测之前，连接可保持空闲的时间 (以毫秒为单位) 。
## distributed\_cache\_throw\_on\_error
仅在 ClickHouse Cloud 中生效。重新抛出与分布式缓存通信期间发生的异常，或从分布式缓存接收到的异常；否则，出错时回退为跳过分布式缓存。
## distributed\_cache\_use\_clients\_cache\_for\_read
仅在 ClickHouse Cloud 中生效。读取请求使用客户端缓存。
## distributed\_cache\_use\_clients\_cache\_for\_write
仅在 ClickHouse Cloud 中生效。对写入请求使用客户端缓存。
## distributed\_cache\_wait\_connection\_from\_pool\_milliseconds
仅在 ClickHouse Cloud 中生效。如果 distributed\_cache\_pool\_behaviour\_on\_limit 设置为 wait，则此项表示从连接池获取连接的等待时间 (毫秒) 。
## distributed\_cache\_write\_request\_max\_tries
仅在 ClickHouse Cloud 中生效。分布式缓存写请求失败时的重试次数
## distributed\_connections\_pool\_size
针对单个 Distributed 表的所有查询，在进行分布式处理时与远程服务器建立的最大同时连接数。建议将该值设置为不小于集群中的服务器数量。
## distributed\_ddl\_entry\_format\_version
分布式 DDL (ON CLUSTER) 查询的兼容性版本
Cloud 默认值：`6`。
## distributed\_ddl\_output\_mode
设置分布式 DDL 查询结果的格式。
可能的值：
* `throw` — 返回结果集，其中包含查询已完成的所有主机上的查询执行状态。如果查询在某些主机上失败，则会重新抛出第一个异常。如果查询在某些主机上尚未完成，且已超过 [distributed\_ddl\_task\_timeout](#distributed_ddl_task_timeout)，则会抛出 `TIMEOUT_EXCEEDED` 异常。
* `none` — 与 `throw` 类似，但分布式 DDL 查询不返回结果集。
* `null_status_on_timeout` — 如果查询在对应主机上尚未完成，则在结果集的某些行中返回 `NULL` 作为执行状态，而不是抛出 `TIMEOUT_EXCEEDED`。
* `never_throw` — 如果查询在某些主机上失败，则不会抛出 `TIMEOUT_EXCEEDED`，也不会重新抛出异常。
* `none_only_active` - 与 `none` 类似，但不会等待 `Replicated` 数据库的非活动副本。注意：在此模式下，无法判断查询是否未在某个副本上执行，以及它是否会在后台执行。
* `null_status_on_timeout_only_active` — 与 `null_status_on_timeout` 类似，但不会等待 `Replicated` 数据库的非活动副本
* `throw_only_active` — 与 `throw` 类似，但不会等待 `Replicated` 数据库的非活动副本
Cloud 默认值：`none_only_active`。
## distributed\_ddl\_task\_timeout
设置集群中所有主机返回 DDL 查询响应的超时时间。如果某个 DDL 请求尚未在所有主机上执行完成，响应将包含超时错误，并且该请求将以异步模式执行。负值表示无限等待。
可能的值：
* 正整数。
* 0 — 异步模式。
* 负整数 — 无限超时。
## distributed\_foreground\_insert
**别名**: `insert_distributed_sync`
启用或禁用向 [Distributed](/zh/reference/engines/table-engines/special/distributed) 表同步插入数据。
默认情况下，向 `Distributed` 表插入数据时，ClickHouse server 会以后台模式将数据发送到集群节点。设置 `distributed_foreground_insert=1` 时，数据会以同步方式处理，并且只有在所有分片上的数据都已保存后，`INSERT` 操作才会成功 (如果 `internal_replication` 为 true，则每个分片至少保存到一个副本) 。
可能的值：
* `0` — 数据以后台模式插入。
* `1` — 数据以同步模式插入。
Cloud 默认值：`1`。
**另请参见**
* [Distributed 表引擎](/zh/reference/engines/table-engines/special/distributed)
* [管理分布式表](/zh/reference/statements/system#managing-distributed-tables)
## distributed\_group\_by\_no\_merge
在分布式查询处理中，不合并来自不同服务器的聚合状态；当能够确定不同分片上的键各不相同时，可使用此设置
可能的值：
* `0` — 禁用 (最终查询处理在 initiator 节点上完成) 。
* `1` - 在分布式查询处理中，不合并来自不同服务器的聚合状态 (查询完全在分片上处理，initiator 仅负责代理数据) ；当能够确定不同分片上的键各不相同时，可使用此设置。
* `2` - 与 `1`` 相同，但会在 initiator 上应用 `ORDER BY`和`LIMIT`（对于像 `distributed\_group\_by\_no\_merge=1`这样在远程节点上完全处理的查询，这是无法实现的）；可用于带有`ORDER BY`和/或`LIMIT\` 的查询。
**示例**
```sql theme={null}
SELECT *
FROM remote('127.0.0.{2,3}', system.one)
GROUP BY dummy
LIMIT 1
SETTINGS distributed_group_by_no_merge = 1
FORMAT PrettyCompactMonoBlock
┌─dummy─┐
│ 0 │
│ 0 │
└───────┘
```
```sql theme={null}
SELECT *
FROM remote('127.0.0.{2,3}', system.one)
GROUP BY dummy
LIMIT 1
SETTINGS distributed_group_by_no_merge = 2
FORMAT PrettyCompactMonoBlock
┌─dummy─┐
│ 0 │
└───────┘
```
## distributed\_index\_analysis
索引分析将在各副本间分布式执行。
这对于共享存储以及 cluster 中海量数据的场景很有帮助。
使用 `cluster_for_parallel_replicas` 中的副本。
**另请参见**
* [distributed\_index\_analysis\_for\_non\_shared\_merge\_tree](#distributed_index_analysis_for_non_shared_merge_tree)
* [distributed\_index\_analysis\_min\_parts\_to\_activate](/zh/reference/settings/merge-tree-settings#distributed_index_analysis_min_parts_to_activate)
* [distributed\_index\_analysis\_min\_indexes\_bytes\_to\_activate](/zh/reference/settings/merge-tree-settings#distributed_index_analysis_min_indexes_bytes_to_activate)
## distributed\_index\_analysis\_for\_non\_shared\_merge\_tree
即使对非 SharedMergeTree (仅 Cloud 提供的引擎) 也启用分布式索引分析。
## distributed\_index\_analysis\_only\_on\_coordinator
如果启用，分布式索引分析将仅在协调器上执行。
当谓词包含子查询 (例如 `IN (SELECT ...)`) 时，这可以避免生成 O(N^2) 的查询，
因为否则每个 follower 副本都会各自触发自己的分布式索引分析；
但如果子查询中使用了大表，也会降低分布式索引分析的效率。
## distributed\_insert\_skip\_read\_only\_replicas
启用后，对 Distributed 执行 INSERT 查询时会跳过只读副本。
可选值：
* 0 — INSERT 与往常一样；如果发送到只读副本，则会失败
* 1 — 发起节点会在将数据发送到分片之前跳过只读副本。
## distributed\_plan\_default\_reader\_bucket\_count
分布式查询中并行读取的默认任务数。任务会分散到各个副本之间。
## distributed\_plan\_default\_shuffle\_join\_bucket\_count
分布式 shuffle-hash-join 的默认桶数。
## distributed\_plan\_execute\_locally
在本地执行分布式查询计划的所有任务。适用于测试和调试。
## distributed\_plan\_force\_exchange\_kind
强制指定分布式查询各阶段之间使用的 Exchange 算子类型。
可能的值：
* '' - 不强制使用任何类型的 Exchange 算子，由优化器自行选择，
* 'Persisted' - 在对象存储中使用临时 File，
* 'Streaming' - 通过网络流式传输 Exchange 数据。
## distributed\_plan\_force\_shuffle\_aggregation
在分布式查询计划中，使用 Shuffle 聚合策略，而不是 PartialAggregation + Merge。
## distributed\_plan\_max\_rows\_to\_broadcast
在分布式查询计划中，使用广播 join 而非 shuffle join 的最大行数。
## distributed\_plan\_optimize\_exchanges
移除分布式查询计划中不必要的 exchange。如需调试，请将其禁用。
## distributed\_plan\_prefer\_replicas\_over\_workers
将分布式查询计划序列化，以便在副本上执行。
## distributed\_product\_mode
更改[分布式子查询](/zh/reference/statements/in)的行为。
当查询包含分布式表的乘积时，也就是针对某个分布式表的查询中包含该分布式表的非 `GLOBAL` 子查询时，ClickHouse 会应用此设置。
限制：
* 仅适用于 `IN` 和 `JOIN` 子查询。
* 仅当 `FROM` 部分使用了包含多个分片的分布式表时。
* 仅当子查询涉及包含多个分片的分布式表时。
* 不适用于表值 [remote](/zh/reference/functions/table-functions/remote) 函数。
可能的值：
* `deny` — 默认值。禁止使用这类子查询 (返回 “Double-distributed in/JOIN subqueries is denied” 异常) 。
* `local` — 将子查询中的数据库和表替换为目标服务器 (分片) 的本地数据库和表，同时保留普通的 `IN`/`JOIN`。
* `global` — 将 `IN`/`JOIN` 查询替换为 `GLOBAL IN`/`GLOBAL JOIN`。
* `allow` — 允许使用这类子查询。
## distributed\_push\_down\_limit
启用或禁用在每个分片上分别应用 [LIMIT](#limit)。
这有助于避免：
* 通过网络传输额外的行；
* 在发起节点上处理超出限制的行。
从 21.9 版本开始，将不再出现不准确的结果，因为 `distributed_push_down_limit` 只有在至少满足以下一个条件时才会更改查询执行方式：
* [distributed\_group\_by\_no\_merge](#distributed_group_by_no_merge) > 0。
* 查询**不包含** `GROUP BY`/`DISTINCT`/`LIMIT BY`，但包含 `ORDER BY`/`LIMIT`。
* 查询**包含**带有 `ORDER BY`/`LIMIT` 的 `GROUP BY`/`DISTINCT`/`LIMIT BY`，并且：
* [optimize\_skip\_unused\_shards](#optimize_skip_unused_shards) 已启用。
* [optimize\_distributed\_group\_by\_sharding\_key](#optimize_distributed_group_by_sharding_key) 已启用。
可能的值：
* 0 — 禁用。
* 1 — 启用。
另请参见：
* [distributed\_group\_by\_no\_merge](#distributed_group_by_no_merge)
* [optimize\_skip\_unused\_shards](#optimize_skip_unused_shards)
* [optimize\_distributed\_group\_by\_sharding\_key](#optimize_distributed_group_by_sharding_key)
## distributed\_replica\_error\_cap
* 类型：无符号整数
* 默认值：1000
每个副本的错误计数上限为该值，以防止单个副本累计过多错误。
另请参见：
* [load\_balancing](#load_balancing-round_robin)
* [Distributed 表引擎](/zh/reference/engines/table-engines/special/distributed)
* [distributed\_replica\_error\_half\_life](#distributed_replica_error_half_life)
* [distributed\_replica\_max\_ignored\_errors](#distributed_replica_max_ignored_errors)
## distributed\_replica\_error\_half\_life
* 类型：秒
* 默认值：60 秒
控制分布式表中的错误计数归零的速度。如果某个副本在一段时间内不可用，累计了 5 次错误，并且 distributed\_replica\_error\_half\_life 设置为 1 秒，那么在最后一次出错 3 秒后，该副本会被视为恢复正常。
另请参见：
* [load\_balancing](#load_balancing-round_robin)
* [Distributed 表引擎](/zh/reference/engines/table-engines/special/distributed)
* [distributed\_replica\_error\_cap](#distributed_replica_error_cap)
* [distributed\_replica\_max\_ignored\_errors](#distributed_replica_max_ignored_errors)
## distributed\_replica\_max\_ignored\_errors
* 类型：无符号整数
* 默认值：0
根据 `load_balancing` 算法选择副本时，可忽略的错误数。
另请参见：
* [load\_balancing](#load_balancing-round_robin)
* [Distributed 表引擎](/zh/reference/engines/table-engines/special/distributed)
* [distributed\_replica\_error\_cap](#distributed_replica_error_cap)
* [distributed\_replica\_error\_half\_life](#distributed_replica_error_half_life)
## do\_not\_merge\_across\_partitions\_select\_final
通过避免跨不同分区进行合并，提升 FINAL 查询的性能。
启用后，在 SELECT FINAL 查询期间，来自不同分区的 parts 不会合并在一起，而只会在各个分区内分别进行合并。这在处理分区表时可显著提升查询性能。
## dynamic\_disk\_allow\_from\_env
允许在动态磁盘配置中使用 `from_env` 替换 (即在 `disk()` 函数的参数中使用) 。
默认禁用，以防止用户在定义表存储时读取任意环境变量。
## dynamic\_disk\_allow\_from\_zk
允许在动态磁盘配置中使用 `from_zk` 替换 (即在 `disk()` 函数参数中使用) 。
默认禁用。
## dynamic\_disk\_allow\_include
允许在动态磁盘配置中使用 `include` (即在 `disk()` 函数参数中) 。
默认禁用。
## dynamic\_throw\_on\_type\_mismatch
使用默认实现对 [Dynamic](/zh/reference/data-types/dynamic) 列应用函数时，
控制实际类型与该函数不兼容的那些行如何处理：
* `true` (默认) — 抛出异常。
* `false` — 对这些行返回 `NULL`。
## empty\_result\_for\_aggregation\_by\_constant\_keys\_on\_empty\_set
在空集上按常量键聚合时，返回空结果。
## empty\_result\_for\_aggregation\_by\_empty\_set
对空集进行无键聚合时，返回空结果。
## enable\_adaptive\_memory\_spill\_scheduler
触发处理器将数据自适应落盘到外部存储。目前仅支持 grace join。
## enable\_add\_distinct\_to\_in\_subqueries
在 `IN` 子查询中启用 `DISTINCT`。这是一个需要权衡的设置：启用后，通过确保只发送唯一值，可以大幅减小为分布式 `IN` 子查询传输的临时表大小，并显著加快分片之间的数据传输。
不过，启用此设置会给每个节点带来额外的合并开销，因为必须执行去重 (`DISTINCT`) 。当网络传输成为瓶颈，且可以接受额外的合并成本时，可使用此设置。
## enable\_automatic\_decision\_for\_merging\_across\_partitions\_for\_final
如果启用此项，当分区键表达式具有确定性，且分区键表达式中使用的所有列都包含在主键中时，ClickHouse 会自动启用此优化。
这种自动推导可确保具有相同主键值的行始终属于同一分区，因此可以安全地避免跨分区合并。
## enable\_blob\_storage\_log
将 blob 存储操作信息写入 system.blob\_storage\_log 表
## enable\_blob\_storage\_log\_for\_read\_operations
将 blob 存储读取操作的信息写入 system.blob\_storage\_log 表。
还需要同时启用 `enable_blob_storage_log`。
## enable\_early\_constant\_folding
启用查询优化：分析函数和子查询的结果；如果其中包含常量，则重写查询
## enable\_extended\_results\_for\_datetime\_functions
启用或禁用返回扩展范围的 `Date32` 类型结果 (相较于 `Date` 类型) ，
或返回扩展范围的 `DateTime64` 类型结果 (相较于 `DateTime` 类型) 。
Possible values:
* `0` — 对于所有类型的参数，函数均返回 `Date` 或 `DateTime`。
* `1` — 对于 `Date32` 或 `DateTime64` 参数，函数返回 `Date32` 或 `DateTime64`；否则返回 `Date` 或 `DateTime`。
下表展示了此设置对各种日期时间函数行为的影响。
| 函数 | `enable_extended_results_for_datetime_functions = 0` | `enable_extended_results_for_datetime_functions = 1` |
| ------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `toStartOfYear` | 返回 `Date` 或 `DateTime` | 对于 `Date`/`DateTime` 类型的输入，返回 `Date`/`DateTime`
对于 `Date32`/`DateTime64` 类型的输入，返回 `Date32`/`DateTime64` |
| `toStartOfISOYear` | 返回 `Date` 或 `DateTime` | 对于 `Date`/`DateTime` 类型的输入，返回 `Date`/`DateTime`
对于 `Date32`/`DateTime64` 类型的输入，返回 `Date32`/`DateTime64` |
| `toStartOfQuarter` | 返回 `Date` 或 `DateTime` | 对于 `Date`/`DateTime` 类型的输入，返回 `Date`/`DateTime`
对于 `Date32`/`DateTime64` 类型的输入，返回 `Date32`/`DateTime64` |
| `toStartOfMonth` | 返回 `Date` 或 `DateTime` | `Date`/`DateTime` 输入时，返回 `Date`/`DateTime`
`Date32`/`DateTime64` 输入时，返回 `Date32`/`DateTime64` |
| `toStartOfWeek` | 返回 `Date` 或 `DateTime` | 对于 `Date`/`DateTime` 类型的输入，返回 `Date`/`DateTime`
对于 `Date32`/`DateTime64` 类型的输入，返回 `Date32`/`DateTime64` |
| `toLastDayOfWeek` | 返回 `Date` 或 `DateTime` | 对于 `Date`/`DateTime` 类型的输入，返回 `Date`/`DateTime`
对于 `Date32`/`DateTime64` 类型的输入，返回 `Date32`/`DateTime64` |
| `toLastDayOfMonth` | 返回 `Date` 或 `DateTime` | 对于 `Date`/`DateTime` 类型的输入，返回 `Date`/`DateTime`
对于 `Date32`/`DateTime64` 类型的输入，返回 `Date32`/`DateTime64` |
| `toMonday` | 返回 `Date` 或 `DateTime` | 对于 `Date`/`DateTime` 类型的输入，返回 `Date`/`DateTime`
对于 `Date32`/`DateTime64` 类型的输入，返回 `Date32`/`DateTime64` |
| `toStartOfDay` | 返回 `DateTime`
*注意：对于超出 1970-2149 范围的值，会返回错误结果* | 对于 `Date`/`DateTime` 类型的输入，返回 `DateTime`
对于 `Date32`/`DateTime64` 类型的输入，返回 `DateTime64` |
| `toStartOfHour` | 返回 `DateTime`
*注意：对于超出 1970–2149 范围的值，结果会不正确* | 对于 `Date`/`DateTime` 类型的输入，返回 `DateTime`
对于 `Date32`/`DateTime64` 类型的输入，返回 `DateTime64` |
| `toStartOfFifteenMinutes` | 返回 `DateTime`
*注意：对于超出 1970-2149 范围的值，结果会不正确。* | 对于 `Date`/`DateTime` 类型的输入，返回 `DateTime`
对于 `Date32`/`DateTime64` 类型的输入，返回 `DateTime64` |
| `toStartOfTenMinutes` | 返回 `DateTime`
*注意：对于超出 1970-2149 范围的值，结果可能不正确* | 对于 `Date`/`DateTime` 类型的输入，返回 `DateTime`
对于 `Date32`/`DateTime64` 类型的输入，返回 `DateTime64` |
| `toStartOfFiveMinutes` | 返回 `DateTime`
*注意：对于超出 1970-2149 范围的值，结果会不正确* | 对于 `Date`/`DateTime` 类型的输入，返回 `DateTime`
对于 `Date32`/`DateTime64` 类型的输入，返回 `DateTime64` |
| `toStartOfMinute` | 返回 `DateTime`
*注意：对于超出 1970-2149 范围的值，结果会不正确* | 对于 `Date`/`DateTime` 类型的输入，返回 `DateTime`
对于 `Date32`/`DateTime64` 类型的输入，返回 `DateTime64` |
| `timeSlot` | 返回 `DateTime`
*注意：对于超出 1970-2149 范围的值，结果会不正确。* | 对于 `Date`/`DateTime` 类型的输入，返回 `DateTime`
对于 `Date32`/`DateTime64` 类型的输入，返回 `DateTime64` |
## enable\_filesystem\_cache
对远程文件系统使用缓存。此设置不会为磁盘启用/禁用缓存 (必须通过 disk 配置完成) ，但如果需要，它允许某些查询绕过缓存
## enable\_filesystem\_cache\_log
允许为每个查询记录文件系统缓存日志
## enable\_filesystem\_cache\_on\_write\_operations
启用或禁用 `write-through` 缓存。若设置为 `false`，则对写入操作禁用 `write-through` 缓存。若设置为 `true`，则只要在 server config 的 cache disk configuration 部分启用了 `cache_on_write_operations`，就会启用 `write-through` 缓存。
更多详情请参见[“使用本地缓存”](/zh/concepts/features/configuration/server-config/storing-data#using-local-cache)。
Cloud 默认值：`1`。
## enable\_filesystem\_read\_prefetches\_log
在查询期间向 system.filesystem prefetch\_log 记录日志。仅应用于测试或调试，不建议默认启用
## enable\_full\_text\_index
**别名**: `allow_experimental_full_text_index`
如果设置为 true，则允许使用文本索引。
## enable\_global\_with\_statement
将 WITH 语句应用于 UNION 查询及所有子查询
## enable\_hdfs\_pread
启用或禁用 HDFS 文件的 pread。默认使用 `hdfsPread`。如果禁用，则会使用 `hdfsRead` 和 `hdfsSeek` 来读取 HDFS 文件。
## enable\_http\_compression
启用或禁用 HTTP 请求响应中的数据压缩。
更多信息，请参阅 [HTTP 接口说明](/zh/concepts/features/interfaces/http)。
可能的值：
* 0 — 禁用。
* 1 — 启用。
## enable\_identifier\_resolve\_cache
在查询分析器中启用标识符解析缓存。该缓存会共享已解析的别名节点，以避免多次引用同一别名时 AST 膨胀。如果怀疑会产生错误结果，可将其设置为 false 以禁用缓存。
## enable\_job\_stack\_trace
当 job 导致异常时，输出 job 创建者的堆栈跟踪。默认禁用，以避免性能开销。
## enable\_join\_fixed\_hash\_table\_conversion
当键为值域较小的单个整数时，启用将用于 join 的哈希表转换为扁平数组。
## enable\_join\_runtime\_filters
在运行时，根据从右侧收集的 JOIN 连接键集合对左侧进行过滤。
## enable\_join\_transitive\_predicates
根据现有 JOIN 条件推断传递性的等值 JOIN 谓词。
例如，给定 `A.x = B.x` 和 `B.x = C.x`，会额外添加一个 `A.x = C.x` 谓词，
以便 JOIN 顺序优化器能够考虑直接的 (A JOIN C) 执行计划。
## enable\_lazy\_columns\_replication
启用 JOIN 和 ARRAY JOIN 中的惰性列复制，可避免在内存中多次重复复制相同的行。
## enable\_lightweight\_delete
**别名**: `allow_experimental_lightweight_delete`
启用 MergeTree 表的轻量级 DELETE 变更功能。
## enable\_lightweight\_update
**别名**: `allow_experimental_lightweight_update`
允许使用轻量级更新。
## enable\_materialized\_cte
启用物化公共表表达式；其优先级高于 enable\_global\_with\_statement
## enable\_memory\_bound\_merging\_of\_aggregation\_results
启用用于聚合的内存受限合并策略。
## enable\_multiple\_prewhere\_read\_steps
如果存在多个以 AND 连接的条件，则将更多条件从 WHERE 移至 PREWHERE，并分多步执行磁盘读取和过滤
## enable\_named\_columns\_in\_function\_tuple
当所有名称都唯一且可视为不带引号的标识符时，在 tuple() 函数中生成命名元组。
## enable\_optimize\_predicate\_expression
在 `SELECT` 查询中启用谓词下推。
对于分布式查询，谓词下推可显著减少网络流量。
可能的值：
* 0 — 禁用。
* 1 — 启用。
用法
请参考以下查询：
1. `SELECT count() FROM test_table WHERE date = '2018-10-10'`
2. `SELECT count() FROM (SELECT * FROM test_table) WHERE date = '2018-10-10'`
如果 `enable_optimize_predicate_expression = 1`，这两个查询的执行时间相同，因为 ClickHouse 在处理子查询时会将 `WHERE` 条件下推到子查询中。
如果 `enable_optimize_predicate_expression = 0`，那么第二个查询的执行时间会长得多，因为只有在子查询完成后，`WHERE` 子句才会应用到所有数据上。
## enable\_optimize\_predicate\_expression\_to\_final\_subquery
允许将谓词下推到 FINAL 子查询。
## enable\_order\_by\_all
启用或禁用 `ORDER BY ALL` 排序语法，参见 [ORDER BY](/zh/reference/statements/select/order-by)。
可能的值：
* 0 — 禁用 ORDER BY ALL。
* 1 — 启用 ORDER BY ALL。
**示例**
查询：
```sql theme={null}
CREATE TABLE TAB(C1 Int, C2 Int, ALL Int) ENGINE=Memory();
INSERT INTO TAB VALUES (10, 20, 30), (20, 20, 10), (30, 10, 20);
SELECT * FROM TAB ORDER BY ALL; -- 返回错误，提示 ALL 存在歧义
SELECT * FROM TAB ORDER BY ALL SETTINGS enable_order_by_all = 0;
```
结果：
```text theme={null}
┌─C1─┬─C2─┬─ALL─┐
│ 20 │ 20 │ 10 │
│ 30 │ 10 │ 20 │
│ 10 │ 20 │ 30 │
└────┴────┴─────┘
```
## enable\_parallel\_blocks\_marshalling
仅影响分布式查询。如果启用，块会在发送给发起节点之前/之后，在管道线程上进行 (反) 序列化和 (反) 压缩 (即并行度高于默认情况) 。
## enable\_parsing\_to\_custom\_serialization
如果为 true，则可根据从表中获取的序列化提示，将数据直接解析到采用自定义序列化 (例如 Sparse) 的列中。
## enable\_positional\_arguments
启用或禁用在 [GROUP BY](/zh/reference/statements/select/group-by)、[LIMIT BY](/zh/reference/statements/select/limit-by) 和 [ORDER BY](/zh/reference/statements/select/order-by) 语句中对位置参数的支持。
可能的值：
* 0 — 不支持位置参数。
* 1 — 支持位置参数：可使用列编号代替列名。
**示例**
查询：
```sql theme={null}
CREATE TABLE positional_arguments(one Int, two Int, three Int) ENGINE=Memory();
INSERT INTO positional_arguments VALUES (10, 20, 30), (20, 20, 10), (30, 10, 20);
SELECT * FROM positional_arguments ORDER BY 2,3;
```
结果：
```text theme={null}
┌─one─┬─two─┬─three─┐
│ 30 │ 10 │ 20 │
│ 20 │ 20 │ 10 │
│ 10 │ 20 │ 30 │
└─────┴─────┴───────┘
```
## enable\_positional\_arguments\_for\_projections
启用或禁用在 PROJECTION 定义中使用位置参数。另请参阅 [enable\_positional\_arguments](#enable_positional_arguments) 设置。
这是一个专家级设置；如果你刚开始使用 ClickHouse，则不应更改它。
可能的值：
* 0 — 不支持位置参数。
* 1 — 支持位置参数：可以使用列号代替列名。
## enable\_producing\_buckets\_out\_of\_order\_in\_aggregation
允许内存高效的聚合 (参见 `distributed_aggregation_memory_efficient`) 乱序生成桶。
当聚合中的桶大小分布不均时，此设置可允许副本在仍处理一些较重的低 ID 桶时，向发起节点发送更高 ID 的桶，从而提升性能。
缺点是可能会增加内存使用量。
## enable\_reads\_from\_query\_cache
启用后，将从[查询缓存](/zh/concepts/features/performance/caches/query-cache)中读取 `SELECT` 查询结果。
可能的值：
* 0 - 禁用
* 1 - 启用
## enable\_s3\_requests\_logging
启用非常详细的 S3 请求日志记录。仅建议在调试时使用。
## enable\_scalar\_subquery\_optimization
如果将其设置为 true，则可防止标量子查询对大型标量值进行 (反) 序列化，并且还可能避免重复执行同一子查询。
## enable\_scopes\_for\_with\_statement
如果禁用此设置，父级 WITH 子句中的声明将与在当前作用域中声明时具有相同的作用域行为。
请注意，这是 analyzer 的兼容性设置，用于允许运行一些旧 analyzer 可以执行的无效查询。
## enable\_sharding\_aggregator
启用分片式 `GROUP BY` 优化。该优化通过对分组键进行哈希，将行分散到各个线程，使每个线程都能聚合互不重叠的键子集，无需经过合并阶段。
对于数据分布均匀的高基数键，这种方式效率很高；但如果键分布高度倾斜，或者查询中不同键的数量很少，效果可能会较差。
可能的值：
* 0 — 禁用分片聚合优化。
* 1 — 启用分片聚合优化。
## enable\_shared\_storage\_snapshot\_in\_query
如果启用，单个查询中的所有子查询都会为每个表共享同一个 StorageSnapshot。
这可确保整个查询中的数据视图保持一致，即使同一个表被多次访问也是如此。
对于要求数据分区片段内部一致性的查询，这是必需的。示例：
```sql theme={null}
SELECT
count()
FROM events
WHERE (_part, _part_offset) IN (
SELECT _part, _part_offset
FROM events
WHERE user_id = 42
)
```
如果没有启用此设置，外层查询和内层查询可能会基于不同的数据快照执行，从而导致结果不正确。
启用此设置后，会禁用这样一项优化：在规划阶段完成后，从快照中移除不必要的数据分区片段。
因此，长时间运行的查询可能会在整个耗时期间一直保留已过时的数据分区片段，从而延迟分区片段清理并增加存储压力。
此设置当前仅适用于 MergeTree 家族的表。
可选值：
* 0 - 已禁用
* 1 - 已启用
## enable\_sharing\_sets\_for\_mutations
允许在同一变更的不同任务之间共享为 IN 子查询构建的 Set 对象。这将减少内存占用和 CPU 消耗
## enable\_software\_prefetch\_in\_aggregation
启用在聚合过程中使用软件预取
## enable\_software\_prefetch\_in\_join
启用在哈希连接探测阶段使用软件预取，以掩盖大型哈希表的内存访问延迟。
## enable\_streaming\_queries
允许 `SELECT ... FROM t STREAM [CURSOR '{...}']` 持续查询。
关闭时，任何使用 `STREAM` 修饰符的表表达式都会在构建执行计划时被拒绝。
这是流式查询功能的总开关；其他相关能力可能还受其各自设置的控制。
## enable\_time\_time64\_type
**别名**: `allow_experimental_time_time64_type`
允许创建 [Time](/zh/reference/data-types/time) 和 [Time64](/zh/reference/data-types/time64) 数据类型。
## enable\_unaligned\_array\_join
允许对多个长度不同的数组执行 ARRAY JOIN。启用此设置后，数组会调整为与最长数组相同的长度。
## enable\_url\_encoding
允许在 [URL](/zh/reference/engines/table-engines/special/url) 引擎表中启用或禁用对 URI 中路径部分的解码/编码。
默认禁用。
## enable\_vertical\_final
如果启用，则会在 FINAL 期间通过将行标记为已删除并在后续过滤掉这些行来移除重复行，而不是合并这些行
## enable\_writes\_to\_query\_cache
启用后，`SELECT` 查询的结果会存储在[查询缓存](/zh/concepts/features/performance/caches/query-cache)中。
可能的值：
* 0 - 禁用
* 1 - 启用
## enforce\_strict\_identifier\_format
启用后，将只允许由字母、数字和下划线组成的标识符。
## engine\_file\_allow\_create\_multiple\_files
对于 File 表引擎的表，如果格式带有后缀 (`JSON`、`ORC`、`Parquet` 等) ，此设置用于启用或禁用每次插入时创建新文件的行为。如果启用，则每次插入都会按以下模式创建一个新文件：
`data.Parquet` -> `data.1.Parquet` -> `data.2.Parquet`，等等。
可能的值：
* 0 — `INSERT` 查询会将新数据追加到文件末尾。
* 1 — `INSERT` 查询会创建一个新文件。
## engine\_file\_empty\_if\_not\_exists
允许在文件不存在时从 File 表引擎表中查询数据。
可能的值：
* 0 — `SELECT` 抛出异常。
* 1 — `SELECT` 返回空结果。
## engine\_file\_skip\_empty\_files
启用或禁用在 [File 表引擎](/zh/reference/engines/table-engines/special/file) 表中跳过空文件的行为。
可能的值：
* 0 — 如果空文件与请求的格式不兼容，`SELECT` 会抛出异常。
* 1 — 对于空文件，`SELECT` 返回空结果。
## engine\_file\_truncate\_on\_insert
启用或禁用在 [File 表引擎](/zh/reference/engines/table-engines/special/file) 表中执行插入前截断。
可能的值：
* 0 — `INSERT` 查询会将新数据追加到文件末尾。
* 1 — `INSERT` 查询会用新数据替换文件的现有内容。
## engine\_url\_skip\_empty\_files
启用或禁用在 [URL](/zh/reference/engines/table-engines/special/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 时，不构建也不存储指定的跳过索引。被排除的跳过索引仍会[在合并期间](/zh/reference/settings/merge-tree-settings#materialize_skip_indexes_on_merge)构建并存储，或者通过显式执行
[MATERIALIZE INDEX](/zh/reference/statements/alter/skipping-index#materialize-index)查询来构建并存储。
如果 [materialize\_skip\_indexes\_on\_insert](#materialize_skip_indexes_on_insert) 为 false，则此设置无效。
示例：
```sql theme={null}
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 在插入时不会被更新
--SET exclude_materialize_skip_indexes_on_insert='idx_a, idx_b'; -- 两个索引在插入时均不会被更新
INSERT INTO tab SELECT number, number / 50 FROM numbers(100); -- 仅 idx_b 会被更新
-- 由于这是会话级设置，可以在单次查询时单独指定
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; -- 可通过此查询显式物化该索引
SET exclude_materialize_skip_indexes_on_insert = DEFAULT; -- 将设置重置为默认值
```
## execute\_exists\_as\_scalar\_subquery
将非关联 EXISTS 子查询作为标量子查询执行。与标量子查询一样，会使用缓存，并对结果进行常量折叠。
Cloud 默认值：`0`。
## external\_storage\_connect\_timeout\_sec
连接超时时间 (秒) 。目前仅支持 MySQL
## external\_storage\_max\_read\_bytes
限制使用 external engine 的表在刷新历史数据时可读取的最大字节数。当前仅支持 MySQL table engine、database engine 和字典。如果该值等于 0，则禁用此设置。
## external\_storage\_max\_read\_rows
当使用 external engine 的表需要刷新历史数据时，限制可读取的最大行数。目前仅支持 MySQL table engine、database engine 和字典。如果等于 0，则此设置禁用
## external\_storage\_rw\_timeout\_sec
读写超时时间 (秒) 。目前仅支持 MySQL
## external\_table\_functions\_use\_nulls
定义 [mysql](/zh/reference/functions/table-functions/mysql)、[postgresql](/zh/reference/functions/table-functions/postgresql) 和 [odbc](/zh/reference/functions/table-functions/odbc) 表函数如何使用 Nullable 列。
可能的值：
* 0 — 表函数显式使用 Nullable 列。
* 1 — 表函数隐式使用 Nullable 列。
**用法**
如果将该设置设为 `0`，表函数不会生成 Nullable 列，而是插入默认值来代替 NULL。这同样适用于数组中的 NULL 值。
## external\_table\_strict\_query
如果设置为 true，则禁止在针对外部表的查询中将表达式转换为本地过滤器。
**别名**: `extract_kvp_max_pairs_per_row`
`extractKeyValuePairs` 函数可生成的键值对最大数量。用于防止占用过多内存。
## 极值
是否统计极值 (即查询结果各列中的最小值和最大值) 。可取值为 0 或 1。默认值为 0 (禁用) 。
更多信息，请参见“极值”部分。
## fallback\_to\_stale\_replicas\_for\_distributed\_queries
如果最新数据不可用，则强制将查询发送到过时的副本。请参阅 [复制](/zh/reference/engines/table-engines/mergetree-family/replication)。
ClickHouse 会从该表的过期副本中选择最合适的一个。
在对指向复制表的分布式表执行 `SELECT` 时使用。
默认值为 1 (已启用) 。
## file\_like\_engine\_default\_partition\_strategy
类文件表引擎的默认分区策略。
## filesystem\_cache\_allow\_background\_download
允许文件系统缓存将从远程存储读取的数据加入后台下载队列。禁用后，当前查询/会话的下载将继续在前台进行。
## filesystem\_cache\_boundary\_alignment
文件系统缓存的边界对齐。此设置仅适用于非磁盘读取 (例如远程表引擎 / 表函数的缓存，而不适用于 MergeTree 表的存储配置) 。值为 0 表示不对齐。
## filesystem\_cache\_enable\_background\_download\_during\_fetch
仅在 ClickHouse Cloud 中生效。为在文件系统缓存中预留空间而锁定缓存时的等待时间
## filesystem\_cache\_enable\_background\_download\_for\_metadata\_files\_in\_packed\_storage
仅在 ClickHouse Cloud 中生效。在文件系统缓存中为预留空间而获取缓存锁的等待时间
## filesystem\_cache\_max\_download\_size
单个查询可下载的远程文件系统缓存最大大小
## filesystem\_cache\_name
用于无状态表引擎或数据湖的文件系统缓存名称
## filesystem\_cache\_prefer\_bigger\_buffer\_size
如果启用了文件系统缓存，则优先使用更大的缓冲区大小，以避免写入较小的 File 段而降低缓存性能。另一方面，启用此设置可能会增加内存使用量。
## filesystem\_cache\_reserve\_space\_wait\_lock\_timeout\_milliseconds
在文件系统缓存中为预留空间而等待获取缓存锁的时间
## filesystem\_cache\_segments\_batch\_size
读取缓冲区单次可从缓存请求的 File 段批次大小上限。值过低会导致向缓存发起过多请求，值过高则可能减慢缓存的淘汰速度
## filesystem\_cache\_skip\_download\_if\_exceeds\_per\_query\_cache\_write\_limit
**别名**: `skip_download_if_exceeds_query_cache`
如果会超过查询缓存大小，则跳过从远程文件系统下载
## filesystem\_prefetch\_max\_memory\_usage
预取操作的最大内存用量。
Cloud 默认值：总内存的 10%。
## filesystem\_prefetch\_step\_bytes
预取步长，单位为字节。零表示 `auto`——系统会自动推导出大致最佳的预取步长，但可能并非 100% 最优。由于受设置 filesystem\_prefetch\_min\_bytes\_for\_single\_read\_task 的影响，实际值可能会有所不同
## filesystem\_prefetch\_step\_marks
以标记为单位的预取步长。零表示 `auto` —— 系统会自动推导出一个近似最优的预取步长，但不一定是 100% 最优。由于受设置 filesystem\_prefetch\_min\_bytes\_for\_single\_read\_task 的影响，实际值可能有所不同
## filesystem\_prefetches\_limit
预取操作的最大数量。0 表示不受限制。如果你想限制预取数量，建议优先使用设置 `filesystem_prefetches_max_memory_usage`
## final
自动对查询中的所有表应用 [FINAL](/zh/reference/statements/select/from#final-modifier) 修饰符，包括所有可使用 [FINAL](/zh/reference/statements/select/from#final-modifier) 的表、联接表、子查询中的表，以及
分布式表。
可能的值：
* 0 - 禁用
* 1 - 启用
示例：
```sql theme={null}
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 的输出 stream 都会保持打开状态，直到整个 part (包括所有 projections) 都完成最终化；这样可以让 S3 上传并行重叠进行，但也会使峰值内存占用随 projections 数量增加而上升。此设置仅影响 INSERT 路径；merge 和 mutation 已经会同步最终化 projections。
## flatten\_nested
设置 [nested](/zh/reference/data-types/nested-data-structures/index) 列的数据格式。
可能的值：
* 1 — Nested 列会展平为独立的数组。
* 0 — Nested 列保持为单个元组数组。
**用法**
如果将该设置设为 `0`，则可以使用任意层级的嵌套。
**示例**
查询：
```sql theme={null}
SET flatten_nested = 1;
CREATE TABLE t_nest (`n` Nested(a UInt32, b UInt32)) ENGINE = MergeTree ORDER BY tuple();
SHOW CREATE TABLE t_nest;
```
结果：
```text theme={null}
┌─statement───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ CREATE TABLE default.t_nest
(
`n.a` Array(UInt32),
`n.b` Array(UInt32)
)
ENGINE = MergeTree
ORDER BY tuple()
SETTINGS index_granularity = 8192 │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```
查询：
```sql theme={null}
SET flatten_nested = 0;
CREATE TABLE t_nest (`n` Nested(a UInt32, b UInt32)) ENGINE = MergeTree ORDER BY tuple();
SHOW CREATE TABLE t_nest;
```
结果：
```text theme={null}
┌─statement──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ CREATE TABLE default.t_nest
(
`n` Nested(a UInt32, b UInt32)
)
ENGINE = MergeTree
ORDER BY tuple()
SETTINGS index_granularity = 8192 │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```
## force\_aggregate\_partitions\_independently
在适用时强制启用该优化，即使启发式规则判断不使用它
## force\_aggregation\_in\_order
此设置由服务器自身用于支持分布式查询。请勿手动修改，否则会影响正常运行。 (在分布式聚合期间，强制远程节点使用按顺序聚合。)
## force\_data\_skipping\_indices
如果指定的数据跳过索引未被使用，则禁用查询执行。
考虑以下示例：
```sql theme={null}
CREATE TABLE data
(
key Int,
d1 Int,
d1_null Nullable(Int),
INDEX d1_idx d1 TYPE minmax GRANULARITY 1,
INDEX d1_null_idx assumeNotNull(d1_null) TYPE minmax GRANULARITY 1
)
Engine=MergeTree()
ORDER BY key;
SELECT * FROM data_01515;
SELECT * FROM data_01515 SETTINGS force_data_skipping_indices=''; -- 查询将产生 CANNOT_PARSE_TEXT 错误。
SELECT * FROM data_01515 SETTINGS force_data_skipping_indices='d1_idx'; -- 查询将产生 INDEX_NOT_USED 错误。
SELECT * FROM data_01515 WHERE d1 = 0 SETTINGS force_data_skipping_indices='d1_idx'; -- 正常。
SELECT * FROM data_01515 WHERE d1 = 0 SETTINGS force_data_skipping_indices='`d1_idx`'; -- 正常（完整解析器示例）。
SELECT * FROM data_01515 WHERE d1 = 0 SETTINGS force_data_skipping_indices='`d1_idx`, d1_null_idx'; -- 查询将产生 INDEX_NOT_USED 错误，因为 d1_null_idx 未被使用。
SELECT * FROM data_01515 WHERE d1 = 0 AND assumeNotNull(d1_null) = 0 SETTINGS force_data_skipping_indices='`d1_idx`, d1_null_idx'; -- 正常。
```
## force\_grouping\_standard\_compatibility
使 GROUPING 函数在参数未用作聚合键时返回 1
## force\_index\_by\_date
如果查询无法利用日期索引，则禁用查询执行。
适用于 MergeTree 家族中的表。
如果 `force_index_by_date=1`，ClickHouse 会检查查询是否包含可用于限制数据范围的日期键条件。如果没有合适的条件，则会抛出异常。不过，它不会检查该条件是否能减少需要读取的数据量。例如，即使条件 `Date != ' 2000-01-01 '` 与表中的所有数据都匹配 (即运行该查询需要全表扫描) ，该条件也是可接受的。有关 MergeTree 表中数据范围的更多信息，请参见 [MergeTree](/zh/reference/engines/table-engines/mergetree-family/mergetree)。
## force\_optimize\_projection
在启用投影优化时 (请参见 [optimize\_use\_projections](#optimize_use_projections) 设置) ，控制是否在 `SELECT` 查询中强制使用[投影](/zh/reference/engines/table-engines/mergetree-family/mergetree#projections)。
可能的值：
* 0 — 不强制使用投影优化。
* 1 — 强制使用投影优化。
## force\_optimize\_projection\_name
如果将其设置为非空字符串，则会检查查询中是否至少使用过一次该投影。
可能的值：
* string：查询中使用的投影名称
## force\_optimize\_skip\_unused\_shards
如果启用了 [optimize\_skip\_unused\_shards](#optimize_skip_unused_shards)，但无法跳过未使用的分片，此设置可用于启用或禁用查询执行。若无法跳过且启用了此设置，则会抛出异常。
可能的值：
* 0 — 已禁用。ClickHouse 不会抛出异常。
* 1 — 已启用。仅当表具有分片键时，才会禁用查询执行。
* 2 — 已启用。无论表是否定义了分片键，都会禁用查询执行。
## force\_optimize\_skip\_unused\_shards\_nesting
根据分布式查询的嵌套层级来控制 [`force_optimize_skip_unused_shards`](#force_optimize_skip_unused_shards) (因此仍需启用 [`force_optimize_skip_unused_shards`](#force_optimize_skip_unused_shards)) 。例如，一个 `Distributed` 表查询另一个 `Distributed` 表时就属于这种情况。
可能的值：
* 0 - 禁用，`force_optimize_skip_unused_shards` 始终生效。
* 1 — 仅在第一层启用 `force_optimize_skip_unused_shards`。
* 2 — 在最多两层嵌套内启用 `force_optimize_skip_unused_shards`。
## force\_primary\_key
如果查询无法利用主键索引，则禁止执行查询。
适用于 MergeTree 家族中的表。
如果 `force_primary_key=1`，ClickHouse 会检查查询是否包含可用于限制数据范围的主键条件。如果没有合适的条件，则会抛出异常。不过，它不会检查该条件是否会减少需要读取的数据量。有关 MergeTree 表中数据范围的更多信息，请参见 [MergeTree](/zh/reference/engines/table-engines/mergetree-family/mergetree)。
## force\_remove\_data\_recursively\_on\_drop
在执行 DROP 查询时递归删除数据。可避免出现“Directory not empty”错误，但也可能静默删除 detached 数据
## formatdatetime\_e\_with\_space\_padding
函数 `formatDateTime` 中的格式说明符 '%e' 会在个位数日期前补一个空格，例如输出 ' 2'，而不是 '2'。
## formatdatetime\_f\_prints\_scale\_number\_of\_digits
函数 `formatDateTime` 中的格式说明符 `%f` 对于 DateTime64 只会输出与标度相对应位数的数字，而不是固定输出 6 位数字。
## formatdatetime\_f\_prints\_single\_zero
函数 `formatDateTime` 中的格式说明符 `%f` 在格式化值不含秒的小数部分时，会输出单个零，而不是六个零。
## formatdatetime\_format\_without\_leading\_zeros
函数 `formatDateTime` 中的格式说明符 `%c`、`%l` 和 `%k` 在输出月份和小时时不会补前导零。
## formatdatetime\_parsedatetime\_m\_is\_month\_name
函数 `formatDateTime` 和 `parseDateTime` 中的格式说明符 `%M` 会输出/解析月份名称，而不是分钟。
## fsync\_metadata
控制在写入 `.sql` 文件时是否执行 [fsync](http://pubs.opengroup.org/onlinepubs/9699919799/functions/fsync.html)。默认启用。
如果 server 中有数百万个持续创建和删除的小型表，禁用它会更合适。
## function\_base58\_max\_input\_size
函数 `base58Encode`、`base58Decode` 和 `tryBase58Decode` 的单个输入值的最大大小 (以字节为单位) 。通用的 `base58` 转换相对于输入长度具有二次复杂度，因此单个较大的值可能会运行很长时间。`base58` 适用于较短的数据 (键、哈希、地址) ，因此默认的 10 KB 是一个较为宽松的安全阈值。对于更大的输入，`base58Encode` 和 `base58Decode` 会抛出 `TOO_LARGE_STRING_SIZE`，而 `tryBase58Decode` 会返回空字符串。值为 `0` 时会禁用该限制 (即引入此设置之前的行为) 。线性的 `base32` 和 `base64` 函数不受影响。
## function\_date\_trunc\_return\_type\_behavior
允许更改 `dateTrunc` 函数结果类型的行为。
Possible values:
* 0 - 当第二个参数为 `DateTime64/Date32` 时，返回类型将为 `DateTime64/Date32`，不受第一个参数中时间单位的影响。
* 1 - 对于 `Date32`，结果始终为 `Date`。对于 `DateTime64`，当时间单位为 `second` 及以上时，结果为 `DateTime`。
## function\_implementation
为特定目标或 Variant 选择函数实现 (Experimental) 。如果留空，则启用全部实现。
## function\_json\_value\_return\_type\_allow\_complex
控制是否允许 `json_value` 函数返回复杂类型 (例如 struct、array、map) 。
```sql theme={null}
SELECT JSON_VALUE('{"hello":{"world":"!"}}', '$.hello') settings function_json_value_return_type_allow_complex=true
┌─JSON_VALUE('{"hello":{"world":"!"}}', '$.hello')─┐
│ {"world":"!"} │
└──────────────────────────────────────────────────┘
1 row in set. Elapsed: 0.001 sec.
```
可选值：
* true — 允许。
* false — 不允许。
## function\_json\_value\_return\_type\_allow\_nullable
控制在 JSON\_VALUE 函数的值不存在时，是否允许返回 `NULL`。
```sql theme={null}
SELECT JSON_VALUE('{"hello":"world"}', '$.b') settings function_json_value_return_type_allow_nullable=true;
┌─JSON_VALUE('{"hello":"world"}', '$.b')─┐
│ ᴺᵁᴸᴸ │
└────────────────────────────────────────┘
1 row in set. Elapsed: 0.001 sec.
```
可选值：
* true — 允许。
* false — 不允许。
## function\_locate\_has\_mysql\_compatible\_argument\_order
控制函数 [locate](/zh/reference/functions/regular-functions/string-search-functions#locate) 的参数顺序。
可能的值：
* 0 — 函数 `locate` 接受参数 `(haystack, needle[, start_pos])`。
* 1 — 函数 `locate` 接受参数 `(needle, haystack[, start_pos])` (兼容 MySQL 的行为)
## function\_range\_max\_elements\_in\_block
设置函数 [range](/zh/reference/functions/regular-functions/array-functions#range) 生成数据量的安全阈值。定义该函数在每个数据块内可生成的最大值数量 (即一个块中每一行数组大小之和) 。
可能的值：
* 正整数。
**另请参见**
* [`max_block_size`](#max_block_size)
* [`min_insert_block_size_rows`](#min_insert_block_size_rows)
## function\_sleep\_max\_microseconds\_per\_block
函数 `sleep` 每个块允许休眠的最大微秒数。如果用户调用时传入更大的值，则会抛出异常。这是一个安全阈值。
## function\_visible\_width\_behavior
`visibleWidth` 行为的版本。0 - 仅统计码点数量；1 - 正确统计零宽字符和组合字符，将全宽字符按两个字符计数，估算制表符宽度，并统计删除字符。
## 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
允许的地址数量上限 (用于外部存储、表函数等) 。
## grace\_hash\_join\_initial\_buckets
grace hash join 的初始桶数量
## grace\_hash\_join\_max\_buckets
grace hash join 的桶数量上限
## group\_by\_overflow\_mode
设置当用于聚合的唯一键数量超过限制时的行为：
* `throw`：抛出异常
* `break`：停止执行查询并返回部分结果
* `any`：继续对已进入集合的键进行聚合，但不再向集合中添加新键。
使用 `any` 值可以运行 GROUP BY 的近似计算。该近似结果的质量
取决于数据的统计特性。
## group\_by\_two\_level\_threshold
键的数量从多少开始时启用两级聚合。0 表示未设置该阈值。
## group\_by\_two\_level\_threshold\_bytes
当聚合状态的大小达到多少字节时，开始使用两级聚合。0 表示未设置阈值。当任一阈值被触发时，即会使用两级聚合。
## group\_by\_use\_nulls
更改 [GROUP BY 子句](/zh/reference/statements/select/group-by) 处理聚合键类型的方式。
使用 `ROLLUP`、`CUBE` 或 `GROUPING SETS` 指定器时，某些聚合键可能不会参与生成某些结果行。
这些键对应的列会根据此设置，在相应行中填充默认值或 `NULL`。
可能的值：
* 0 — 使用聚合键类型的默认值来填补缺失值。
* 1 — ClickHouse 会按照 SQL 标准执行 `GROUP BY`。聚合键的类型会转换为 [Nullable](/zh/reference/data-types/nullable)。对于未使用相应聚合键的行，其对应列将填充为 [NULL](/zh/reference/syntax#null)。
另请参见：
* [GROUP BY 子句](/zh/reference/statements/select/group-by)
## h3togeo\_lon\_lat\_result\_order
当值为 true 时，函数 `h3ToGeo` 返回 (lon, lat)；否则返回 (lat, lon)。
## handshake\_timeout\_ms
握手期间，从副本接收 Hello 数据包的超时时间，单位为毫秒。
## hdfs\_create\_new\_file\_on\_insert
用于启用或禁用在 HDFS engine 表中每次 insert 时创建新文件。如果启用，则每次 insert 都会创建一个新的 HDFS 文件，文件名类似以下模式：
初始：`data.Parquet.gz` -> `data.1.Parquet.gz` -> `data.2.Parquet.gz` 等。
Possible values:
* 0 — `INSERT` 查询会将新数据追加到文件末尾。
* 1 — `INSERT` 查询会创建一个新文件。
## hdfs\_ignore\_file\_doesnt\_exist
读取某些键时，如果文件不存在，则忽略文件不存在的情况。
可能的值：
* 1 — `SELECT` 返回空结果。
* 0 — `SELECT` 抛出异常。
## hdfs\_replication
实际的副本数可在创建 HDFS 文件时指定。
## hdfs\_skip\_empty\_files
启用或禁用在 [HDFS](/zh/reference/engines/table-engines/integrations/hdfs) 引擎表中跳过空文件的行为。
可能的值：
* 0 — 如果空文件与所请求的格式不兼容，`SELECT` 会抛出异常。
* 1 — 对于空文件，`SELECT` 返回空结果。
## hdfs\_throw\_on\_zero\_files\_match
如果按 glob 展开规则未匹配到任何文件，则抛出错误。
可能的值：
* 1 — `SELECT` 抛出异常。
* 0 — `SELECT` 返回空结果。
## hdfs\_truncate\_on\_insert
控制是否在 HDFS engine 表中执行 insert 前先截断文件。若禁用，当 HDFS 中的文件已存在时，尝试插入将抛出异常。
可能的值：
* 0 — `INSERT` 查询会将新数据追加到文件末尾。
* 1 — `INSERT` 查询会用新数据替换文件中的现有内容。
## hedged\_connection\_timeout\_ms
在对冲请求中与副本建立连接的超时时间
## highlight\_max\_matches\_per\_row
设置 [highlight](/zh/reference/functions/regular-functions/string-search-functions#highlight) 函数中每行高亮匹配的最大数量。可用于在大文本中高亮高度重复的模式时，防止内存占用过高。
可能的值：
* 正整数。
## hnsw\_candidate\_list\_size\_for\_search
搜索向量相似度索引时的动态候选列表大小，也称为“ef\_search”。
## hsts\_max\_age
HSTS 的有效期。0 表示禁用 HSTS。
## http\_connection\_timeout
HTTP 连接超时 (单位：秒) 。
可选值：
* 任意正整数。
* 0 - 禁用 (无限超时) 。
发送 HTTP 请求头 X-ClickHouse-Progress 的间隔不得短于此处指定的时间间隔。
读取全部 HTTP 请求头的最长时间 (以秒为单位) 。这是整个请求头解析阶段的总时限，而不是单次读取的超时时间。它可防范 slowloris 类攻击：客户端以极慢的速度持续发送请求头数据，从而让连接长时间保持打开状态。
## http\_make\_head\_request
`http_make_head_request` 设置允许在通过 HTTP 读取数据时发送 `HEAD` 请求，以获取待读取文件的信息，例如文件大小。该设置默认启用，因此如果 server 不支持 `HEAD` 请求，可能需要将其禁用。
## http\_max\_field\_name\_size
HTTP 请求头、查询参数和表单数据中字段名称的最大长度。
## http\_max\_field\_value\_size
HTTP 请求头、查询参数和表单数据中字段值的最大长度。
## http\_max\_fields
HTTP 请求头、查询参数和表单数据中的最大字段数。
## http\_max\_multipart\_form\_data\_size
multipart/form-data 内容大小限制。此设置无法通过 URL 参数解析，应在用户 profile 中设置。请注意，在查询开始执行前，内容会先被解析，并在内存中创建外部表。此外，这是该阶段唯一生效的限制 (读取 HTTP form data 时，最大内存使用和最大执行时间限制均不生效) 。
所有 HTTP 请求头 (名称和值合计) 的总大小上限，单位为字节。
## http\_max\_request\_param\_data\_size
限制预定义 HTTP 请求中作为查询参数使用的请求数据大小。
## http\_max\_tries
通过 HTTP 读取时的最大尝试次数。
## http\_max\_uri\_size
设置 HTTP 请求的最大 URI 长度。
可能的值：
* 正整数。
## http\_native\_compression\_disable\_checksumming\_on\_decompress
启用或禁用在解压来自客户端的 HTTP POST 数据时进行校验和验证。仅适用于 ClickHouse 原生压缩格式 (不适用于 `gzip` 或 `deflate`) 。
更多信息，请参阅 [HTTP 接口说明](/zh/concepts/features/interfaces/http)。
可能的值：
* 0 — 已禁用。
* 1 — 已启用。
## http\_receive\_timeout
HTTP 接收超时时间 (以秒为单位) 。
可选值：
* 任意正整数。
* 0 - 禁用 (无限超时) 。
## http\_response\_buffer\_size
在向客户端发送 HTTP 响应，或 (启用 `http_wait_end_of_query` 时) 刷新到磁盘之前，在 server 内存中缓冲的字节数。
允许添加或覆盖服务器在查询成功时随响应返回的 HTTP 请求头。
这仅影响 HTTP 接口。
如果该请求头默认已设置，则提供的值会覆盖它。
如果该请求头默认未设置，则会将其添加到请求头列表中。
服务器默认设置且未被此设置覆盖的请求头将保持不变。
此设置允许你将请求头设为常量值。目前还无法将请求头设为动态计算的值。
名称和值都不能包含 ASCII 控制字符。
如果你实现了一个允许用户修改设置、但同时又会基于返回的请求头做出决策的 UI 应用程序，建议将此设置限制为 readonly。
示例：`SET http_response_headers = '{"Content-Type": "image/png"}'`
## http\_retry\_initial\_backoff\_ms
通过 HTTP 重试读取时的最小退避时间 (毫秒)
## http\_retry\_max\_backoff\_ms
通过 HTTP 重试读取时的最大退避时间 (毫秒)
## http\_send\_timeout
HTTP 发送超时时间 (以秒为单位) 。
可能的取值：
* 任意正整数。
* 0 - 已禁用 (超时无限制) 。
仅适用于默认 profile。更改生效需要重启服务器。
## http\_skip\_not\_found\_url\_for\_globs
跳过因 HTTP\_NOT\_FOUND 错误而未找到的通配符 URL
## http\_wait\_end\_of\_query
启用服务端 HTTP 响应缓冲。
## http\_write\_exception\_in\_output\_format
以输出格式写入异常信息，以生成有效输出。适用于 JSON 和 XML 格式。
## http\_zlib\_compression\_level
如果 [enable\_http\_compression = 1](#enable_http_compression)，则设置 HTTP 响应中数据的压缩级别。
可能的值：1 到 9 的数字。
## iceberg\_compaction\_data\_cleanup
超过此时间后，数据将被删除。
## iceberg\_compaction\_delay\_bias
两次后台合并整理操作之间的最短延迟时间。
## iceberg\_data\_file\_size\_lower\_threshold\_compaction
Iceberg 中数据文件合并整理的阈值。
## iceberg\_data\_file\_size\_upper\_threshold\_compaction
Iceberg 中数据文件合并整理的阈值。
## iceberg\_delete\_data\_on\_drop
是否在执行 drop 时删除所有 Iceberg 文件。
## iceberg\_expire\_default\_max\_ref\_age\_ms
当 Iceberg 表属性 `history.expire.max-ref-age-ms` 不存在时，`expire_snapshots` 使用的默认值。
## iceberg\_expire\_default\_max\_snapshot\_age\_ms
当未设置该属性时，`expire_snapshots` 使用的 Iceberg 表属性 `history.expire.max-snapshot-age-ms` 的默认值。
## iceberg\_expire\_default\_min\_snapshots\_to\_keep
当该属性不存在时，`expire_snapshots` 使用的 Iceberg 表属性 `history.expire.min-snapshots-to-keep` 的默认值。
## iceberg\_insert\_max\_bytes\_in\_data\_file
插入操作时 Iceberg Parquet 数据文件的最大字节数。
## iceberg\_insert\_max\_partitions
Iceberg 表引擎中单次插入操作允许的最大分区数。
## iceberg\_insert\_max\_rows\_in\_data\_file
插入操作时 Iceberg Parquet 数据文件的最大行数上限。
## iceberg\_max\_number\_datafiles\_to\_compact
Iceberg 中触发数据文件合并整理的阈值。
## iceberg\_metadata\_compression\_method
压缩 `.metadata.json` 文件所用的方法。
## iceberg\_metadata\_log\_level
控制写入 system.iceberg\_metadata\_log 的 Iceberg 表元数据日志级别。
通常仅在调试时修改此设置。
可选值：
* none - 不记录元数据日志。
* metadata - 根 metadata.json 文件。
* manifest\_list\_metadata - 包含以上全部内容，外加与某个快照对应的 avro manifest 列表中的元数据。
* manifest\_list\_entry - 包含以上全部内容，外加 avro manifest 列表条目。
* manifest\_file\_metadata - 包含以上全部内容，外加已遍历的 avro manifest 文件中的元数据。
* manifest\_file\_entry - 包含以上全部内容，外加已遍历的 avro manifest 文件条目。
## iceberg\_metadata\_staleness\_ms
如果该值非零，且存在比给定 staleness 窗口更新的缓存元数据快照，则跳过从远程 catalog 拉取 Iceberg 元数据。值为零表示始终从远程 catalog 拉取最新的元数据版本。将此项设为非零，会以一定的陈旧性为代价来降低读操作延迟。
## iceberg\_orphan\_files\_older\_than\_seconds
Iceberg 表中删除孤立文件时使用的默认年龄阈值 (以秒为单位) 。比该阈值更新的文件不会被视为孤立文件。当调用 `remove_orphan_files()` 过程时，如果省略 `older_than` 参数，则使用该值。默认值为 259200 (3 天) 。
## iceberg\_snapshot\_id
使用指定的快照 ID 查询 Iceberg 表。
## iceberg\_timestamp\_ms
使用特定时间戳对应的快照查询 Iceberg 表。
## idle\_connection\_timeout
空闲 TCP 连接在达到指定秒数后关闭的超时时间。
可能的值：
* 正整数 (0 表示立即关闭，即 0 秒后) 。
## ignore\_cold\_parts\_seconds
仅在 ClickHouse Cloud 中生效。在新的数据分区片段被预热 (参见 [cache\_populated\_by\_fetch](/zh/reference/settings/merge-tree-settings#cache_populated_by_fetch)) 或已存在达到这么多秒之前，将其从 SELECT 查询中排除。仅适用于 Replicated-/SharedMergeTree。
## ignore\_data\_skipping\_indices
如果查询会使用指定的跳过索引，则忽略这些索引。
请看以下示例：
```sql theme={null}
CREATE TABLE data
(
key Int,
x Int,
y Int,
INDEX x_idx x TYPE minmax GRANULARITY 1,
INDEX y_idx y TYPE minmax GRANULARITY 1,
INDEX xy_idx (x,y) TYPE minmax GRANULARITY 1
)
Engine=MergeTree()
ORDER BY key;
INSERT INTO data VALUES (1, 2, 3);
SELECT * FROM data;
SELECT * FROM data SETTINGS ignore_data_skipping_indices=''; -- 该查询将产生 CANNOT_PARSE_TEXT 错误。
SELECT * FROM data SETTINGS ignore_data_skipping_indices='x_idx'; -- 正常。
SELECT * FROM data SETTINGS ignore_data_skipping_indices='na_idx'; -- 正常。
SELECT * FROM data WHERE x = 1 AND y = 1 SETTINGS ignore_data_skipping_indices='xy_idx',force_data_skipping_indices='xy_idx' ; -- 该查询将产生 INDEX_NOT_USED 错误，因为 xy_idx 已被显式忽略。
SELECT * FROM data WHERE x = 1 AND y = 2 SETTINGS ignore_data_skipping_indices='xy_idx';
```
未忽略任何索引时的查询：
```sql theme={null}
EXPLAIN indexes = 1 SELECT * FROM data WHERE x = 1 AND y = 2;
Expression ((Projection + Before ORDER BY))
Filter (WHERE)
ReadFromMergeTree (default.data)
Indexes:
PrimaryKey
Condition: true
Parts: 1/1
Granules: 1/1
Skip
Name: x_idx
Description: minmax GRANULARITY 1
Parts: 0/1
Granules: 0/1
Skip
Name: y_idx
Description: minmax GRANULARITY 1
Parts: 0/0
Granules: 0/0
Skip
Name: xy_idx
Description: minmax GRANULARITY 1
Parts: 0/0
Granules: 0/0
```
忽略 `xy_idx` 索引：
```sql theme={null}
EXPLAIN indexes = 1 SELECT * FROM data WHERE x = 1 AND y = 2 SETTINGS ignore_data_skipping_indices='xy_idx';
Expression ((Projection + Before ORDER BY))
Filter (WHERE)
ReadFromMergeTree (default.data)
Indexes:
PrimaryKey
Condition: true
Parts: 1/1
Granules: 1/1
Skip
Name: x_idx
Description: minmax GRANULARITY 1
Parts: 0/1
Granules: 0/1
Skip
Name: y_idx
Description: minmax GRANULARITY 1
Parts: 0/0
Granules: 0/0
```
适用于 MergeTree 家族中的表。
## ignore\_drop\_queries\_probability
启用后，server 将按指定概率忽略所有 DROP 表查询 (对于 Memory 和 JOIN 引擎，会将 DROP 替换为 TRUNCATE) 。用于测试
## ignore\_format\_null\_for\_explain
如果启用，`EXPLAIN` 查询中的 `FORMAT Null` 将被忽略，转而使用默认输出格式。
如果禁用，带有 `FORMAT Null` 的 `EXPLAIN` 查询将不会产生任何输出 (这是向后兼容的行为) 。
## ignore\_materialized\_views\_with\_dropped\_target\_table
在向视图推送时，忽略目标表已删除的 materialized view
## ignore\_on\_cluster\_for\_replicated\_access\_entities\_queries
对于复制访问实体的管理查询，忽略 ON CLUSTER 子句。
## ignore\_on\_cluster\_for\_replicated\_database
始终忽略针对 Replicated 数据库的 DDL 查询中的 ON CLUSTER 子句。
## ignore\_on\_cluster\_for\_replicated\_named\_collections\_queries
在复制的命名集合管理查询中忽略 ON CLUSTER 子句。
## ignore\_on\_cluster\_for\_replicated\_udf\_queries
在复制 UDF 的管理查询中忽略 ON CLUSTER 子句。
## implicit\_select
允许编写不以 `SELECT` 关键字开头的简单 SELECT 查询，便于计算器式用法；例如，`1 + 2` 也会成为有效查询。
在 `clickhouse-local` 中，此设置默认启用，也可显式禁用。
## implicit\_table\_at\_top\_level
如果该设置非空，顶层不带 FROM 的查询将从此表读取，而不是从 system.one 读取。
这用于 clickhouse-local 中的输入数据处理。
用户可以显式设置此设置，但它并非为这种用法而设计。
子查询不受此设置影响 (无论是标量子查询、FROM 子查询还是 IN 子查询) 。
UNION、INTERSECT、EXCEPT 链中顶层的 SELECT 都会被统一处理，并受此设置影响，而不受其括号分组方式影响。
此设置如何影响视图和分布式查询，未作规定。
该设置接受表名 (此时会从当前数据库解析该表) ，也接受形如 'database.table' 的限定名称。
数据库名和表名都不能加引号——只允许使用简单标识符。
## implicit\_transaction
如果启用此设置且当前尚未处于事务中，则会将该查询放入一个完整的事务中 (begin + commit 或 rollback)
## inject\_random\_order\_for\_select\_without\_order\_by
如果启用，会为不带 ORDER BY 子句的 SELECT 查询注入 `ORDER BY rand()`。
仅在子查询深度 = 0 时应用。子查询和 INSERT INTO ... SELECT 不受影响。
如果顶层结构是 UNION，则会分别为其所有子项独立注入 `ORDER BY rand()`。
仅对测试和开发有用 (缺少 ORDER BY 是导致查询结果非确定性的原因之一) 。
## insert\_allow\_materialized\_columns
启用此设置后，允许在 INSERT 中插入 materialized 列。
## insert\_deduplicate
启用或禁用 `INSERT` 的块去重功能 (适用于 Replicated\* 表) 。
可能的值：
* 0 — 禁用。
* 1 — 启用。
默认情况下，通过 `INSERT` 语句插入到复制表中的块会执行去重 (参见 [数据复制](/zh/reference/engines/table-engines/mergetree-family/replication)) 。
对于复制表，默认情况下每个分区仅对最近的 100 个块执行去重 (参见 [replicated\_deduplication\_window](/zh/reference/settings/merge-tree-settings#replicated_deduplication_window)、[replicated\_deduplication\_window\_seconds](/zh/reference/settings/merge-tree-settings#replicated_deduplication_window_seconds)) 。
对于非复制表，请参见 [non\_replicated\_deduplication\_window](/zh/reference/settings/merge-tree-settings#non_replicated_deduplication_window)。
## insert\_deduplication\_token
该设置允许用户在 MergeTree/ReplicatedMergeTree 中自定义去重语义。
例如，在每条 INSERT 语句中为该设置提供一个唯一值，
用户就可以避免相同的已插入数据被去重。
可能的值：
* 任意字符串
仅当 `insert_deduplication_token` 非空时，才会将其用于去重。
对于复制表，默认情况下，每个分区只有最近 100 次插入会被去重 (请参见 [replicated\_deduplication\_window](/zh/reference/settings/merge-tree-settings#replicated_deduplication_window)、[replicated\_deduplication\_window\_seconds](/zh/reference/settings/merge-tree-settings#replicated_deduplication_window_seconds)) 。
对于非复制表，请参见 [non\_replicated\_deduplication\_window](/zh/reference/settings/merge-tree-settings#non_replicated_deduplication_window)。
`insert_deduplication_token` 在分区级别生效 (与 `insert_deduplication` checksum 相同) 。多个分区可以使用相同的 `insert_deduplication_token`。
示例：
```sql theme={null}
CREATE TABLE test_table
( A Int64 )
ENGINE = MergeTree
ORDER BY A
SETTINGS non_replicated_deduplication_window = 100;
INSERT INTO test_table SETTINGS insert_deduplication_token = 'test' VALUES (1);
-- 下一次插入不会被去重，因为 insert_deduplication_token 不同
INSERT INTO test_table SETTINGS insert_deduplication_token = 'test1' VALUES (1);
-- 下一次插入将被去重，因为 insert_deduplication_token
-- 与之前某次插入的值相同
INSERT INTO test_table SETTINGS insert_deduplication_token = 'test' VALUES (2);
SELECT * FROM test_table
┌─A─┐
│ 1 │
└───┘
┌─A─┐
│ 1 │
└───┘
```
## insert\_keeper\_fault\_injection\_probability
插入期间 Keeper 请求发生故障的大致概率。有效值范围为 \[0.0f, 1.0f]
## insert\_keeper\_fault\_injection\_seed
0 - 使用随机种子，否则使用该设置的值
## insert\_keeper\_max\_retries
此设置用于指定向 Replicated MergeTree 执行 insert 期间，ClickHouse Keeper (或 ZooKeeper) 请求的最大重试次数。只有因网络错误、Keeper 会话超时或请求超时而失败的 Keeper 请求才会被重试。
可能的值：
* 正整数。
* 0 — 禁用重试
Cloud 默认值：`20`。
Keeper 请求会在经过一定超时后进行重试。该超时由以下设置控制：`insert_keeper_retry_initial_backoff_ms`、`insert_keeper_retry_max_backoff_ms`。
第一次重试会在 `insert_keeper_retry_initial_backoff_ms` 指定的超时后执行。后续超时将按如下方式计算：
```
timeout = min(insert_keeper_retry_max_backoff_ms, latest_timeout * 2)
```
例如，如果 `insert_keeper_retry_initial_backoff_ms=100`、`insert_keeper_retry_max_backoff_ms=10000` 且 `insert_keeper_max_retries=8`，那么超时时间将依次为 `100, 200, 400, 800, 1600, 3200, 6400, 10000`。
除了提供容错能力外，重试机制也旨在带来更好的用户体验——例如，当 Keeper 因升级而重启时，它可以避免在执行 INSERT 期间返回错误。
## insert\_keeper\_retry\_initial\_backoff\_ms
执行 INSERT 查询期间，重试失败的 Keeper 请求的初始超时时间 (毫秒)
可选值：
* 正整数。
* 0 — 无超时
## insert\_keeper\_retry\_max\_backoff\_ms
执行 INSERT 查询期间，重试失败的 Keeper 请求时的最大超时时间 (以毫秒为单位)
可能的值：
* 正整数。
* 0 — 最大超时时间不受限制
## insert\_null\_as\_default
启用或禁用在向非 [Nullable](/zh/reference/data-types/nullable) 数据类型的列中插入数据时，用[默认值](/zh/reference/statements/create/table#default_values)替代 [NULL](/zh/reference/syntax#null)。
如果列类型不是 Nullable 且此设置被禁用，则插入 `NULL` 会导致异常。如果列类型是 Nullable，则无论此设置如何，`NULL` 值都会按原样插入。
此设置适用于 [INSERT ... SELECT](/zh/reference/statements/insert-into#inserting-the-results-of-select) 查询。请注意，`SELECT` 子查询可以通过 `UNION ALL` 子句进行拼接。
可能的值：
* 0 — 向非 Nullable 列插入 `NULL` 会导致异常。
* 1 — 插入列的默认值而不是 `NULL`。
## insert\_quorum
此设置不适用于 SharedMergeTree，更多信息请参见 [SharedMergeTree 一致性](/zh/products/cloud/features/infrastructure/shared-merge-tree#consistency)。
启用仲裁写入。
* 如果 `insert_quorum < 2`，则禁用仲裁写入。
* 如果 `insert_quorum >= 2`，则启用仲裁写入。
* 如果 `insert_quorum = 'auto'`，则使用多数值 (`number_of_replicas / 2 + 1`) 作为仲裁数。
仲裁写入
只有当 ClickHouse 在 `insert_quorum_timeout` 期间成功将数据写入 `insert_quorum` 个副本时，`INSERT` 才会成功。如果由于任何原因，成功写入的副本数未达到 `insert_quorum`，则此次写入会被视为失败，ClickHouse 会从所有已写入数据的副本中删除已插入的块。
当禁用 `insert_quorum_parallel` 时，仲裁中的所有副本都是一致的，也就是说，它们都包含此前所有 `INSERT` 查询的数据 (`INSERT` 序列会被线性化) 。读取通过 `insert_quorum` 写入的数据时，如果 `insert_quorum_parallel` 已禁用，可以使用 [select\_sequential\_consistency](#select_sequential_consistency) 为 `SELECT` 查询启用顺序一致性。
在以下情况下，ClickHouse 会抛出异常：
* 如果查询时可用副本的数量少于 `insert_quorum`。
* 当禁用 `insert_quorum_parallel` 时，如果前一个块尚未写入 `insert_quorum` 个副本就尝试写入数据。这种情况可能发生在用户试图在前一个带有 `insert_quorum` 的 `INSERT` 查询完成之前，对同一张表执行另一个 `INSERT` 查询时。
另请参见：
* [insert\_quorum\_timeout](#insert_quorum_timeout)
* [insert\_quorum\_parallel](#insert_quorum_parallel)
* [select\_sequential\_consistency](#select_sequential_consistency)
## insert\_quorum\_parallel
此设置不适用于 SharedMergeTree，更多信息请参见 [SharedMergeTree 一致性](/zh/products/cloud/features/infrastructure/shared-merge-tree#consistency)。
启用或禁用 quorum `INSERT` 查询的并行执行。启用后，在先前查询尚未完成时，仍可发送额外的 `INSERT` 查询。禁用后，对同一表的额外写入将被拒绝。
可能的值：
* 0 — 禁用。
* 1 — 启用。
另请参见：
* [insert\_quorum](#insert_quorum)
* [insert\_quorum\_timeout](#insert_quorum_timeout)
* [select\_sequential\_consistency](#select_sequential_consistency)
## insert\_quorum\_timeout
写入达到法定副本数的超时时间 (以毫秒为单位) 。如果超时时间已过但仍未完成写入，ClickHouse 将抛出异常，客户端必须重新执行该查询，将同一个块写入同一副本或其他任意副本。
另请参见：
* [insert\_quorum](#insert_quorum)
* [insert\_quorum\_parallel](#insert_quorum_parallel)
* [select\_sequential\_consistency](#select_sequential_consistency)
## insert\_shard\_id
如果不为 `0`，则指定数据将同步插入到 [Distributed](/zh/reference/engines/table-engines/special/distributed) 表中的哪个分片。
如果 `insert_shard_id` 的值不正确，服务器将抛出异常。
要获取 `requested_cluster` 上的分片数量，可以检查服务器配置或使用以下查询：
```sql theme={null}
SELECT uniq(shard_num) FROM system.clusters WHERE cluster = 'requested_cluster';
```
可能的取值：
* 0 — 已禁用。
* 从 `1` 到对应 [Distributed](/zh/reference/engines/table-engines/special/distributed) 表的 `shards_num` 之间的任意数字。
**示例**
查询：
```sql theme={null}
CREATE TABLE x AS system.numbers ENGINE = MergeTree ORDER BY number;
CREATE TABLE x_dist AS x ENGINE = Distributed('test_cluster_two_shards_localhost', currentDatabase(), x);
INSERT INTO x_dist SELECT * FROM numbers(5) SETTINGS insert_shard_id = 1;
SELECT * FROM x_dist ORDER BY number ASC;
```
结果：
```text theme={null}
┌─number─┐
│ 0 │
│ 0 │
│ 1 │
│ 1 │
│ 2 │
│ 2 │
│ 3 │
│ 3 │
│ 4 │
│ 4 │
└────────┘
```
## interactive\_delay
以微秒为单位的时间间隔，用于检查请求执行是否已取消，以及发送进度信息。
## intersect\_default\_mode
设置 INTERSECT 查询的默认模式。可选值：空字符串、'ALL'、'DISTINCT'。如果为空，不带模式的查询将抛出异常。
## jemalloc\_collect\_profile\_samples\_in\_trace\_log
在 trace 日志中收集 jemalloc 的分配和释放样本。
## jemalloc\_enable\_profiler
为该查询启用 jemalloc profiler。jemalloc 会对内存分配进行采样，并记录这些已采样分配的所有释放。
可以使用 SYSTEM JEMALLOC FLUSH PROFILE 刷新 profile，以用于分配分析。
还可以通过 config jemalloc\_collect\_global\_profile\_samples\_in\_trace\_log，或通过查询设置 jemalloc\_collect\_profile\_samples\_in\_trace\_log，将样本存储到 system.trace\_log 中。
请参阅 [分配分析](/zh/concepts/features/performance/allocation-profiling)
## jemalloc\_profile\_text\_collapsed\_use\_count
使用 jemalloc 堆内存剖析的 'collapsed' 输出格式时，按分配次数而非字节数聚合。为 false (默认值) 时，每个栈按存活字节数加权；为 true 时，则按存活分配次数加权。
## jemalloc\_profile\_text\_output\_format
system.jemalloc\_profile\_text 表中 jemalloc 堆内存剖析的输出格式。可取值为：'raw' (原始剖析) 、'symbolized' (带符号的 jeprof 格式) 或 'collapsed' (FlameGraph 格式) 。
## jemalloc\_profile\_text\_symbolize\_with\_inline
控制在对 jemalloc 堆内存剖析进行符号化时是否包含内联帧。启用后会包含内联帧，这可能会显著拖慢符号化过程；禁用后则会跳过它们。仅影响 `symbolized` 和 `collapsed` 输出格式。
## join\_algorithm
指定使用哪种 [JOIN](/zh/reference/statements/select/join) 算法。
可以指定多种算法，系统会根据具体查询的 kind/strictness 和表引擎选择可用的一种。
可能的值：
* grace\_hash
使用 [Grace hash join](https://en.wikipedia.org/wiki/Hash_join#Grace_hash_join)。Grace hash 提供了一种算法选项，可在限制内存使用的同时高效执行复杂 JOIN。
grace join 的第一阶段会读取右表，并根据键列的哈希值将其拆分为 N 个桶 (初始时，N 为 `grace_hash_join_initial_buckets`) 。这样可以确保每个桶都能独立处理。第一个桶中的行会加入内存中的哈希表，其余行则保存到磁盘。如果哈希表增长超出内存限制 (例如由 [`max_bytes_in_join`](/zh/reference/settings/session-settings#max_bytes_in_join) 设置) ，则会增加桶的数量，并重新确定每一行所属的桶。凡是不属于当前桶的行，都会被刷写并重新分配。
支持 `INNER/LEFT/RIGHT/FULL ALL/ANY JOIN`。
* hash
使用 [Hash join algorithm](https://en.wikipedia.org/wiki/Hash_join)。这是最通用的实现，支持所有 kind 和 strictness 的组合，以及在 `JOIN ON` 部分通过 `OR` 组合的多个连接键。
使用 `hash` 算法时，`JOIN` 的右侧部分会加载到 RAM 中。
* parallel\_hash
这是 `hash` join 的一种变体：它会将数据拆分为多个桶，并并发构建多个哈希表而不是一个，以加快这一过程。
使用 `parallel_hash` 算法时，`JOIN` 的右侧部分会加载到 RAM 中。
* partial\_merge
这是 [sort-merge algorithm](https://en.wikipedia.org/wiki/Sort-merge_join) 的一种变体，其中只有右表会被完全排序。
`RIGHT JOIN` 和 `FULL JOIN` 仅支持 `ALL` strictness (不支持 `SEMI`、`ANTI`、`ANY` 和 `ASOF`) 。
使用 `partial_merge` 算法时，ClickHouse 会对数据进行排序并将其转储到磁盘。ClickHouse 中的 `partial_merge` 算法与经典实现略有不同。首先，ClickHouse 会按连接键对右表按块排序，并为已排序的块创建 min-max 索引。然后，它会按 `join key` 对左表的各个部分进行排序，并将其与右表连接。min-max 索引也会用于跳过不需要的右表块。
* direct
`direct` (也称为 nested loop) 算法使用左表中的行作为键，在右表中执行查找。
它适用于 [Dictionary](/zh/reference/engines/table-engines/special/dictionary)、[EmbeddedRocksDB](/zh/reference/engines/table-engines/integrations/embedded-rocksdb) 和 [MergeTree](/zh/reference/engines/table-engines/mergetree-family/mergetree) 表等特殊存储。
对于 MergeTree 表，该算法会将连接键过滤器直接下推到存储层。如果该键可以利用表的主键索引进行查找，则效率会更高；否则，它会对左表的每个块都对右表执行全表扫描。
支持 `INNER` 和 `LEFT` joins，并且仅支持不带其他条件的单列等值连接键。
* auto
当设置为 `auto` 时，会先尝试 `hash` join；如果超出内存限制，则会动态切换到另一种算法。
* full\_sorting\_merge
在执行连接前，对参与连接的表进行完全排序的 [Sort-merge algorithm](https://en.wikipedia.org/wiki/Sort-merge_join)。
* prefer\_partial\_merge
如果可能，ClickHouse 总是尝试使用 `partial_merge` join，否则使用 `hash`。*已弃用*，等同于 `partial_merge,hash`。
* default (deprecated)
旧版取值，请不要再使用。
与 `direct,hash` 相同，即尝试使用 direct join 和 hash join (按此顺序) 。
## join\_any\_take\_last\_row
更改 `ANY` strictness 的 join 操作行为。
此设置仅适用于右表使用 [Join](/zh/reference/engines/table-engines/special/join) 表引擎的 `JOIN` 操作。
可能的值：
* 0 — 如果右表中有多行匹配行，则仅连接找到的第一行。
* 1 — 如果右表中有多行匹配行，则仅连接找到的最后一行。
另请参见：
* [JOIN 子句](/zh/reference/statements/select/join)
* [Join 表引擎](/zh/reference/engines/table-engines/special/join)
* [join\_default\_strictness](#join_default_strictness)
## join\_default\_strictness
设置 [JOIN 子句](/zh/reference/statements/select/join)的默认 strictness。
Possible values:
* `ALL` — 如果右表有多行匹配，ClickHouse 会基于这些匹配行创建[笛卡尔积](https://en.wikipedia.org/wiki/Cartesian_product)。这是标准 SQL 中 `JOIN` 的常规行为。
* `ANY` — 如果右表有多行匹配，则只连接找到的第一行。如果右表只有一行匹配，则 `ANY` 和 `ALL` 的结果相同。
* `ASOF` — 用于连接匹配关系不确定的序列。
* `Empty string` — 如果查询中未指定 `ALL` 或 `ANY`，ClickHouse 会抛出异常。
## join\_on\_disk\_max\_files\_to\_merge
限制在磁盘上执行 MergeJoin 操作时，并行排序可合并的文件数量。
该设置值越大，占用的 RAM 越多，所需的磁盘 I/O 就越少。
可能的值：
* 从 2 开始的任意正整数。
## join\_output\_by\_rowlist\_perkey\_rows\_threshold
在 hash join 中，用于判断是否按行列表输出时，右表中每个键平均行数的下限。
## join\_overflow\_mode
定义当 join 达到以下任一限制时，ClickHouse 会执行什么操作：
* [max\_bytes\_in\_join](/zh/reference/settings/session-settings#max_bytes_in_join)
* [max\_rows\_in\_join](/zh/reference/settings/session-settings#max_rows_in_join)
此设置仅对 [`join_algorithm`](/zh/reference/settings/session-settings#join_algorithm) 的 `hash` 和 `parallel_hash` 配置值生效。其他
算法 (例如 `partial_merge`、`grace_hash`、`auto`) 会以不同方式处理这些
限制——例如通过落盘、重新分区或切换
策略——请参见
[`join_algorithm`](/zh/reference/settings/session-settings#join_algorithm)。
可能的值：
* `THROW` — ClickHouse 会抛出异常并停止查询。
* `BREAK` — ClickHouse 会停止查询，但不抛出异常。
默认值：`THROW`。
**另请参见**
* [JOIN 子句](/zh/reference/statements/select/join)
* [Join 表引擎](/zh/reference/engines/table-engines/special/join)
## join\_runtime\_bloom\_filter\_bytes
作为 JOIN 运行时过滤器使用的布隆过滤器大小 (以字节为单位) (参见 `enable_join_runtime_filters` 设置) 。
## join\_runtime\_bloom\_filter\_hash\_functions
作为 JOIN 运行时过滤器使用的布隆过滤器中哈希函数的数量 (参见 enable\_join\_runtime\_filters 设置) 。
## join\_runtime\_bloom\_filter\_max\_ratio\_of\_set\_bits
如果运行时布隆过滤器中的置位占比超过该比值，则会完全禁用该过滤器，以降低开销。
## join\_runtime\_filter\_blocks\_to\_skip\_before\_reenabling
在尝试动态重新启用先前因过滤效果不佳而被禁用的运行时过滤器之前，需要跳过的块数。
## join\_runtime\_filter\_exact\_values\_limit
运行时过滤器中以原样存储在集合里的元素数量上限；超过该阈值后，会切换为 bloom filter。
## join\_runtime\_filter\_from\_fixed\_hash\_table
当哈希 join 的构建侧被转换为 FixedHashMap 时 (参见 `enable_join_fixed_hash_table_conversion`) ，直接将该哈希表用作运行时过滤器。
## join\_runtime\_filter\_pass\_ratio\_threshold\_for\_disabling
如果通过的行数与已检查行数的比率超过此阈值，则认为运行时过滤器效果不佳，并会在接下来的 `join_runtime_filter_blocks_to_skip_before_reenabling` 个块内将其禁用，以降低开销。
## join\_to\_sort\_maximum\_table\_rows
在 LEFT JOIN 或 INNER JOIN 中，判断是否需要按键对右表重新排序时，右表的最大行数。
## join\_to\_sort\_minimum\_perkey\_rows
右侧表中每个键平均行数的下限，用于确定在 LEFT JOIN 或 INNER JOIN 中，是否需要按键对右侧表重新排序。此设置可确保在表键较为稀疏时不会应用该优化
## join\_use\_nulls
用于设置 [JOIN](/zh/reference/statements/select/join) 的行为。在合并表时，可能会出现空单元。ClickHouse 会根据此设置以不同方式对其进行填充。
可能的值：
* 0 — 空单元使用对应字段类型的默认值填充。
* 1 — `JOIN` 的行为与标准 SQL 相同。对应字段的类型会转换为 [Nullable](/zh/reference/data-types/nullable)，空单元会填充为 [NULL](/zh/reference/syntax)。
## joined\_block\_split\_single\_row
允许按左表中单行对应的行来切分哈希 join 结果。
当左表中的某一行在右表中有大量匹配项时，这可以减少内存使用，但也可能增加 CPU 使用率。
请注意，必须设置 `max_joined_block_size_rows != 0`，此设置才会生效。
将 `max_joined_block_size_bytes` 与此设置结合使用，有助于避免在数据倾斜、且某些大行在右表中有大量匹配项时出现过高的内存使用。
## joined\_subquery\_requires\_alias
强制要求参与 join 的子查询和表函数必须使用别名，以确保名称限定正确。
## kafka\_disable\_num\_consumers\_limit
禁用 `kafka_num_consumers` 基于可用 CPU 核心数量的限制。
## kafka\_max\_wait\_ms
重试前，从 [Kafka](/zh/reference/engines/table-engines/integrations/kafka) 读取消息时的等待时间 (以毫秒为单位) 。
可选值：
* 正整数。
* 0 — 无限超时。
另请参阅：
* [Apache Kafka](https://kafka.apache.org/)
## keeper\_map\_strict\_mode
在对 KeeperMap 执行操作时启用额外检查。例如，对已存在的键执行 insert 时会抛出异常
## keeper\_max\_retries
常规 Keeper 操作的最大重试次数
## keeper\_retry\_initial\_backoff\_ms
用于常规 Keeper 操作的初始 backoff 超时时间
## keeper\_retry\_max\_backoff\_ms
常规 Keeper 操作的最大退避超时
## least\_greatest\_legacy\_null\_behavior
如果启用此设置，当 'least' 和 'greatest' 函数的任一参数为 NULL 时，函数将返回 NULL。
## legacy\_column\_name\_of\_tuple\_literal
对于大型 Tuple 字面量，将其所有元素名称列为列名，而不是使用哈希。此设置仅用于兼容性。在将低于 21.7 的集群滚动更新到更高版本时，建议将其设为 'true'。
## lightweight\_delete\_mode
轻量级删除过程中执行的内部更新查询模式。
可能的值：
* `alter_update` - 运行 `ALTER UPDATE` 查询，这会创建重量级变更。
* `lightweight_update` - 如果可以，则运行轻量级更新；否则运行 `ALTER UPDATE`。
* `lightweight_update_force` - 如果可以，则运行轻量级更新；否则抛出异常。
## lightweight\_deletes\_sync
与 [`mutations_sync`](#mutations_sync) 相同，但仅控制轻量级删除的执行。
可能的值：
| 值 | 说明 |
| --- | -------------------------------------------------------------------------------------- |
| `0` | 变更将异步执行。 |
| `1` | 查询会等待当前服务器上的轻量级删除完成。 |
| `2` | 查询会等待所有副本 (如果存在) 上的轻量级删除完成。 |
| `3` | 查询仅等待活跃副本。仅支持 `SharedMergeTree`。对于 `ReplicatedMergeTree`，其行为与 `mutations_sync = 2` 相同。 |
**另请参见**
* [ALTER 查询的同步性](/zh/reference/statements/alter/index#synchronicity-of-alter-queries)
* [变更](/zh/reference/statements/alter/index#mutations)
Cloud 默认值：`1`。
## limit
设置可从查询结果中获取的最大行数。它会调整 [LIMIT](/zh/reference/statements/select/limit) 子句设置的值，因此查询中指定的 limit 不能超过此设置所规定的 limit。
Possible values:
* 0 — 行数不受限制。
* 正整数。
## load\_balancing
指定分布式查询处理中用于选择副本的算法。
ClickHouse 支持以下副本选择算法：
* [Random](#load_balancing-random) (默认)
* [最近的主机名](#load_balancing-nearest_hostname)
* [主机名 Levenshtein 距离](#load_balancing-hostname_levenshtein_distance)
* [主机名最长公共前缀](#load_balancing-hostname_longest_common_prefix)
* [主机名最长公共后缀](#load_balancing-hostname_longest_common_suffix)
* [按顺序](#load_balancing-in_order)
* [第一个或随机](#load_balancing-first_or_random)
* [轮询](#load_balancing-round_robin)
另请参见：
* [distributed\_replica\_max\_ignored\_errors](#distributed_replica_max_ignored_errors)
### Random (默认)
```sql theme={null}
load_balancing = random
```
会分别统计每个副本的错误数。查询会发送到错误数最少的副本；如果有多个这样的副本，则会从中任意选择一个。
缺点：不会考虑服务器的远近；如果各副本中的数据不同，得到的数据也会不同。
### 最近的主机名
```sql theme={null}
load_balancing = nearest_hostname
```
每个副本都会统计错误次数。每隔 5 分钟，错误次数都会整除 2。因此，最近一段时间内的错误次数是通过指数平滑计算得出的。如果某个副本的错误次数最少 (即其他副本最近出现过错误) ，查询就会发送到该副本。如果有多个副本的最小错误次数相同，则会将查询发送到主机名与配置文件中服务器主机名最相似的那个副本 (根据相同位置上不同字符的数量计算，只比较到两个主机名中的较短长度为止) 。
例如，example01-01-1 和 example01-01-2 只有 1 个位置不同，而 example01-01-1 和 example01-02-2 则有 2 个位置不同。
这种方法看起来可能有些原始，但它不需要额外的网络拓扑数据，也不比较 IP 地址，而对于我们的 IPv6 地址来说，比较 IP 地址会很复杂。
因此，如果存在等效的副本，就会优先选择名称最接近的那个。
我们还可以认为，在没有故障的情况下，当查询发送到同一台服务器时，Distributed 查询也会转发到相同的服务器。因此，即使各副本上存放的数据不同，查询返回的结果也大多相同。
### 主机名 Levenshtein 距离
```sql theme={null}
load_balancing = hostname_levenshtein_distance
```
与 `nearest_hostname` 类似，但它会按 [Levenshtein 距离](https://en.wikipedia.org/wiki/Levenshtein_distance) 比较主机名。例如：
```text theme={null}
example-clickhouse-0-0 ample-clickhouse-0-0
1
example-clickhouse-0-0 example-clickhouse-1-10
2
example-clickhouse-0-0 example-clickhouse-12-0
3
```
### 主机名最长公共前缀
```sql theme={null}
load_balancing = hostname_longest_common_prefix
```
与 `nearest_hostname` 类似，但会优先选择其 主机名 与本地 主机名 具有最长公共前缀的副本 (公共前缀越长，优先级越高) 。不同于 `nearest_hostname` 逐个位置统计不同字符，这种策略不会因 主机名 中数字分段的长度不同而受到干扰。例如，对于本地 主机名 `sfe301`：
```text theme={null}
sfe301 sde301
1
sfe301 sfe10101
3
sfe301 sde505
1
```
这里会优先选择 `sfe10101`，因为它与 `sfe301` 具有最长的公共前缀 (`sfe`，长度为 3) 。
如果多个副本的公共前缀长度相同，则随机选择。特别是，当没有任何副本与本地主机名具有相同前缀时 (所有公共前缀长度都为 0) ，该策略的行为与 \`random\`\` 完全相同。
### 主机名的最长公共后缀
```sql theme={null}
load_balancing = hostname_longest_common_suffix
```
与 `hostname_longest_common_prefix` 类似，但这里比较的是最长公共*后缀*，而不是前缀。当数据中心标识编码在主机名后缀中时，这一功能就很有用。例如，对于本地主机名 `et46gtghn.qc.localdomain`：
```text theme={null}
et46gtghn.qc.localdomain tr676ddgh.td.localdomain
12
et46gtghn.qc.localdomain ab999.qc.localdomain
15
```
这里会优先选择 `ab999.qc.localdomain`，因为它与 `et46gtghn.qc.localdomain` 具有最长的共同后缀 (`.qc.localdomain`，长度为 15) 。
如果副本的共同后缀长度相同，则会随机选择。特别是，当没有任何副本与本地主机名具有共同后缀时 (即所有共同后缀长度都为 0) ，该策略的行为与 `random` 完全相同。
### 按顺序
```sql theme={null}
load_balancing = in_order
```
错误数相同的副本会按照其在配置中指定的顺序依次访问。
当你明确知道哪个副本更合适时，这种方法比较适用。
### 第一个或随机
```sql theme={null}
load_balancing = first_or_random
```
该算法会选择集合中的第一个副本；如果第一个不可用，则选择一个随机副本。它在交叉复制拓扑中效果很好，但在其他配置中则没有什么用处。
`first_or_random` 算法解决了 `in_order` 算法的问题。使用 `in_order` 时，如果一个副本宕机，下一个副本将承受双倍负载，而其余副本仍处理平时数量的流量。使用 `first_or_random` 算法时，负载会在仍可用的副本之间均匀分配。
可以通过设置 `load_balancing_first_offset` 显式指定哪个副本是第一个副本。这样就能更灵活地控制在各副本之间重新平衡查询工作负载。
### 轮询
```sql theme={null}
load_balancing = round_robin
```
该算法在错误数相同的副本之间采用轮转策略 (仅将采用 `round_robin` 策略的查询计入统计) 。
## load\_balancing\_first\_offset
使用 FIRST\_OR\_RANDOM 负载均衡策略时，优先将查询发送到哪个副本。
## load\_marks\_asynchronously
异步加载 MergeTree 标记文件
Cloud 默认值：`1`。
## local\_filesystem\_read\_method
从本地文件系统读取数据的方法，可选值包括：read、pread、mmap、io\_uring、pread\_threadpool。
'io\_uring' 方法处于 Experimental 状态，在存在并发读写时，不适用于 Log、TinyLog、StripeLog、File 表引擎、Set、Join 以及其他使用可追加文件的表。
如果你在互联网上读过各种关于 'io\_uring' 的文章，不要被它们带偏。除了存在大量小型 IO 请求的场景外，它并不是更好的文件读取方法，而 ClickHouse 并不属于这种场景。因此，没有理由启用 'io\_uring'。
## local\_filesystem\_read\_prefetch
从本地文件系统读取数据时，是否使用预取。
## lock\_acquire\_timeout
定义锁定请求在失败前会等待多少秒。
锁定超时用于在对表执行读/写操作时避免发生死锁。当超时时间到期且锁定请求失败时，ClickHouse server 会抛出异常 "Locking attempt timed out! Possible deadlock avoided. Client should retry."，错误代码为 `DEADLOCK_AVOIDED`。
可能的值：
* 正整数 (以秒为单位) 。
* 0 — 不设置锁定超时。
指定 [system.query\_log](/zh/reference/system-tables/query_log) 表中 `log_comment` 字段的值，以及服务器日志中的注释文本。
它可用于提高服务器日志的可读性。此外，在运行 [clickhouse-test](/zh/resources/develop-contribute/contribute/tests) 后，还可帮助从 `system.query_log` 中筛选出与测试相关的查询。
可能的值：
* 任何长度不超过 [max\_query\_size](#max_query_size) 的字符串。如果超过 max\_query\_size，服务器会抛出异常。
**示例**
查询：
```sql theme={null}
SET log_comment = 'log_comment test', log_queries = 1;
SELECT 1;
SYSTEM FLUSH LOGS;
SELECT type, query FROM system.query_log WHERE log_comment = 'log_comment test' AND event_date >= yesterday() ORDER BY event_time DESC LIMIT 2;
```
结果：
```text theme={null}
┌─type────────┬─query─────┐
│ QueryStart │ SELECT 1; │
│ QueryFinish │ SELECT 1; │
└─────────────┴───────────┘
```
## log\_formatted\_queries
允许将格式化后的查询记录到 [system.query\_log](/zh/reference/system-tables/query_log) 系统表中 (即填充 [system.query\_log](/zh/reference/system-tables/query_log) 中的 `formatted_query` 列) 。
可能的值：
* 0 — 格式化后的查询不会记录到系统表中。
* 1 — 格式化后的查询会记录到系统表中。
## log\_processors\_profiles
将处理器在执行期间或等待数据时耗费的时间写入 `system.processors_profile_log` 表。
另请参见：
* [`system.processors_profile_log`](/zh/reference/system-tables/processors_profile_log)
* [`EXPLAIN PIPELINE`](/zh/reference/statements/explain#explain-pipeline)
## log\_profile\_events
将查询性能统计数据记录到 query\_log、query\_thread\_log 和 query\_views\_log 中。
## log\_queries
设置是否记录查询日志。
发送到 ClickHouse 的查询在启用此设置时，会根据服务器配置参数 [query\_log](/zh/reference/settings/server-settings/settings#query_log) 中的规则进行记录。
示例：
```text theme={null}
log_queries=1
```
## log\_queries\_cut\_to\_length
如果查询长度超过指定阈值 (以字节为单位) ，则在写入查询日志时截断该查询。同时也会限制在普通文本日志中打印的查询长度。
## log\_queries\_min\_query\_duration\_ms
如果启用 (非零) ，则执行时间短于此设置值的查询不会被记入日志 (可以将其理解为 [MySQL 慢查询日志](https://dev.mysql.com/doc/refman/5.7/slow-query-log.html) 中的 `long_query_time`) 。这意味着你将无法在以下表中找到这些查询：
* `system.query_log`
* `system.query_thread_log`
只有以下类型的查询才会被写入日志：
* `QUERY_FINISH`
* `EXCEPTION_WHILE_PROCESSING`
* 类型：毫秒
* 默认值：0 (任何查询)
## log\_queries\_min\_type
`query_log` 中要记录的最小类型。
可能的值：
* `QUERY_START` (`=1`)
* `QUERY_FINISH` (`=2`)
* `EXCEPTION_BEFORE_START` (`=3`)
* `EXCEPTION_WHILE_PROCESSING` (`=4`)
可用于限制哪些条目会写入 `query_log`；例如，如果你只关心错误，则可以使用 `EXCEPTION_WHILE_PROCESSING`：
```text theme={null}
log_queries_min_type='EXCEPTION_WHILE_PROCESSING'
```
## log\_queries\_probability
允许用户仅以指定概率随机选取部分查询，并将其写入 [query\_log](/zh/reference/system-tables/query_log)、[query\_thread\_log](/zh/reference/system-tables/query_thread_log) 和 [query\_views\_log](/zh/reference/system-tables/query_views_log) 系统表。这有助于在每秒查询量较大时降低负载。
可能的值：
* 0 — 查询不会记录到系统表中。
* 范围为 \[0..1] 的正浮点数。例如，如果设置值为 `0.5`，则大约一半的查询会记录到系统表中。
* 1 — 所有查询都会记录到系统表中。
## log\_query\_settings
将查询设置写入 query\_log 和 OpenTelemetry span 日志。
## log\_query\_threads
配置查询线程日志记录。
查询线程的日志会写入 [system.query\_thread\_log](/zh/reference/system-tables/query_thread_log) 表。仅当 [log\_queries](#log_queries) 为 true 时，此设置才会生效。启用此设置后，ClickHouse 运行的查询线程会按照服务器配置参数 [query\_thread\_log](/zh/reference/settings/server-settings/settings#query_thread_log) 中的规则进行记录。
可能的值：
* 0 — 已禁用。
* 1 — 已启用。
**示例**
```text theme={null}
log_query_threads=1
```
## log\_query\_views
设置查询视图日志记录。
当 ClickHouse 在启用此设置的情况下运行某个查询，且该查询关联了视图 (materialized 或 live views) 时，这些视图会被记录到服务器配置参数 [query\_views\_log](/zh/reference/settings/server-settings/settings#query_views_log) 中。
示例：
```text theme={null}
log_query_views=1
```
## low\_cardinality\_allow\_in\_native\_format
允许或禁止在 [Native](/zh/reference/formats/Native) 格式中使用 [LowCardinality](/zh/reference/data-types/lowcardinality) 数据类型。
如果禁止使用 `LowCardinality`，ClickHouse server 会在 `SELECT` 查询中将 `LowCardinality` 列转换为普通列，并在 `INSERT` 查询中将普通列转换为 `LowCardinality` 列。
此设置主要用于不支持 `LowCardinality` 数据类型的第三方客户端。
可能的值：
* 1 — 不限制使用 `LowCardinality`。
* 0 — 限制使用 `LowCardinality`。
## low\_cardinality\_max\_dictionary\_size
为可写入存储文件系统的 [LowCardinality](/zh/reference/data-types/lowcardinality) 数据类型的共享全局字典设置最大行数。此设置可防止字典无限增长而导致 RAM 相关问题。对于因字典大小达到上限而无法编码的数据，ClickHouse 会以普通方式写入。
可能的值：
* 任意正整数。
## low\_cardinality\_use\_single\_dictionary\_for\_part
控制是否对数据分区片段使用单个字典。
默认情况下，ClickHouse 服务器会监控字典的大小；如果某个字典溢出，服务器就会开始写入下一个字典。要禁止创建多个字典，请设置 `low_cardinality_use_single_dictionary_for_part = 1`。
可能的值：
* 1 — 禁止为数据分区片段创建多个字典。
* 0 — 不禁止为数据分区片段创建多个字典。
## low\_priority\_query\_wait\_time\_ms
采用查询优先级机制时 (请参见设置 `priority`) ，低优先级查询会等待更高优先级的查询完成。此设置指定等待的时长。
## make\_distributed\_plan
生成分布式查询计划。
## materialize\_skip\_indexes\_on\_insert
是否在 INSERT 时构建并存储跳过索引。若禁用，则仅会[在合并期间](/zh/reference/settings/merge-tree-settings#materialize_skip_indexes_on_merge)构建并存储跳过索引，或者通过显式执行 [MATERIALIZE INDEX](/zh/reference/statements/alter/skipping-index#materialize-index) 来构建并存储。
另请参见 [exclude\_materialize\_skip\_indexes\_on\_insert](#exclude_materialize_skip_indexes_on_insert)。
## materialize\_statistics\_on\_insert
是否在 INSERT 时构建并插入统计信息。如果禁用，统计信息将在合并期间或通过显式执行 MATERIALIZE STATISTICS 进行构建并存储
## materialize\_ttl\_after\_modify
执行 ALTER MODIFY TTL 查询后，对旧数据应用 TTL
## materialized\_views\_ignore\_errors
如果启用，将数据推送到依赖的 materialized view 时 (在其 `SELECT` 中或内部表 sink 端) 抛出的异常会被记录为警告，且 `INSERT` 语句会成功。如果禁用 (默认) ，这类异常会继续向上传播，`INSERT` 语句也会失败。
此设置仅控制错误报告。它不会回滚对源表的写入，也不保证当依赖视图的管道中发生错误时，原始块是否已提交到源表。禁用时 (默认) ，`INSERT` 会因视图错误而失败——请结合插入去重 (`insert_deduplicate`, `deduplicate_blocks_in_dependent_materialized_views`) 进行重试，以确保源表和所有依赖视图都实现精确一次投递。启用时，即使向出错视图及其下游事件链的投递只是部分完成，`INSERT` 仍会报告成功；仅应在源表写入绝不能被视图侧问题阻塞时使用此设置 (例如 `system.*_log` 表) 。完整语义请参见 `CREATE VIEW` 文档。
## materialized\_views\_squash\_parallel\_inserts
将单个 INSERT 查询中并行插入到 materialized view 目标表的数据块进行合并，以减少生成的 parts 数量。
如果设置为 false 且启用了 `parallel_view_processing`，则 INSERT 查询会在目标表中为每个 `max_insert_thread` 生成一个 part。
## max\_analyze\_depth
解释器执行分析的最大次数。
## max\_ast\_depth
查询语法树的最大嵌套深度。超过该限制时，将抛出异常。
目前，这一项不会在解析过程中检查，而只会在查询解析完成后检查。
这意味着，在解析过程中可能会创建出过深的语法树，
但查询会失败。
## max\_ast\_elements
查询语法树中的最大元素数量。超过时会抛出异常。
目前不会在解析期间进行检查，而只会在查询解析完成后检查。
这意味着，解析期间仍可能创建出过深的语法树，
但查询会失败。
## max\_autoincrement\_series
由 `generateSerialID` 函数创建的序列数量上限。
由于每个序列都对应 Keeper 中的一个节点，建议其数量不要超过几百万个。
## max\_backup\_bandwidth
服务器上特定备份的最大读取速度，单位为每秒字节数。零表示不受限制。
## max\_block\_size
在 ClickHouse 中，数据以块为单位进行处理，块是列分片的集合。单个块的内部处理流程效率很高，但处理每个块时都会产生明显的开销。
`max_block_size` 设置表示从表中加载数据时，单个块建议包含的最大行数。从表中加载的块并不总是会达到 `max_block_size`：如果 ClickHouse 判断只需读取较少的数据，就会处理更小的块。
块大小不应过小，以避免处理每个块时产生明显开销；也不应过大，以确保带有 LIMIT 子句的查询在处理完第一个块后能够快速执行。设置 `max_block_size` 时，目标应是避免在多线程提取大量列时占用过多内存，并尽可能保留一定的缓存局部性。
## max\_bytes\_before\_external\_group\_by
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`。
如果 GROUP BY 操作期间的内存使用量超过此阈值 (以字节为单位) ，
则会启用“外部聚合”模式 (将数据落盘) 。
建议值为可用系统内存的一半。
## max\_bytes\_before\_external\_join
如果将其设为非零值，且 `join_algorithm` 为 `hash`、`parallel_hash`、`default` 或 `auto`，当右侧数据超过该字节数时，hash join 会自动转换为 grace hash join，以支持落盘到 disk。设为 0 (默认值) 时，此绝对字节阈值会被禁用，但仍可能通过 `max_bytes_ratio_before_external_join` (默认值为 `0.5`) 触发自动落盘；将两者都设为 `0` 可完全禁用自动落盘。它会阻止通过 join 进行按顺序读取优化。
## max\_bytes\_before\_external\_sort
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
对于带有 LIMIT 的 ORDER BY，当内存使用量高于指定阈值时，会在最终合并之前额外执行块合并步骤，以仅保留前 LIMIT 行。
## max\_bytes\_for\_lazy\_final
lazy FINAL 优化中集合的最大字节数。超过该值时，将回退为普通 FINAL。
## max\_bytes\_in\_distinct
使用 DISTINCT 时，哈希表在内存中用于存储状态的最大字节数 (按未压缩字节计算) 。
## max\_bytes\_in\_join
执行表连接时右侧数据结构 (通常为哈希表) 的最大大小，以字节数表示。
此设置适用于 [SELECT ... JOIN](/zh/reference/statements/select/join)
操作以及 [Join table engine](/zh/reference/engines/table-engines/special/join)。
如果查询包含多个 JOIN，ClickHouse 会针对每个
中间结果检查此设置。达到该限制时，所采取的操作取决于所选的
[`join_algorithm`](/zh/reference/settings/session-settings#join_algorithm) —— 请参阅
该设置，了解各算法的具体行为 (落盘、重新分区、切换，或根据
[`join_overflow_mode`](/zh/reference/settings/session-settings#join_overflow_mode) 执行 throw/break) 。
可能的值：
* 正整数。
* 0 — 禁用内存控制。
## max\_bytes\_in\_set
由子查询创建的 IN 子句中的 Set 可使用的最大字节数 (未压缩数据) 。
## max\_bytes\_ratio\_before\_external\_group\_by
允许 `GROUP BY` 使用的可用内存比例。达到该比例后，
聚合将使用外部内存。
例如，如果设置为 `0.6`，则 `GROUP BY` 在执行开始时最多可使用 60% 的可用内存
(相对于 server/user/merges 可用的内存) ，之后将
开始使用外部聚合。
## max\_bytes\_ratio\_before\_external\_join
允许 `JOIN` 使用的可用内存占比。达到该比例后，hash 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` 为 `hash`、`parallel_hash`、`default` 或 `auto`，且已配置临时数据路径时，此设置才会生效。
## 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 部分时，可传输到远程服务器或保存到临时表中的最大字节数 (未压缩数据) 。
## max\_columns\_to\_read
单个查询从表中可读取的最大列数。
如果查询需要读取的列数超过指定数量，
则会抛出异常。
此设置可用于防止查询过于复杂。
`0` 表示不受限制。
## max\_compress\_block\_size
写入表时，压缩前未压缩数据块的最大大小。默认值为 1,048,576 (1 MiB) 。指定较小的块大小通常会使压缩率略有下降；但由于缓存局部性更好，压缩和解压速度会略有提升，同时内存消耗也会降低。
这是一个专家级设置；如果你刚开始使用 ClickHouse，不建议更改它。
不要将用于压缩的块 (由字节组成的一段内存) 与用于查询处理的块 (表中的一组行) 混淆。
## max\_concurrent\_queries\_for\_all\_users
如果此设置的值小于或等于当前正在同时处理的查询数，则抛出异常。
示例：可将 `max_concurrent_queries_for_all_users` 为所有用户设置为 99，而数据库管理员可将其自身的值设为 100，以便即使在 server 过载时也能运行用于调查的查询。
为单个查询或用户修改此设置，不会影响其他查询。
可能的值：
* 正整数。
* 0 — 不限制。
**示例**
```xml theme={null}
99
```
**另请参阅**
* [max\_concurrent\_queries](/zh/reference/settings/server-settings/settings#max_concurrent_queries)
Cloud 默认值：`1000`。
## 每个用户的最大并发查询数
每个用户可同时处理的查询数量上限。
可能的值：
* 正整数。
* 0 — 无限制。
**示例**
```xml theme={null}
5
```
## max\_consume\_snapshots
每次增量读取最多可消费的 Paimon 快照数量。0 表示不限制。
## max\_distributed\_connections
对单个 Distributed 表执行单次查询的分布式处理时，与远程服务器之间允许建立的最大并发连接数。建议将该值设置为不小于集群中的服务器数量。
以下参数仅在创建 Distributed 表时 (以及服务器启动时) 使用，因此没有必要在运行时更改它们。
## max\_distributed\_depth
限制 [Distributed](/zh/reference/engines/table-engines/special/distributed) 表递归查询的最大深度。
如果超过该值，server 会抛出异常。
Possible values:
* 正整数。
* 0 — 深度无限制。
## max\_download\_buffer\_size
每个线程用于并行下载 (例如 URL engine) 的缓冲区最大大小。
## max\_download\_threads
下载数据时可使用的最大线程数 (例如用于 URL engine) 。
## max\_estimated\_execution\_time
查询的最大预计执行时间 (秒) 。当 [`timeout_before_checking_execution_speed`](/zh/reference/settings/session-settings#timeout_before_checking_execution_speed)
到期时，会在每个数据块上检查。
## max\_execution\_speed
每秒最大执行行数。当
[`timeout_before_checking_execution_speed`](/zh/reference/settings/session-settings#timeout_before_checking_execution_speed)
超时后，会在每个数据块上进行检查。如果执行速度过高，则会降低执行速度。
## max\_execution\_speed\_bytes
每秒最大执行字节数。每当
[`timeout_before_checking_execution_speed`](/zh/reference/settings/session-settings#timeout_before_checking_execution_speed)
到期时，都会在每个数据块上检查一次。如果执行速度过高，则会对其进行限制。
## max\_execution\_time
查询的最长执行时间，单位为秒。
`max_execution_time` 参数可能有些难理解。
它的工作方式是根据当前查询的执行速度进行插值估算，
(这种行为由 [`timeout_before_checking_execution_speed`](/zh/reference/settings/session-settings#timeout_before_checking_execution_speed) 控制) 。
如果预计执行时间超过指定的 `max_execution_time`，ClickHouse 将中断该查询。默认情况下，`timeout_before_checking_execution_speed`
设置为 10 秒。这意味着在查询执行 10 秒后，ClickHouse
会开始估算总执行时间。例如，如果将 `max_execution_time`
设置为 3600 秒 (1 小时) ，那么当估算出的总执行时间超过
3600 秒这一限制时，ClickHouse 将终止该查询。如果将 `timeout_before_checking_execution_speed`
设置为 0，ClickHouse 将以实际时钟时间作为 `max_execution_time` 的判断依据。
如果查询运行时间超过指定秒数，其行为将由
`timeout_overflow_mode` 决定，默认值为 `throw`。
只有在数据处理过程中的特定位置才会检查是否超时并停止查询。
目前，在聚合状态合并期间或查询分析期间无法停止，
因此实际运行时间会高于此设置的值。
## max\_execution\_time\_leaf
在语义上类似于 [`max_execution_time`](#max_execution_time)，但它仅
适用于分布式或远程查询的叶子节点。
例如，如果我们希望将叶子节点上的执行时间限制为 `10s`，但
对起始节点不设限制，那么就不应在嵌套子查询的设置中使用 `max_execution_time`：
```sql theme={null}
SELECT count()
FROM cluster(cluster, view(SELECT * FROM t SETTINGS max_execution_time = 10));
```
我们可以将 `max_execution_time_leaf` 用作查询设置：
```sql theme={null}
SELECT count()
FROM cluster(cluster, view(SELECT * FROM t)) SETTINGS max_execution_time_leaf = 10;
```
## max\_expanded\_ast\_elements
别名和星号展开后，查询语法树的最大节点数。
## max\_fetch\_partition\_retries\_count
从另一台主机拉取分区时的重试次数。
## max\_final\_threads
设置带有 [FINAL](/zh/reference/statements/select/from#final-modifier) 修饰符的 `SELECT` 查询在数据读取阶段可使用的最大并行线程数。
可能的值：
* 正整数。
* 0 或 1 — 禁用。`SELECT` 查询将以单线程执行。
## max\_http\_get\_redirects
允许的 HTTP GET 重定向跳转次数上限。该设置可提供额外的安全保障，防止恶意服务器将你的请求重定向到非预期的服务。\n\n例如，外部服务器可能会将请求重定向到另一个地址，而该地址看起来属于公司内部基础设施。这样一来，向该内部服务器发送 HTTP 请求时，你就可能从内部网络访问内部 API，绕过身份验证，甚至查询其他服务，例如 Redis 或 Memcached。如果你没有内部基础设施 (包括在 localhost 上运行的任何服务) ，或者你信任该服务器，则允许重定向是安全的。但请注意，如果 URL 使用的是 HTTP 而非 HTTPS，那么你不仅需要信任远程服务器，还需要信任你的 ISP 以及中间经过的所有网络。
Cloud default value: `10`.
## max\_hyperscan\_regexp\_length
定义 [hyperscan 多模式匹配函数](/zh/reference/functions/regular-functions/string-search-functions#multiMatchAny) 中每个正则表达式的最大长度。
可能的值：
* 正整数。
* 0 — 长度不受限制。
**示例**
查询：
```sql theme={null}
SELECT multiMatchAny('abcd', ['ab','bcd','c','d']) SETTINGS max_hyperscan_regexp_length = 3;
```
结果：
```text theme={null}
┌─multiMatchAny('abcd', ['ab', 'bcd', 'c', 'd'])─┐
│ 1 │
└────────────────────────────────────────────────┘
```
查询：
```sql theme={null}
SELECT multiMatchAny('abcd', ['ab','bcd','c','d']) SETTINGS max_hyperscan_regexp_length = 2;
```
结果：
```text theme={null}
Exception: Regexp length too large.
```
**另请参阅**
* [max\_hyperscan\_regexp\_total\_length](#max_hyperscan_regexp_total_length)
## max\_hyperscan\_regexp\_total\_length
设置每个 [hyperscan 多模式匹配函数](/zh/reference/functions/regular-functions/string-search-functions#multiMatchAny) 中所有正则表达式总长度的上限。
可能的值：
* 正整数。
* 0 - 长度不受限制。
**示例**
查询：
```sql theme={null}
SELECT multiMatchAny('abcd', ['a','b','c','d']) SETTINGS max_hyperscan_regexp_total_length = 5;
```
结果：
```text theme={null}
┌─multiMatchAny('abcd', ['a', 'b', 'c', 'd'])─┐
│ 1 │
└─────────────────────────────────────────────┘
```
查询：
```sql theme={null}
SELECT multiMatchAny('abcd', ['ab','bc','c','d']) SETTINGS max_hyperscan_regexp_total_length = 5;
```
结果：
```text theme={null}
Exception: Total regexp lengths too large.
```
**另请参见**
* [max\_hyperscan\_regexp\_length](#max_hyperscan_regexp_length)
## max\_insert\_block\_size
**别名**: `max_insert_block_size_rows`
为插入表而生成的块的最大大小 (按行数计) 。
此设置在以下两种场景中控制块的生成：
1. 格式解析：当服务器通过任意接口 (HTTP、带内联数据的 clickhouse-client、gRPC、PostgreSQL wire protocol) 解析基于行的输入格式 (CSV、TSV、JSONEachRow 等) 时，会在以下情况下输出块：
* 同时达到 min\_insert\_block\_size\_rows AND min\_insert\_block\_size\_bytes，OR
* 达到 max\_insert\_block\_size\_rows OR max\_insert\_block\_size\_bytes 中的任意一个
注意：使用 clickhouse-client 或 clickhouse-local 从文件读取时，数据由客户端自身解析，因此此设置在客户端侧生效。
2. INSERT 操作：在执行 INSERT queries 期间，以及数据流经 materialized views 时，此设置的行为取决于 `use_strict_insert_block_limits`：
* 启用时：会在以下情况下输出块：
* 最小阈值 (AND) ：同时达到 min\_insert\_block\_size\_rows AND min\_insert\_block\_size\_bytes
* 最大阈值 (OR) ：达到 max\_insert\_block\_size\_rows OR max\_insert\_block\_size\_bytes 中的任意一个
* 禁用时：达到 min\_insert\_block\_size\_rows OR min\_insert\_block\_size\_bytes 时就会输出块。max\_insert\_block\_size 设置不会生效。
可能的值：
* 正整数。
## max\_insert\_block\_size\_bytes
为插入表而生成的块的最大大小 (以字节为单位) 。
此设置与 max\_insert\_block\_size\_rows 配合使用，并在相同上下文中控制块的生成。有关这些设置会在何时以及如何生效的详细信息，请参见 max\_insert\_block\_size\_rows。
Possible values:
* 正整数。
* 0 — 该设置不参与块的生成。
## max\_insert\_delayed\_streams\_for\_parallel\_write
延迟最终分片刷写的最大流 (列) 数。默认值为自动 (如果底层存储支持并行写入，例如 S3，则为 100；否则为禁用)
Cloud 默认值：`50`。
## max\_insert\_threads
执行 `INSERT SELECT` 查询时使用的最大线程数。
可能的值：
* 0 (或 1) — `INSERT SELECT` 不会并行执行。
* 大于 1 的正整数。
Cloud 默认值：
* 8 GiB 内存的节点为 `1`
* 16 GiB 内存的节点为 `2`
* 更大规格的节点为 `4`
只有当 `SELECT` 部分并行执行时，并行 `INSERT SELECT` 才会生效，请参见 [`max_threads`](#max_threads) 设置。
值越大，内存使用量越高。
## max\_insert\_threads\_min\_free\_memory\_per\_thread
与 `max_threads_min_free_memory_per_thread` 相同，但它作用于 `max_insert_threads`，而不是 `max_threads`。默认值更高，因为插入管道通常比读取管道为每个线程保留更大的缓冲区 (MergeTree parts、压缩块) 。
如果空闲内存小于 `max_insert_threads` 与该值的乘积，则会下调 `max_insert_threads` 以适应可用内存，最少降至 `1`。
将其设为 `0` 可禁用此限制。
## max\_joined\_block\_size\_bytes
JOIN 结果的最大块大小 (以字节为单位，前提是 JOIN 算法支持) 。0 表示无限制。
## max\_joined\_block\_size\_rows
JOIN 结果的最大块大小 (如果所用的 join 算法支持) 。0 表示无限制。
## max\_limit\_for\_vector\_search\_queries
LIMIT 大于此设置值的 SELECT 查询不能使用向量相似度索引。这有助于防止向量相似度索引发生内存溢出。
## max\_local\_read\_bandwidth
本地读取的最高速度，以每秒字节数为单位。
## max\_local\_write\_bandwidth
本地写入的最大速度，单位为每秒字节数。
## max\_memory\_usage
Cloud 默认值：取决于副本上的 RAM 大小。
在单台服务器上运行单个查询时可使用的最大 RAM 量。
值为 `0` 表示无限制。
此设置不考虑可用内存大小，也不考虑机器上的
总内存大小。该限制仅适用于单台
服务器上的单个查询。
你可以使用 `SHOW PROCESSLIST` 查看每个查询当前的内存占用。
系统会跟踪每个查询的峰值内存占用，并将其写入日志。
对于以下使用 `String` 和 `Array` 参数的聚合函数状态，
内存占用无法被完全跟踪：
* `min`
* `max`
* `any`
* `anyLast`
* `argMin`
* `argMax`
内存占用还受参数 [`max_memory_usage_for_user`](/zh/reference/settings/session-settings#max_memory_usage_for_user)
和 [`max_server_memory_usage`](/zh/reference/settings/server-settings/settings#max_server_memory_usage) 的限制。
## max\_memory\_usage\_for\_user
在单台服务器上执行某个用户的查询时，允许使用的最大 RAM 量。0 表示不受限制。
默认情况下，该值不受限制 (`max_memory_usage_for_user = 0`) 。
另请参阅 [`max_memory_usage`](/zh/reference/settings/session-settings#max_memory_usage) 的说明。
例如，如果要将名为 `clickhouse_read` 的用户的 `max_memory_usage_for_user` 设置为 1000 字节，可以使用以下语句
```sql theme={null}
ALTER USER clickhouse_read SETTINGS max_memory_usage_for_user = 1000;
```
你可以先退出客户端并重新登录，再使用 `getSetting` 函数验证是否生效：
```sql theme={null}
SELECT getSetting('max_memory_usage_for_user');
```
## max\_network\_bandwidth
限制网络数据交换速度，单位为字节/秒。此设置适用于每个查询。
可能的值：
* 正整数。
* 0 — 禁用带宽控制。
## max\_network\_bandwidth\_for\_all\_users
限制通过网络交换数据的速率，单位为字节/秒。此设置适用于 server 上所有并发运行的查询。
可能的值：
* 正整数。
* 0 — 禁用数据速率控制。
## max\_network\_bandwidth\_for\_user
限制网络数据交换速度，单位为字节/秒。此设置适用于单个用户执行的所有并发查询。
可能的值：
* 正整数。
* 0 — 禁用数据传输速率控制。
## max\_network\_bytes
限制执行查询时通过网络接收或传输的数据量 (以字节为单位) 。此设置适用于每个单独的查询。
可能的值：
* 正整数。
* 0 — 禁用数据量限制。
## 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](#parallel_replicas_custom_key) 进行并行处理
此设置适用于任何复制表。
## max\_parser\_backtracks
解析器最大回溯次数 (即在递归下降解析过程中尝试不同备选方案的次数) 。
## max\_parser\_depth
限制递归下降解析器的最大递归深度，可用于控制栈大小。
可能的值：
* 正整数。
* 0 — 递归深度不受限制。
## max\_parsing\_threads
用于解析支持并行解析的输入格式数据时可使用的最大线程数。默认情况下，该值会自动确定。
## max\_partition\_size\_to\_drop
对查询时执行删除分区操作的限制。值 `0` 表示可以不受任何限制地删除分区。
Cloud 默认值：1 TB。
此查询设置会覆盖对应的服务器级设置，参见 [max\_partition\_size\_to\_drop](/zh/reference/settings/server-settings/settings#max_partition_size_to_drop)
## max\_partitions\_per\_insert\_block
限制单个插入块中的最大分区数；
如果该块包含的分区过多，则会抛出异常。
* 正整数。
* `0` — 分区数量不受限制。
**详情**
插入数据时，ClickHouse 会计算插入块中的分区数。如果分区数超过
`max_partitions_per_insert_block`，ClickHouse 会根据 `throw_on_max_partitions_per_insert_block`
记录警告或抛出异常。异常文本如下：
> "单个 INSERT 块中的分区过多 (`partitions_count` 个分区，限制为 " + toString(max\_partitions) + ") 。
> 该限制由 'max\_partitions\_per\_insert\_block' 设置控制。
> 使用大量分区是一种常见误区。这会对性能造成严重负面影响，包括 server 启动缓慢、INSERT 查询缓慢
> 以及 SELECT 查询缓慢。对于一张表，建议分区总数控制在 1000..10000 以内。请注意，
> 分区并不是为了加速 SELECT 查询 (ORDER BY key 足以让范围查询保持较快) 。
> 分区是用于数据操作的 (DROP PARTITION 等) 。"
此设置是一个安全阈值，因为使用大量分区是一种常见误区。
## max\_partitions\_to\_read
限制单个查询可访问的最大分区数。
在创建表时指定的设置值，可以通过查询级别的设置覆盖。
可选值：
* 正整数
* `-1` - 不限 (默认)
你也可以在表设置中指定 MergeTree 设置 [`max_partitions_to_read`](/zh/reference/settings/session-settings#max_partitions_to_read)。
## max\_parts\_to\_move
限制单次查询中可移动的 parts 数量。0 表示不受限制。
## max\_projection\_rows\_to\_use\_projection\_index
如果从投影索引中读取的行数小于或等于该阈值，ClickHouse 将在查询执行期间尝试使用投影索引。
## max\_query\_size
由 SQL 解析器解析的查询字符串的最大字节数。
INSERT 查询中 VALUES 子句里的数据由单独的 stream parser 处理 (其 RAM 占用为 O(1)) ，因此不受此限制影响。
`max_query_size` 不能在 SQL 查询内部设置 (例如 `SELECT now() SETTINGS max_query_size=10000`) ，因为 ClickHouse 需要先分配一个 buffer 来解析查询，而该 buffer 的大小由 `max_query_size` 设置决定；因此，它必须在查询执行前完成配置。
## max\_rand\_distribution\_parameter
`randChiSquared`、`randStudentT` 和 `randFisherF` 等 random distribution functions 的分布形态参数最大值。此设置可防止参数值过于极端时导致计算时间过长。
## max\_rand\_distribution\_trials
`randBinomial` 和 `randNegativeBinomial` 等随机分布函数允许的最大试验次数。这可以避免在试验次数很大时导致计算时间过长。
## max\_read\_buffer\_size
从文件系统读取时缓冲区的最大大小。
## max\_read\_buffer\_size\_local\_fs
从本地文件系统读取数据时，缓冲区的最大大小。如果设置为 0，则使用 max\_read\_buffer\_size。
## max\_read\_buffer\_size\_remote\_fs
从远程文件系统读取数据时，缓冲区的最大大小。如果设置为 0，则使用 max\_read\_buffer\_size。
## max\_recursive\_cte\_evaluation\_depth
递归 CTE 求值深度上限
## max\_remote\_read\_network\_bandwidth
读取时网络数据交换的最大速率，以字节/秒为单位。
## max\_remote\_write\_network\_bandwidth
写入时网络数据交换的最大速度，以字节/秒为单位。
## max\_replica\_delay\_for\_distributed\_queries
对分布式查询禁用延迟过高的副本。请参阅 [复制](/zh/reference/engines/table-engines/mergetree-family/replication)。
设置一个以秒为单位的时间值。如果某个副本的延迟大于或等于该值，则不会使用该副本。
可能的值：
* 正整数。
* 0 — 不检查副本延迟。
若要防止使用任何存在非零延迟的副本，请将此参数设置为 1。
在对指向复制表的分布式表执行 `SELECT` 时使用。
## max\_result\_bytes
限制结果大小 (以字节计，未压缩) 。如果达到阈值，查询会在处理完一个数据块后停止，
但不会截断结果的最后一个块，因此结果大小可能会超过该阈值。
**注意事项**
此阈值会将内存中的结果大小计算在内。
即使结果本身很小，它也可能引用内存中更大的数据结构，
例如 LowCardinality 列的字典，以及 AggregateFunction 列的 Arena，
因此即使结果较小，也可能超过该阈值。
该设置较为底层，应谨慎使用
## max\_result\_rows
Cloud 默认值：`0`。
限制结果中的行数。此限制也会应用于子查询，以及在远程服务器上执行分布式查询的各个部分时。
当该值为 `0` 时，不作限制。
如果达到阈值，查询会在处理完一个数据块后停止，
但不会截断结果中的最后一个块，因此结果大小可能会
超过该阈值。
## max\_reverse\_dictionary\_lookup\_cache\_size\_bytes
函数 `dictGetKeys` 使用的每个查询反向字典查找缓存的最大大小 (以字节为单位) 。该缓存会针对每个属性值存储序列化后的键 Tuple，以避免在同一查询中重复扫描字典。达到上限时，条目会按 LRU 策略逐出。将其设置为 0 可禁用缓存。
## max\_rows\_for\_lazy\_final
用于 lazy FINAL 优化的集合最大行数。超过该值时，将回退到普通 FINAL。
## max\_rows\_in\_distinct
使用 DISTINCT 时，不同`行`的最大数量。
## max\_rows\_in\_join
限制用于表连接时右侧数据结构 (通常为哈希表) 中的行数。
此设置适用于 [SELECT ... JOIN](/zh/reference/statements/select/join)
操作以及 [Join](/zh/reference/engines/table-engines/special/join) 表引擎。
如果一个查询包含多个 JOIN，ClickHouse 会对每个
中间结果检查此设置。达到该限制时，具体操作取决于所选的
[`join_algorithm`](/zh/reference/settings/session-settings#join_algorithm) —— 请参阅该设置，了解各算法对应的行为 (落盘、重新分区、切换，或根据
[`join_overflow_mode`](/zh/reference/settings/session-settings#join_overflow_mode) 执行 `throw/break`) 。
可能的值：
* 正整数。
* `0` — 行数不受限制。
## max\_rows\_in\_set
由子查询创建的 IN 子句中的数据集所允许的最大行数。
## max\_rows\_in\_set\_to\_optimize\_join
在执行连接之前，使用彼此的行集对待连接表进行过滤时，集合的最大大小。
可能的值：
* 0 — 禁用。
* 任意正整数。
## max\_rows\_to\_group\_by
聚合产生的唯一键的最大数量。此设置可帮助
您在聚合时限制内存消耗。
如果 GROUP BY 期间的聚合生成的
行数 (唯一的 GROUP BY 键) 超过指定数量，则其行为由
'group\_by\_overflow\_mode' 决定，默认值为 `throw`，也可以切换
为近似 GROUP BY 模式。
## max\_rows\_to\_read
运行查询时可从表中读取的最大行数。
该限制会在每个已处理的数据块上进行检查，仅适用于
最深层的表表达式；当从远程服务器读取时，也仅在
远程服务器上进行检查。
## max\_rows\_to\_read\_leaf
执行分布式查询时，叶节点上从本地表可读取的最大行数。虽然分布式查询可以向每个分片 (叶节点) 发出多个子查询，但该限制只会在叶节点的读取阶段进行检查，在根节点的结果合并阶段会被忽略。
例如，一个集群由 2 个分片组成，每个分片都包含一个有 100 行的表。某个分布式查询原本要从这两个表中读取全部数据，并设置了 `max_rows_to_read=150`，因此会失败，因为总行数为 200。若查询设置 `max_rows_to_read_leaf=150`，则会成功，因为叶节点最多只会读取 100 行。
该限制会对每个已处理的数据块进行检查。
此设置在 `prefer_localhost_replica=1` 时属于不稳定状态。
## max\_rows\_to\_sort
排序前允许的最大行数。这有助于在排序时限制内存占用。
如果为执行 ORDER BY 操作而需要处理的记录数超过指定数量，
则其行为由 `sort_overflow_mode` 决定，该值默认设置为 `throw`。
## max\_rows\_to\_transfer
执行 GLOBAL IN/JOIN 部分时，可传递到远程服务器或保存到临时表中的最大行数。
## max\_sessions\_for\_user
每个已通过身份验证的用户在 ClickHouse server 上允许的最大并发会话数。
示例：
```xml theme={null}
1
2
0
single_session_user
two_sessions_profile
unlimited_sessions_profile
```
可选值：
* 正整数
* `0` - 并发会话数无限制 (默认)
## max\_size\_to\_preallocate\_for\_aggregation
在聚合之前，所有哈希表总共允许为多少个元素预分配空间
## max\_size\_to\_preallocate\_for\_joins
在 joi 之前，允许在所有哈希表中总共为多少个元素预分配空间
## max\_skip\_unavailable\_shards\_num
启用 `skip_unavailable_shards` 时，该设置用于限制可静默跳过的分片最大数量。
如果不可用分片的数量超过此值，则不会静默跳过，而是抛出异常。
值为 0 表示不设限制 (默认行为——可跳过所有不可用分片) 。
## max\_skip\_unavailable\_shards\_ratio
启用 `skip_unavailable_shards` 时，此设置用于限制可静默跳过的分片最大比例 (0 到 1) 。
如果不可用分片占总分片的比例超过此值，则不会静默跳过，而会抛出异常。
值为 0 表示不设限制 (默认行为——可跳过所有不可用分片) 。
## max\_streams\_for\_files\_processing\_in\_cluster\_functions
如果不为 0，则限制 \*Cluster 表函数中从文件读取数据的线程数。
## max\_streams\_for\_merge\_tree\_reading
如果该值不为 0，则限制 MergeTree 表的读取流数量。
## max\_streams\_for\_union\_step
限制 `UNION` 步骤中同时活跃的数据流数量 (适用于 `UNION ALL` 和 `UNION DISTINCT`，因为 `UNION DISTINCT` 的实现方式是先执行 `UNION ALL` 步骤，再执行 `DISTINCT` 步骤) 。当 `UNION` 查询包含大量子查询时，这些子查询会同时打开各自的读缓冲区，导致内存占用与子查询数量成正比。此设置会插入 `Concat` 处理器来收窄管道，使同时活跃的流数量最多不超过该值，从而显著降低峰值内存占用。实际限制为该值与 `max_threads * max_streams_for_union_step_to_max_threads_ratio` 两者中的较小值 (任一值为 0 都表示忽略该值) 。当两者都为 0 时，则不会进行收窄。当查询计划要求 `UNION` 的每个输出流都必须分别保持各自的排序状态时 (例如在 `UNION` 上应用按序读取优化时) ，也不会应用此限制；在这种情况下，排序正确性优先，因此会跳过收窄。
## max\_streams\_for\_union\_step\_to\_max\_threads\_ratio
该比率乘以 `max_threads` 后，用于确定 `UNION` 步骤中同时活跃的流数上限 (同时适用于 `UNION ALL` 和 `UNION DISTINCT`) 。实际限制取该计算值与 `max_streams_for_union_step` 中的较小者 (任一值为 0 都表示忽略该值) 。例如，当 `max_threads = 8` 且该比率设置为 1 时，最多会有 8 个流同时活跃。将其设置为 0 可禁用基于该比率的限制。与 `max_streams_for_union_step` 类似，当查询计划要求 `UNION` 的每个输出流分别保持排序时，不会应用此限制。
## max\_streams\_multiplier\_for\_merge\_tables
从 Merge 表读取时请求更多流。这些流会分配到 Merge 表使用的各个表上。这样可以让工作在线程之间分布得更均衡，尤其适用于已合并表大小不一致的情况。
## max\_streams\_to\_max\_threads\_ratio
允许使用比线程数更多的流，以便在线程之间更均匀地分配工作。这里假定这只是一个临时方案，因为未来将能够使流的数量等于线程数，同时让每个流动态选择自己可用的工作。
## max\_subquery\_depth
如果某个查询中嵌套的子查询数量超过指定值，则会抛出异常。
这样可以进行合理性检查，防止集群中的用户编写过于复杂的查询。
## max\_table\_size\_to\_drop
对查询时删除表的限制。值 `0` 表示可以不受任何限制地删除所有表。
Cloud 默认值：1 TB。
此查询设置会覆盖对应的服务器设置，参见 [max\_table\_size\_to\_drop](/zh/reference/settings/server-settings/settings#max_table_size_to_drop)
## max\_temporary\_columns
执行查询时，包括常量列在内，同时保存在 RAM 中的临时列的最大数量。如果查询因中间计算在内存中生成的临时列数量超过指定值，则会抛出异常。
此设置有助于防止查询过于复杂。
`0` 表示不受限制。
## max\_temporary\_data\_on\_disk\_size\_for\_query
所有并发运行的查询在磁盘上使用的临时 File 数据总量上限，单位为字节。
可能的值：
* 正整数。
* `0` — 无限制 (默认)
## max\_temporary\_data\_on\_disk\_size\_for\_user
用户所有并发运行的查询在磁盘上的临时 File 所消耗的数据总量上限，单位为字节。
可能的值：
* 正整数。
* `0` — 不限制 (默认)
## max\_temporary\_non\_const\_columns
与 `max_temporary_columns` 类似，它表示执行查询时需要同时保存在 RAM 中的临时列的最大数量，但不包括常量列。
执行查询时经常会生成常量列，但它们几乎不消耗计算资源。
## max\_threads
查询处理线程的最大数量，不包括用于从远程服务器获取数据的线程 (参见 ['max\_distributed\_connections'](/zh/reference/settings/session-settings#max_distributed_connections) 参数) 。
此参数适用于并行执行查询处理管道中相同阶段的线程。
例如，从表中读取数据时，如果能够至少使用 'max\_threads' 个线程并行完成函数表达式求值、`WHERE` 过滤以及 `GROUP BY` 的预聚合，那么就会使用 'max\_threads'。
对于因 LIMIT 而很快完成的查询，可以将 'max\_threads' 设置得更低。
例如，如果每个块中都包含所需数量的条目，且 max\_threads = 8，那么会读取 8 个块，尽管实际上只读取 1 个块就足够了。
`max_threads` 的值越小，消耗的内存就越少。
默认情况下，`max_threads` 设置与 ClickHouse 可用的硬件线程数 (CPU 核心数) 一致。
不过有一种特殊情况：对于 CPU 核心数少于 32 且启用了 SMT (例如 Intel HyperThreading) 的 x86 处理器，ClickHouse 默认使用逻辑核心数 (= 2 x 物理核心数) 。
如果未启用 SMT (例如 Intel HyperThreading) ，则该值对应于 CPU 核心数。
对于 ClickHouse Cloud 用户，默认值会显示为 `auto(N)`，其中 N 与你的服务的 vCPU 规格一致，例如 2vCPU/8GiB、4vCPU/16GiB 等。
所有服务规格的列表可在 Cloud Console 的设置选项卡中查看。
## max\_threads\_for\_indexes
用于处理索引的最大线程数。
## max\_threads\_min\_free\_memory\_per\_thread
当 server 面临内存压力时，会降低 `max_threads`，以避免启动很可能触及内存限制的高并行查询。
空闲内存的计算方式为：server 的 `max_server_memory_usage` 减去当前由全局 memory tracker 跟踪的内存。如果该空闲内存小于 `max_threads` 与此值的乘积，则会将 `max_threads` 降低为满足 `N * value <= free_memory` 的最大 N，且最小值为 `1`。
将其设置为 `0` 可禁用此限制。
例如，默认值为 1 GiB 且空闲内存为 32 GiB 时，`max_threads` 上限为 32；空闲内存为 1 GiB 时，则会回落到 1。
此设置适用于读取侧并行度 (`SELECT`、`UNION`、`INTERSECT`/`EXCEPT`，以及 `INSERT ... SELECT` 中的 `SELECT` 侧) 。对于写入侧，请参见 `max_insert_threads_min_free_memory_per_thread`。
## max\_untracked\_memory
较小的内存分配和释放会在线程局部变量中归并，只有当其数量 (按绝对值计算) 超过指定值时，才会被跟踪或进行性能分析。如果该值高于 `memory_profiler_step`，则实际上会被下调为 `memory_profiler_step`。
## max\_wkb\_geometry\_elements
通过 `readWKB` 及相关函数解析时，单个 WKB 几何元素中允许包含的点、Ring 或 Polygon 的最大数量。这可防止格式错误的 WKB 数据造成过量内存分配。设置为 0 可使用硬编码限制 (1 亿) 。
## memory\_overcommit\_ratio\_denominator
它表示在全局层面达到硬限制时的软内存限制。
该值用于计算查询的 overcommit 比率。
零表示跳过该查询。
更多信息，请参阅[内存 overcommit](/zh/concepts/features/configuration/settings/memory-overcommit)。
## memory\_overcommit\_ratio\_denominator\_for\_user
它表示在用户级别达到硬内存限制时的软内存限制。
该值用于计算查询的 overcommit ratio。
值为 0 表示跳过该查询。
更多信息请参阅[内存 overcommit](/zh/concepts/features/configuration/settings/memory-overcommit)。
## memory\_profiler\_sample\_max\_allocation\_size
以 `memory_profiler_sample_probability` 的概率收集大小小于或等于指定值的随机内存分配。0 表示禁用。你可能需要将 `max_untracked_memory` 设置为 0，以使该阈值按预期生效。
## memory\_profiler\_sample\_min\_allocation\_size
以 `memory_profiler_sample_probability` 指定的概率，对大小大于或等于指定值的随机内存分配进行采样收集。0 表示禁用。你可能需要将 `max_untracked_memory` 设为 0，才能使此阈值按预期生效。
## memory\_profiler\_sample\_probability
随机收集内存分配与释放事件，并以 'MemorySample' trace\_type 写入 system.trace\_log。这里的概率适用于每一次 alloc/free，与分配大小无关 (可通过 `memory_profiler_sample_min_allocation_size` 和 `memory_profiler_sample_max_allocation_size` 调整) 。请注意，只有在未跟踪内存量超过 'max\_untracked\_memory' 时才会进行采样。若要获得更细粒度的采样，你可能需要将 'max\_untracked\_memory' 设置为 0。
## memory\_profiler\_step
设置内存分析器的步长。每当查询的内存使用量超过下一个以字节数表示的步长阈值时，内存分析器都会收集分配时的 stacktrace，并将其写入 [trace\_log](/zh/reference/system-tables/trace_log)。
可能的值：
* 以字节为单位的正整数。
* 0 表示关闭内存分析器。
## memory\_tracker\_fault\_probability
用于测试 `exception safety`：在每次分配内存时，都按指定概率抛出异常。
## memory\_usage\_overcommit\_max\_wait\_microseconds
在用户级别发生内存 overcommit 时，线程等待内存释放的最长时间。
如果达到 timeout 且内存仍未释放，则会抛出异常。
有关[内存 overcommit](/zh/concepts/features/configuration/settings/memory-overcommit)的更多信息，请参见。
## merge\_table\_max\_tables\_to\_look\_for\_schema\_inference
创建未显式指定 schema 的 `Merge` 表，或使用 `merge` 表函数时，schema 会推断为匹配表中不超过指定数量的表的并集。
如果表的数量超过该值，则 schema 将根据前指定数量的表进行推断。
## merge\_tree\_coarse\_index\_granularity
搜索数据时，ClickHouse 会检查索引文件中的数据标记。如果 ClickHouse 发现所需键位于某个范围内，就会将该范围划分为 `merge_tree_coarse_index_granularity` 个子范围，并在这些子范围内递归搜索所需键。
可能的值：
* 任意正偶数。
## merge\_tree\_compact\_parts\_min\_granules\_to\_multibuffer\_read
仅在 ClickHouse Cloud 中生效。该设置指定在 MergeTree 表的 compact part 的 stripe 中，达到多少个粒度时使用 multibuffer reader；该读取器支持并行读取和预取。如果从远程文件系统读取，使用 multibuffer reader 会增加读取请求数量。
## merge\_tree\_determine\_task\_size\_by\_prewhere\_columns
是否仅根据 prewhere 列的大小来确定读取任务的大小。
## merge\_tree\_max\_bytes\_to\_use\_cache
如果 ClickHouse 在一次查询中需要读取超过 `merge_tree_max_bytes_to_use_cache` 字节的数据，则不会使用未压缩块缓存。
未压缩块缓存用于存储查询提取出的数据。ClickHouse 使用此缓存来加快重复小型查询的响应速度。此设置可防止读取大量数据的查询挤占缓存。[uncompressed\_cache\_size](/zh/reference/settings/server-settings/settings#uncompressed_cache_size) 服务器设置定义了未压缩块缓存的大小。
可能的值：
* 任意正整数。
## merge\_tree\_max\_rows\_to\_use\_cache
如果 ClickHouse 在一次查询中需要读取超过 `merge_tree_max_rows_to_use_cache` 行，则不会使用未压缩块缓存。
未压缩块缓存会存储为查询提取出的数据。ClickHouse 使用此缓存来加快重复执行的小型查询的响应速度。此设置可防止读取大量数据的查询导致该缓存被频繁淘汰。[uncompressed\_cache\_size](/zh/reference/settings/server-settings/settings#uncompressed_cache_size) 服务器设置定义了未压缩块缓存的大小。
可能的值：
* 任意正整数。
## merge\_tree\_min\_bytes\_for\_concurrent\_read
如果从 [MergeTree](/zh/reference/engines/table-engines/mergetree-family/mergetree) 引擎表的单个文件中读取的字节数超过 `merge_tree_min_bytes_for_concurrent_read`，ClickHouse 会尝试使用多个线程并发读取该文件。
可能的值：
* 正整数。
## merge\_tree\_min\_bytes\_for\_concurrent\_read\_for\_remote\_filesystem
从远程 filesystem 读取时，[MergeTree](/zh/reference/engines/table-engines/mergetree-family/mergetree) 引擎在可并行读取之前，从单个文件中至少需要读取的字节数。我们不建议使用此设置。
可能的值：
* 正整数。
## merge\_tree\_min\_bytes\_for\_seek
如果同一文件中待读取的两个数据块之间的距离小于 `merge_tree_min_bytes_for_seek` 字节，ClickHouse 就会顺序读取包含这两个块的文件范围，从而避免额外的寻道操作。
可能的值：
* 任意正整数。
## merge\_tree\_min\_bytes\_per\_task\_for\_remote\_reading
**别名**: `filesystem_prefetch_min_bytes_for_single_read_task`
每个任务最少读取的字节数。
## merge\_tree\_min\_read\_task\_size
任务大小的硬性最小值 (即使粒度数量较少且可用线程数较多，我们也不会分配更小的任务
## merge\_tree\_min\_rows\_for\_concurrent\_read
如果从 [MergeTree](/zh/reference/engines/table-engines/mergetree-family/mergetree) 表文件中读取的行数超过 `merge_tree_min_rows_for_concurrent_read`，ClickHouse 会尝试使用多个线程并发读取该文件。
可能的值：
* 正整数。
## merge\_tree\_min\_rows\_for\_concurrent\_read\_for\_remote\_filesystem
从远程文件系统读取时，[MergeTree](/zh/reference/engines/table-engines/mergetree-family/mergetree) 引擎在能够并行读取之前，必须先从单个文件中读取的最小行数。我们不建议使用此设置。
可能的值：
* 正整数。
## merge\_tree\_min\_rows\_for\_seek
如果在同一文件中，两个待读取数据块之间的距离小于 `merge_tree_min_rows_for_seek` 行，则 ClickHouse 不会在文件中寻道，而是按顺序读取数据。
可能的值：
* 任意正整数。
## merge\_tree\_read\_split\_ranges\_into\_intersecting\_and\_non\_intersecting\_injection\_probability
用于测试 `PartsSplitter`——以指定概率，在每次从 MergeTree 读取时，将读取范围拆分为相交和不相交两部分。
## merge\_tree\_storage\_snapshot\_sleep\_ms
在为 MergeTree 表创建存储快照时，注入人为延迟 (以毫秒为单位) 。
仅用于测试和调试。
可能的值：
* 0 - 无延迟 (默认)
* N - 延迟的毫秒数
## merge\_tree\_use\_const\_size\_tasks\_for\_remote\_reading
是否在从远程表读取时使用固定大小的任务。
## merge\_tree\_use\_deserialization\_prefixes\_cache
启用在 MergeTree 从远程磁盘读取时，对文件前缀中的列元数据进行缓存。
## merge\_tree\_use\_prefixes\_deserialization\_thread\_pool
启用在线程池中并行读取 MergeTree 中 Wide parts 的前缀。该线程池的大小由服务器设置 `max_prefixes_deserialization_thread_pool_size` 控制。
## merge\_tree\_use\_v1\_object\_and\_dynamic\_serialization
启用后，MergeTree 将对 JSON 和 Dynamic 类型使用 V1 序列化版本，而不是 V2。更改此设置仅在 server 重启后才会生效。
## metrics\_perf\_events\_enabled
启用后，将在查询执行期间测量部分 perf 事件。
## metrics\_perf\_events\_list
以逗号分隔的 perf 指标列表，会在查询执行过程中进行测量。为空表示所有事件。可用事件请参见源代码中的 PerfEventInfo。
## min\_bytes\_to\_use\_direct\_io
启用直接 I/O 访问存储磁盘所需的最小数据量。
ClickHouse 在从表中读取数据时会使用此设置。如果待读取的所有数据总量超过 `min_bytes_to_use_direct_io` 字节，ClickHouse 就会使用 `O_DIRECT` 选项从存储磁盘读取数据。
Possible values:
* 0 — 禁用直接 I/O。
* 正整数。
## min\_bytes\_to\_use\_mmap\_io
这是一个 Experimental 设置。它设置了读取大文件时，使用无需将数据从内核复制到用户空间的方式所需的最小内存量。由于 [mmap/munmap](https://en.wikipedia.org/wiki/Mmap) 较慢，建议的阈值约为 64 MB。它只对大文件有意义，并且仅在数据位于页缓存中时才有帮助。
可能的值：
* 正整数。
* 0 — 读取大文件时，仅使用将数据从内核复制到用户空间的方式。
## min\_chunk\_bytes\_for\_parallel\_parsing
* 类型：无符号整数
* 默认值：1 MiB
每个线程并行解析时的最小块大小 (以字节为单位) 。
## min\_compress\_block\_size
适用于 [MergeTree](/zh/reference/engines/table-engines/mergetree-family/mergetree) 表。为降低查询处理延迟，当写入下一个标记时，如果某个块的大小至少达到 `min_compress_block_size`，就会对其进行压缩。默认值为 65,536。
如果未压缩数据小于 `max_compress_block_size`，则块的实际大小不会小于该值，也不会小于一个标记对应的数据量。
来看一个示例。假设在创建表时，`index_granularity` 设置为 8192。
假设写入的是一个 UInt32 类型的列 (每个值 4 字节) 。写入 8192 行时，总数据量为 32 KB。由于 min\_compress\_block\_size = 65,536，因此每两个标记会形成一个压缩块。
假设写入的是一个 URL 列，类型为 String 类型 (每个值平均 60 字节) 。写入 8192 行时，平均数据量会略低于 500 KB。由于这大于 65,536，因此每个标记都会形成一个压缩块。在这种情况下，从磁盘读取单个标记范围内的数据时，不会额外解压其他数据。
这是一个专家级设置；如果你刚开始使用 ClickHouse，则不应更改它。
## min\_count\_to\_compile\_aggregate\_expression
开始 JIT 编译所需的相同聚合表达式的最小数量。仅在启用 [compile\_aggregate\_expressions](#compile_aggregate_expressions) 设置时生效。
Possible values:
* 正整数。
* 0 — 始终对相同的聚合表达式进行 JIT 编译。
## min\_count\_to\_compile\_expression
同一表达式在编译前需执行的最小次数。
## min\_count\_to\_compile\_sort\_description
在触发 JIT 编译前，相同排序描述出现的次数
## min\_execution\_speed
最小执行速度，单位为每秒行数。在
[`timeout_before_checking_execution_speed`](/zh/reference/settings/session-settings#timeout_before_checking_execution_speed)
超时后，会对每个数据块进行检查。如果执行速度低于该值，则会抛出异常。
## min\_execution\_speed\_bytes
每秒执行的最小字节数。当
[`timeout_before_checking_execution_speed`](/zh/reference/settings/session-settings#timeout_before_checking_execution_speed)
超时后，会在每个数据块上检查一次。如果执行速度低于该值，则会抛出异常。
## min\_external\_table\_block\_size\_bytes
如果传递给外部表的块不够大，则将其压缩合并到指定的字节大小。
## min\_external\_table\_block\_size\_rows
如果传递给外部表的块不够大，则按指定的行数将其压缩合并到该大小。
## min\_filtered\_ratio\_for\_lazy\_final
索引分析为 lazy FINAL 优化过滤掉的标记的最小比例。如果过滤掉的标记比例低于该值，则回退为普通 FINAL。值为 0 时将禁用此检查。
## min\_free\_disk\_bytes\_to\_perform\_insert
执行插入操作所需的最小空闲磁盘空间 (字节) 。
## min\_free\_disk\_ratio\_to\_perform\_insert
执行插入操作所需的最小空闲磁盘空间比率。
## min\_free\_disk\_space\_for\_temporary\_data
在写入外部排序和聚合所用的临时数据时，需要保留的最小磁盘空间。
## min\_hit\_rate\_to\_use\_consecutive\_keys\_optimization
为保持聚合中连续键优化处于启用状态，所使用缓存的最低命中率
## min\_insert\_block\_size\_bytes
插入表时生成的块的最小大小 (以字节为单位) 。
此设置与 min\_insert\_block\_size\_rows 配合使用，并在相同的上下文中控制块的生成 (格式解析和 INSERT 操作) 。有关这些设置会在何时以及如何应用的详细信息，请参见 min\_insert\_block\_size\_rows。
可能的值：
* 正整数。
* 0 — 该设置不参与块的生成。
## min\_insert\_block\_size\_bytes\_for\_materialized\_views
设置可通过 `INSERT` 查询插入表中的块的最小字节数。较小的块会被合并为更大的块。此设置仅适用于插入到 [materialized view](/zh/reference/statements/create/view) 的块。调整此设置可以控制推送到 materialized view 时的块合并，并避免过高的内存占用。
可能的值：
* 任意正整数。
* 0 — 禁用合并。
**另请参见**
* [min\_insert\_block\_size\_bytes](#min_insert_block_size_bytes)
## min\_insert\_block\_size\_rows
插入到表时生成块的最小大小 (按行数计算) 。
此设置在以下两种场景中控制块的生成：
1. 格式解析：当 server 通过任意 interface (HTTP、带内联数据的 clickhouse-client、gRPC、PostgreSQL wire protocol) 解析基于行的输入格式 (CSV、TSV、JSONEachRow 等) 时，会在以下情况下输出块：
* 同时达到 min\_insert\_block\_size\_rows AND min\_insert\_block\_size\_bytes，或者
* 达到 max\_insert\_block\_size\_rows OR max\_insert\_block\_size\_bytes 之一
注意：使用 clickhouse-client 或 clickhouse-local 从文件读取时，数据由客户端自行解析，此设置在客户端侧生效。
2. INSERT 操作：在执行 INSERT 查询以及数据流经 materialized view 时，此设置的行为取决于 `use_strict_insert_block_limits`：
* 启用时：会在以下情况下输出块：
* 最小阈值 (AND) ：同时达到 min\_insert\_block\_size\_rows AND min\_insert\_block\_size\_bytes
* 最大阈值 (OR) ：达到 max\_insert\_block\_size\_rows OR max\_insert\_block\_size\_bytes 之一
* 禁用时 (默认) ：当达到 min\_insert\_block\_size\_rows OR min\_insert\_block\_size\_bytes 之一时，就会输出块。不强制应用 max\_insert\_block\_size 设置。
可能的值：
* 正整数。
* 0 — 此设置不参与块的生成。
## min\_insert\_block\_size\_rows\_for\_materialized\_views
设置可通过 `INSERT` 查询插入到表中的块所需的最小行数。较小的块会合并成更大的块。此设置仅适用于插入到 [materialized view](/zh/reference/statements/create/view) 的块。调整此设置后，您可以控制推送到 materialized view 时的块合并，从而避免过高的内存使用量。
可能的值：
* 任意正整数。
* 0 — 禁用块合并。
**另请参见**
* [min\_insert\_block\_size\_rows](#min_insert_block_size_rows)
## min\_joined\_block\_size\_bytes
JOIN 输入块和输出块的最小块大小 (以字节为单位) (如果 JOIN 算法支持) 。较小的块会被合并。0 表示不受限制。
## min\_joined\_block\_size\_rows
JOIN 输入块和输出块的最小行数 (如果 JOIN 算法支持) 。较小的块会被合并为更大的块。0 表示不受限制。
## min\_os\_cpu\_wait\_time\_ratio\_to\_throw
将 OS CPU 等待时间 (`OSCPUWaitMicroseconds` 指标) 与忙碌时间 (`OSCPUVirtualTimeMicroseconds` 指标) 之间的最小比率，作为考虑拒绝查询的阈值。系统会使用最小比率与最大比率之间的线性插值来计算概率，在该点处概率为 0。
## min\_outstreams\_per\_resize\_after\_split
指定在管道生成过程中执行 split 后，`Resize` 或 `StrictResize` 处理器的最小输出流数量。如果最终得到的流数量小于该值，则不会进行 split 操作。
### 什么是 Resize 节点
`Resize` 节点是查询管道中的一种处理器，用于调整管道中数据流的数量。它既可以增加，也可以减少流的数量，以便在多个线程或处理器之间平衡工作负载。例如，如果某个查询需要更高的并行度，`Resize` 节点可以将单个流拆分为多个流。反过来，它也可以将多个流合并为更少的流，以集中处理数据。
`Resize` 节点可确保数据在各个流之间均匀分布，同时保持数据块的结构。这有助于优化资源利用率并提升查询性能。
### 为什么需要拆分 Resize 节点
在管道执行过程中，作为中心枢纽的 `Resize` 节点，其 ExecutingGraph::Node::status\_mutex 会发生严重争用，尤其是在高核心数环境下。这种争用会导致：
1. ExecutingGraph::updateNode 的延迟增加，直接影响查询性能。
2. 大量 CPU 周期浪费在自旋锁争用 (native\_queued\_spin\_lock\_slowpath) 上，导致效率下降。
3. CPU 利用率降低，从而限制并行度和吞吐量。
### Resize 节点如何拆分
1. 首先会检查输出流的数量，以确保可以执行拆分：拆分后每个处理器的输出流数量都达到或超过 `min_outstreams_per_resize_after_split` 阈值。
2. `Resize` 节点会被拆分为多个更小的 `Resize` 节点，这些节点的端口数量相同，每个节点分别处理一部分输入流和输出流。
3. 每个组都会独立处理，从而减少锁竞争。
### 具有任意输入/输出的 Resize 节点拆分
在某些情况下，如果输入/输出无法被拆分后的 `Resize` 节点数量整除，部分输入会连接到 `NullSource`，部分输出会连接到 `NullSink`。这样就能在不影响整体数据流的情况下完成拆分。
### 设置的作用
`min_outstreams_per_resize_after_split` 设置可确保对 `Resize` 节点的拆分确有意义，并避免创建过少的流，否则可能导致并行处理效率低下。通过强制规定最少输出流数量，该设置有助于在并行度与开销之间保持平衡，从而在涉及流拆分与合并的场景中优化查询执行。
### 禁用此设置
要禁用 `Resize` 节点的拆分，请将此设置设为 0。这样可防止在生成管道时拆分 `Resize` 节点，使其保持原有结构，而不会再被拆分为更小的节点。
## min\_table\_rows\_to\_use\_projection\_index
如果估算从表中读取的行数大于或等于此阈值，ClickHouse 会在查询执行时尝试使用投影索引。
## mongodb\_throw\_on\_unsupported\_query
如果启用，当无法构建 MongoDB 查询时，MongoDB 表会返回错误。否则，ClickHouse 会读取整个表并在本地处理。`allow_experimental_analyzer=0` 时，此选项不适用。
## move\_all\_conditions\_to\_prewhere
将 WHERE 中所有适用的条件移到 PREWHERE
## move\_primary\_key\_columns\_to\_end\_of\_prewhere
将包含主键列的 PREWHERE 条件移至 AND 事件链的末尾。这些条件很可能会在主键分析阶段就被考虑到，因此对 PREWHERE 过滤的额外作用不大。
## multiple\_joins\_try\_to\_keep\_original\_names
在多个 JOIN 重写时，不要向顶层表达式列表添加别名
## mutations\_execute\_nondeterministic\_on\_initiator
如果为 true，常量非确定性函数 (例如 `now()` 函数) 会在 initiator 上执行，并在 `UPDATE` 和 `DELETE` 查询中替换为字面量。这有助于在使用常量非确定性函数执行变更时，保持各副本上的数据同步。默认值：`false`。
## mutations\_execute\_subqueries\_on\_initiator
如果为 true，则在发起节点上执行标量子查询，并在 `UPDATE` 和 `DELETE` 查询中将其替换为字面量。默认值：`false`。
## mutations\_max\_literal\_size\_to\_replace
在 `UPDATE` 和 `DELETE` 查询中可用于替换的序列化字面量的最大大小 (以字节为单位) 。仅当上述两个设置中至少有一个启用时，此设置才会生效。默认值：16384 (16 KiB) 。
## mutations\_sync
允许同步执行 `ALTER TABLE ... UPDATE|DELETE|MATERIALIZE INDEX|MATERIALIZE PROJECTION|MATERIALIZE COLUMN|MATERIALIZE STATISTICS` 查询 ([变更](/zh/reference/statements/alter/index#mutations)) 。
可能的值：
| 值 | 描述 |
| --- | --------------------------------------------------------------------------------------- |
| `0` | 变更将异步执行。 |
| `1` | 查询会等待当前服务器上的所有变更完成。 |
| `2` | 查询会等待所有副本 (如果存在) 上的全部变更完成。 |
| `3` | 查询仅等待活跃副本。仅 `SharedMergeTree` 支持。对于 `ReplicatedMergeTree`，其行为与 `mutations_sync = 2` 相同。 |
## mysql\_datatypes\_support\_level
定义 MySQL 类型如何转换为对应的 ClickHouse 类型。其值为一个逗号分隔列表，可由 `decimal`、`datetime64`、`date2Date32` 或 `date2String` 任意组合而成。默认启用所有现代映射 (`decimal`、`datetime64`、`date2Date32`) 。
* `decimal`：在精度允许的情况下，将 `NUMERIC` 和 `DECIMAL` 类型转换为 `Decimal`。
* `datetime64`：当精度不为 `0` 时，将 `DATETIME` 和 `TIMESTAMP` 类型转换为 `DateTime64`，而不是 `DateTime`。
* `date2Date32`：将 `DATE` 转换为 `Date32`，而不是 `Date`。其优先级高于 `date2String`。
* `date2String`：将 `DATE` 转换为 `String`，而不是 `Date`。会被 `datetime64` 覆盖。
## mysql\_map\_fixed\_string\_to\_text\_in\_show\_columns
启用后，ClickHouse 的 [FixedString](/zh/reference/data-types/fixedstring) 数据类型会在 [SHOW COLUMNS](/zh/reference/statements/show#show_columns) 中显示为 `TEXT`。
仅在通过 MySQL wire 协议建立连接时生效。
* 0 - 使用 `BLOB`。
* 1 - 使用 `TEXT`。
## mysql\_map\_string\_to\_text\_in\_show\_columns
启用后，[String](/zh/reference/data-types/string) ClickHouse 数据类型会在 [SHOW COLUMNS](/zh/reference/statements/show#show_columns) 中显示为 `TEXT`。
仅在通过 MySQL wire 协议建立连接时生效。
* 0 - 使用 `BLOB`。
* 1 - 使用 `TEXT`。
## mysql\_max\_rows\_to\_insert
MySQL 存储引擎执行 MySQL 批量插入时的最大行数
## network\_compression\_method
用于压缩客户端/服务器以及服务器/服务器通信的编解码器。
可能的值：
* `NONE` — 不压缩。
* `LZ4` — 使用 LZ4 编解码器。
* `LZ4HC` — 使用 LZ4HC 编解码器。
* `ZSTD` — 使用 ZSTD 编解码器。
**另请参阅**
* [network\_zstd\_compression\_level](#network_zstd_compression_level)
## network\_zstd\_compression\_level
用于调整 ZSTD 压缩级别。仅在 [network\_compression\_method](#network_compression_method) 设置为 `ZSTD` 时生效。
可能的值：
* 1 到 15 的正整数。
## normalize\_function\_names
将函数名规范化为其标准名称
## number\_of\_mutations\_to\_delay
如果该表中至少有这么多尚未完成的变更操作，则人为降低该表变更操作的速度。0 - 禁用
## number\_of\_mutations\_to\_throw
如果表中至少包含这么多个尚未完成的变更，则抛出 'Too many mutations ...' 异常。0 - 禁用
## odbc\_bridge\_connection\_pool\_size
ODBC bridge 中每个连接设置字符串对应的连接池大小。
## odbc\_bridge\_use\_connection\_pooling
在 ODBC bridge 中启用连接池。如果设置为 false，则每次都会创建一个新连接。
## offset
设置在查询开始返回行之前要跳过的行数。它会调整由 [OFFSET](/zh/reference/statements/select/offset) 子句设置的偏移量，因此这两个值会相加。
可能的值：
* 0 — 不跳过任何行。
* 正整数。
**示例**
输入表：
```sql theme={null}
CREATE TABLE test (i UInt64) ENGINE = MergeTree() ORDER BY i;
INSERT INTO test SELECT number FROM numbers(500);
```
查询：
```sql theme={null}
SET limit = 5;
SET offset = 7;
SELECT * FROM test LIMIT 10 OFFSET 100;
```
结果：
```text theme={null}
┌───i─┐
│ 107 │
│ 108 │
│ 109 │
└─────┘
```
## opentelemetry\_start\_keeper\_trace\_probability
为 ZooKeeper 请求启动 trace 的概率，无论是否存在父 trace。
可能的值：
* 'auto' - 等同于 `opentelemetry_start_trace_probability` 设置
* 0 — 禁用追踪
* 0 到 1 — 概率 (例如，1.0 = 始终启用)
## opentelemetry\_start\_trace\_probability
设置 ClickHouse 为已执行的查询启动 trace 的概率 (如果未提供父 [trace context](https://www.w3.org/TR/trace-context/)) 。
可能的值：
* 0 — 禁用所有已执行查询的 trace (如果未提供父 trace context) 。
* 范围为 \[0..1] 的正浮点数。例如，如果该设置值为 `0,5`，则 ClickHouse 平均会为一半的查询启动 trace。
* 1 — 启用所有已执行查询的 trace。
## opentelemetry\_trace\_cpu\_scheduling
收集工作负载抢占式 CPU 调度的 OpenTelemetry span。
## opentelemetry\_trace\_processors
收集处理器的 OpenTelemetry span。
## optimize\_aggregation\_in\_order
在 [MergeTree](/zh/reference/engines/table-engines/mergetree-family/mergetree) 表中，启用对按相应顺序聚合数据的 [SELECT](/zh/reference/statements/select/index) 查询进行 [GROUP BY](/zh/reference/statements/select/group-by) 优化。
可能的值：
* 0 — `GROUP BY` 优化已禁用。
* 1 — `GROUP BY` 优化已启用。
**另请参阅**
* [GROUP BY 优化](/zh/reference/statements/select/group-by#group-by-optimization-depending-on-table-sorting-key)
## optimize\_aggregators\_of\_group\_by\_keys
消除 SELECT 子句中 GROUP BY 键上的 min/max/any/anyLast 聚合器
## optimize\_and\_compare\_chain
在 AND 链中补全与常量的比较条件，以增强过滤能力。支持运算符 `<`、`<=`、`>`、`>=`、`=` 及其混合使用。例如，`(a < b) AND (b < c) AND (c < 5)` 将变为 `(a < b) AND (b < c) AND (c < 5) AND (b < 5) AND (a < 5)`。
## optimize\_append\_index
使用[约束](/zh/reference/statements/create/table#constraints)来附加索引条件。默认值为 `false`。
可能的值：
* true, false
## optimize\_arithmetic\_operations\_in\_aggregate\_functions
将算术运算从聚合函数中移出
## optimize\_const\_name\_size
替换为标量，并将哈希用作大型常量的名称 (大小按名称长度估算) 。
可能的值：
* 正整数 - 名称的最大长度，
* 0 — 始终，
* 负整数 - 从不。
## optimize\_count\_from\_files
启用或禁用从不同输入格式的文件中统计行数的优化功能。该设置适用于表函数/引擎 `file`/`s3`/`url`/`hdfs`/`azureBlobStorage`。
可能的值：
* 0 — 禁用该优化。
* 1 — 启用该优化。
## optimize\_dictget\_tuple\_element
将 `tupleElement(dictGet('dict', ('a', 'b', 'c'), key), 2)` 重写为 `dictGet('dict', 'b', key)`，以避免拉取不必要的字典属性。支持按位置 (`.1`、`.2`、...) 和按名称 (`.b`) 访问；也适用于 `dictGetOrDefault`，前提是默认参数为常量 Tuple，或由常量组成的 `tuple(...)`。
## optimize\_distinct\_in\_order
如果 DISTINCT 中的某些列构成排序前缀，则启用 DISTINCT 优化。例如，MergeTree 中排序键的前缀，或 ORDER BY 语句中的前缀。
## optimize\_distributed\_group\_by\_sharding\_key
通过避免在发起端服务器上执行高开销的聚合，来优化 `GROUP BY sharding_key` 查询 (这会减少该查询在发起端服务器上的内存使用量) 。
支持以下类型的查询 (以及它们的任意组合) ：
* `SELECT DISTINCT [..., ]sharding_key[, ...] FROM dist`
* `SELECT ... FROM dist GROUP BY sharding_key[, ...]`
* `SELECT ... FROM dist GROUP BY sharding_key[, ...] ORDER BY x`
* `SELECT ... FROM dist GROUP BY sharding_key[, ...] LIMIT 1`
* `SELECT ... FROM dist GROUP BY sharding_key[, ...] LIMIT 1 BY x`
不支持以下类型的查询 (其中部分查询后续可能会增加支持) ：
* `SELECT ... GROUP BY sharding_key[, ...] WITH TOTALS`
* `SELECT ... GROUP BY sharding_key[, ...] WITH ROLLUP`
* `SELECT ... GROUP BY sharding_key[, ...] WITH CUBE`
* `SELECT ... GROUP BY sharding_key[, ...] SETTINGS extremes=1`
可能的值：
* 0 — 已禁用。
* 1 — 已启用。
另请参见：
* [distributed\_group\_by\_no\_merge](#distributed_group_by_no_merge)
* [distributed\_push\_down\_limit](#distributed_push_down_limit)
* [optimize\_skip\_unused\_shards](#optimize_skip_unused_shards)
目前它要求启用 `optimize_skip_unused_shards` (这是因为将来它可能会默认启用，而只有在数据通过 Distributed 表插入，即数据按照 `sharding_key` 分布时，它才能正确工作) 。
## optimize\_dry\_run\_check\_part
启用后，`OPTIMIZE ... DRY RUN` 会使用 `checkDataPart` 验证生成的合并后分片。如果检查失败，则会抛出异常。
## optimize\_empty\_string\_comparisons
将 `col = ''` 或 `'' = col` 之类的表达式转换为 `empty(col)`，并将 `col != ''` 或 `'' != col` 转换为 `notEmpty(col)`，
仅在 `col` 为 String 或 FixedString 类型时执行此转换。
允许从 WHERE、PREWHERE、ON、HAVING 和 QUALIFY 表达式的析取中提取公共表达式。像 `(A AND B) OR (A AND C)` 这样的逻辑表达式可以改写为 `A AND (B OR C)`，这可能有助于利用：
* 简单过滤表达式中的索引
* cross join 到 inner join 的优化
## optimize\_functions\_to\_subcolumns
启用或禁用一项优化：将某些函数转换为读取子列，从而减少需要读取的数据量。
这些函数可被转换：
* [length](/zh/reference/functions/regular-functions/array-functions#length) 转换为读取 [size0](/zh/reference/data-types/array#array-size) 子列。
* [empty](/zh/reference/functions/regular-functions/array-functions#empty) 转换为读取 [size0](/zh/reference/data-types/array#array-size) 子列。
* [notEmpty](/zh/reference/functions/regular-functions/array-functions#notEmpty) 转换为读取 [size0](/zh/reference/data-types/array#array-size) 子列。
* [isNull](/zh/reference/functions/regular-functions/functions-for-nulls#isNull) 转换为读取 [null](/zh/reference/data-types/nullable#finding-null) 子列。
* [isNotNull](/zh/reference/functions/regular-functions/functions-for-nulls#isNotNull) 转换为读取 [null](/zh/reference/data-types/nullable#finding-null) 子列。
* [count](/zh/reference/functions/aggregate-functions/count) 转换为读取 [null](/zh/reference/data-types/nullable#finding-null) 子列。
* [mapKeys](/zh/reference/functions/regular-functions/tuple-map-functions#mapKeys) 转换为读取 [keys](/zh/reference/data-types/map#reading-subcolumns-of-map) 子列。
* [mapValues](/zh/reference/functions/regular-functions/tuple-map-functions#mapValues) 转换为读取 [values](/zh/reference/data-types/map#reading-subcolumns-of-map) 子列。
可选值：
* 0 — 禁用优化。
* 1 — 启用优化。
## optimize\_group\_by\_constant\_keys
当块中的所有键均为常量时，优化 GROUP BY
## optimize\_group\_by\_function\_keys
消除 GROUP BY 子句中其他键上的函数
## optimize\_if\_chain\_to\_multiif
将 if(cond1, then1, if(cond2, ...)) 事件链替换为 multiIf。目前这对数值类型没有明显收益。
## optimize\_if\_transform\_strings\_to\_enum
将 If 和 Transform 中的 String 类型参数替换为枚举。默认处于禁用状态，因为这可能导致分布式查询中出现不一致的更改，从而使查询失败。
## optimize\_injective\_functions\_in\_group\_by
将 GROUP BY 子句中的单射函数替换为其参数
## optimize\_injective\_functions\_in\_limit\_by
将 LIMIT BY 中的单射函数替换为其参数。
示例：`LIMIT 5 BY toString(x)` 会变为 `LIMIT 5 BY x`。
## optimize\_injective\_functions\_inside\_uniq
移除 uniq\*() 函数中单参数的单射函数。
## optimize\_inverse\_dictionary\_lookup
通过更快地查找预先计算好的一组可能键值，避免重复进行反向字典查找。
## optimize\_limit\_by\_function\_keys
消除 LIMIT BY 子句中那些可由其他键确定的函数项。
示例：`LIMIT 5 BY x, f(x)` 变为 `LIMIT 5 BY x`。
## optimize\_limit\_by\_in\_order
当 `` (顺序不限) 构成表排序键的前缀，或者在通过 `WHERE col = const` 固定前导列后构成此前缀时，可优化 `SELECT ... LIMIT N BY ` 查询。启用后，数据源会按主键顺序读取数据，因此 `BY` 列取值相同的行会在每个流内相邻到达。当数据以单个已排序流到达时，`LIMIT BY` 会以流式方式对其进行过滤，只需 O(1) 内存，而无需为已见到的每种不同 `BY` 列组合都构建哈希表。当已排序数据通过多个流到达，且相同的 `BY` 值可能出现在多个流中时，系统会先以流式方式对每个流进行预过滤，将每组最多保留 `LIMIT + OFFSET` 行，然后再合并这些流，并通过最终基于哈希的 `LIMIT BY` 对跨多个流的组进行去重。最终这一步仍会为 `BY` 列的每种不同组合保留一个条目，但只处理预过滤后的行。
## optimize\_min\_equality\_disjunction\_chain\_length
触发对表达式 `expr = x1 OR ... expr = xN` 进行优化的最小长度
## optimize\_min\_inequality\_conjunction\_chain\_length
可进行优化的表达式 `expr <> x1 AND ... expr <> xN` 的最小长度
## optimize\_move\_to\_prewhere
启用或禁用 [SELECT](/zh/reference/statements/select/index) 查询中的自动 [PREWHERE](/zh/reference/statements/select/prewhere) 优化。
仅对 [\*MergeTree](/zh/reference/engines/table-engines/mergetree-family/index) 表生效。
可能的值：
* 0 — 禁用自动 `PREWHERE` 优化。
* 1 — 启用自动 `PREWHERE` 优化。
## optimize\_move\_to\_prewhere\_if\_final
启用或禁用在带有 [FINAL](/zh/reference/statements/select/from#final-modifier) 修饰符的 [SELECT](/zh/reference/statements/select/index) 查询中自动应用 [PREWHERE](/zh/reference/statements/select/prewhere) 优化。
仅对 [\*MergeTree](/zh/reference/engines/table-engines/mergetree-family/index) 表生效。
Possible values:
* 0 — 在带有 `FINAL` 修饰符的 `SELECT` 查询中，自动 `PREWHERE` 优化已禁用。
* 1 — 在带有 `FINAL` 修饰符的 `SELECT` 查询中，自动 `PREWHERE` 优化已启用。
**See Also**
* [optimize\_move\_to\_prewhere](#optimize_move_to_prewhere) 设置
## optimize\_multiif\_to\_if
将仅有一个条件的 `multiIf` 替换为 `if`。
## optimize\_normalize\_count\_variants
将语义上等价于 count() 的聚合函数重写为 count()。
## optimize\_on\_insert
启用或禁用在插入前对数据进行转换，效果如同已根据表引擎对该块执行了 merge。
可能的值：
* 0 — 禁用。
* 1 — 启用。
**示例**
启用与禁用时的区别：
查询：
```sql theme={null}
SET optimize_on_insert = 1;
CREATE TABLE test1 (`FirstTable` UInt32) ENGINE = ReplacingMergeTree ORDER BY FirstTable;
INSERT INTO test1 SELECT number % 2 FROM numbers(5);
SELECT * FROM test1;
SET optimize_on_insert = 0;
CREATE TABLE test2 (`SecondTable` UInt32) ENGINE = ReplacingMergeTree ORDER BY SecondTable;
INSERT INTO test2 SELECT number % 2 FROM numbers(5);
SELECT * FROM test2;
```
结果：
```text theme={null}
┌─FirstTable─┐
│ 0 │
│ 1 │
└────────────┘
┌─SecondTable─┐
│ 0 │
│ 0 │
│ 0 │
│ 1 │
│ 1 │
└─────────────┘
```
请注意，此设置会影响 [materialized view](/zh/reference/statements/create/view#materialized-view) 的行为。
## optimize\_or\_like\_chain
将多个 OR LIKE 条件优化为 multiMatchAny。默认不应启用此优化，因为在某些情况下它会干扰索引分析。
## optimize\_prewhere\_after\_pushdown
在后续查询计划优化之后，再执行一轮 `PREWHERE` 提升，因为这些优化可能会
在 `MergeTree` 读取步骤之上新增过滤器 (例如通过
`JOIN` 的谓词下推、投影重写) 。如果已存在 `PREWHERE`，新的
过滤器会通过 `AND` 合并到其中，而不是作为单独的过滤步骤保留。
## optimize\_qbit\_distance\_function\_reads
将 `QBit` 数据类型上的距离函数替换为等效函数，使其仅从存储中读取计算所需的列。
## optimize\_read\_in\_order
在 [SELECT](/zh/reference/statements/select/index) 查询中启用 [ORDER BY](/zh/reference/statements/select/order-by#optimization-of-data-reading) 优化，以优化从 [MergeTree](/zh/reference/engines/table-engines/mergetree-family/mergetree) 表读取数据的方式。
可能的值：
* 0 — 禁用 `ORDER BY` 优化。
* 1 — 启用 `ORDER BY` 优化。
**另请参见**
* [ORDER BY 子句](/zh/reference/statements/select/order-by#optimization-of-data-reading)
## optimize\_redundant\_functions\_in\_order\_by
如果函数的参数也在 ORDER BY 中，则将该函数从 ORDER BY 中移除
## optimize\_respect\_aliases
如果设置为 true，则会在 WHERE/GROUP BY/ORDER BY 中遵循别名，这有助于分区裁剪、次级索引、optimize\_aggregation\_in\_order、optimize\_read\_in\_order 和 optimize\_trivial\_count
## optimize\_rewrite\_aggregate\_function\_with\_if
当逻辑上等价时，将参数为 `if` 表达式的 aggregate functions 进行重写。
例如，`avg(if(cond, col, null))` 可以重写为 `avgOrNullIf(cond, col)`。这可能会提升性能。
仅在启用 analyzer (`enable_analyzer = 1`) 时支持。
## optimize\_rewrite\_array\_exists\_to\_has
当逻辑上等价时，将 arrayExists() 函数重写为 has()。例如，arrayExists(x -> x = 1, arr) 可以重写为 has(arr, 1)
## optimize\_rewrite\_has\_to\_in
当第一个参数为常量数组时，将 `has` 函数重写为 `IN`。例如，`has([1, 2, 3], x)` 可以重写为 `x IN [1, 2, 3]`，这样在处理常量数组时性能更好
## optimize\_rewrite\_like\_perfect\_affix
将具有完整前缀或后缀的 LIKE 表达式 (例如 `col LIKE 'ClickHouse%'`) 重写为 startsWith 或 endsWith 函数 (例如 `startsWith(col, 'ClickHouse')`) 。
## optimize\_rewrite\_regexp\_functions
将正则表达式相关函数重写为更简单且更高效的形式
## optimize\_rewrite\_sum\_if\_to\_count\_if
当在逻辑上等价时，将 sumIf() 和 sum(if()) 函数重写为 countIf() 函数
## optimize\_skip\_merged\_partitions
如果只有一个 level > 0 的 part，且其生存时间 (TTL) 尚未过期，则控制是否对 [OPTIMIZE TABLE ... FINAL](/zh/reference/statements/optimize) 查询启用优化。
* `OPTIMIZE TABLE ... FINAL SETTINGS optimize_skip_merged_partitions=1`
默认情况下，即使只有一个 part，`OPTIMIZE TABLE ... FINAL` 查询也会重写该 part。
可能的值：
* 1 - 启用优化。
* 0 - 禁用优化。
## optimize\_skip\_unused\_shards
为在 `WHERE/PREWHERE` 中包含分片键条件的 [SELECT](/zh/reference/statements/select/index) 查询启用或禁用跳过未使用分片，并启用分布式查询的相关优化 (例如按分片键进行聚合) 。
前提是数据按分片键进行分布，否则查询结果会不正确。
可能的值：
* 0 — 禁用。
* 1 — 启用。
## optimize\_skip\_unused\_shards\_limit
限制分片键值的数量；达到该限制时，将关闭 `optimize_skip_unused_shards`。
值过多可能需要消耗大量资源进行处理，而实际收益未必明显，因为如果 `IN (...)` 中包含大量值，查询很可能最终仍会发送到所有分片。
## optimize\_skip\_unused\_shards\_nesting
控制 [`optimize_skip_unused_shards`](#optimize_skip_unused_shards) 的生效嵌套层级 (因此仍需启用 [`optimize_skip_unused_shards`](#optimize_skip_unused_shards)) 。这适用于分布式查询存在嵌套的情况 (例如，一个 `Distributed` 表查询另一个 `Distributed` 表) 。
可能的值：
* 0 — 禁用，`optimize_skip_unused_shards` 始终生效。
* 1 — 仅在第一层启用 `optimize_skip_unused_shards`。
* 2 — 在最多两层内启用 `optimize_skip_unused_shards`。
## optimize\_skip\_unused\_shards\_rewrite\_in
对发往远程分片的查询，重写其中的 IN，以排除不属于该分片的值 (需要 `optimize_skip_unused_shards`) 。
可选值：
* 0 — 已禁用。
* 1 — 已启用。
## optimize\_sorting\_by\_input\_stream\_properties
根据输入流的排序属性优化排序
## optimize\_substitute\_columns
使用[约束](/zh/reference/statements/create/table#constraints)进行列替换。默认值为 `false`。
可能的值：
* true, false
## optimize\_syntax\_fuse\_functions
启用将参数相同的聚合函数进行融合。它会将包含至少两个参数相同的 [sum](/zh/reference/functions/aggregate-functions/sum)、[count](/zh/reference/functions/aggregate-functions/count) 或 [avg](/zh/reference/functions/aggregate-functions/avg) 聚合函数的查询重写为 [sumCount](/zh/reference/functions/aggregate-functions/sumCount)。
Possible values:
* 0 — 参数相同的函数不会融合。
* 1 — 参数相同的函数会融合。
**示例**
查询：
```sql theme={null}
CREATE TABLE fuse_tbl(a Int8, b Int8) Engine = Log;
SET optimize_syntax_fuse_functions = 1;
EXPLAIN SYNTAX run_query_tree_passes = 1 SELECT sum(a), sum(b), count(b), avg(b) from fuse_tbl FORMAT TSV;
```
结果：
```text theme={null}
SELECT
sum(__table1.a) AS `sum(a)`,
tupleElement(sumCount(__table1.b), 1) AS `sum(b)`,
tupleElement(sumCount(__table1.b), 2) AS `count(b)`,
divide(tupleElement(sumCount(__table1.b), 1), toFloat64(tupleElement(sumCount(__table1.b), 2))) AS `avg(b)`
FROM default.fuse_tbl AS __table1
```
## optimize\_throw\_if\_noop
启用或禁用以下行为：如果 [OPTIMIZE](/zh/reference/statements/optimize) 查询未执行 merge，则抛出异常。
默认情况下，即使 `OPTIMIZE` 没有执行任何操作，也会成功返回。通过此设置，您可以区分这些情况，并在异常消息中获取原因。
可能的值：
* 1 — 启用抛出异常。
* 0 — 禁用抛出异常。
## optimize\_time\_filter\_with\_preimage
col >= '2023-01-01' AND col <= '2023-12-31'`）"}]}]} />
通过将函数改写为无需转换的等价比较来优化 Date 和 DateTime 谓词 (例如 `toYear(col) = 2023 -> col >= '2023-01-01' AND col <= '2023-12-31'`)
## optimize\_trivial\_approximate\_count\_query
对于支持此类估算的存储 (例如 EmbeddedRocksDB) ，在简单计数优化中使用近似计数值。
可能的值：
* 0 — 禁用优化。
* 1 — 启用优化。
## optimize\_trivial\_count\_query
启用或禁用基于 MergeTree 元数据对简单查询 `SELECT count() FROM table` 的优化。如果需要使用行级安全，请禁用此设置。
可能的值：
* 0 — 禁用优化。
* 1 — 启用优化。
另请参阅：
* [optimize\_functions\_to\_subcolumns](#optimize_functions_to_subcolumns)
## optimize\_trivial\_group\_by\_limit\_query
通过设置 `max_rows_to_group_by = n + offset` 和 `group_by_overflow_mode = 'any'`，启用或禁用对简单查询 `SELECT key_expr FROM table GROUP BY key_expr LIMIT n` 的优化 (即投影中不包含聚合函数、没有 `HAVING`/`ORDER BY`/`LIMIT BY`/窗口子句，且没有 `GROUP BY` 修饰符) 。生成 `n + offset` 个不同键后，聚合即会停止。
如果用户已显式将 `group_by_overflow_mode` 设为非 `any` 值 (以保留其显式指定的 `throw`/`break` 语义) ，或者用户已设置了更严格的 `max_rows_to_group_by` (此时该优化将成为空操作) ，则不会应用此优化。
可能的值：
* 0 — 禁用优化。
* 1 — 启用优化。
## optimize\_trivial\_insert\_select
对简单的 'INSERT INTO table SELECT ... FROM TABLES' 查询进行优化
## optimize\_truncate\_order\_by\_after\_group\_by\_keys
当 ORDER BY 前缀已覆盖所有 GROUP BY 键时，移除末尾多余的 ORDER BY 元素。
## optimize\_uniq\_to\_count
如果子查询包含 distinct 或 group by 子句，则将 uniq 及其变体 (uniqUpTo 除外) 重写为 count。
## optimize\_use\_implicit\_projections
自动选择隐式投影来执行 SELECT 查询
## optimize\_use\_projection\_filtering
即使未选择使用投影来执行 SELECT 查询，也可利用投影过滤分片范围。
## optimize\_use\_projections
**别名**: `allow_experimental_projection_optimization`
启用或禁用在处理 `SELECT` 查询时的[投影](/zh/reference/engines/table-engines/mergetree-family/mergetree#projections)优化。
可能的值：
* 0 — 投影优化已禁用。
* 1 — 投影优化已启用。
## optimize\_using\_constraints
使用[约束](/zh/reference/statements/create/table#constraints)进行查询优化。默认值是 `false`。
可能的值：
* true, false
## os\_threads\_nice\_value\_materialized\_view
materialized view 线程的 Linux nice 值。值越低，CPU 优先级越高。
需要 CAP\_SYS\_NICE 能力，否则为空操作。
可能的值：-20 到 19。
## os\_threads\_nice\_value\_query
**别名**: `os_thread_priority`
用于查询处理线程的 Linux nice 值。值越低，CPU 优先级越高。
需要具备 CAP\_SYS\_NICE 能力，否则为**空操作**。
可能的值：-20 到 19。
## page\_cache\_block\_size
存储在用户态页缓存中的文件块大小，单位为字节。所有通过缓存的读取都会向上取整到该大小的整数倍。
此设置可以按单个查询进行调整，但块大小不同的缓存条目无法复用。更改此设置实际上会使缓存中现有条目失效。
较大的值 (如 1 MiB) 适合高吞吐查询，较小的值 (如 64 KiB) 适合低延迟点查询。
## page\_cache\_inject\_eviction
用户态页缓存有时会随机使某些页失效。用于测试。
## page\_cache\_lookahead\_blocks
当用户态页缓存未命中时，如果后续连续的块也未命中缓存，则会一次性从底层存储中最多读取这么多个连续块。每个块的大小为 page\_cache\_block\_size 字节。
较高的值适合高吞吐量查询，而低延迟的点查询则在不进行预读时效果更好。
## page\_cache\_max\_coalesced\_bytes
当 `readBigAt` 填充用户态页缓存时，连续的缓存未命中会被合并为一次对底层存储的读取。此设置以字节为单位限制单次合并读取的大小；更长的未命中序列会被拆分为多次读取。它可限制并行冷读期间临时缓冲区的瞬时内存使用量。
较高的值可减少对象存储冷扫描时的 HTTP 请求数；较低的值可降低瞬时内存峰值占用。
## paimon\_target\_snapshot\_id
用于 Paimon 增量模式的查询级定向快照读取。当 >0 时，读取器仅会拉取
指定 snapshot\_id 的增量，而不会推进已提交的水位线。
默认值：-1 (禁用)
## parallel\_distributed\_insert\_select
启用并行分布式 `INSERT ... SELECT` 查询。
如果执行 `INSERT INTO distributed_table_a SELECT ... FROM distributed_table_b` 查询，且两个表使用同一个集群，并且两个表要么都是[复制表](/zh/reference/engines/table-engines/mergetree-family/replication)，要么都是非复制表，则该查询会在每个分片上本地执行。
可选值：
* `0` — 禁用。
* `1` — `SELECT` 将在每个分片上针对分布式引擎的底层表执行。
* `2` — `SELECT` 和 `INSERT` 将在每个分片上分别针对分布式引擎的底层表执行读写。
从 v25.4 起，源表为 `ReplicatedMergeTree` 或 `SharedMergeTree` 的 `INSERT ... SELECT` 也可以在副本间并行执行。要启用此功能：
* `parallel_distributed_insert_select = 2`
* `enable_parallel_replicas = 1`
## parallel\_hash\_join\_threshold
当使用基于哈希的 JOIN 算法时，此阈值可帮助决定使用 `hash` 还是 `parallel_hash` (仅在能够估算右侧表大小时) 。
如果已知右侧表的大小低于该阈值，则使用前者。
## parallel\_non\_joined\_rows\_processing
允许多个线程在 RIGHT 和 FULL JOIN 期间并行处理右表中未 JOIN 的行。
使用 `parallel_hash` join algorithm 处理大表时，这可以加快未 JOIN 阶段的处理速度。
禁用后，未 JOIN 的行将由单个线程处理。
## parallel\_replica\_offset
这是一个内部设置，不应直接使用，表示“并行副本”模式的实现细节。对于分布式查询，此设置会由发起端服务器自动设为在并行副本中参与查询处理的副本索引。
## parallel\_replicas\_allow\_in\_with\_subquery
如果为 true，IN 的子查询会在每个 follower 副本上执行。
## parallel\_replicas\_allow\_materialized\_views
允许并行副本使用 materialized views
## parallel\_replicas\_allow\_view\_over\_mergetree
允许并行副本对基于 `MergeTree` 表的简单视图执行外层查询 (而非视图的内层查询) ，从而提升跨节点并行执行的效果。此设置也适用于 `UNION ALL` 视图，前提是其所有分支都从不同的 `MergeTree` 表读取。
## parallel\_replicas\_connect\_timeout\_ms
使用并行副本执行查询时，连接远程副本的超时时间，单位为毫秒。如果超时，则不会使用相应的副本执行查询
## parallel\_replicas\_count
这是一个内部设置，不应直接使用，属于“并行副本”模式的实现细节。对于分布式查询，发起服务器会自动将此设置设为参与查询处理的并行副本数。
## parallel\_replicas\_custom\_key
一个任意的整数表达式，可用于在特定表的各个副本之间拆分工作。
其值可以是任何整数表达式。
建议优先使用基于主键的简单表达式。
如果该设置用于由单个分片和多个副本组成的集群，这些副本将被转换为虚拟分片。
否则，其行为与 `SAMPLE` 键相同，即会使用每个分片的多个副本。
## parallel\_replicas\_custom\_key\_range\_lower
允许 `range` 类型的过滤器基于自定义范围 `[parallel_replicas_custom_key_range_lower, INT_MAX]`，在各副本之间均匀分配工作。
与 [parallel\_replicas\_custom\_key\_range\_upper](#parallel_replicas_custom_key_range_upper) 结合使用时，该过滤器可针对范围 `[parallel_replicas_custom_key_range_lower, parallel_replicas_custom_key_range_upper]` 在各副本之间均匀分配工作。
注意：此设置不会在查询处理期间额外过滤任何数据，而是会改变范围过滤器为并行处理拆分范围 `[0, INT_MAX]` 时的分割点。
## parallel\_replicas\_custom\_key\_range\_upper
允许 `range` 类型的过滤器基于自定义范围 `[0, parallel_replicas_custom_key_range_upper]`，在各个副本之间均匀分配工作。值为 0 时会禁用上界，并将其设为自定义键表达式的最大值。
与 [parallel\_replicas\_custom\_key\_range\_lower](#parallel_replicas_custom_key_range_lower) 结合使用时，它可让过滤器在范围 `[parallel_replicas_custom_key_range_lower, parallel_replicas_custom_key_range_upper]` 内将工作均匀分配到各个副本。
注意：此设置不会在查询处理期间额外过滤任何数据，而只会改变范围过滤器为并行处理拆分 `[0, INT_MAX]` 范围时的分界点
## parallel\_replicas\_filter\_pushdown
允许将过滤器下推到由并行副本选择执行的那部分查询
## parallel\_replicas\_for\_cluster\_engines
将表函数引擎替换为对应的 -Cluster 版本
## parallel\_replicas\_for\_non\_replicated\_merge\_tree
如果为 true，ClickHouse 也会对非复制的 MergeTree 表使用并行副本算法
## parallel\_replicas\_index\_analysis\_only\_on\_coordinator
仅在副本协调器上执行索引分析，跳过其他副本。仅在启用 parallel\_replicas\_local\_pla 时生效
## parallel\_replicas\_insert\_select\_local\_pipeline
在启用并行副本的分布式 INSERT SELECT 中使用本地管道
## parallel\_replicas\_local\_plan
为本地副本构建本地执行计划
## parallel\_replicas\_mark\_segment\_size
parts 会在逻辑上划分为多个分段，以便在并行读取时分配给各个副本。此设置控制这些分段的大小。除非你完全确定自己在做什么，否则不建议更改。值应在 \[128; 16384] 范围内
## parallel\_replicas\_min\_number\_of\_rows\_per\_replica
将查询中使用的副本数量限制为 (预估待读取行数 / 每个副本的最小行数) 。最大值仍然受 'max\_parallel\_replicas' 限制。
## parallel\_replicas\_mode
用于并行副本中自定义键的过滤器类型。default - 对自定义键使用取模运算；range - 使用自定义键值类型的所有可能值，对自定义键应用范围过滤器。
## parallel\_replicas\_only\_with\_analyzer
必须启用 analyzer 才能使用并行副本。若未启用 analyzer，即使已启用从副本并行读取，查询执行也会回退到本地执行。不支持在未启用 analyzer 的情况下使用并行副本。
## parallel\_replicas\_prefer\_local\_join
如果为 true，且 JOIN 可使用并行副本算法执行，并且 JOIN 右侧部分的所有存储均为 \*MergeTree，则将使用本地 JOIN 而非 GLOBAL JOIN。
## parallel\_replicas\_prefer\_local\_replica
启用时 (默认) ，本地副本始终会包含在用于并行读取的副本集合中。
禁用时，本地副本不会被优先考虑，副本将完全由负载均衡算法选择。
这样一来，带有 `max_parallel_replicas = 1` 的查询就可以被路由到其他主机；当大量短查询分布在集群中时，这有助于提升缓存局部性。
## parallel\_replicas\_support\_projection
投影优化可在并行副本中应用。仅在启用 parallel\_replicas\_local\_plan 且 aggregation\_in\_order 未启用时生效。
## parallel\_view\_processing
启用并发推送到已附加视图，而不是按顺序推送。
## parallelize\_output\_from\_storages
对存储读取步骤的输出进行并行化。如果条件允许，可在从存储读取后立即并行执行查询处理。
## parsedatetime\_e\_requires\_space\_padding
函数 `parseDateTime` 中的格式说明符 '%e' 要求个位数的日期以空格补齐，例如可接受 ' 2'，而 '2' 会报错。
## parsedatetime\_parse\_without\_leading\_zeros
函数 `parseDateTime` 中的格式说明符 `%c`、`%l` 和 `%k` 可解析不带前导零的月份和小时。
## partial\_merge\_join\_left\_table\_buffer\_bytes
如果不为 0，则会将 partial merge join 左侧表中的块合并成更大的块。每个连接线程最多会使用指定内存的 2 倍。
## partial\_merge\_join\_rows\_in\_right\_blocks
限制 [JOIN](/zh/reference/statements/select/join) 查询中 partial merge join 算法右侧 join 数据块的大小。
ClickHouse server：
1. 将右侧 join 数据拆分为多个块，每个块最多包含指定数量的行。
2. 使用每个块的最小值和最大值为其建立索引。
3. 如果可能，将已准备好的块卸载到磁盘。
可能的值：
* 任意正整数。建议取值范围：\[1000, 100000]。
## partial\_result\_on\_first\_cancel
允许查询在取消后返回部分结果。
## parts\_to\_delay\_insert
如果目标表在单个分区中至少包含这么多活跃的 parts，则会人为降低向该表 insert 的速度。
## parts\_to\_throw\_insert
如果目标表中某个分区的活动 parts 数量超过此值，则抛出“parts 过多 ...”异常。
## per\_part\_index\_stats
按分片记录日志索引统计信息
## poll\_interval
在服务器端的查询等待循环中阻塞指定的秒数。
## polyglot\_dialect
polyglot transpiler 的源 SQL 方言 (例如 'sqlite'、'mysql'、'postgresql'、'snowflake'、'duckdb') 。
## postgresql\_connection\_attempt\_timeout
单次连接 PostgreSQL 端点的连接超时时间 (以秒为单位) 。
该值会作为连接 URL 的 `connect_timeout` 参数传递。
## postgresql\_connection\_pool\_auto\_close\_connection
在将连接放回连接池之前关闭该连接。
## postgresql\_connection\_pool\_retries
用于 PostgreSQL 表引擎和数据库引擎的连接池 push/pop 重试次数。
## postgresql\_connection\_pool\_size
PostgreSQL 表引擎和数据库引擎的连接池大小。
## postgresql\_connection\_pool\_wait\_timeout
PostgreSQL 表引擎和数据库引擎在连接池为空时，执行连接池 push/pop 操作的超时时间。默认情况下，连接池为空时会阻塞等待。
## postgresql\_fault\_injection\_probability
内部 (用于复制) 的 PostgreSQL 查询发生失败的近似概率。有效值范围为 \[0.0f, 1.0f]
## predicate\_statistics\_sample\_rate
将谓词选择性统计数据收集到 `system.predicate_statistics_log` 中。设置为 N > 0 时，约有 1/N 的查询 (按查询 ID) 会被采样。0 表示禁用。
## prefer\_column\_name\_to\_alias
启用或禁用在查询表达式和子句中使用原始列名而非别名。尤其是在别名与列名相同的情况下，这一点非常重要，参见 [表达式别名](/zh/reference/syntax#notes-on-usage)。启用此设置后，ClickHouse 中别名的语法规则将更兼容大多数其他数据库引擎。
可能的值：
* 0 — 列名会被替换为别名。
* 1 — 列名不会被替换为别名。
**示例**
启用和禁用时的区别：
查询：
```sql theme={null}
SET prefer_column_name_to_alias = 0;
SELECT avg(number) AS number, max(number) FROM numbers(10);
```
结果：
```text theme={null}
Received exception from server (version 21.5.1):
Code: 184. DB::Exception: Received from localhost:9000. DB::Exception: Aggregate function avg(number) is found inside another aggregate function in query: While processing avg(number) AS number.
```
查询：
```sql theme={null}
SET prefer_column_name_to_alias = 1;
SELECT avg(number) AS number, max(number) FROM numbers(10);
```
结果：
```text theme={null}
┌─number─┬─max(number)─┐
│ 4.5 │ 9 │
└────────┴─────────────┘
```
## prefer\_external\_sort\_block\_bytes
外部排序时优先使用更大的块字节数，以降低合并过程中的内存使用量。
## prefer\_global\_in\_and\_join
启用将 `IN`/`JOIN` 运算符替换为 `GLOBAL IN`/`GLOBAL JOIN`。
可能的值：
* 0 — 已禁用。`IN`/`JOIN` 运算符不会被替换为 `GLOBAL IN`/`GLOBAL JOIN`。
* 1 — 已启用。`IN`/`JOIN` 运算符会被替换为 `GLOBAL IN`/`GLOBAL JOIN`。
**用法**
虽然 `SET distributed_product_mode=global` 可以改变分布式表的查询行为，但它不适用于本地表或来自外部资源的表。这时，`prefer_global_in_and_join` 设置就派上用场了。
例如，我们有一些提供查询服务的节点，其中包含不适合做分布式处理的本地表。我们需要在分布式处理过程中借助 `GLOBAL` 关键字即时分散这些表中的数据——即使用 `GLOBAL IN`/`GLOBAL JOIN`。
`prefer_global_in_and_join` 的另一个使用场景是访问由 external engine 创建的表。该设置有助于减少连接这类表时对外部源的调用次数：每个查询只需调用一次。
**另请参见：**
* [分布式子查询](/zh/reference/statements/in#distributed-subqueries) ，了解如何使用 `GLOBAL IN`/`GLOBAL JOIN` 的更多信息
## prefer\_localhost\_replica
启用/禁用在处理分布式查询时优先使用 localhost 副本。
可能的值：
* 1 — 如果存在 localhost 副本，ClickHouse 始终会将查询发送到该副本。
* 0 — ClickHouse 使用 [load\_balancing](#load_balancing) 设置中指定的负载均衡策略。
如果你在未使用 [parallel\_replicas\_custom\_key](#parallel_replicas_custom_key) 的情况下使用了 [max\_parallel\_replicas](#max_parallel_replicas)，请禁用此设置。
如果设置了 [parallel\_replicas\_custom\_key](#parallel_replicas_custom_key)，则只有在它用于包含多个分片且每个分片都有多个副本的集群时，才应禁用此设置。
如果它用于仅有一个分片但有多个副本的集群，禁用此设置会带来负面影响。
## prefer\_warmed\_unmerged\_parts\_seconds
仅在 ClickHouse Cloud 中生效。如果某个 merged part 合并完成距今不足这么多秒，且尚未预热 (参见 [cache\_populated\_by\_fetch](/zh/reference/settings/merge-tree-settings#cache_populated_by_fetch)) ，但它的所有 source parts 都可用且已预热，则 SELECT 查询会转而从这些 parts 读取。仅适用于 Replicated-/SharedMergeTree。请注意，这里只会检查 CacheWarmer 是否处理过该 part；如果该 part 是被其他机制拉取到 cache 中的，那么在 CacheWarmer 处理到它之前，仍会被视为冷数据；如果它已经预热，之后又从 cache 中被驱逐，仍会被视为已预热。
## preferred\_block\_size\_bytes
此设置用于调整查询处理时的数据块大小，是对较为粗略的 `max_block_size` 设置的进一步微调。如果列较大，并且按 `max_block_size` 的行数生成的块大小很可能超过指定字节数，则会减小块大小，以提高 CPU 缓存局部性。
## preferred\_max\_column\_in\_block\_size\_bytes
读取时，块中单列的最大大小限制。有助于减少缓存未命中的次数。应接近 L2 缓存大小。
## preferred\_optimize\_projection\_name
如果将其设置为非空字符串，ClickHouse 将尝试在查询中应用指定的投影。
可能的值：
* String：首选投影的名称
## prefetch\_buffer\_size
从文件系统读取时，预取缓冲区的最大大小。
## print\_pretty\_type\_names
可在 `DESCRIBE` 查询和 `toTypeName()` 函数中，以带缩进的更易读方式输出深层嵌套的类型名称。
示例：
```sql theme={null}
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)
)
```
## 优先级
查询优先级。1 为最高优先级，数值越大优先级越低；0 表示不使用优先级。
## promql\_database
指定 `promql` 方言使用的数据库名称。空字符串表示当前数据库。
## promql\_evaluation\_time
**别名**: `evaluation_time`
设置 promql 方言使用的求值时间。`auto` 表示当前时间。
## promql\_table
指定 `promql` 方言所使用的 TimeSeries 表名称。
## push\_external\_roles\_in\_interserver\_queries
启用在执行查询时，将用户角色从发起节点推送到其他节点。
## query\_cache\_compress\_entries
压缩[查询缓存](/zh/concepts/features/performance/caches/query-cache)中的条目。这样可减少查询缓存的内存占用，但代价是向其中写入 / 从其中读取的速度会变慢。
可能值：
* 0 - 已禁用
* 1 - 已启用
## query\_cache\_for\_subqueries
启用后，子查询结果可写入并从[查询缓存](/zh/concepts/features/performance/caches/query-cache)中读取。这会将 `use_query_cache` 传递到所有子查询。
可能的值：
* 0 - 已禁用
* 1 - 已启用
## query\_cache\_max\_entries
当前用户可在 [query cache](/zh/concepts/features/performance/caches/query-cache) 中存储的查询结果的最大数量。0 表示不受限制。
可能的值：
* 大于或等于 0 的整数。
## query\_cache\_max\_size\_in\_bytes
当前用户可在 [query cache](/zh/concepts/features/performance/caches/query-cache) 中分配的最大内存量 (以字节为单位) 。0 表示不受限制。
可能的值：
* 大于等于 0 的整数。
## query\_cache\_min\_query\_duration
查询的运行耗时至少达到多少毫秒，其结果才会存储到 [query cache](/zh/concepts/features/performance/caches/query-cache) 中。
可选值：
* 非负整数 >= 0。
## query\_cache\_min\_query\_runs
`SELECT` 查询的结果在存储到 [query cache](/zh/concepts/features/performance/caches/query-cache) 之前，至少需要运行的次数。
可能的值：
* 大于等于 0 的整数。
## query\_cache\_nondeterministic\_function\_handling
控制[查询缓存](/zh/concepts/features/performance/caches/query-cache)如何处理包含 `rand()` 或 `now()` 等非确定性函数的 `SELECT` 查询。
可选值：
* `'throw'` - 抛出异常，并且不缓存查询结果。
* `'save'` - 缓存查询结果。
* `'ignore'` - 不缓存查询结果，也不抛出异常。
## query\_cache\_share\_between\_users
如果开启此设置，缓存在[查询缓存](/zh/concepts/features/performance/caches/query-cache)中的 `SELECT` 查询结果可被其他用户读取。
出于安全考虑，不建议启用此设置。
可能的值：
* 0 - 已禁用
* 1 - 已启用
## query\_cache\_squash\_partial\_results
将部分结果块合并为大小为 [max\_block\_size](#max_block_size) 的块。这样会降低写入[查询缓存](/zh/concepts/features/performance/caches/query-cache)的性能，但能提高缓存条目的可压缩性 (参见 [query\_cache\_compress-entries](#query_cache_compress_entries)) 。
可能的值：
* 0 - 已禁用
* 1 - 已启用
## query\_cache\_system\_table\_handling
控制 [query cache](/zh/concepts/features/performance/caches/query-cache) 如何处理针对系统表的 `SELECT` 查询，即数据库 `system.*` 和 `information_schema.*` 中的表。
可能的值：
* `'throw'` - 抛出异常，并且不缓存查询结果。
* `'save'` - 缓存查询结果。
* `'ignore'` - 不缓存查询结果，也不抛出异常。
## query\_cache\_tag
一个 String 类型的字符串，用作[查询缓存](/zh/concepts/features/performance/caches/query-cache)条目的标签。
相同的查询如果标签不同，在查询缓存中会被视为不同的查询。
可能的值：
* 任意字符串
## query\_cache\_ttl
经过这么多秒后，[查询缓存](/zh/concepts/features/performance/caches/query-cache)中的条目将变为过期。
可选值：
* 正整数 >= 0。
## query\_metric\_log\_interval
按毫秒计，为各个查询收集 [query\_metric\_log](/zh/reference/system-tables/query_metric_log) 的时间间隔。
如果设置为任意负值，则会采用 [query\_metric\_log 设置](/zh/reference/settings/server-settings/settings#query_metric_log) 中的 `collect_interval_milliseconds` 值；如果不存在，则默认使用 1000。
要禁用单个查询的收集，请将 `query_metric_log_interval` 设为 0。
默认值：-1
## query\_plan\_aggregation\_in\_order
控制按序聚合这一查询计划级别优化的开关。
仅在设置 [`query_plan_enable_optimizations`](#query_plan_enable_optimizations) 为 1 时生效。
这是一个专家级设置，仅应供开发人员用于调试。该设置未来可能会以不向后兼容的方式更改，或被移除。
可能的值：
* 0 - 禁用
* 1 - 启用
## query\_plan\_convert\_any\_join\_to\_semi\_or\_anti\_join
如果 JOIN 后的过滤器对未匹配行或已匹配行的计算结果始终为 false，则允许将 ANY JOIN 转换为 SEMI 或 ANTI JOIN
## query\_plan\_convert\_join\_to\_in
如果输出列仅来自左表，则允许将 `JOIN` 转换为带 `IN` 的子查询。对于非 ANY JOIN (例如默认的 ALL JOIN) ，这可能导致结果错误。
## query\_plan\_convert\_outer\_join\_to\_inner\_join
如果 `JOIN` 之后的过滤器始终会过滤掉默认值，则允许将 `OUTER JOIN` 转换为 `INNER JOIN`
## query\_plan\_direct\_read\_from\_text\_index
允许在查询计划中仅使用倒排文本索引进行全文检索过滤。
## query\_plan\_display\_internal\_aliases
显示 EXPLAIN PLAN 中的内部别名 (如 \_\_table1) ，而非原始查询中指定的别名。
## query\_plan\_enable\_multithreading\_after\_window\_functions
在计算完窗口函数后启用多线程，以支持并行流处理
## query\_plan\_enable\_optimizations
控制是否在查询计划层启用查询优化。
这是一个专家级设置，仅应由开发人员在调试时使用。该设置未来可能会以不向后兼容的方式发生变化，或被移除。
可能的值：
* 0 - 禁用查询计划层的所有优化
* 1 - 启用查询计划层的优化 (但各项单独优化仍可通过各自的设置禁用)
## query\_plan\_execute\_functions\_after\_sorting
控制一项查询计划级别的优化，该优化会将表达式移到排序步骤之后执行。
仅在设置 [`query_plan_enable_optimizations`](#query_plan_enable_optimizations) 为 1 时生效。
这是一个专家级设置，仅供开发人员在调试时使用。该设置未来可能会以不向后兼容的方式发生变化，或被移除。
可能的值：
* 0 - 禁用
* 1 - 启用
## query\_plan\_filter\_push\_down
控制是否启用一种查询计划级别的优化，该优化会将过滤器下推到执行计划的更下层。
仅当设置 [query\_plan\_enable\_optimizations](#query_plan_enable_optimizations) 为 1 时才生效。
这是一个专家级设置，仅应由开发人员用于调试。该设置今后可能会以不向后兼容的方式发生变化，或被移除。
可能的值：
* 0 - 禁用
* 1 - 启用
## query\_plan\_join\_shard\_by\_pk\_ranges
如果两个表的连接键都包含 PRIMARY KEY 的前缀，则对 JOIN 进行分片。支持 `hash`、`parallel_hash` 和 `full_sorting_merge` 算法。通常不会提升查询速度，但可能会降低内存消耗。
## query\_plan\_join\_swap\_table
确定在查询计划中，join 的哪一侧应作为构建表 (也称为 inner，即在 hash join 中插入哈希表的一侧) 。此设置仅支持 `ALL` join strictness 和 `JOIN ON` clause。可能的值为：
* 'auto'：由 planner 决定使用哪张表作为构建表。
* 'false'：从不交换表 (右表为构建表) 。
* 'true'：始终交换表 (左表为构建表) 。
## query\_plan\_lift\_up\_array\_join
控制一项查询计划级别的优化，该优化会将 ARRAY JOIN 在执行计划中上提。
仅当设置 [query\_plan\_enable\_optimizations](#query_plan_enable_optimizations) 为 1 时才会生效。
这是一个专家级设置，仅应供开发人员用于调试。该设置未来可能会发生不向后兼容的变更，也可能被移除。
可能的值：
* 0 - 禁用
* 1 - 启用
## query\_plan\_lift\_up\_union
切换一项查询计划级别的优化。该优化会将查询计划中更大的子树提升到 union 中，以便进行进一步优化。
仅在设置 [`query_plan_enable_optimizations`](#query_plan_enable_optimizations) 为 1 时生效。
这是一个专家级设置，仅供开发人员在调试时使用。该设置未来可能会以不向后兼容的方式发生变更，或被移除。
可能的值：
* 0 - 禁用
* 1 - 启用
## query\_plan\_max\_limit\_for\_join\_lazy\_indexing
控制可在 JOIN 中使用查询计划进行惰性索引优化的最大 limit 值。如果为 0，则不受限制。
## query\_plan\_max\_limit\_for\_lazy\_materialization
控制可使用查询计划进行延迟物化优化的最大阈值。为零表示不受限制。
## query\_plan\_max\_limit\_for\_top\_k\_optimization
控制借助 minmax 跳过索引和动态阈值过滤评估 TopK 优化查询计划时允许的最大 limit 值。如果为 0，则不受限制。
## query\_plan\_max\_optimizations\_to\_apply
限制可应用于查询计划的优化总次数，参见设置 [query\_plan\_enable\_optimizations](#query_plan_enable_optimizations)。
这有助于避免复杂查询的优化耗时过长。
在 EXPLAIN PLAN 查询中，达到此限制后会停止应用优化，并按原样返回查询计划。
对于常规查询执行，如果实际优化次数超过此设置，则会抛出异常。
这是一个专家级设置，仅应由开发人员在调试时使用。该设置将来可能会以不向后兼容的方式发生变更，或者被移除。
## query\_plan\_max\_set\_size\_for\_projection\_match
对于 `IN` 子句 Set 中的行数，若不超过该值，投影匹配器会在判断两个 Set 是否相等时计算并比较其内容哈希。超过该值的 Set 会被视为不匹配，并跳过该投影。值为 0 时将完全禁用内容哈希比较：对于包含 `IN` 子句 Set 的节点，投影匹配永远不会成功。
该设置由聚合投影匹配器使用 (以及未来任何需要比较 `IN` 子句 Set 的投影匹配器) 。计算内容哈希的复杂度相对于 Set 元素数量为 `O(N log N)`；当查询或投影中出现大量 `IN` 子句时，该设置可限制规划阶段的开销。
## query\_plan\_max\_step\_description\_length
EXPLAIN PLAN 中步骤说明的最大长度。
## query\_plan\_merge\_expressions
切换一项查询计划级别的优化，该优化会合并连续的过滤器。
仅在设置 [query\_plan\_enable\_optimizations](#query_plan_enable_optimizations) 为 1 时生效。
这是一个专家级设置，仅应供开发人员在调试时使用。该设置未来可能会以不向后兼容的方式更改，或被移除。
可能的值：
* 0 - 禁用
* 1 - 启用
## query\_plan\_merge\_filter\_into\_join\_condition
允许将过滤器合并到 `JOIN` 条件中，并将 `CROSS JOIN` 转换为 `INNER`。
## query\_plan\_merge\_filters
支持在查询计划中合并过滤器。
## query\_plan\_min\_columns\_for\_join\_lazy\_indexing
控制启用 JOIN 中惰性索引优化所需的左侧最小载荷列数。0 表示禁用此优化。
## query\_plan\_optimize\_join\_order\_algorithm
指定在查询计划优化期间要尝试哪些 JOIN 顺序算法。可用算法如下：
* `greedy` - 基础贪心算法 - 速度快，但不一定能生成最佳的 JOIN 顺序
* `dpsize` - 实现了 DPsize 算法，目前仅适用于 inner join - 会考虑所有可能的 JOIN 顺序，并找出最优方案，但对于包含大量表和 JOIN 谓词的查询，速度可能较慢
* `dphyp` - 实现了 DPhyp (通过超图分区进行动态规划) 算法，目前仅适用于 inner join - 搜索的空间与 `dpsize` 相同，但只会枚举连通子图对，因此在稀疏 JOIN 图上生成的中间 JOIN 更少，不过代价是不考虑交叉乘积
可以将多个算法指定为逗号分隔的列表，例如 `dphyp,greedy`。系统会按顺序尝试它们；如果某个算法无法处理该查询 (例如由于 outer join 或存在不连通分量) ，则会回退到下一个算法。
## query\_plan\_optimize\_join\_order\_limit
优化同一子查询内 JOIN 的顺序。目前仅支持非常有限的场景。
值表示要优化的表的最大数量。
## query\_plan\_optimize\_join\_order\_max\_searched\_plans
JOIN 顺序优化器在放弃并回退到 `query_plan_optimize_join_order_algorithm` 中的下一个算法之前，最多可枚举的部分计划数量。
这会以确定性的方式限制优化时间 (与实际耗时无关) ，适用于团或星形等稠密 JOIN 图，在这类图中，搜索空间会呈指数级增长。
将其设为 0 可禁用此限制。对于默认的 `query_plan_optimize_join_order_limit`，该设置无效，因为此时搜索范围始终远低于该上限。
## query\_plan\_optimize\_join\_order\_randomize
当该值为非零时，JOIN 顺序优化器会使用随机生成的基数和 NDV，而不使用真实统计信息。
当设置为 1 时，会生成一个随机种子；当设置为大于 1 的值时，则直接将该值用作种子。
此设置用于测试，以发现由不同 JOIN 顺序引发的错误。
## query\_plan\_optimize\_lazy\_final
通过构建一组主键并将其用于索引分析，优化从 ReplacingMergeTree 使用 FINAL 的读取。
## query\_plan\_optimize\_lazy\_materialization
使用查询计划进行惰性物化优化。
## query\_plan\_optimize\_prewhere
允许将过滤器下推到受支持存储的 PREWHERE 表达式中
## query\_plan\_push\_down\_limit
控制一项查询计划级别的优化，该优化会将 LIMIT 下推到执行计划的更底层。
仅在设置 [query\_plan\_enable\_optimizations](#query_plan_enable_optimizations) 为 1 时生效。
这是一个专家级设置，仅供开发人员在调试时使用。该设置未来可能会发生不向后兼容的变更，或被移除。
可能的值：
* 0 - 禁用
* 1 - 启用
## query\_plan\_push\_limit\_by\_into\_sort
控制 `ORDER BY ... LIMIT BY` 查询的查询计划级别的优化。当 `LIMIT BY` 的列是 `ORDER BY` 子句的前缀时，每个并行排序流都会在合并为一个流之前先应用 `LIMIT BY`，从而减少最终合并以及后续管道阶段处理的行数。可加快 `LIMIT BY` 会丢弃大量行的查询。
仅当设置 [query\_plan\_enable\_optimizations](#query_plan_enable_optimizations) 为 1 时，此设置才会生效。
可能的值：
* 0 - 禁用
* 1 - 启用
## query\_plan\_read\_in\_order
用于切换按序读取这一查询计划级别的优化。
仅在设置 [`query_plan_enable_optimizations`](#query_plan_enable_optimizations) 为 1 时生效。
这是一个专家级设置，仅应由开发者在调试时使用。该设置未来可能会以不向后兼容的方式变更，或被移除。
可能的值：
* 0 - 禁用
* 1 - 启用
## query\_plan\_read\_in\_order\_through\_join
在 JOIN 操作中继续按顺序从左侧表读取，以便后续步骤加以利用。
## query\_plan\_remove\_redundant\_distinct
用于启用或禁用一项查询计划级别的优化，该优化会移除冗余的 DISTINCT 步骤。
仅在设置 [`query_plan_enable_optimizations`](#query_plan_enable_optimizations) 为 1 时生效。
这是一个专家级设置，仅应由开发人员在调试时使用。该设置未来可能会以不向后兼容的方式变更，或被移除。
可能的值：
* 0 - 禁用
* 1 - 启用
## query\_plan\_remove\_redundant\_sorting
控制一项查询计划级别的优化，用于移除冗余的排序步骤，例如子查询中的排序步骤。
仅在设置 [`query_plan_enable_optimizations`](#query_plan_enable_optimizations) 为 1 时生效。
这是一个专家级设置，仅供开发者用于调试。该设置未来可能会以不向后兼容的方式更改，或被移除。
可能的值：
* 0 - 禁用
* 1 - 启用
## query\_plan\_remove\_unused\_columns
用于启用或禁用一项查询计划级别的优化，该优化会尝试从查询计划的各个步骤中移除未使用的列 (包括输入列和输出列) 。
仅在设置 [query\_plan\_enable\_optimizations](#query_plan_enable_optimizations) 为 1 时生效。
这是一个专家级设置，仅应由开发人员用于调试。该设置未来可能会以不向后兼容的方式发生变化，或被移除。
可能的值：
* 0 - 禁用
* 1 - 启用
## query\_plan\_reuse\_storage\_ordering\_for\_window\_functions
**别名**：`optimize_read_in_window_order`
控制是否启用一项查询计划级别的优化：在为窗口函数进行排序时复用存储排序顺序。
仅在设置 [`query_plan_enable_optimizations`](#query_plan_enable_optimizations) 为 1 时生效。
这是一个专家级设置，仅供开发人员在调试时使用。该设置未来可能会以不向后兼容的方式变更，或被移除。
可能的值：
* 0 - 禁用
* 1 - 启用
## query\_plan\_split\_filter
这是一个专家级设置，仅应供开发人员在调试时使用。该设置未来可能会以不向后兼容的方式变更，或被移除。
控制一项查询计划级别的优化，该优化会将过滤器拆分为表达式。
仅在设置 [query\_plan\_enable\_optimizations](#query_plan_enable_optimizations) 为 1 时生效。
可能的值：
* 0 - 禁用
* 1 - 启用
## query\_plan\_text\_index\_add\_hint
允许为查询计划中基于倒排文本索引构建的过滤器添加提示 (附加谓词) 。
## query\_plan\_top\_k\_through\_join
用于切换一项查询计划级别的优化：当排序键仅引用连接 (LEFT/RIGHT) 中保留侧的列时，将 `ORDER BY ... LIMIT n` 下推到连接之前。这会限制保留侧输入在执行连接前需要产生的行数。
仅当设置 [query\_plan\_enable\_optimizations](#query_plan_enable_optimizations) 为 1 时才生效。
可能的值：
* 0 - 禁用
* 1 - 启用
## query\_plan\_try\_use\_vector\_search
控制是否启用一项会尝试使用向量相似度索引的查询计划级别的优化。
仅当设置 [`query_plan_enable_optimizations`](#query_plan_enable_optimizations) 为 1 时，此设置才会生效。
这是一个专家级设置，仅应供开发人员用于调试。该设置未来可能会发生不向后兼容的变更，或被移除。
可能的值：
* 0 - 禁用
* 1 - 启用
## query\_profiler\_cpu\_time\_period\_ns
设置 [查询分析器](/zh/concepts/features/performance/troubleshoot/sampling-query-profiler) 的 CPU 时钟计时器周期。此计时器仅统计 CPU 时间。
可能的值：
* 以纳秒为单位的正整数。
推荐值：
* 对于单个查询，建议设为 10000000 (每秒 100 次) 纳秒或更大。
* 对于集群级性能分析，建议设为 1000000000 (每秒一次) 。
* 0 表示关闭计时器。
另请参见：
* 系统表 [trace\_log](/zh/reference/system-tables/trace_log)
## query\_profiler\_real\_time\_period\_ns
设置 [查询分析器](/zh/concepts/features/performance/troubleshoot/sampling-query-profiler) 的实时时钟计时器周期。实时时钟计时器统计挂钟时间。
可选值：
* 以纳秒为单位的正整数。
推荐值：
* 对于单个查询，`10000000` (每秒 100 次) 纳秒及更低的值。
* 对于集群级性能分析，`1000000000` (每秒一次) 。
* `0` 表示关闭计时器。
另请参阅：
* 系统表 [trace\_log](/zh/reference/system-tables/trace_log)
Cloud 默认值：`3000000000`。
## queue\_max\_wait\_ms
如果并发请求数超过最大值，请求在队列中的等待时间。
## rabbitmq\_max\_wait\_ms
从 RabbitMQ 读取数据前，重试前的等待时间。
## read\_backoff\_max\_throughput
用于在读取速度较慢时减少线程数的设置。当读取吞吐量低于该字节/秒阈值时，开始对事件进行计数。
## read\_backoff\_min\_concurrency
用于在读取速度较慢时尽量保持最小线程数的设置。
## read\_backoff\_min\_events
用于在读取速度较慢时减少线程数的设置。达到该事件次数后，线程数将减少。
## read\_backoff\_min\_interval\_between\_events\_ms
在读取较慢时，用于减少线程数量的设置。如果距离上一个事件发生还不到某个时间间隔，则忽略该事件。
## read\_backoff\_min\_latency\_ms
用于在读取速度较慢时减少线程数的设置。仅考虑耗时至少达到该时长的读取操作。
## read\_from\_distributed\_cache\_if\_exists\_otherwise\_bypass\_cache
仅在 ClickHouse Cloud 中生效。与 read\_from\_filesystem\_cache\_if\_exists\_otherwise\_bypass\_cache 相同，但适用于分布式缓存。
## read\_from\_filesystem\_cache\_if\_exists\_otherwise\_bypass\_cache
允许以被动模式使用文件系统缓存：利用现有的缓存条目，但不再向缓存中添加更多条目。如果对此设置为高负载的临时查询启用，而对短时实时查询保持禁用，则有助于避免重负载查询造成缓存抖动，并提高系统整体效率。
## read\_from\_page\_cache\_if\_exists\_otherwise\_bypass\_cache
以被动模式使用用户态页缓存，类似于 `read_from_filesystem_cache_if_exists_otherwise_bypass_cache`。
## read\_in\_order\_two\_level\_merge\_threshold
按主键顺序进行多线程读取时，执行 preliminary merge 步骤所需读取的最少 parts 数。
## read\_in\_order\_use\_buffering
按主键顺序读取时，在合并前启用缓冲。它会提高查询执行的并行度
## read\_in\_order\_use\_virtual\_row
在按主键或其单调函数顺序读取时使用虚拟行。在跨多个 parts 搜索时，这很有用，因为只会访问相关的 parts。
## read\_in\_order\_use\_virtual\_row\_per\_block
当与 `read_in_order_use_virtual_row` 一起启用时，在读取完每个块后都会发出一个虚拟行 (而不只是每个 part 的开头) 。
这使 `MergingSortedTransform` 能够更频繁地重新调整数据源的优先级，这在下游过滤器丢弃了大量行，且数据在各个 part 之间分布不均时尤其有用。
请注意，这会禁用读取时的 `read_in_order_use_buffering` 优化和预合并 (`read_in_order_two_level_merge_threshold`) 。
## read\_overflow\_mode
超出限制时的处理方式。
## read\_overflow\_mode\_leaf
设置当读取的数据量超过某个 leaf 限制之一时的处理方式。
可选项：
* `throw`：抛出异常 (默认) 。
* `break`：停止执行查询并返回部分结果。
## read\_priority
从本地文件系统或远程文件系统读取数据时的优先级。仅支持本地文件系统的 'pread\_threadpool' method 和远程文件系统的 `threadpool` method。
## read\_through\_distributed\_cache
仅在 ClickHouse Cloud 中生效。允许从分布式缓存中读取
## readonly
0 - 无只读限制。1 - 仅允许读取请求，以及修改显式允许的设置。2 - 仅允许读取请求，以及修改设置，但 `readonly` 设置除外。
## receive\_data\_timeout\_ms
接收首个数据包或来自副本的正进度数据包时的连接超时时间
## receive\_timeout
从网络接收数据的超时时间，单位为秒。如果在此时间间隔内未接收到任何字节，则会抛出异常。如果在客户端设置此项，套接字的 `send_timeout` 也会在服务器端对应连接的另一端设置。
## recursive\_cte\_max\_steps\_in\_type\_inference
在递归 CTE 中推断列类型时的最大迭代次数。列类型的确定方式是：在 UNION ALL 的非递归部分和递归部分之间反复应用 `getLeastSupertype`，直到收敛为止。设置为 0 可禁用类型扩宽，并且仅使用非递归部分的类型。
## regexp\_dict\_allow\_hyperscan
允许 regexp\_tree 字典使用 Hyperscan 库。
## regexp\_dict\_flag\_case\_insensitive
对 regexp\_tree 字典启用不区分大小写的匹配。可在单个表达式中使用 (?i) 和 (?-i) 进行覆盖。
## regexp\_dict\_flag\_dotall
允许在 regexp\_tree 字典中，`.` 匹配换行符。
## regexp\_max\_matches\_per\_row
设置每行中单个 regular expression 的最大匹配次数。使用 [extractAllGroupsHorizontal](/zh/reference/functions/regular-functions/string-search-functions#extractAllGroupsHorizontal) 函数中的贪婪 regular expression 时，可用此设置防止内存过载。
Possible values:
* 正整数。
## reject\_expensive\_hyperscan\_regexps
拒绝那些使用 hyperscan 评估时可能代价较高的模式 (由于 NFA 状态爆炸)
## remerge\_sort\_lowered\_memory\_bytes\_ratio
如果 remerge 后内存使用量未按此比例降低，则会禁用 remerge。
## remote\_filesystem\_read\_method
用于从远程文件系统读取数据的方法，可选值为：read、threadpool。
## remote\_filesystem\_read\_prefetch
从远程文件系统读取数据时，是否使用预取。
## remote\_fs\_read\_backoff\_max\_tries
采用退避机制读取时的最大重试次数
## remote\_fs\_read\_max\_backoff\_ms
从远程磁盘读取数据时的最长退避等待时间
## remote\_read\_min\_bytes\_for\_seek
远程读取 (url、S3) 时，执行寻道而不是带忽略的读取所需的最小字节数。
## rename\_files\_after\_processing
* **类型：** String
* **默认值：** 空字符串
此设置允许为由 `file` 表函数处理的文件指定重命名模式。设置此选项后，`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`
## replace\_running\_query
使用 HTTP 接口时，可以传入 `query_id` 参数。它可以是任意字符串，用作查询标识符。
如果此时同一用户已存在具有相同 `query_id` 的查询，则其行为取决于 `replace_running_query` 参数。
`0` (默认) – 抛出异常 (如果具有相同 `query_id` 的查询已在运行，则不允许该查询运行) 。
`1` – 取消旧查询并开始运行新查询。
将此参数设置为 1，可用于实现分段条件建议功能。输入下一个字符后，如果旧查询尚未完成，则应将其取消。
## replace\_running\_query\_max\_wait\_ms
启用 [replace\_running\_query](#replace_running_query) 设置时，等待具有相同 `query_id` 的正在运行中的查询结束的时间。
可能的值：
* 正整数。
* 0 — 抛出异常；如果服务器已在执行具有相同 `query_id` 的查询，则不允许运行新的查询。
## replication\_wait\_for\_inactive\_replica\_timeout
指定等待非活动副本执行 [`ALTER`](/zh/reference/statements/alter/index)、[`OPTIMIZE`](/zh/reference/statements/optimize) 或 [`TRUNCATE`](/zh/reference/statements/truncate) 查询的时间长度 (以秒为单位) 。
可能的值：
* `0` — 不等待。
* 负整数 — 无限期等待。
* 正整数 — 等待的秒数。
## restore\_replace\_external\_dictionary\_source\_to\_null
恢复时将外部字典源替换为 Null。适用于测试用途
## restore\_replace\_external\_engines\_to\_null
用于测试。将所有 external engine 替换为 Null，以避免发起外部连接。
## restore\_replace\_external\_table\_functions\_to\_null
用于测试。将所有外部表函数替换为 Null，以防止发起外部连接。
## restore\_replicated\_merge\_tree\_to\_shared\_merge\_tree
在 RESTORE 期间，将表引擎从 Replicated*MergeTree 替换为 Shared*MergeTree。
Cloud 默认值：`1`。
## result\_overflow\_mode
Cloud 默认值：`throw`
设置当结果量超过某一限制时应如何处理。
可能的值：
* `throw`：抛出异常 (默认值) 。
* `break`：停止执行查询并返回部分结果，就像
源数据已经耗尽一样。
使用 'break' 与使用 LIMIT 类似。`Break` 仅会在
块级别中断执行。这意味着返回的行数会大于
[`max_result_rows`](/zh/reference/settings/session-settings#max_result_rows)，是 [`max_block_size`](/zh/reference/settings/session-settings#max_block_size)
的倍数，并且取决于 [`max_threads`](/zh/reference/settings/session-settings#max_threads)。
**示例**
```sql title="Query" theme={null}
SET max_threads = 3, max_block_size = 3333;
SET max_result_rows = 3334, result_overflow_mode = 'break';
SELECT *
FROM numbers_mt(100000)
FORMAT Null;
```
```text title="Result" theme={null}
6666 rows in set. ...
```
## rewrite\_count\_distinct\_if\_with\_count\_distinct\_implementation
允许使用 [count\_distinct\_implementation](#count_distinct_implementation) 设置来改写 `countDistcintIf`。
可能的值：
* true — 允许。
* false — 不允许。
## rewrite\_in\_to\_join
将类似 `x IN subquery` 的表达式重写为 JOIN。这可能有助于通过 JOIN 重排序优化整个查询。
## rows\_before\_aggregation
启用后，ClickHouse 将为 rows\_before\_aggregation 统计信息提供精确的值，即聚合前读取的行数
## s3\_allow\_multipart\_copy
允许在 S3 中进行分片复制。
## s3\_allow\_parallel\_part\_upload
使用多个线程执行 S3 分段上传。这可能会使内存占用略有增加
## s3\_check\_objects\_after\_upload
对每个上传到 S3 的对象发起 head 请求，以确认上传是否成功
## s3\_connect\_timeout\_ms
S3 磁盘中主机的连接超时时间。
## s3\_create\_new\_file\_on\_insert
启用或禁用在 S3 引擎表中每次 insert 时创建新文件。如果启用，每次 insert 都会使用该键创建一个新的 S3 对象，模式类似如下：
初始：`data.Parquet.gz` -> `data.1.Parquet.gz` -> `data.2.Parquet.gz`，等等。
可能的值：
* 0 — `INSERT` 查询会创建一个新文件；如果文件已存在且未设置 s3\_truncate\_on\_insert，则会失败。
* 1 — 如果未设置 s3\_truncate\_on\_insert，则 `INSERT` 查询会在每次 insert 时使用后缀 (从第二个文件开始) 创建一个新文件。
更多详情请参见[此处](/zh/integrations/connectors/data-ingestion/AWS/integrating-s3-with-clickhouse#inserting-data)。
## s3\_disable\_checksum
向 S3 发送文件时不计算校验和。这样可避免对文件进行额外的处理，从而加快写入速度。通常来说，这样做基本是安全的，因为 MergeTree 表的数据本身就会由 ClickHouse 计算校验和；此外，通过 HTTPS 访问 S3 时，TLS 层也已经在网络传输过程中提供了完整性保护。不过，在 S3 上额外计算校验和仍然可以提供纵深防御。
## s3\_ignore\_file\_doesnt\_exist
读取某些键时，如果文件不存在，则忽略该文件缺失。
可能的值：
* 1 — `SELECT` 返回空结果。
* 0 — `SELECT` 抛出异常。
## s3\_list\_object\_keys\_size
ListObject 请求单个批次中可返回的最大文件数
## s3\_max\_connections
每台服务器的最大连接数。
## s3\_max\_get\_burst
在达到每秒请求数限制之前，可同时发起的最大请求数。默认值 (0) 等于 `s3_max_get_rps`
## s3\_max\_get\_rps
在开始限流前，S3 GET 请求的每秒速率上限。0 表示不受限制。
## s3\_max\_inflight\_parts\_for\_one\_file
分段上传请求中可同时上传的最大分片数。0 表示不受限制。
## s3\_max\_part\_number
S3 上传分片允许的最大分片编号。
## s3\_max\_put\_burst
在达到每秒请求数限制前，可同时发出的最大请求数。默认值为 (0) ，等同于 `s3_max_put_rps`
## s3\_max\_put\_rps
在触发限流之前，对 S3 PUT 请求的每秒速率进行限制。0 表示无限制。
## s3\_max\_single\_operation\_copy\_size
S3 中单次复制操作的最大大小。仅当 s3\_allow\_multipart\_copy 为 true 时，此设置才会生效。
## s3\_max\_single\_part\_upload\_size
使用单分片方式上传到 S3 时，对象的最大上传大小。
## s3\_max\_single\_read\_retries
单次 S3 读取的最大重试次数。
## s3\_max\_unexpected\_write\_error\_retries
在 S3 写入过程中发生意外错误时的最大重试次数。
## s3\_max\_upload\_part\_size
向 S3 进行分段上传时，单个分段的最大大小。
## s3\_min\_upload\_part\_size
向 S3 执行分段上传时，每个分片的最小大小。
## s3\_path\_filter\_limit
可从查询过滤器中提取并用于文件遍历、替代 glob 列表的 `_path` 值的最大数量。
0 表示禁用。
## s3\_request\_timeout\_ms
向 S3 发送和从 S3 接收数据时的空闲超时时间。如果单次 TCP 读取或写入调用阻塞时间达到这么久，则会失败。
## s3\_skip\_empty\_files
启用或禁用在 [S3](/zh/reference/engines/table-engines/integrations/s3) 表引擎中跳过空文件。
可能的值：
* 0 — 如果空文件与请求的 format 不兼容，`SELECT` 会抛出异常。
* 1 — 对于空文件，`SELECT` 返回空结果。
## s3\_slow\_all\_threads\_after\_network\_error
当设置为 `true` 时，只要任意一个 S3 请求遇到可重试的网络错误 (例如套接字超时) ，
所有向同一备份端点发起 S3 请求的线程都会被放慢。
当设置为 `false` 时，每个线程都会独立处理 S3 请求的 backoff，不受其他线程影响。
## s3\_strict\_upload\_part\_size
向 S3 进行分段上传时，单个上传分段的精确大小 (某些实现不支持大小可变的分片) 。
## s3\_throw\_on\_zero\_files\_match
当 ListObjects 请求未匹配到任何文件时，抛出错误
## s3\_truncate\_on\_insert
启用或禁用在 S3 引擎表中执行 `insert` 前先截断内容。如果禁用，当 S3 对象已存在时，尝试 `insert` 会抛出异常。
可能的值：
* 0 — `INSERT` 查询会创建新文件；如果文件已存在且未设置 s3\_create\_new\_file\_on\_insert，则会失败。
* 1 — `INSERT` 查询会用新数据替换文件中的现有内容。
更多详情请参见[此处](/zh/integrations/connectors/data-ingestion/AWS/integrating-s3-with-clickhouse#inserting-data)。
## s3\_upload\_part\_size\_multiply\_factor
当单次写入到 S3 上传的 parts 数达到 s3\_multiply\_parts\_count\_threshold 时，就将 s3\_min\_upload\_part\_size 乘以该因子。
## s3\_upload\_part\_size\_multiply\_parts\_count\_threshold
每当上传到 S3 的分片数量达到这个值时，`s3_min_upload_part_size` 就会乘以 `s3_upload_part_size_multiply_factor`。
## s3\_uri\_style
强制指定 S3 端点样式。可选值：auto、virtual\_hosted、path。
## s3\_use\_adaptive\_timeouts
设置为 `true` 时，所有 S3 请求的前两次尝试都会使用较短的发送和接收超时时间。
设置为 `false` 时，所有尝试都会使用相同的超时时间。
## s3\_validate\_request\_settings
启用 S3 请求设置校验。
可能的值：
* 1 — 校验设置。
* 0 — 不校验设置。
## s3queue\_default\_zookeeper\_path
S3Queue 引擎的默认 ZooKeeper 路径前缀
## s3queue\_enable\_logging\_to\_s3queue\_log
启用向 system.s3queue\_log 写入日志。该值可通过表设置针对各个表进行覆盖
## s3queue\_keeper\_fault\_injection\_probability
S3Queue 的 Keeper 故障注入概率。
## s3queue\_migrate\_old\_metadata\_to\_buckets
将 S3Queue 表的旧元数据结构迁移到新结构
## schema\_inference\_cache\_require\_modification\_time\_for\_url
对带有最后修改时间校验的 URL 使用缓存中的 schema (适用于带有 Last-Modified 请求头的 URL)
## schema\_inference\_use\_cache\_for\_azure
使用 Azure 表函数时，在 schema 推断期间使用缓存
## schema\_inference\_use\_cache\_for\_file
使用 file 表函数时，在 schema 推断过程中使用缓存
## schema\_inference\_use\_cache\_for\_hdfs
在使用 hdfs 表函数时，在 schema 推断过程中使用缓存
## schema\_inference\_use\_cache\_for\_s3
使用 S3 表函数时，在 schema 推断过程中使用缓存
## schema\_inference\_use\_cache\_for\_url
使用 url 表 functio 进行 schema 推断时使用缓存
## secondary\_indices\_enable\_bulk\_filtering
启用索引的批量过滤算法。按预期，它应当始终表现更好；不过，为了兼容性和便于控制，我们仍保留了此设置。
## select\_sequential\_consistency
此设置在 SharedMergeTree 和 ReplicatedMergeTree 中的行为不同。有关 `select_sequential_consistency` 在 SharedMergeTree 中的行为的更多信息，请参阅 [SharedMergeTree 一致性](/zh/products/cloud/features/infrastructure/shared-merge-tree#consistency)。
为 `SELECT` 查询启用或禁用顺序一致性。要求禁用 `insert_quorum_parallel` (默认启用) 。
可能的值：
* 0 — 禁用。
* 1 — 启用。
用法
启用顺序一致性后，ClickHouse 只允许客户端在包含此前所有通过 `insert_quorum` 执行的 `INSERT` 查询所写入数据的副本上执行 `SELECT` 查询。如果客户端访问的是不完整的副本，ClickHouse 将抛出异常。`SELECT` 查询不会包含尚未写入 quorum 所要求副本数的数据。
启用 `insert_quorum_parallel` 时 (默认即为启用) ，`select_sequential_consistency` 将不起作用。这是因为并行 `INSERT` 查询可能会写入不同的一组 quorum 副本，因此无法保证某一个副本一定已经接收到所有写入。
另请参见：
* [insert\_quorum](#insert_quorum)
* [insert\_quorum\_timeout](#insert_quorum_timeout)
* [insert\_quorum\_parallel](#insert_quorum_parallel)
## send\_logs\_level
将服务器文本日志中不低于指定级别的日志发送给客户端。有效值：'trace'、'debug'、'information'、'warning'、'error'、'fatal'、'none'
## send\_logs\_source\_regexp
使用指定的正则表达式匹配日志源名称，并发送服务器文本日志。留空表示所有来源。
## send\_profile\_events
启用或禁用向客户端发送 [ProfileEvents](/zh/resources/develop-contribute/native-protocol/server#profile-events) 数据包的功能。
对于不需要 profile events 的客户端，可以禁用此设置以减少网络流量。
可选值：
* 0 — 已禁用。
* 1 — 已启用。
在 `clickhouse-server` 的响应中启用或禁用 `X-ClickHouse-Progress` HTTP 响应头。
如需了解更多信息，请参阅 [HTTP interface 说明](/zh/concepts/features/interfaces/http)。
可能的值：
* 0 — 禁用。
* 1 — 启用。
## send\_table\_structure\_on\_insert\_with\_inline\_data
如果禁用此设置，且 INSERT 查询包含内联数据，服务器将不会通过原生协议向客户端返回表结构和列默认值。相反，服务器会自行解析内联数据。这可以提升通过原生协议执行大量小型插入操作时的性能。
## send\_timeout
发送数据到网络的超时时间，单位为秒。如果客户端需要发送数据，但在此时间间隔内无法发送任何字节，则会抛出异常。如果你在客户端设置了此项，那么服务器端对应连接上的套接字 `receive_timeout` 也会一并设置。
## serialize\_query\_plan
对分布式处理的查询计划进行序列化
## serialize\_string\_in\_memory\_with\_zero\_byte
在聚合期间序列化 String 值时，在末尾附加一个零字节。启用此设置可在查询版本不兼容的集群时保持兼容性。
## session\_timezone
设置当前 session 或查询的隐式时区。
隐式时区是应用于未显式指定时区的 DateTime/DateTime64 类型值的时区。
此设置的优先级高于全局配置的 (server 级别) 隐式时区。
值为 '' (空字符串) 表示当前 session 或查询的隐式时区等于[server 时区](/zh/reference/settings/server-settings/settings#timezone)。
你可以使用函数 `timeZone()` 和 `serverTimeZone()` 获取 session 时区和 server 时区。
可能的值：
* `system.time_zones` 中的任意时区名称，例如 `Europe/Berlin`、`UTC` 或 `Zulu`
示例：
```sql theme={null}
SELECT timeZone(), serverTimeZone() FORMAT CSV
"Europe/Berlin","Europe/Berlin"
```
```sql theme={null}
SELECT timeZone(), serverTimeZone() SETTINGS session_timezone = 'Asia/Novosibirsk' FORMAT CSV
"Asia/Novosibirsk","Europe/Berlin"
```
将会话时区 'America/Denver' 应用于未显式指定时区的内部 DateTime：
```sql theme={null}
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`。这可能会导致一些隐蔽的错误。
请参见下面的示例和说明。
```sql theme={null}
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。
* 在第二个查询中，DateTime 是从 String 解析出来的，并继承了现有列 `d` 的类型和 time zone。因此，`session_timezone` 设置和全局 time zone 都不会生效。
**另请参见**
* [timezone](/zh/reference/settings/server-settings/settings#timezone)
## set\_overflow\_mode
设置当数据量超过某个限制时的处理方式。
可能的值：
* `throw`：抛出异常 (默认) 。
* `break`：停止执行查询并返回部分结果，就像
源数据已经耗尽一样。
## shared\_merge\_tree\_sequential\_consistency\_initial\_parts\_update\_backoff\_ms
使用 `select_sequential_consistency` 和 `SharedMergeTree` 时，parts 更新的初始退避时间 (毫秒) 。仅在 ClickHouse Cloud 中可用。
## shared\_merge\_tree\_sequential\_consistency\_max\_parts\_update\_backoff\_ms
在将 `select_sequential_consistency` 与 `SharedMergeTree` 配合使用时，parts 更新的最大退避时间 (毫秒) 。仅在 ClickHouse Cloud 中可用。
## shared\_merge\_tree\_sequential\_consistency\_parts\_update\_max\_retries
在将 `select_sequential_consistency` 与 `SharedMergeTree` 一起使用时，parts 更新的最大重试次数。仅在 ClickHouse Cloud 中可用。
## shared\_merge\_tree\_sync\_parts\_on\_partition\_operations
在 SMT 表中执行 MOVE|REPLACE|ATTACH 分区操作后，自动同步一组数据分区片段。仅限 Cloud
## short\_circuit\_function\_evaluation
允许按照[短路求值](https://en.wikipedia.org/wiki/Short-circuit_evaluation)方式计算 [if](/zh/reference/functions/regular-functions/conditional-functions#if)、[multiIf](/zh/reference/functions/regular-functions/conditional-functions#multiIf)、[and](/zh/reference/functions/regular-functions/logical-functions#and) 和 [or](/zh/reference/functions/regular-functions/logical-functions#or) 函数。这有助于优化这些函数中复杂表达式的执行，并防止可能出现的异常 (例如在不应发生时出现除零) 。
可能的值：
* `enable` — 为适合使用短路求值的函数启用短路函数求值 (即可能抛出异常或计算开销较大的函数) 。
* `force_enable` — 为所有函数启用短路函数求值。
* `disable` — 禁用短路函数求值。
## short\_circuit\_function\_evaluation\_for\_nulls
用于优化这类函数的求值：只要任一参数为 NULL，函数就会返回 NULL。当函数参数中的 NULL 值占比超过 short\_circuit\_function\_evaluation\_for\_nulls\_threshold 时，系统将跳过对该函数的逐行求值，而是直接为所有行返回 NULL，从而避免不必要的计算。
## short\_circuit\_function\_evaluation\_for\_nulls\_threshold
NULL 值占比的阈值。对于具有 Nullable 参数的函数，仅在所有参数值都非 NULL 的行上执行。仅在启用设置 short\_circuit\_function\_evaluation\_for\_nulls 时适用。
当包含 NULL 值的行数占总行数的比例超过此阈值时，这些包含 NULL 值的行将不会被计算。
## show\_processlist\_include\_internal
在 `SHOW PROCESSLIST` 查询输出中显示内部辅助进程。
内部进程包括字典重新加载、可刷新materialized view 重新加载、在 `SHOW ...` 查询中执行的辅助 `SELECT`、为处理损坏表而在内部执行的辅助 `CREATE DATABASE ...` 查询等。
## show\_remote\_databases\_in\_system\_tables
**别名**: `show_data_lake_catalogs_in_system_tables`
启用在系统表中显示远程数据库 (数据湖目录、MySQL、PostgreSQL) 。
## show\_table\_uuid\_in\_table\_create\_query\_if\_not\_nil
设置 `SHOW TABLE` 查询的显示内容。
可选值：
* 0 — 查询显示时不包含表 UUID。
* 1 — 查询显示时包含表 UUID。
## single\_join\_prefer\_left\_table
对于单个 JOIN，当标识符存在歧义时，优先使用左表
## skip\_redundant\_aliases\_in\_udf
为简化使用，用户自定义函数中不会使用 (替换) 冗余别名。
可能的值：
* 1 — 在 UDF 中会跳过 (替换) 这些别名。
* 0 — 在 UDF 中不会跳过 (替换) 这些别名。
**示例**
启用与禁用的区别：
查询：
```sql theme={null}
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);
```
结果：
```text theme={null}
SELECT ((4 + 2) + 1 AS y, y + 2)
```
查询：
```sql theme={null}
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);
```
结果：
```text theme={null}
SELECT ((4 + 2) + 1, ((4 + 2) + 1) + 2)
```
## skip\_unavailable\_shards
启用或禁用静默跳过不可用分片。
如果某个分片的所有副本都不可用，则认为该分片不可用。副本在以下情况下会被视为不可用：
* ClickHouse 因任何原因无法连接到副本。
连接副本时，ClickHouse 会进行多次尝试。如果这些尝试全部失败，则该副本会被视为不可用。
* 无法通过 DNS 解析副本主机名。
如果无法通过 DNS 解析副本的主机名，可能意味着以下情况：
* 副本所在主机没有 DNS 记录。这可能发生在使用动态 DNS 的系统中，例如 [Kubernetes](https://kubernetes.io)。在这类系统中，节点在停机期间可能无法解析，这并不属于错误。
* 配置错误。ClickHouse 配置文件中包含错误的主机名。
可能的值：
* 1 — 启用跳过。
如果某个分片不可用，ClickHouse 会基于部分数据返回结果，并且不会报告节点可用性问题。
* 0 — 禁用跳过。
如果某个分片不可用，ClickHouse 会抛出异常。
## sleep\_after\_receiving\_query\_ms
在 TCPHandler 中接收到查询后睡眠的时间
## sleep\_in\_send\_data\_ms
TCPHandler 发送数据时的休眠时间
## sleep\_in\_send\_tables\_status\_ms
TCPHandler 发送表状态响应前的休眠时间
## sort\_overflow\_mode
设置在排序前接收的行数超过某个限制时的处理方式。
可能的值：
* `throw`：抛出异常。
* `break`：停止执行查询并返回部分结果。
## split\_intersecting\_parts\_ranges\_into\_layers\_final
在 FINAL 优化期间按层拆分相交的 parts 范围
## split\_parts\_ranges\_into\_intersecting\_and\_non\_intersecting\_final
在 FINAL 优化期间将 parts 的范围拆分为相交部分和不相交部分
## splitby\_max\_substrings\_includes\_remaining\_string
控制当函数 [splitBy\*()](/zh/reference/functions/regular-functions/splitting-merging-functions) 的参数 `max_substrings` > 0 时，是否将剩余字符串包含在结果数组的最后一个元素中。
可能的值：
* `0` - 剩余字符串不会包含在结果数组的最后一个元素中。
* `1` - 剩余字符串会包含在结果数组的最后一个元素中。这与 Spark 的 [`split()`](https://spark.apache.org/docs/3.1.2/api/python/reference/api/pyspark.sql.functions.split.html) 函数和 Python 的 ['string.split()'](https://docs.python.org/3/library/stdtypes.html#str.split) 方法的行为一致。
## stop\_refreshable\_materialized\_views\_on\_startup
在 server 启动时，阻止调度可刷新materialized view，效果等同于使用 SYSTEM STOP VIEWS。之后你可以手动使用 `SYSTEM START VIEWS` 或 `SYSTEM START VIEW ` 启动它们。该设置也适用于新创建的视图。对不可刷新的 materialized view 不生效。
## storage\_file\_read\_method
从存储文件读取数据的方法，可选值包括：`read`、`pread`、`mmap`。`mmap` 方法不适用于 clickhouse-server (其适用对象是 clickhouse-local) 。
## storage\_system\_stack\_trace\_pipe\_read\_timeout\_ms
查询 `system.stack_trace` 表时，为接收来自线程的信息而从管道读取的最长等待时间。此设置仅用于测试，不建议用户更改。
## stream\_flush\_interval\_ms
适用于启用流式处理的表：在发生超时，或某个线程生成了 [max\_insert\_block\_size](#max_insert_block_size) 行时生效。
默认值为 7500。
该值越小，数据刷写到表中的频率就越高。将该值设置得过低会导致性能下降。
## stream\_like\_engine\_allow\_direct\_select
允许直接对 Kafka、RabbitMQ、FileLog、Redis Streams、S3Queue、AzureQueue 和 NATS 引擎执行 SELECT 查询。如果存在已附加的 materialized view，即使启用此设置，也不允许执行 SELECT 查询。
如果不存在已附加的 materialized view，启用此设置后即可读取数据。请注意，读取的数据通常会从队列中移除。为避免移除已读取的数据，应正确配置相关引擎设置。
## stream\_like\_engine\_insert\_queue
当流式引擎从多个队列中读取时，用户在写入数据时需要选择要插入的队列。Redis Streams 和 NATS 会用到此设置。
## stream\_poll\_timeout\_ms
从流式存储拉取数据/向其发送数据时的轮询超时时间。
## system\_events\_show\_zero\_values
允许从 [`system.events`](/zh/reference/system-tables/events) 中选择值为 0 的事件。
某些监控系统要求在每个检查点都传递所有指标值，即使某个指标值为 0 也是如此。
可能的值：
* 0 — 已禁用。
* 1 — 已启用。
**示例**
查询
```sql theme={null}
SELECT * FROM system.events WHERE event='QueryMemoryLimitExceeded';
```
结果
```text theme={null}
Ok.
```
查询
```sql theme={null}
SET system_events_show_zero_values = 1;
SELECT * FROM system.events WHERE event='QueryMemoryLimitExceeded';
```
结果
```text theme={null}
┌─event────────────────────┬─value─┬─description───────────────────────────────────────────┐
│ QueryMemoryLimitExceeded │ 0 │ Number of times when memory limit exceeded for query. │
└──────────────────────────┴───────┴───────────────────────────────────────────────────────┘
```
## system\_metric\_log\_show\_zero\_values\_in\_histograms
控制是否将零值直方图数据写入 `system.metric_log` 的 `histograms` 嵌套列。
默认情况下，总观测 `count` 为 0 的直方图会被跳过；而在每个已输出的直方图中，没有任何观测的桶条目也会从 `histogram` map 中省略。启用此设置后，无论 `count` 如何，都会写入每个直方图和每个桶——这对于要求每个指标在每个检查点都出现的监控系统很有用。
可能的值：
* 0 — 已禁用。`count = 0` 的直方图不会输出；已输出的直方图仅包含至少有一次观测的桶。
* 1 — 已启用。所有直方图都会被写入，且每个桶边界都会出现在 `histogram` 中。
## table\_engine\_read\_through\_distributed\_cache
仅在 ClickHouse Cloud 中生效。允许通过表引擎 / 表函数 (s3、azure 等) 从分布式缓存中读取数据
## table\_function\_remote\_max\_addresses
设置根据模式为 [remote](/zh/reference/functions/table-functions/remote) 函数生成的地址最大数量。
可能的值：
* 正整数。
## tcp\_keep\_alive\_timeout
在 TCP 开始发送 keepalive 探测之前，连接可保持空闲的时间 (秒)
## temporary\_data\_in\_cache\_reserve\_space\_wait\_lock\_timeout\_milliseconds
为文件系统缓存中的临时数据预留空间时，锁定缓存的等待时间
## temporary\_files\_buffer\_size
用于写入临时 File 的缓冲区大小。缓冲区越大，系统调用越少，但内存消耗也越高。
## temporary\_files\_codec
设置在磁盘上执行排序和连接操作时所用临时 File 的压缩编解码器。
可能的值：
* LZ4 — 使用 [LZ4](https://en.wikipedia.org/wiki/LZ4_\(compression_algorithm\)) 压缩。
* NONE — 不使用压缩。
## text\_index\_density\_threshold
用于在惰性倒排列表模式中选择算法的密度阈值。
低于该阈值：leapfrog 求交。达到或高于该阈值：穷举 bitmap。
## text\_index\_hint\_max\_selectivity
使用基于倒排文本索引构建的提示时，过滤器允许的最大选择性。
## text\_index\_like\_max\_postings\_to\_read
启用通过 dictionary scan 执行 text index LIKE 评估时，可读取的大型 postings 的最大数量。
需要启用 `use_text_index_like_evaluation_by_dictionary_scan`。
## text\_index\_like\_min\_pattern\_length
在 LIKE/ILIKE 模式中，若要使用通过 dictionary scan 进行的文本索引 LIKE 求值，字母数字 `needle` 必须达到的最小长度。
短于此阈值的模式会匹配过多的字典标记，因此会被跳过，以避免高成本扫描。
要求启用 `use_text_index_like_evaluation_by_dictionary_scan`。
## text\_index\_posting\_list\_apply\_mode
控制在文本索引查询期间如何应用倒排列表。
'materialize' (默认) 会立即将倒排列表解码为 Roaring Bitmap。
'lazy' 使用基于游标的按需解码 (需要 V2 索引格式以及 allow\_experimental\_text\_index\_lazy\_apply) 。
## throw\_if\_no\_data\_to\_insert
允许或禁止空 INSERT，默认启用 (空插入时会报错) 。仅适用于通过 [`clickhouse-client`](/zh/concepts/features/interfaces/cli) 或 [gRPC 接口](/zh/concepts/features/interfaces/grpc) 执行的 INSERT。
## throw\_on\_error\_from\_cache\_on\_write\_operations
在对写入操作 (INSERT、合并) 进行缓存时，忽略缓存错误
## throw\_on\_max\_partitions\_per\_insert\_block
用于控制达到 `max_partitions_per_insert_block` 时的行为。
可能的值：
* `true` - 当插入块达到 `max_partitions_per_insert_block` 时，会抛出异常。
* `false` - 当达到 `max_partitions_per_insert_block` 时，会记录一条警告日志。
如果你想了解修改 [`max_partitions_per_insert_block`](/zh/reference/settings/session-settings#max_partitions_per_insert_block) 会对用户产生什么影响，此设置会很有帮助。
## throw\_on\_unsupported\_query\_inside\_transaction
如果在事务内使用了不受支持的查询，则会抛出异常
## timeout\_before\_checking\_execution\_speed
在指定的秒数过去后，检查执行速度是否过慢 (不得低于 `min_execution_speed`) 。
## timeout\_overflow\_mode
设置当查询运行时间超过 `max_execution_time`，或预计运行时间超过 `max_estimated_execution_time` 时的处理方式。
可选值：
* `throw`：抛出异常 (默认值) 。
* `break`：停止执行查询并返回部分结果，就像源数据已经耗尽一样。
## timeout\_overflow\_mode\_leaf
设置叶子节点上的查询运行时间超过 `max_execution_time_leaf` 时的行为。
可能的值：
* `throw`：抛出异常 (默认) 。
* `break`：停止执行查询并返回部分结果，就像
源数据已经耗尽一样。
## totals\_auto\_threshold
`totals_mode = 'auto'` 的阈值。
参见“WITH TOTALS 修饰符”一节。
## totals\_mode
指定在存在 HAVING 时，以及在设置了 max\_rows\_to\_group\_by 且 group\_by\_overflow\_mode = 'any' 时，如何计算 TOTALS。
请参见“WITH TOTALS 修饰符”一节。
## trace\_profile\_events
启用或禁用以下功能：每次更新 profile events 时，收集 stacktraces，并连同 profile event 的名称和增量值一起发送到 [trace\_log](/zh/reference/system-tables/trace_log)。
可能的值：
* 1 — 启用 profile events 追踪。
* 0 — 禁用 profile events 追踪。
## trace\_profile\_events\_list
启用设置 `trace_profile_events` 后，会将被追踪的事件限制为指定的逗号分隔名称列表。
如果 `trace_profile_events_list` 为空字符串 (默认值) ，则会追踪所有 profile events。
示例值：'DiskS3ReadMicroseconds,DiskS3ReadRequestsCount,SelectQueryTimeMicroseconds,ReadBufferFromS3Bytes'
使用此设置可以在查询量很大时更精确地收集数据，因为否则大量事件可能会撑爆内部系统日志队列，导致其中一部分事件被丢弃。
## transfer\_overflow\_mode
设置当数据量超过某一限制时的处理方式。
可能的值：
* `throw`：抛出异常 (默认) 。
* `break`：停止执行查询并返回部分结果，就像
源数据已经耗尽一样。
## transform\_null\_in
启用 [IN](/zh/reference/statements/in) 运算符中 [NULL](/zh/reference/syntax#null) 值的相等比较。
默认情况下，`NULL` 值不能参与比较，因为 `NULL` 表示未定义的值。因此，比较 `expr = NULL` 必须始终返回 `false`。启用此设置后，在 `IN` 运算符中，`NULL = NULL` 将返回 `true`。
可能的值：
* 0 — `IN` 运算符中对 `NULL` 值的比较返回 `false`。
* 1 — `IN` 运算符中对 `NULL` 值的比较返回 `true`。
**示例**
假设有一张 `null_in` 表：
```text theme={null}
┌──idx─┬─────i─┐
│ 1 │ 1 │
│ 2 │ NULL │
│ 3 │ 3 │
└──────┴───────┘
```
查询：
```sql theme={null}
SELECT idx, i FROM null_in WHERE i IN (1, NULL) SETTINGS transform_null_in = 0;
```
结果：
```text theme={null}
┌──idx─┬────i─┐
│ 1 │ 1 │
└──────┴──────┘
```
查询：
```sql theme={null}
SELECT idx, i FROM null_in WHERE i IN (1, NULL) SETTINGS transform_null_in = 1;
```
结果：
```text theme={null}
┌──idx─┬─────i─┐
│ 1 │ 1 │
│ 2 │ NULL │
└──────┴───────┘
```
**另请参阅**
* [IN 运算符中的 NULL 处理](/zh/reference/statements/in#null-processing)
## traverse\_shadow\_remote\_data\_paths
查询 system.remote\_data\_paths 时，除实际表数据外，还会遍历冻结数据 (shadow 目录)
## union\_default\_mode
设置合并 `SELECT` 查询结果的模式。只有在使用 [UNION](/zh/reference/statements/select/union) 且未显式指定 `UNION ALL` 或 `UNION DISTINCT` 时，此设置才会生效。
可能的值：
* `'DISTINCT'` — ClickHouse 在合并查询结果时会去除重复行。
* `'ALL'` — ClickHouse 在合并查询结果时会保留所有行，包括重复行。
* `''` — 与 `UNION` 一起使用时，ClickHouse 会抛出异常。
示例请参见 [UNION](/zh/reference/statements/select/union)。
## unique\_key\_max\_encoded\_size
单个 `UNIQUE KEY` 行的保序二进制编码最大大小 (字节) 。
## unknown\_packet\_in\_send\_data
在第 N 个数据包处发送未知包，而不是数据包
## update\_parallel\_mode
决定并发更新查询的行为。
可能的值：
* `sync` - 按顺序运行所有 `UPDATE` 查询。
* `auto` - 仅按顺序运行那些其更新列与另一查询表达式中使用的列之间存在依赖关系的 `UPDATE` 查询。
* `async` - 不对更新查询进行同步。
## update\_sequential\_consistency
如果为 true，则会在执行更新前先将 parts 集合更新为最新版本。
## url\_base
在 [url](/zh/reference/functions/table-functions/url) 表函数和 [URL](/zh/reference/engines/table-engines/special/url) 表引擎中，用于解析相对 URL 的基准 URL。
设置后，相对 URL 将按以下方式解析：
* 路径相对 URL (例如 `data.csv`) ：根据 RFC 3986 与基准 URL 的路径合并。基准路径中最后一个 `/` 之后的所有内容都会被相对 URL 替换，因此末尾是否带斜杠很重要：`https://example.com/dir/` + `data.csv` = `https://example.com/dir/data.csv`，而 `https://example.com/dir` + `data.csv` = `https://example.com/data.csv`。如果基准 URL 没有路径 (例如 `https://example.com`) ，则会插入一个 `/`：`https://example.com/data.csv`。相对 URL 中的点分段 (`./` 和 `../`) 会被归一化：`https://example.com/dir/` + `../a.csv` = `https://example.com/a.csv`。
* 主机相对 URL (例如 `/test/data.csv`) ：根据基准 URL 的 scheme 和主机解析。
* 协议相对 URL (例如 `//other.com/test/data.csv`) ：使用基准 URL 的协议进行解析。
* 仅包含查询字符串的引用 (例如 `?x=1`) ：追加到基准 URL 的路径后 (替换现有的查询字符串/片段) 。
* 仅包含片段的引用 (例如 `#frag`) ：追加到基准 URL 后，并保留现有的查询字符串 (替换现有片段) 。
* 空引用：返回不带片段的基准 URL。
例如，如果 `url_base` 为 `https://example.com/def/`，则：
* `data.csv` 解析为 `https://example.com/def/data.csv`
* `/test/data.csv` 解析为 `https://example.com/test/data.csv`
* `//other.com/test/data.csv` 解析为 `https://other.com/test/data.csv`
## use\_async\_executor\_for\_materialized\_views
对 materialized view 查询使用异步且可能为多线程的执行方式，可加快 INSERT 期间的视图处理速度，但也会消耗更多内存。
## use\_cache\_for\_count\_from\_files
启用在表函数 `file`/`s3`/`url`/`hdfs`/`azureBlobStorage` 中对文件执行 count 时的行数缓存。
默认启用。
## use\_client\_time\_zone
使用客户端时区来解析 DateTime 字符串值，而不是使用服务器时区。
## use\_compact\_format\_in\_distributed\_parts\_names
对于使用 `Distributed` 引擎的表，在后台 (`distributed_foreground_insert`) 执行 `INSERT` 时，使用紧凑格式存储块。
可能的值：
* 0 — 使用 `user[:password]@host:port#default_database` 目录格式。
* 1 — 使用 `[shard{shard_index}[_replica{replica_index}]]` 目录格式。
- 当 `use_compact_format_in_distributed_parts_names=0` 时，集群定义中的更改不会应用于后台 `INSERT`。
- 当 `use_compact_format_in_distributed_parts_names=1` 时，调整集群定义中节点的顺序会改变 `shard_index`/`replica_index`，请留意。
## use\_concurrency\_control
遵循服务器的并发控制 (请参见全局服务器设置 `concurrent_threads_soft_limit_num` 和 `concurrent_threads_soft_limit_ratio_to_cores`) 。如果禁用，即使服务器已过载，也允许使用更多线程 (不建议在正常使用时这样做，主要仅用于测试) 。
Cloud 默认值：`0`。
## use\_hash\_table\_stats\_for\_join\_reordering
启用在 join 重排序期间使用已收集的哈希表统计信息进行基数估计
## use\_hedged\_requests
为远程查询启用 hedged requests 机制。它允许针对同一查询与不同副本建立多个连接。
如果与副本的现有连接未能在 `hedged_connection_timeout`
内建立，或者在 `receive_data_timeout` 内未收到任何数据，则会启用新连接。查询会使用第一个发送非空 Progress 数据包的连接 (如果启用了 `allow_changing_replica_until_first_data_packet`，则也可以是 Data 数据包) ；
其他连接会被取消。支持 `max_parallel_replicas > 1` 的查询。
默认启用。
Cloud 默认值：`0`。
## use\_hive\_partitioning
启用后，ClickHouse 会在文件类表引擎 [File 表引擎](/zh/reference/functions/table-functions/file#hive-style-partitioning)/[S3](/zh/reference/functions/table-functions/s3#hive-style-partitioning)/[URL](/zh/reference/functions/table-functions/url#hive-style-partitioning)/[HDFS](/zh/reference/functions/table-functions/hdfs#hive-style-partitioning)/[AzureBlobStorage](/zh/reference/functions/table-functions/azureBlobStorage#hive-style-partitioning) 的路径 (`/name=value/`) 中检测 Hive 风格分区，并允许在查询中将分区列作为虚拟列使用。这些虚拟列的名称将与分区路径中的名称相同，但以下划线 `_` 开头。
## use\_iceberg\_metadata\_files\_cache
启用后，Iceberg 表函数和 Iceberg 存储可能会使用 Iceberg 元数据文件缓存。
可选值：
* 0 - 已禁用
* 1 - 已启用
## use\_iceberg\_partition\_pruning
对 Iceberg 表启用 Iceberg 分区裁剪
## use\_index\_for\_in\_with\_subqueries
如果 `IN` 运算符右侧是子查询或表表达式，则尝试使用索引。
## use\_index\_for\_in\_with\_subqueries\_max\_values
IN 运算符右侧集合可使用表索引进行过滤时的最大大小。该设置可避免大查询因构建额外数据结构而导致性能下降和内存占用增加。0 表示不限制。
## use\_join\_disjunctions\_push\_down
启用将 JOIN 条件中由 OR 连接的部分下推到对应的输入侧 (“部分下推”) 。
这样可使存储引擎更早进行过滤，从而减少读取的数据量。
该优化不会改变语义，且仅在每个顶层 OR 分支都至少为目标侧提供一个确定性
谓词时才会应用。
## use\_legacy\_to\_time
启用后，可使用旧版 toTime 函数。该函数会将日期时间转换为某个固定日期，同时保留时间部分。
否则，将使用新的 toTime 函数，它会将不同类型的数据转换为 Time 类型。
旧版函数也始终可通过 toTimeWithFixedDate 直接使用。
## use\_lightweight\_primary\_key\_index\_analysis
优化主键较长的 `MergeTree` 表的主键索引分析。
启用后，索引分析的运行时间主要取决于查询过滤器的复杂度 (即它实际使用的键列) ，而不是主键长度。因此，对于只按其中少数几列进行过滤的查询，扩展排序键几乎不会给索引分析带来额外开销。
可能的值：
* 0 — 已禁用。索引分析期间会处理所有主键列。
* 1 — 已启用。
## use\_page\_cache\_for\_disks\_without\_file\_cache
对未启用文件系统缓存的远程磁盘使用用户态页缓存。
## use\_page\_cache\_for\_local\_disks
从本地磁盘读取时使用用户态页缓存。此设置主要用于测试，实际中不太可能提升性能。要求 `local_filesystem_read_method = 'pread'` 或 `'read'`。它不会禁用操作系统页缓存；如需禁用，可使用 `min_bytes_to_use_direct_io`。仅影响常规表，不影响 `file()` 表函数或 `File()` File 表引擎。
## use\_page\_cache\_for\_object\_storage
从对象存储表函数 (s3、azure、hdfs) 和表引擎 (S3、Azure、HDFS) 读取时，使用用户态页缓存。
## use\_page\_cache\_with\_distributed\_cache
使用分布式缓存时，启用用户态页缓存。
## use\_paimon\_partition\_pruning
对 Paimon 表函数启用 Paimon 分区裁剪
## use\_parquet\_metadata\_cache
启用后，Parquet format 可能会使用 Parquet 元数据缓存。
可能的值：
* 0 - 禁用
* 1 - 启用
## use\_partition\_pruning
**别名**: `use_partition_key`
在 MergeTree 表的查询执行期间，使用分区键进行分区剪枝。
可能的值：
* 0 — 禁用。
* 1 — 启用。
## use\_primary\_key
对于 MergeTree 表，在查询执行期间使用主键进行粒度级剪枝。
可能的值：
* 0 — 禁用。
* 1 — 启用。
## use\_query\_cache
启用后，`SELECT` 查询可使用[查询缓存](/zh/concepts/features/performance/caches/query-cache)。参数 [enable\_reads\_from\_query\_cache](#enable_reads_from_query_cache)
和 [enable\_writes\_to\_query\_cache](#enable_writes_to_query_cache) 可进一步控制缓存的使用方式。
可能的值：
* 0 - 已禁用
* 1 - 已启用
## use\_query\_condition\_cache
启用[查询条件缓存](/zh/concepts/features/performance/caches/query-condition-cache)。该缓存会存储数据分区片段中不满足 `WHERE` 子句条件的粒度范围，
并将这些信息作为临时索引用于后续查询。
可能的值：
* 0 - 已禁用
* 1 - 已启用
## use\_reader\_executor
实验性功能。通过新的管道 `ReaderExecutor` 处理读取，而不是使用旧版读取缓冲区的层层嵌套结构。对于执行器尚未支持的配置，会回退到旧版路径。
## use\_roaring\_bitmap\_iceberg\_positional\_deletes
对 Iceberg 的位置删除使用 roaring bitmap。
## use\_skip\_indexes
在查询执行期间使用数据跳过索引。
可能的值：
* 0 — 禁用。
* 1 — 启用。
## use\_skip\_indexes\_for\_disjunctions
使用跳过索引来评估同时包含 AND 和 OR 的 WHERE 过滤条件。示例：WHERE A = 5 AND (B = 5 OR C = 5)。
如果禁用，跳过索引仍可用于评估 WHERE 条件，但这些条件只能包含用 AND 连接的子句。
可能的值：
* 0 — 禁用。
* 1 — 启用。
## use\_skip\_indexes\_for\_top\_k
启用在 TopK 过滤中使用数据跳过索引。
启用后，如果 `ORDER BY LIMIT n` 查询中的列上存在 minmax 跳过索引，优化器将尝试使用该 minmax 索引跳过与最终结果无关的粒度。这可以降低查询延迟。
可能的值：
* 0 — 已禁用。
* 1 — 已启用。
## use\_skip\_indexes\_if\_final
控制在使用 FINAL 修饰符执行查询时，是否使用跳过索引。
跳过索引可能会排除包含最新数据的行 (粒度) ，从而导致带有 FINAL 修饰符的查询结果不正确。启用此设置后，即使使用 FINAL 修饰符，也会应用跳过索引，这可能提升性能，但也存在遗漏最近更新的风险。此设置应与 use\_skip\_indexes\_if\_final\_exact\_mode 设置同步启用 (默认已启用) 。
可能的值：
* 0 — 禁用。
* 1 — 启用。
## use\_skip\_indexes\_if\_final\_exact\_mode
控制在使用 FINAL 修饰符执行查询时，是否需要在较新的 parts 中扩展跳过索引返回的粒度范围，以确保结果正确。
使用跳过索引时，可能会排除包含最新数据的行 (粒度) ，从而导致结果不正确。此设置会扫描与跳过索引返回范围重叠的较新 parts，以确保返回正确结果。只有在应用可以接受基于跳过索引查找得到的近似结果时，才应禁用此设置。
可能的值：
* 0 — 已禁用。
* 1 — 已启用。
## use\_skip\_indexes\_on\_data\_read
启用在读取数据时使用数据跳过索引。
启用后，跳过索引会在读取每个数据粒度时动态进行评估，而不是在查询开始执行前预先分析。这有助于降低查询启动延迟。
可选值：
* 0 — 已禁用。
* 1 — 已启用。
## use\_statistics
/// 出于与 `use_primary_key` 和 `use_skip_indexes` 保持一致的考虑，优先使用此名称而非 `allow_statistics_optimize`
允许使用统计信息优化查询
## use\_statistics\_cache
在查询中使用统计信息缓存，以避免加载每个 part 的统计信息所带来的开销
## use\_statistics\_for\_part\_pruning
在查询执行期间使用统计信息过滤 parts。
启用后，SELECT 查询中的 pruning 会使用列统计信息 (例如 MinMax 统计信息) ，在读取任何数据之前排除不可能包含匹配数据的 parts。
可能的值：
* 0 — 禁用。
* 1 — 启用。
## use\_strict\_insert\_block\_limits
启用后，会严格同时执行最小和最大插入块大小限制。
在以下情况下会生成一个块：
* 最小阈值 (与) ：当 min\_insert\_block\_size\_rows 和 min\_insert\_block\_size\_bytes 都达到时。
* 最大阈值 (或) ：当 max\_insert\_block\_size\_rows 或 max\_insert\_block\_size\_bytes 任一达到时。
禁用后，在以下情况下会生成一个块：
* 最小阈值 (或) ：当 min\_insert\_block\_size\_rows 或 min\_insert\_block\_size\_bytes 达到时。
**注意**：如果 max 设置小于 min 设置，则 max 限制优先，块会在达到最小阈值之前生成。
**注意**：对于异步插入，此设置会自动禁用，因为异步插入会附加按条目区分的去重标记，而这与强制执行严格限制所需的块拆分不兼容。
默认禁用。
## use\_structure\_from\_insertion\_table\_in\_table\_functions
使用插入表的结构，而不是根据数据进行 schema 推断。可能的值：0 - 已禁用，1 - 已启用，2 - 自动
是否使用反序列化后的文本索引头部缓存。
处理大量文本索引查询时，使用文本索引头部缓存可显著降低延迟并提高吞吐量。
## use\_text\_index\_like\_evaluation\_by\_dictionary\_scan
启用通过扫描倒排文本索引字典来对 LIKE/ILIKE 查询进行求值。
## use\_text\_index\_postings\_cache
是否使用已反序列化的文本索引倒排列表缓存。
对于大量文本索引查询，使用文本索引倒排列表缓存可显著降低延迟并提高吞吐量。
## use\_text\_index\_tokens\_cache
是否使用反序列化后的文本索引标记信息缓存。
处理大量文本索引查询时，使用文本索引标记缓存可显著降低延迟并提高吞吐量。
## use\_top\_k\_dynamic\_filtering
在执行 `ORDER BY LIMIT n` 查询时启用动态过滤优化。
启用后，查询执行器会尝试跳过那些不会进入结果集中最终 `top N` 行的粒度和行。此优化是动态的，延迟改善效果取决于数据分布以及查询中是否存在其他谓词。
可能的值：
* 0 — 已禁用。
* 1 — 已启用。
## use\_top\_k\_dynamic\_filtering\_for\_variable\_length\_types
允许在排序列具有可变长度数据类型 (例如 `String`、`Array`、`Map`、包含可变长度元素的 `Tuple`) 时应用 `use_top_k_dynamic_filtering`。
对于这类类型，如果列中的字典序最小值占主导 (例如大多是空字符串) ，且只能跳过少量粒度，那么动态过滤器执行的逐行阈值比较所带来的开销可能会超过其节省的成本。在这种情况下，动态过滤器非但不能改善查询延迟，反而会使其变差。
当此设置为 `0` 时，动态过滤仅适用于值在内存中具有固定最大大小的列 (数值、`Date`、`DateTime`、`FixedString`、`Enum`、这些类型的 `Nullable` 以及这些类型的 `Tuple`) 。设置为 `1` 时，动态过滤也会应用于可变长度类型。
可能的值：
* 0 — 禁用。
* 1 — 启用。
## use\_uncompressed\_cache
是否使用未压缩块缓存。可接受 0 或 1。默认值为 0 (禁用) 。
使用未压缩缓存 (仅适用于 MergeTree 家族中的表) 可在处理大量短查询时显著降低延迟并提高吞吐量。对于频繁发送短请求的用户，建议启用此设置。同时还要注意 [uncompressed\_cache\_size](/zh/reference/settings/server-settings/settings#uncompressed_cache_size) 配置参数 (只能在 config 文件中设置) ——它表示未压缩缓存块的大小。默认值为 8 GiB。未压缩缓存会按需填充，并自动删除最少使用的数据。
对于读取数据量较大的查询 (100 万行或更多) ，系统会自动禁用未压缩缓存，以便为真正的小查询节省空间。这意味着你可以始终将 `use_uncompressed_cache` 设为 1。
## use\_variant\_as\_common\_type
当参数类型没有公共类型时，允许将 `Variant` 类型用作 [if](/zh/reference/functions/regular-functions/conditional-functions#if)/[multiIf](/zh/reference/functions/regular-functions/conditional-functions#multiIf)/[array](/zh/reference/functions/regular-functions/array-functions)/[map](/zh/reference/functions/regular-functions/tuple-map-functions) 函数的结果类型。
示例：
```sql theme={null}
SET use_variant_as_common_type = 1;
SELECT toTypeName(if(number % 2, number, range(number))) as variant_type FROM numbers(1);
SELECT if(number % 2, number, range(number)) as variant FROM numbers(5);
```
```text theme={null}
┌─variant_type───────────────────┐
│ Variant(Array(UInt64), UInt64) │
└────────────────────────────────┘
┌─variant───┐
│ [] │
│ 1 │
│ [0,1] │
│ 3 │
│ [0,1,2,3] │
└───────────┘
```
```sql theme={null}
SET use_variant_as_common_type = 1;
SELECT toTypeName(multiIf((number % 4) = 0, 42, (number % 4) = 1, [1, 2, 3], (number % 4) = 2, 'Hello, World!', NULL)) AS variant_type FROM numbers(1);
SELECT multiIf((number % 4) = 0, 42, (number % 4) = 1, [1, 2, 3], (number % 4) = 2, 'Hello, World!', NULL) AS variant FROM numbers(4);
```
```text theme={null}
─variant_type─────────────────────────┐
│ Variant(Array(UInt8), String, UInt8) │
└──────────────────────────────────────┘
┌─variant───────┐
│ 42 │
│ [1,2,3] │
│ Hello, World! │
│ ᴺᵁᴸᴸ │
└───────────────┘
```
```sql theme={null}
SET use_variant_as_common_type = 1;
SELECT toTypeName(array(range(number), number, 'str_' || toString(number))) as array_of_variants_type from numbers(1);
SELECT array(range(number), number, 'str_' || toString(number)) as array_of_variants FROM numbers(3);
```
```text theme={null}
┌─array_of_variants_type────────────────────────┐
│ Array(Variant(Array(UInt64), String, UInt64)) │
└───────────────────────────────────────────────┘
┌─array_of_variants─┐
│ [[],0,'str_0'] │
│ [[0],1,'str_1'] │
│ [[0,1],2,'str_2'] │
└───────────────────┘
```
```sql theme={null}
SET use_variant_as_common_type = 1;
SELECT toTypeName(map('a', range(number), 'b', number, 'c', 'str_' || toString(number))) as map_of_variants_type from numbers(1);
SELECT map('a', range(number), 'b', number, 'c', 'str_' || toString(number)) as map_of_variants FROM numbers(3);
```
```text theme={null}
┌─map_of_variants_type────────────────────────────────┐
│ Map(String, Variant(Array(UInt64), String, UInt64)) │
└─────────────────────────────────────────────────────┘
┌─map_of_variants───────────────┐
│ {'a':[],'b':0,'c':'str_0'} │
│ {'a':[0],'b':1,'c':'str_1'} │
│ {'a':[0,1],'b':2,'c':'str_2'} │
└───────────────────────────────┘
```
## use\_variant\_default\_implementation\_for\_comparisons
启用或禁用在比较函数中对 Variant 类型使用默认实现。
## use\_with\_fill\_by\_sorting\_prefix
在 ORDER BY 子句中，位于 WITH FILL 列之前的列构成排序前缀。排序前缀值不同的行会分别填充
## validate\_enum\_literals\_in\_operators
如果启用，则会检查 `IN`、`NOT IN`、`==`、`!=` 等运算符中的枚举字面量是否符合枚举类型；如果字面量不是有效的枚举值，则会抛出异常。
## validate\_mutation\_query
在接受变更查询之前先进行校验。变更会在后台执行，执行无效查询会导致变更卡住，并需要手动干预。
仅当遇到向后不兼容的 bug 时，才应更改此设置。
## validate\_polygons
如果多边形存在自相交或自切情况，则启用或禁用 [pointInPolygon](/zh/reference/functions/regular-functions/geo/coordinates#pointinpolygon) 函数抛出异常。
可能的值：
* 0 — 禁用抛出异常。`pointInPolygon` 接受无效多边形，并可能返回不正确的结果。
* 1 — 启用抛出异常。
## variant\_throw\_on\_type\_mismatch
当使用默认实现对 [Variant](/zh/reference/data-types/variant) 列应用函数时，
该设置用于控制那些实际类型与函数不兼容的行应如何处理：
* `true` (默认) — 抛出异常。
* `false` — 对这些行返回 `NULL`。
## vector\_search\_filter\_strategy
如果向量搜索查询带有 WHERE 子句，则此设置决定是先评估该子句 (前过滤) ，还是先检查向量相似度索引 (后过滤) 。可选值：
* 'auto' - 后过滤 (具体语义未来可能会变化) 。
* 'postfilter' - 使用向量相似度索引识别最近邻，然后再应用其他过滤条件
* 'prefilter' - 先评估其他过滤条件，再执行暴力搜索以识别最近邻。
## vector\_search\_index\_fetch\_multiplier
**别名**: `vector_search_postfilter_multiplier`
将从向量相似度索引中拉取的最近邻数量乘以该值。仅在使用其他谓词进行后过滤时，或在设置 'vector\_search\_with\_rescoring = 1' 时生效。
## vector\_search\_with\_rescoring
控制 ClickHouse 是否对使用向量相似度索引的查询执行 rescoring。
不使用 rescoring 时，向量相似度索引会直接返回包含最佳匹配的行。
使用 rescoring 时，会将行扩展到粒度级别，并重新检查该粒度中的所有行。
在大多数情况下，rescoring 对准确性的提升微乎其微，但会显著降低向量搜索查询的性能。
注意：在不使用 rescoring 且启用了并行副本的情况下运行的查询，可能会回退到使用 rescoring。
## wait\_changes\_become\_visible\_after\_commit\_mode
等待已提交的更改在最新快照中真正可见
## wait\_for\_async\_insert
如果为 true，则等待异步插入处理完成
## wait\_for\_async\_insert\_timeout
等待异步插入处理完成的超时时间
## wait\_for\_part\_commit\_in\_dependent\_materialized\_views
控制每个 sink 是否要在其依赖的 materialized view 级联运行之前，先提交自己刚写入的 part，这样一来，通过 `JOIN` 从源表回读数据的级联就能看到该 sink 写入的 part。
该保证仅针对单个 sink 实例——同一次 `INSERT` 中其他 sink 线程写入的 parts 此时可能仍然不可见。此设置不保证跨线程的提交顺序。
对于插入到没有依赖 materialized views 的表，此设置不起作用。
## wait\_for\_window\_view\_fire\_signal\_timeout
在事件时间处理中等待 window view 触发信号的超时时间
## webassembly\_udf\_max\_fuel
每个 WebAssembly UDF 实例单次执行的 fuel 限制。每条 WebAssembly 指令都会消耗一定量的 fuel。该值在传递给运行时之前会先乘以 1024，因此 `webassembly_udf_max_fuel = 1` 大致对应 1024 个 fuel 单位。设为 0 表示无上限。仅适用于每个函数的 `webassembly_udf_enable_fuel` 设置为 true 的函数，而这也是默认值。
## webassembly\_udf\_max\_input\_block\_size
单个块中传递给 WebAssembly UDF 的最大行数。设置为 0 表示一次处理所有行。
## webassembly\_udf\_max\_instances
每个函数可并行运行的 WebAssembly UDF 实例最大数量。
## webassembly\_udf\_max\_memory
每个 WebAssembly UDF 实例的内存上限 (以字节为单位) 。
## window\_view\_clean\_interval
window view 的清理间隔 (单位：秒) ，用于释放过期数据。
## window\_view\_heartbeat\_interval
用于指示 watch 查询仍处于活动状态的心跳间隔 (以秒为单位) 。
## 工作负载
用于访问资源的工作负载名称
## write\_full\_path\_in\_iceberg\_metadata
将完整路径 (包括 s3://) 写入 Iceberg 元数据文件中。
## write\_through\_distributed\_cache
仅在 ClickHouse Cloud 中生效。允许写入分布式缓存 (写入 S3 也将由分布式缓存执行)
## write\_through\_distributed\_cache\_buffer\_size
仅在 ClickHouse Cloud 中生效。设置写穿分布式缓存的缓冲区大小。如果为 0，则使用在没有分布式缓存时原本会使用的缓冲区大小。
## zstd\_window\_log\_max
允许选择 ZSTD 的最大窗口日志 (不用于 MergeTree 家族)