会话设置

以下所有设置也可在表 system.settings 中找到。这些设置是自动生成的，来自 source。

add_http_cors_header​

写入添加 HTTP CORS 头。

additional_result_filter​

应用于 SELECT 查询结果的附加过滤表达式。 此设置不应用于任何子查询。

示例

INSERT INTO table_1 VALUES (1, 'a'), (2, 'bb'), (3, 'ccc'), (4, 'dddd');
SElECT * FROM table_1;

┌─x─┬─y────┐
│ 1 │ a    │
│ 2 │ bb   │
│ 3 │ ccc  │
│ 4 │ dddd │
└───┴──────┘

SELECT *
FROM table_1
SETTINGS additional_result_filter = 'x != 2'

┌─x─┬─y────┐
│ 1 │ a    │
│ 3 │ ccc  │
│ 4 │ dddd │
└───┴──────┘

additional_table_filters​

在从指定表读取后应用的附加过滤表达式。

示例

INSERT INTO table_1 VALUES (1, 'a'), (2, 'bb'), (3, 'ccc'), (4, 'dddd');
SELECT * FROM table_1;

┌─x─┬─y────┐
│ 1 │ a    │
│ 2 │ bb   │
│ 3 │ ccc  │
│ 4 │ dddd │
└───┴──────┘

SELECT *
FROM table_1
SETTINGS additional_table_filters = {'table_1': 'x != 2'}

┌─x─┬─y────┐
│ 1 │ a    │
│ 3 │ ccc  │
│ 4 │ dddd │
└───┴──────┘

aggregate_functions_null_for_empty​

启用或禁用在查询中重写所有聚合函数，为它们添加 -OrNull 后缀。为了兼容 SQL 标准，请启用此选项。 它是通过查询重写实现的（类似于 count_distinct_implementation 设置），以便为分布式查询获取一致的结果。

可能值：

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

示例

考虑以下带有聚合函数的查询：

SELECT SUM(-1), MAX(0) FROM system.one WHERE 0;

在 aggregate_functions_null_for_empty = 0 时，它会产生：

┌─SUM(-1)─┬─MAX(0)─┐
│       0 │      0 │
└─────────┴────────┘

在 aggregate_functions_null_for_empty = 1 时，结果将是：

┌─SUMOrNull(-1)─┬─MAXOrNull(0)─┐
│          NULL │         NULL │
└───────────────┴──────────────┘

aggregation_in_order_max_block_bytes​

按照主键顺序聚合时块的最大字节大小。较小的块大小可以在聚合的最终合并阶段实现更大的并行性。

aggregation_memory_efficient_merge_threads​

用于以内存高效模式合并中间聚合结果的线程数量。更大时，消耗更多内存。0 表示 - 同 'max_threads'。

allow_aggregate_partitions_independently​

当分区键适合分组键时，启用在单独线程上独立聚合分区。当分区数量接近核心数量且分区大小大致相等时，这是有益的。

allow_archive_path_syntax​

文件/S3 引擎/表函数将解析路径为 '::' 作为 <archive> :: <file>，前提是归档具有正确的扩展名。

allow_asynchronous_read_from_io_pool_for_merge_tree​

使用后台 I/O 池从 MergeTree 表中读取。此设置可以提高 I/O 绑定查询的性能。

allow_changing_replica_until_first_data_packet​

如果启用，在加速请求中，我们可以在接收第一个数据包之前建立新的连接，即使我们已经取得了一些进展 （但进展没有更新到 receive_data_timeout 超时），否则在第一次取得进展后我们禁用更改副本。

allow_create_index_without_type​

允许没有 TYPE 的 CREATE INDEX 查询。查询将被忽略。用于 SQL 兼容性测试。

allow_custom_error_code_in_throwif​

在函数 throwIf() 中启用自定义错误代码。如果为真，抛出的异常可能具有意外的错误代码。

allow_ddl​

如果设置为 true，则用户可以执行 DDL 查询。

allow_deprecated_database_ordinary​

允许创建具有已废弃普通引擎的数据库。

allow_deprecated_error_prone_window_functions​

允许使用已废弃的易出错窗口函数（邻近、runningAccumulate、runningDifferenceStartingWithFirstValue、runningDifference）。

allow_deprecated_snowflake_conversion_functions​

函数 snowflakeToDateTime、snowflakeToDateTime64、dateTimeToSnowflake 和 dateTime64ToSnowflake 已被废弃并默认禁用。 请改用函数 snowflakeIDToDateTime、snowflakeIDToDateTime64、dateTimeToSnowflakeID 和 dateTime64ToSnowflakeID。

要重新启用已废弃的函数（例如，在过渡期间），请将此设置设置为 true。

allow_deprecated_syntax_for_merge_tree​

允许使用已废弃引擎定义语法创建 *MergeTree 表。

allow_distributed_ddl​

如果设置为 true，则用户可以执行分布式 DDL 查询。

allow_drop_detached​

允许执行 ALTER TABLE ... DROP DETACHED PART[ITION] ... 查询。

allow_dynamic_type_in_join_keys​

允许在 JOIN 键中使用动态类型。添加兼容性。由于与其他类型的比较可能导致意外结果，不推荐在 JOIN 键中使用动态类型。

allow_execute_multiif_columnar​

允许以列式模式执行 multiIf 函数。

allow_experimental_analyzer​

允许新查询分析器。

allow_experimental_codecs​

如果设置为 true，允许指定实验性压缩编解码器（但我们还没有这些，且此选项无效）。

allow_experimental_correlated_subqueries​

允许执行相关子查询。

allow_experimental_database_glue_catalog​

允许实验性数据库引擎 DataLakeCatalog，catalog_type = 'glue'。

allow_experimental_database_hms_catalog​

允许实验性数据库引擎 DataLakeCatalog，catalog_type = 'hms'。

allow_experimental_database_iceberg​

允许实验性数据库引擎 DataLakeCatalog，catalog_type = 'iceberg'。

allow_experimental_database_materialized_postgresql​

允许创建数据库，使用 Engine=MaterializedPostgreSQL(...)。

allow_experimental_database_unity_catalog​

允许实验性数据库引擎 DataLakeCatalog，catalog_type = 'unity'。

allow_experimental_delta_kernel_rs​

允许实验性 delta-kernel-rs 实现。

allow_experimental_delta_lake_writes​

启用 delta-kernel 写入功能。

allow_experimental_full_text_index​

如果设置为 true，允许使用实验性文本索引。

allow_experimental_funnel_functions​

启用实验性漏斗分析函数。

allow_experimental_hash_functions​

启用实验性哈希函数。

allow_experimental_iceberg_compaction​

允许明确使用 'OPTIMIZE' 对于 iceberg 表。

allow_experimental_insert_into_iceberg​

允许对 iceberg 执行 insert 查询。

allow_experimental_join_right_table_sorting​

如果设置为 true，并且满足 join_to_sort_minimum_perkey_rows 和 join_to_sort_maximum_table_rows 的条件，那么按键对右边表重新排序以提高左连接或内连接的性能。

allow_experimental_kafka_offsets_storage_in_keeper​

允许实验性功能将与 Kafka 相关的偏移存储在 ClickHouse Keeper 中。当启用时，可以将 ClickHouse Keeper 路径和副本名称指定给 Kafka 表引擎。因此，不使用常规的 Kafka 引擎，而是使用一种新类型的存储引擎，主要在 ClickHouse Keeper 中存储已提交的偏移量。

allow_experimental_kusto_dialect​

启用 Kusto 查询语言 (KQL) - SQL 的替代品。

allow_experimental_live_view​

允许创建已废弃的 LIVE VIEW。

可能的值：

• 0 — 禁用对实时视图的工作。
• 1 — 启用对实时视图的工作。

allow_experimental_materialized_postgresql_table​

允许使用 MaterializedPostgreSQL 表引擎。默认禁用，因为此功能是实验性的。

allow_experimental_nlp_functions​

启用实验性自然语言处理函数。

allow_experimental_object_type​

允许使用过时的对象数据类型。

allow_experimental_parallel_reading_from_replicas​

允许从每个分片中使用最多 max_parallel_replicas 个副本执行 SELECT 查询。读取是并行化和动态协调的。0 - 禁用，1 - 启用，在失败时无声禁用，2 - 启用，在失败时抛出异常。

allow_experimental_prql_dialect​

启用 PRQL - SQL 的替代品。

allow_experimental_qbit_type​

允许创建 QBit 数据类型。

allow_experimental_query_deduplication​

实验性数据去重，用于基于部分 UUID 的 SELECT 查询。

allow_experimental_statistics​

允许定义具有 统计信息 的列，并且能够 操作统计信息。

allow_experimental_time_series_aggregate_functions​

实验性 timeSeries* 聚合函数，用于 Prometheus 类似的时间序列重采样、速率和差异计算。

allow_experimental_time_series_table​

允许创建具有 TimeSeries 表引擎的表。可能的值：

• 0 — TimeSeries 表引擎被禁用。
• 1 — TimeSeries 表引擎被启用。

allow_experimental_time_time64_type​

允许创建 Time 和 Time64 数据类型。

allow_experimental_window_view​

启用窗口视图。尚不成熟。

allow_experimental_ytsaurus_dictionary_source​

实验性字典来源，用于与 YTsaurus 集成。

allow_experimental_ytsaurus_table_engine​

实验性表引擎，用于与 YTsaurus 集成。

allow_experimental_ytsaurus_table_function​

实验性表引擎，用于与 YTsaurus 集成。

allow_general_join_planning​

允许使用更通用的连接规划算法，可以处理更复杂的条件，但仅适用于哈希连接。如果未启用哈希连接，则将使用传统的连接规划算法，而不考虑此设置的值。

allow_get_client_http_header​

允许使用 getClientHTTPHeader 函数来获取当前 HTTP 请求标题的值。出于安全原因，默认未启用此功能，因为某些标题（例如 Cookie）可能包含敏感信息。请注意，X-ClickHouse-* 和 Authentication 标头始终受到限制，无法通过此函数获取。

allow_hyperscan​

允许使用 Hyperscan 库的函数。禁用以避免可能较长的编译时间和过多的资源占用。

allow_introspection_functions​

启用或禁用用于查询剖析的 内省函数。

可能值：

• 1 — 启用内省函数。
• 0 — 禁用内省函数。

另见

• 采样查询分析器
• 系统表 trace_log

allow_materialized_view_with_bad_select​

允许使用引用不存在表或列的 SELECT 查询创建物化视图（MATERIALIZED VIEW）。它仍然必须在语法上有效。该选项不适用于可刷新的 MV。如果 MV 架构需要从 SELECT 查询推断（即 CREATE 缺少列列表且没有 TO 表），则不会使用。可以在其源表之前创建 MV。

allow_named_collection_override_by_default​

允许默认命名集合字段的重写。

allow_non_metadata_alters​

允许执行影响的不仅仅是表元数据的调整，而是还影响磁盘上的数据。

allow_nonconst_timezone_arguments​

允许某些时间相关函数（如 toTimeZone()、fromUnixTimestamp*()、snowflakeToDateTime*()）中的非常量时区参数。 此设置仅存在于兼容性原因。在 ClickHouse 中，时区是数据类型的属性，因此是列的属性。 启用此设置容易给人错觉，认为列中的不同值可以具有不同的时区。 因此，请勿启用此设置。

allow_nondeterministic_mutations​

用户级设置，允许复制表上的变更使用非确定性函数如 dictGet。

考虑到例如字典可以在节点之间不同步，默认情况下不允许从中提取值的变更在复制表上进行。启用此设置允许这种行为，由用户负责确保所使用的数据在所有节点之间保持同步。

示例

<profiles>
    <default>
        <allow_nondeterministic_mutations>1</allow_nondeterministic_mutations>

        <!-- ... -->
    </default>

    <!-- ... -->

</profiles>

allow_nondeterministic_optimize_skip_unused_shards​

允许在分片键中使用非确定性函数（如 rand 或 dictGet，因为后者在更新上有一些陷阱）。

可能值：

• 0 — 不允许。
• 1 — 允许。

allow_not_comparable_types_in_comparison_functions​

允许或限制在比较函数 equal/less/greater/etc 中使用不可比较的类型（如 JSON/对象/聚合函数）。

allow_not_comparable_types_in_order_by​

允许或限制在 ORDER BY 键中使用不可比较的类型（如 JSON/对象/聚合函数）。

allow_prefetched_read_pool_for_local_filesystem​

如果所有部分都位于本地文件系统，则优先考虑预取线程池。

allow_prefetched_read_pool_for_remote_filesystem​

如果所有部分均位于远程文件系统，则优先考虑预取线程池。

allow_push_predicate_ast_for_distributed_subqueries​

允许在启用分析器的分布式子查询的 AST 级别推出谓词。

allow_push_predicate_when_subquery_contains_with​

允许在子查询包含 WITH 子句时推出谓词。

allow_reorder_prewhere_conditions​

移动 WHERE 的条件到 PREWHERE 时，允许重新排序以优化过滤。

allow_settings_after_format_in_insert​

控制在 INSERT 查询中是否允许在 FORMAT 后面使用 SETTINGS。不建议使用此选项，因为这可能将部分 SETTINGS 解释为值。

示例：

INSERT INTO FUNCTION null('foo String') SETTINGS max_threads=1 VALUES ('bar');

但以下查询将仅在 allow_settings_after_format_in_insert 为真时有效：

SET allow_settings_after_format_in_insert=1;
INSERT INTO FUNCTION null('foo String') VALUES ('bar') SETTINGS max_threads=1;

可能值：

• 0 — 禁止。
• 1 — 允许。

allow_simdjson​

允许在 'JSON*' 函数中使用 simdjson 库，如果 AVX2 指令可用。禁用后将使用 rapidjson。

allow_statistics_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 与大小固定为 8 字节或更小的数据类型：数值数据类型和 FixedString(8_bytes_or_less)。

对于小的固定值，使用 LowCardinality 通常效率不高，因为 ClickHouse 为每一行存储一个数值索引。结果：

• 磁盘空间使用可能增加。
• RAM 消耗可能更高，取决于字典的大小。
• 某些函数由于额外的编码/解码操作可能会运行得更慢。

MergeTree 引擎表的合并时间可能因上述所有原因而增加。

可能值：

• 1 — 不限制使用 LowCardinality。
• 0 — 限制使用 LowCardinality。

allow_suspicious_primary_key​

允许可疑的 PRIMARY KEY/ORDER BY 用于 MergeTree（例如 SimpleAggregateFunction）。

allow_suspicious_ttl_expressions​

拒绝不依赖于任何表列的 TTL 表达式。这通常表明用户错误。

allow_suspicious_types_in_group_by​

允许或限制在 GROUP BY 键中使用 Variant 和 Dynamic 类型。

allow_suspicious_types_in_order_by​

允许或限制在 ORDER BY 键中使用 Variant 和 Dynamic 类型。

allow_suspicious_variant_types​

在 CREATE TABLE 语句中，允许指定具有相似变体类型（例如，不同的数值或日期类型）的 Variant 类型。启用此设置可能在处理相似类型值时引入一些模糊性。

allow_unrestricted_reads_from_keeper​

允许无条件地从 system.zookeeper 表中读取，这可能很方便，但对 zookeeper 来说并不安全。

alter_move_to_space_execute_async​

异步执行 ALTER TABLE MOVE ... TO [DISK|VOLUME]。

alter_partition_verbose_result​

启用或禁用成功应用于分区和部分的操作的信息显示。 适用于 ATTACH PARTITION|PART 和 FREEZE PARTITION。

可能值：

• 0 — 禁用详细信息。
• 1 — 启用详细信息。

示例

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​

允许设置在 ALTER、OPTIMIZE 或 TRUNCATE 查询上在副本上等待执行的操作。

可能值：

• 0 — 不等待。
• 1 — 等待自身执行。
• 2 — 等待所有人。

云默认值：1。

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​

允许将复合标识符添加到嵌套。这是一个兼容性设置，因为它会改变查询结果。当禁用时，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) 中，将通过 t1.a + 1 = t2.b 进行连接，而不是 t1.b = t2.b）。

any_join_distinct_right_table_keys​

在 ANY INNER|LEFT JOIN 操作中启用传统的 ClickHouse 服务器行为。

启用传统行为时：

• 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 INNER JOIN 操作的结果从左表和右表各包含一行每个键。

可能值：

• 0 — 禁用传统行为。
• 1 — 启用传统行为。

另见：

• JOIN 严格性

apply_deleted_mask​

启用过滤掉通过轻量级 DELETE 删除的行。如果禁用，查询将能够读取那些行。这对于调试和“取消删除”场景很有用。

apply_mutations_on_fly​

如果为真，则在 SELECT 时应用尚未在数据部分中物化的变更（UPDATE 和 DELETE）。

apply_patch_parts​

如果为真，则在 SELECT 时应用补丁部分（表示轻量级更新）。

apply_patch_parts_join_cache_buckets​

加入模式中应用补丁部分的临时缓存中的桶数。

apply_settings_from_server​

客户端是否应该接受来自服务器的设置。

这仅影响在客户端中执行的操作，特别是解析 INSERT 输入数据和格式化查询结果。大多数查询执行发生在服务器上，并不受此设置的影响。

通常应该在用户配置文件（users.xml 或 ALTER USER 等查询）中设置此设置，而不是通过客户端（客户端命令行参数、SET 查询或 SELECT 查询的 SETTINGS 部分）。通过客户端可以将其更改为 false，但无法更改为 true（因为如果用户配置文件中具有 apply_settings_from_server = false，则服务器不会发送设置）。

请注意，最初（24.12）有一个服务器设置（send_settings_to_client），但后来被此客户端设置取代，以改善可用性。

asterisk_include_alias_columns​

为通配符查询（SELECT *）包括 ALIAS 列。

可能值：

• 0 - 禁用
• 1 - 启用

asterisk_include_materialized_columns​

为通配符查询 (SELECT *) 包括 MATERIALIZED 列。

可能值：

• 0 - 禁用
• 1 - 启用

async_insert​

如果为真，来自 INSERT 查询的数据将存储在队列中，并在后台刷新到表中。如果 wait_for_async_insert 为假，INSERT 查询几乎会立即被处理，否则客户端将等待直到数据被刷新到表中。

async_insert_busy_timeout_decrease_rate​

自适应异步插入超时降低的指数增长率。

async_insert_busy_timeout_increase_rate​

自适应异步插入超时增加的指数增长率。

async_insert_busy_timeout_max_ms​

自第一次数据出现以来每个查询的最大等待时间。

async_insert_busy_timeout_min_ms​

如果通过 async_insert_use_adaptive_busy_timeout 启用自动调整，则在第一个数据出现后，每次查询收集数据之前要等待的最短时间。它也作为自适应算法的初始值。

async_insert_deduplicate​

对于在复制表中的异步 INSERT 查询，指定应执行插入块的去重。

async_insert_max_data_size​

每个查询收集的未经解析的数据的最大字节大小，在插入之前。

async_insert_max_query_number​

在插入之前的最大插入查询数。仅在设置 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​

在执行远程查询时，启用从套接字异步读取。

默认启用。

azure_allow_parallel_part_upload​

使用多个线程进行 Azure 多部分上传。

azure_check_objects_after_upload​

检查每个上传的对象在 Azure Blob 存储中确保上传成功。

azure_connect_timeout_ms​

Azure 磁盘主机的连接超时。

azure_create_new_file_on_insert​

在每次插入 Azure 引擎表时启用或禁用创建新文件。

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 请求每秒的限制。零表示无限制。

azure_max_inflight_parts_for_one_file​

在多部分上传请求中，单个文件的最大并发加载部分数。0 表示无限制。

azure_max_put_burst​

在触及每秒请求限制之前，可以同时发出的最大请求数。默认（0）等于 azure_max_put_rps。

azure_max_put_rps​

在输出限流之前，Azure PUT 请求每秒的限制。零表示无限制。

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 发送和接收数据的空闲超时。如果单个 TCP 读取或写入调用阻塞超过此时间，则失败。

azure_sdk_max_retries​

Azure SDK 中的最大重试次数。

azure_sdk_retry_initial_backoff_ms​

Azure SDK 中重试之间的最小退避时间（毫秒）。

azure_sdk_retry_max_backoff_ms​

Azure SDK 中重试之间的最大退避时间（毫秒）。

azure_sdk_use_native_client​

对 Azure SDK 使用 ClickHouse 原生 HTTP 客户端。

azure_skip_empty_files​

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

可能的值：

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

azure_strict_upload_part_size​

在向 Azure Blob 存储进行多部分上传期间上传部分的确切大小。

azure_throw_on_zero_files_match​

如果根据通配符扩展规则匹配零文件则抛出错误。

可能的值：

• 1 — SELECT 抛出异常。
• 0 — SELECT 返回空结果。

azure_truncate_on_insert​

启用或禁用在 Azure 引擎表中插入之前进行截断。

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 发送的最大批大小。

backup_restore_failure_after_host_disconnected_for_seconds​

如果在 BACKUP ON CLUSTER 或 RESTORE ON CLUSTER 操作期间，主机在此时间段内未能在 ZooKeeper 中重建其短暂的“存活”节点，则整个备份或恢复将被视为失败。此值应大于主机在故障后重新连接到 ZooKeeper 的任何合理时间。零表示无限制。

backup_restore_finish_timeout_after_error_sec​

发起者应等待多长时间，以便其他主机对“错误”节点做出反应并停止其在当前 BACKUP ON CLUSTER 或 RESTORE ON CLUSTER 操作中的工作。

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 操作期间，ZooKeeper 操作的最大重试次数。应足够大，以便整个操作不会因为暂时的 ZooKeeper 故障而失败。

backup_restore_keeper_max_retries_while_handling_error​

在处理 BACKUP ON CLUSTER 或 RESTORE ON CLUSTER 操作错误时，ZooKeeper 操作的最大重试次数。

backup_restore_keeper_max_retries_while_initializing​

在初始化 BACKUP ON CLUSTER 或 RESTORE ON CLUSTER 操作期间，ZooKeeper 操作的最大重试次数。

backup_restore_keeper_retry_initial_backoff_ms​

在备份或恢复期间，ZooKeeper 操作的初始退避超时。

backup_restore_keeper_retry_max_backoff_ms​

在备份或恢复期间，ZooKeeper 操作的最大退避超时。

backup_restore_keeper_value_max_size​

在备份期间，ZooKeeper 节点的最大数据大小。

backup_restore_s3_retry_attempts​

覆盖 Aws::Client::RetryStrategy 的设置，Aws::Client 自行进行重试，0 意味着没有重试。仅适用于备份/恢复。

backup_restore_s3_retry_initial_backoff_ms​

在备份和恢复期间，第一次重试尝试之前的初始退避延迟（毫秒）。每个后续重试将延迟指数增加，直到达到 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​

在备份和恢复操作期间，重试之间的最大延迟（毫秒）。

cache_warmer_threads​

仅在 ClickHouse Cloud 中有效。在启用 cache_populated_by_fetch 时，后台线程的数量用于投机性下载新数据部分到文件缓存。零表示禁用。

calculate_text_stack_trace​

在查询执行期间发生异常时计算文本堆栈跟踪。这是默认值。它需要符号查找，可能会在执行大量错误查询时减慢模糊测试。在正常情况下，您不应该禁用此选项。

cancel_http_readonly_queries_on_client_close​

在客户端关闭连接而不等待响应时，取消 HTTP 只读查询（例如 SELECT）。

云默认值：0。

cast_ipv4_ipv6_default_on_conversion_error​

CAST 操作符转向 IPv4、CAST 操作符转向 IPV6 类型，toIPv4、toIPv6 函数将在转换错误时返回默认值，而不是抛出异常。

cast_keep_nullable​

启用或禁用在 CAST 操作中保留 Nullable 数据类型。

当设置为启用并且 CAST 函数的参数为 Nullable 时，结果也转化为 Nullable 类型。当设置为禁用时，结果始终具有确切的目标类型。

可能的值：

• 0 — CAST 结果有确切的目标类型。
• 1 — 如果参数类型为 Nullable，则 CAST 结果转化为 Nullable(DestinationDataType)。

示例

以下查询结果具有确切的目标数据类型：

SET cast_keep_nullable = 0;
SELECT CAST(toNullable(toInt32(0)) AS Int32) as x, toTypeName(x);

结果：

┌─x─┬─toTypeName(CAST(toNullable(toInt32(0)), 'Int32'))─┐
│ 0 │ Int32                                             │
└───┴───────────────────────────────────────────────────┘

以下查询结果在目标数据类型上有 Nullable 修改：

SET cast_keep_nullable = 1;
SELECT CAST(toNullable(toInt32(0)) AS Int32) as x, toTypeName(x);

结果：

┌─x─┬─toTypeName(CAST(toNullable(toInt32(0)), 'Int32'))─┐
│ 0 │ Nullable(Int32)                                   │
└───┴───────────────────────────────────────────────────┘

另见

• CAST 函数

cast_string_to_date_time_mode​

允许在从字符串转换时选择日期和时间的文本表示解析器。

可能的值：

• 'best_effort' — 启用扩展解析。

  ClickHouse 可以解析基本的 YYYY-MM-DD HH:MM:SS 格式以及所有 ISO 8601 日期和时间格式。例如，'2018-06-08T01:02:03.000Z'。

• 'best_effort_us' — 类似于 best_effort（请查看 parseDateTimeBestEffortUS 中的区别）。

• 'basic' — 使用基本解析器。

  ClickHouse 只能够解析基本的 YYYY-MM-DD HH:MM:SS 或 YYYY-MM-DD 格式。例如，2019-08-20 10:18:56 或 2019-08-20。

另见：

• DateTime 数据类型。
• 用于处理日期和时间的函数。

cast_string_to_dynamic_use_inference​

在字符串到动态转换期间使用类型推断。

cast_string_to_variant_use_inference​

在字符串到变体转换期间使用类型推断。

check_query_single_value_result​

定义 MergeTree 系列引擎的 CHECK TABLE 查询结果的详细程度。

可能的值：

• 0 — 查询显示每个数据部分的检查状态。
• 1 — 查询显示一般的表检查状态。

check_referential_table_dependencies​

检查 DDL 查询（如 DROP TABLE 或 RENAME）不会破坏引用依赖关系。

check_table_dependencies​

检查 DDL 查询（如 DROP TABLE 或 RENAME）不会破坏依赖关系。

checksum_on_read​

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

cloud_mode​

云模式。

cloud_mode_database_engine​

云中允许的数据库引擎。 1 - 重写 DDL 使用复制数据库，2 - 重写 DDL 使用共享数据库。

cloud_mode_engine​

云中允许的引擎系列。

• 0 - 允许一切。
• 1 - 重写 DDL 使用 *ReplicatedMergeTree。
• 2 - 重写 DDL 使用 SharedMergeTree。
• 3 - 重写 DDL 使用 SharedMergeTree，除非明确传递了指定的远程磁盘。

UInt64以最小化公共部分。

cluster_for_parallel_replicas​

当前服务器所在分片的集群。

cluster_function_process_archive_on_multiple_nodes​

如果设置为 true，则提高在集群函数中处理档案的性能。若在早期版本中使用带档案的集群函数，则应将其设置为 false 以确保兼容性并避免在升级到 25.7+ 时的错误。

collect_hash_table_stats_during_aggregation​

启用收集哈希表统计数据以优化内存分配。

collect_hash_table_stats_during_joins​

启用收集哈希表统计数据以优化内存分配。

compatibility​

compatibility 设置使 ClickHouse 使用之前版本 ClickHouse 的默认设置，之前版本作为设置提供。

如果设置为非默认值，则会遵循这些设置（仅未修改的设置会受到 compatibility 设置的影响）。

该设置接受字符串格式的 ClickHouse 版本号，如 22.3、22.8。空值表示禁用此设置。

默认禁用。

compatibility_ignore_auto_increment_in_create_table​

如果为 true，则在列声明中忽略 AUTO_INCREMENT 关键字，否则返回错误。它简化了从 MySQL 的迁移。

compatibility_ignore_collation_in_create_table​

在创建表时的兼容性忽略排序规则。

compile_aggregate_expressions​

启用或禁用将聚合函数 JIT 编译为本地代码。启用此设置可以提高性能。

可能的值：

• 0 — 无需 JIT 编译即可完成聚合。
• 1 — 使用 JIT 编译完成聚合。

另见

• min_count_to_compile_aggregate_expression

compile_expressions​

将某些标量函数和运算符编译为本地代码。

compile_sort_description​

将排序描述编译为本地代码。

connect_timeout​

如果没有副本，则连接超时。

connect_timeout_with_failover_ms​

在集群定义中使用“分片”和“副本”部分时，连接到远程服务器的超时时间（毫秒）。如果连接不成功，将尝试多次连接到不同的副本。

connect_timeout_with_failover_secure_ms​

选择第一个健康副本的连接超时（安全连接）。

connection_pool_max_wait_ms​

连接池满时等待获取连接的时间（毫秒）。

可能的值：

• 正整数。
• 0 — 无限超时。

connections_with_failover_max_tries​

用于分布式表引擎的每个副本的最大连接尝试次数。

convert_query_to_cnf​

当设置为 true 时，SELECT 查询将转换为合取范式（CNF）。在某些情况下，将查询重写为 CNF 可能执行得更快（可以查看这个 Github 问题 进行解释）。

例如，注意以下 SELECT 查询未被修改（默认行为）：

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

结果是：

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

让我们将 convert_query_to_cnf 设置为 true 看看有什么变化：

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

注意 WHERE 子句被重写为 CNF，但结果集保持不变 - 布尔逻辑未改变：

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

可能的值：true, false。

correlated_subqueries_substitute_equivalent_expressions​

使用过滤表达式推断等效表达式，并在创建 CROSS JOIN 时替换这些表达式。

count_distinct_implementation​

指定应使用哪一个 uniq* 函数来执行 COUNT(DISTINCT ...) 结构。

可能的值：

• uniq
• uniqCombined
• uniqCombined64
• uniqHLL12
• uniqExact

count_distinct_optimization​

将计数不同重写为分组的子查询。

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 中压缩的最小块大小。零值表示禁用此阈值。当达到行或字节中的任何两个阈值时，将压缩此块。

cross_join_min_rows_to_compress​

在 CROSS JOIN 中压缩块的最小行数。零值表示禁用此阈值。当达到行或字节中的任何两个阈值时，将压缩此块。

data_type_default_nullable​

允许没有显式修饰符 NULL 或 NOT NULL 的数据类型在列定义中为 Nullable。

可能的值：

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

database_atomic_wait_for_drop_and_detach_synchronously​

为所有 DROP 和 DETACH 查询添加修饰符 SYNC。

可能的值：

• 0 — 查询将在延迟下执行。
• 1 — 查询将立即执行。

database_replicated_allow_explicit_uuid​

0 - 不允许在复制数据库的表中显式指定 UUID。1 - 允许。2 - 允许，但忽略指定的 UUID 并生成一个随机的 UUID。

database_replicated_allow_heavy_create​

允许在复制数据库引擎中运行长时间的 DDL 查询（CREATE AS SELECT 和 POPULATE）。请注意，它可能会长时间阻塞 DDL 队列。

database_replicated_allow_only_replicated_engine​

在复制的数据库中仅允许创建 Replicated 表。

database_replicated_allow_replicated_engine_arguments​

0 - 不允许在复制数据库中为 *MergeTree 表显式指定 ZooKeeper 路径和副本名称。1 - 允许。2 - 允许，但忽略指定的路径，并使用默认路径。3 - 允许，并且不记录警告。

database_replicated_always_detach_permanently​

如果数据库引擎是 Replicated，则将 DETACH TABLE 执行为 DETACH TABLE PERMANENTLY。

database_replicated_enforce_synchronous_settings​

强制某些查询（另请参见 database_atomic_wait_for_drop_and_detach_synchronously、mutations_sync、alter_sync）同步等待。建议不要启用这些设置。

database_replicated_initial_query_timeout_sec​

设置初始 DDL 查询在复制数据库处理之前的 DDL 队列条目时的等待时间（秒）。

可能的值：

• 正整数。
• 0 — 无限期。

decimal_check_overflow​

检查十进制运算/比较操作的溢出。

deduplicate_blocks_in_dependent_materialized_views​

启用或禁用对接收来自 Replicated* 表数据的物化视图的去重检查。

可能的值： 0 — 禁用。 1 — 启用。

启用时，ClickHouse 会在依赖于 Replicated* 表的物化视图中执行块的去重。此设置对于确保当由于故障重试插入操作时，物化视图不包含重复数据非常有用。

另见

• 在重试中处理 NULL 的处理

default_materialized_view_sql_security​

允许在创建物化视图时设置 SQL SECURITY 选项的默认值。 有关 SQL 安全性的更多信息。

默认值为 DEFINER。

default_max_bytes_in_join​

如果需要限制而未设置 max_bytes_in_join，则右侧表的最大大小。

default_normal_view_sql_security​

允许在创建普通视图时设置默认 SQL SECURITY 选项。 有关 SQL 安全性的更多信息。

默认值为 INVOKER。

default_table_engine​

在 CREATE 语句中未设置 ENGINE 时使用的默认表引擎。

可能的值：

• 代表任何有效表引擎名称的字符串。

云默认值：SharedMergeTree。

示例

查询：

SET default_table_engine = 'Log';

SELECT name, value, changed FROM system.settings WHERE name = 'default_table_engine';

结果：

┌─name─────────────────┬─value─┬─changed─┐
│ default_table_engine │ Log   │       1 │
└──────────────────────┴───────┴─────────┘

在此示例中，任何未指定 Engine 的新表将使用 Log 表引擎：

查询：

CREATE TABLE my_table (
    x UInt32,
    y UInt32
);

SHOW CREATE TABLE my_table;

结果：

┌─statement────────────────────────────────────────────────────────────────┐
│ CREATE TABLE default.my_table
(
    `x` UInt32,
    `y` UInt32
)
ENGINE = Log
└──────────────────────────────────────────────────────────────────────────┘

default_temporary_table_engine​

与 default_table_engine 相同，但用于临时表。

在此示例中，任何未指定 Engine 的新临时表将使用 Log 表引擎：

查询：

SET default_temporary_table_engine = 'Log';

CREATE TEMPORARY TABLE my_table (
    x UInt32,
    y UInt32
);

SHOW CREATE TEMPORARY TABLE my_table;

结果：

┌─statement────────────────────────────────────────────────────────────────┐
│ CREATE TEMPORARY TABLE default.my_table
(
    `x` UInt32,
    `y` UInt32
)
ENGINE = Log
└──────────────────────────────────────────────────────────────────────────┘

default_view_definer​

允许在创建视图时设置默认的 DEFINER 选项。 关于 SQL 安全性更多信息。

默认值为 CURRENT_USER。

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_snapshot_version​

要读取的 delta lake 快照版本。值 -1 表示读取最新版本（值 0 是有效的快照版本）。

delta_lake_throw_on_engine_predicate_error​

如果在 delta-kernel 中分析扫描谓词时发生错误，则启用抛出异常。

describe_compact_output​

如果为 true，则只包括列名和类型到 DESCRIBE 查询的结果中。

describe_extend_object_types​

推断 DESCRIBE 查询中 Object 类型列的具体类型。

describe_include_subcolumns​

启用在 DESCRIBE 查询中描述子列。例如，元组中的成员或字典、Nullable 或数组数据类型的子列。

可能的值：

• 0 — 不包括子列在 DESCRIBE 查询中。
• 1 — 包括子列在 DESCRIBE 查询中。

示例

查看 DESCRIBE 语句的示例。

describe_include_virtual_columns​

如果为 true，表的虚拟列将包括在 DESCRIBE 查询的结果中。

dialect​

将用于解析查询的方言。

dictionary_validate_primary_key_type​

验证字典的主键类型。对于简单布局，默认 id 类型将隐式转换为 UInt64。

distinct_overflow_mode​

设置当数据量超过其中一个限制时发生的事情。

可能的值：

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

distributed_aggregation_memory_efficient​

是否启用分布式聚合的节省内存模式。

distributed_background_insert_batch​

启用/禁用插入数据以批量发送。

当启用批量发送时，Distributed 表引擎尝试在一次操作中发送多个插入数据的文件，而不是单独发送。批量发送通过更好地利用服务器和网络资源提高集群性能。

可能的值：

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

distributed_background_insert_max_sleep_time_ms​

Distributed 表引擎发送数据的最大间隔。限制 distributed_background_insert_sleep_time_ms 设置中设定的间隔的指数增长。

可能的值：

• 正整数毫秒数。

distributed_background_insert_sleep_time_ms​

Distributed 表引擎发送数据的基数间隔。实际的间隔在发生错误时会指数增长。

可能的值：

• 正整数毫秒数。

distributed_background_insert_split_batch_on_failure​

启用/禁用在失败时拆分批次。

有时将特定批次发送到远程分片可能会失败，因为在其后的某些复杂管道（例如带有 GROUP BY 的 MATERIALIZED VIEW）中可能由于 Memory limit exceeded 等类似错误而导致。在这种情况下，重试将无济于事（这将阻止分布式发送），但逐个发送该批次中的文件可能会成功进行 INSERT。

因此，将该设置安装为 1 将禁用这些批次的批量处理（即临时禁用失败批次的 distributed_background_insert_batch）。

可能的值：

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

distributed_background_insert_timeout​

分布式插入查询的超时。该设置仅在启用 insert_distributed_sync 时使用。零值表示没有超时。

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_credentials_refresh_period_seconds​

仅在 ClickHouse Cloud 中有效。凭据刷新的周期。

distributed_cache_data_packet_ack_window​

仅在 ClickHouse Cloud 中有效。在单个分布式缓存读取请求中发送数据包 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_log_mode​

仅在 ClickHouse Cloud 中有效。对于系统.logs 记录的写入模式。

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 中有效。等待接收任何类型响应的毫秒数。

distributed_cache_throw_on_error​

仅在 ClickHouse Cloud 中有效。在与分布式缓存通信时重新抛出发生的异常或从分布式缓存接收到的异常。否则，退回到错误时跳过分布式缓存。

distributed_cache_wait_connection_from_pool_milliseconds​

仅在 ClickHouse Cloud 中有效。如果 distributed_cache_pool_behaviour_on_limit 设置为 wait，等待从连接池获得连接的毫秒数。

distributed_connections_pool_size​

用于与远程服务器进行分布式处理的所有查询的最大并发连接数。我们建议设置的值不少于集群中服务器的数量。

distributed_ddl_entry_format_version​

分布式 DDL（ON CLUSTER）查询的兼容版本。

distributed_ddl_output_mode​

设置分布式 DDL 查询结果的格式。

可能的值：

• throw — 返回执行状态的结果集，适用于查询已完成的所有主机。如果某些主机上的查询失败，则将重新抛出第一次异常。如果某些主机上的查询尚未完成并且超过了 distributed_ddl_task_timeout，则将抛出 TIMEOUT_EXCEEDED 异常。
• none — 与抛出类似，但分布式 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 数据库的非活动副本。

云端默认值：throw。

distributed_ddl_task_timeout​

设置来自集群中所有主机的 DDL 查询响应超时。如果在所有主机上没有执行 DDL 请求，则响应将包含超时错误，请求将以异步模式执行。负值表示无限制。

可能的值：

• 正整数。
• 0 — 异步模式。
• 负整数 — 无限超时。

distributed_foreground_insert​

启用或禁用对 Distributed 表的同步数据插入。

默认情况下，当将数据插入到 Distributed 表时，ClickHouse 服务器会在后台模式下将数据发送到集群节点。当 distributed_foreground_insert=1 时，数据以同步方式处理，只有在所有分片上的所有数据都保存后（如果 internal_replication 为 true，则每个分片至少一个副本）INSERT 操作才会成功。

可能的值：

• 0 — 数据在后台模式下插入。
• 1 — 数据以同步模式插入。

云端默认值：0。

另见

• 分布式表引擎
• 管理分布式表

distributed_group_by_no_merge​

在分布式查询处理中，未能合并来自不同服务器的聚合状态，如果可以确认在不同的分片上有不同的键，可以使用此设置。

可能的值：

• 0 — 禁用（最终查询处理在发起节点上完成）。
• 1 - 不合并来自不同服务器的聚合状态进行分布式查询处理（查询在分片上完全处理，发起节点仅代理数据），如果确认在不同分片上有不同的键，则可以使用此设置。
• 2 - 与 1 相同，但在发起节点上应用 ORDER BY 和 LIMIT（当查询在远程节点完全处理时，如 distributed_group_by_no_merge=1，则无法执行）。

示例

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 │
└───────┘

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_insert_skip_read_only_replicas​

启用跳过只读副本的 INSERT 查询到 Distributed。

可能的值：

• 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​

强制分布式查询阶段之间的指定类型交换操作符。

可能的值：

• '' - 不强制任何类型的交换操作符，允许优化器选择，
• 'Persisted' - 使用对象存储中的临时文件，
• 'Streaming' - 在网络上传输交换数据。

distributed_plan_force_shuffle_aggregation​

在分布式查询计划中使用 Shuffle 聚合策略，而不是 PartialAggregation + Merge。

distributed_plan_max_rows_to_broadcast​

在分布式查询计划中，广播连接所使用的最大行数，而不是 shuffle 连接。

distributed_plan_optimize_exchanges​

在分布式查询计划中移除不必要的交换。对于调试，请禁用它。

distributed_product_mode​

更改 分布式子查询 的行为。

ClickHouse 在查询包含分布式表的乘积时应用此设置，即当分布式表的查询包含对该分布式表的非全局子查询时。

限制：

• 仅适用于 IN 和 JOIN 子查询。
• 仅在 FROM 部分使用包含多个分片的分布式表时适用。
• 如果子查询涉及包含多个分片的分布式表。
• 不用于表值 remote 函数。

可能的值：

• deny — 默认值。禁止使用这些类型的子查询（返回“禁止双重分布的 in/JOIN 子查询”异常）。
• local — 在子查询中将数据库和表替换为目标服务器（分片）的本地表，保留正常的IN/JOIN。
• global — 用 GLOBAL IN/GLOBAL JOIN 替换 IN/JOIN 查询。
• allow — 允许使用这些类型的子查询。

distributed_push_down_limit​

启用或禁用在每个分片上单独应用 LIMIT。

这将避免：

• 通过网络发送额外的行；
• 在发起节点处理超出限制的行。

从 21.9 版本开始，您不再会获得不准确的结果，因为 distributed_push_down_limit 仅在满足至少一个条件时才会改变查询执行：

• distributed_group_by_no_merge > 0。
• 查询 没有 GROUP BY/DISTINCT/LIMIT BY，但它有 ORDER BY/LIMIT。
• 查询 有 GROUP BY/DISTINCT/LIMIT BY 带有 ORDER BY/LIMIT 以及：
  • optimize_skip_unused_shards 被启用。
  • optimize_distributed_group_by_sharding_key 被启用。

可能的值：

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

另见：

• distributed_group_by_no_merge
• optimize_skip_unused_shards
• optimize_distributed_group_by_sharding_key

distributed_replica_error_cap​

• 类型：无符号整型
• 默认值：1000

每个副本的错误计数限制在此值，不允许单个副本累积过多错误。

另见：

• load_balancing
• 表引擎 Distributed
• distributed_replica_error_half_life
• distributed_replica_max_ignored_errors

distributed_replica_error_half_life​

• 类型：秒
• 默认值：60秒

控制分布式表中错误归零的速度。如果某个副本在一段时间内不可用，累积 5 个错误，并且 distributed_replica_error_half_life 设置为 1 秒，则在最后一个错误后的 3 秒内，该副本被视为正常。

另见：

• load_balancing
• 表引擎 Distributed
• distributed_replica_error_cap
• distributed_replica_max_ignored_errors

distributed_replica_max_ignored_errors​

• 类型：无符号整型
• 默认值：0

在选择副本时将忽略的错误数（根据 load_balancing 算法）。

另见：

• load_balancing
• 表引擎 Distributed
• distributed_replica_error_cap
• distributed_replica_error_half_life

do_not_merge_across_partitions_select_final​

在 select final 中仅在一个分区合并部分。

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_blob_storage_log​

将有关 blob 存储操作的信息写入 system.blob_storage_log 表。

enable_deflate_qpl_codec​

如果启用，可以使用 DEFLATE_QPL 编解码器压缩列。

enable_early_constant_folding​

启用查询优化，其中我们分析函数和子查询结果，如果存在常量则重写查询。

enable_extended_results_for_datetime_functions​

启用或禁用返回扩展范围的 Date32 类型（与 Date 类型相比）或扩展范围的 DateTime64（与 DateTime 类型相比）的结果。

可能的值：

• 0 — 对所有类型的参数，函数返回 Date 或 DateTime。
• 1 — 函数对 Date32 或 DateTime64 参数返回 Date32 或 DateTime64，而其他情况返回 Date 或 DateTime。

下表展示了该设置对各种日期时间函数的行为。

enable_filesystem_cache​

为远程文件系统使用缓存。此设置不会打开/关闭磁盘的缓存（必须通过磁盘配置完成），但允许在某些查询中绕过缓存（如果有意）。

enable_filesystem_cache_log​

允许记录每个查询的文件系统缓存日志。

enable_filesystem_cache_on_write_operations​

启用或禁用 write-through 缓存。如果设置为 false，则在写操作中禁用 write-through 缓存。如果设置为 true，则只有在服务器配置的缓存磁盘配置部分中开启 cache_on_write_operations 时，才启用 write-through 缓存。 有关更多详细信息，请参阅"使用本地缓存"。

enable_filesystem_read_prefetches_log​

在查询期间记录系统.filesystem prefetch_log。仅应在测试或调试中使用，不建议默认开启。

enable_global_with_statement​

将 WITH 语句传播到 UNION 查询和所有子查询。

enable_hdfs_pread​

启用或禁用 HDFS 文件的 pread。默认情况下使用 hdfsPread。如果禁用，将使用 hdfsRead 和 hdfsSeek 来读取 hdfs 文件。

enable_http_compression​

启用或禁用对 HTTP 请求的响应进行数据压缩。

有关更多信息，请阅读 HTTP 接口描述。

可能的值：

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

enable_job_stack_trace​

当作业结果发生异常时输出作业创建者的堆栈跟踪。默认情况下禁用，以避免性能开销。

enable_join_runtime_filters​

通过在运行时从右侧收集的 JOIN 键集过滤左侧。

enable_lightweight_delete​

启用轻量级 DELETE 变更以用于 mergetree 表。

enable_lightweight_update​

允许使用轻量级更新。

enable_memory_bound_merging_of_aggregation_results​

启用内存限制的聚合合并策略。

enable_multiple_prewhere_read_steps​

将更多条件从 WHERE 移动到 PREWHERE，并在存在多个 AND 条件时以多个步骤从磁盘读取和过滤。

enable_named_columns_in_function_tuple​

在 function 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​

允许将谓词推送到最终子查询。

enable_order_by_all​

启用或禁用带有 ORDER BY ALL 语法的排序，详见 ORDER BY。

可能的值：

• 0 — 禁用 ORDER BY ALL。
• 1 — 启用 ORDER BY ALL。

示例

查询：

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; -- returns an error that ALL is ambiguous

SELECT * FROM TAB ORDER BY ALL SETTINGS enable_order_by_all = 0;

结果：

┌─C1─┬─C2─┬─ALL─┐
│ 20 │ 20 │  10 │
│ 30 │ 10 │  20 │
│ 10 │ 20 │  30 │
└────┴────┴─────┘

enable_parallel_blocks_marshalling​

仅影响分布式查询。如果启用，块将在管道线程上进行（反）序列化和（解）压缩（即在默认并行度以上）在发送给发起者之前/之后。

enable_parsing_to_custom_serialization​

如果为真，则数据可以直接解析为具有自定义序列化（例如 Sparse）的列，按照从表中获得的序列化提示。

enable_positional_arguments​

启用或禁用支持位置参数用于 GROUP BY、LIMIT BY、ORDER BY 语句。

可能的值：

• 0 — 不支持位置参数。
• 1 — 支持位置参数：可以使用列编号代替列名。

示例

查询：

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;

结果：

┌─one─┬─two─┬─three─┐
│  30 │  10 │   20  │
│  20 │  20 │   10  │
│  10 │  20 │   30  │
└─────┴─────┴───────┘

enable_producing_buckets_out_of_order_in_aggregation​

允许内存高效聚合（见 distributed_aggregation_memory_efficient）生成无序的桶。 这可能在聚合桶大小不均衡时提高性能，让副本在处理一些较小的桶时仍然可以将具有更大 id 的桶发送给发起者。 缺点是可能会增加内存使用。

enable_reads_from_query_cache​

如果启用，SELECT 查询的结果将从 查询缓存 中获取。

可能的值：

• 0 - 禁用
• 1 - 启用

enable_s3_requests_logging​

启用 S3 请求的详细日志记录。仅用于调试。

enable_scalar_subquery_optimization​

如果设为真，防止标量子查询（反）序列化大型标量值，有可能避免多次运行相同的子查询。

enable_scopes_for_with_statement​

如果禁用，父级 WITH 子句中的声明将在当前作用域中表现出相同的作用域。

请注意，这是一个兼容性设置，旨在允许运行一些旧分析器能够执行的无效查询。

enable_shared_storage_snapshot_in_query​

如果启用，单个查询内的所有子查询将共享每个表的相同 StorageSnapshot。 这确保了在整个查询中对数据的一致视图，即使是同一表被访问多次。

对于数据部分的内部一致性很重要的查询，这是必需的。示例：

SELECT
    count()
FROM events
WHERE (_part, _part_offset) IN (
    SELECT _part, _part_offset
    FROM events
    WHERE user_id = 42
)

没有这个设置，外部和内部查询可能会在不同的数据快照上操作，导致结果不正确。

可能的值：

• 0 - 禁用
• 1 - 启用

enable_sharing_sets_for_mutations​

允许在相同变更的不同任务之间共享为 IN 子查询构建的集合对象。这样可以减少内存使用和 CPU 消耗。

enable_software_prefetch_in_aggregation​

启用在聚合中的软件预取。

enable_unaligned_array_join​

允许与大小不同的多个数组进行 ARRAY JOIN。当启用此设置时，数组将调整为最长的数组。

enable_url_encoding​

允许在 URL 引擎表中启用/禁用对 uri 路径的解码/编码。

默认情况下禁用。

enable_vertical_final​

如果启用，在 FINAL 期间通过将行标记为删除并稍后过滤它们来移除重复行，而不是合并行。

enable_writes_to_query_cache​

如果启用，SELECT 查询的结果将存储在 查询缓存 中。

可能的值：

• 0 - 禁用
• 1 - 启用

enable_zstd_qat_codec​

如果启用，可以使用 ZSTD_QAT 编解码器来压缩列。

enforce_strict_identifier_format​

如果启用，仅允许包含字母数字字符和下划线的标识符。

engine_file_allow_create_multiple_files​

启用或禁用在文件引擎表中每次插入时创建新文件，如果格式有后缀（JSON、ORC、Parquet 等）。如果启用，每次插入将创建一个新文件，名称遵循以下模式：

data.Parquet -> data.1.Parquet -> data.2.Parquet，以此类推。

可能的值：

• 0 — INSERT 查询将新数据附加到文件末尾。
• 1 — INSERT 查询将创建一个新文件。

engine_file_empty_if_not_exists​

允许从没有文件的文件引擎表中选择数据。

可能的值：

• 0 — SELECT 抛出异常。
• 1 — SELECT 返回空结果。

engine_file_skip_empty_files​

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

可能的值：

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

engine_file_truncate_on_insert​

启用或禁用在 File 引擎表中插入时截断。

可能的值：

• 0 — INSERT 查询将新数据附加到文件末尾。
• 1 — INSERT 查询将用新数据替换文件的现有内容。

engine_url_skip_empty_files​

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

可能的值：

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

except_default_mode​

设置 EXCEPT 查询中的默认模式。可能的值：空字符串、'ALL'、'DISTINCT'。如果为空，则没有模式的查询将抛出异常。

exclude_materialize_skip_indexes_on_insert​

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

如果 materialize_skip_indexes_on_insert 为 false，则无效。

示例：

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

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

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

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

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

SET exclude_materialize_skip_indexes_on_insert = DEFAULT; -- reset setting to default

execute_exists_as_scalar_subquery​

将非相关的 EXISTS 子查询作为标量子查询执行。对于标量子查询，使用缓存，并且常量折叠适用于结果。

external_storage_connect_timeout_sec​

连接超时（秒）。目前仅支持 MySQL。

external_storage_max_read_bytes​

限制外部引擎表在刷新历史数据时的最大字节数。当前仅支持 MySQL 表引擎、数据库引擎和字典。如果等于 0，则该设置无效。

external_storage_max_read_rows​

限制外部引擎表在刷新历史数据时的最大行数。当前仅支持 MySQL 表引擎、数据库引擎和字典。如果等于 0，则该设置无效。

external_storage_rw_timeout_sec​

读取/写入超时（秒）。目前仅支持 MySQL。

external_table_functions_use_nulls​

定义 mysql、postgresql 和 odbc 表函数如何使用 Nullable 列。

可能的值：

• 0 — 表函数明确使用 Nullable 列。
• 1 — 表函数隐式使用 Nullable 列。

用法

如果设置为 0，表函数不会生成 Nullable 列，并在 NULL 处插入默认值。这也适用于数组中的 NULL 值。

external_table_strict_query​

如果设置为 true，则禁止将表达式转化为外部表查询的本地过滤器。

extract_key_value_pairs_max_pairs_per_row​

通过 extractKeyValuePairs 函数生成的最大对数。作为防止过多内存消耗的保障措施。

extremes​

是否计算极值（查询结果中列的最小值和最大值）。接受 0 或 1。默认值为 0（禁用）。更多信息，请参见“极值”部分。

fallback_to_stale_replicas_for_distributed_queries​

如果更新的数据不可用，则强制查询切换到过期副本。请参见 复制。

ClickHouse 会从过期的表副本中选择最相关的。

在进行 SELECT 从指向复制表的分布式表时使用。

默认为 1（启用）。

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​

如果启用文件系统缓存，则优先选择更大的缓冲区大小，以避免写入小文件段，这会降低缓存性能。另一方面，启用此设置可能会增加内存使用。

filesystem_cache_reserve_space_wait_lock_timeout_milliseconds​

锁定缓存以进行空间保留的等待时间。

filesystem_cache_segments_batch_size​

限制读取缓冲区可以从缓存请求的单个批次的文件段的大小。过低的值会导致对缓存的请求过多，过大的值可能会减慢从缓存中逐出。

filesystem_cache_skip_download_if_exceeds_per_query_cache_write_limit​

如果超过查询缓存大小，则跳过从远程文件系统的下载。

filesystem_prefetch_max_memory_usage​

预取的最大内存使用量。

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​

最大预取次数。零表示无限。如果想要限制预取次数，建议设置 filesystem_prefetches_max_memory_usage。

final​

自动对查询中所有表应用 FINAL 修饰符，对适用的表（包括连接表和子查询中的表）以及分布式表。

可能的值：

• 0 - 禁用
• 1 - 启用

示例：

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

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

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

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

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

flatten_nested​

设置 nested 列的数据格式。

可能的值：

• 1 — 嵌套列被展平为单独的数组。
• 0 — 嵌套列保留为单一的元组数组。

用法

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

示例

查询：

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

SHOW CREATE TABLE t_nest;

结果：

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

查询：

SET flatten_nested = 0;

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

SHOW CREATE TABLE t_nest;

结果：

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

force_aggregate_partitions_independently​

强制在适用时使用优化，但启发式决定不使用。

force_aggregation_in_order​

该设置由服务器本身使用以支持分布式查询。请勿手动更改，因为这会破坏正常操作。（强制在分布式聚合期间在远程节点上按顺序使用聚合）。

force_data_skipping_indices​

如果未使用传递的数据跳过索引，则禁用查询执行。

考虑以下示例：

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=''; -- query will produce CANNOT_PARSE_TEXT error.
SELECT * FROM data_01515 SETTINGS force_data_skipping_indices='d1_idx'; -- query will produce INDEX_NOT_USED error.
SELECT * FROM data_01515 WHERE d1 = 0 SETTINGS force_data_skipping_indices='d1_idx'; -- Ok.
SELECT * FROM data_01515 WHERE d1 = 0 SETTINGS force_data_skipping_indices='`d1_idx`'; -- Ok (example of full featured parser).
SELECT * FROM data_01515 WHERE d1 = 0 SETTINGS force_data_skipping_indices='`d1_idx`, d1_null_idx'; -- query will produce INDEX_NOT_USED error, since d1_null_idx is not used.
SELECT * FROM data_01515 WHERE d1 = 0 AND assumeNotNull(d1_null) = 0 SETTINGS force_data_skipping_indices='`d1_idx`, d1_null_idx'; -- Ok.

force_grouping_standard_compatibility​

使 GROUPING 函数在参数未用作聚合键时返回 1。

force_index_by_date​

如果无法按日期索引，则禁用查询执行。

适用于 MergeTree 家族的表。

如果 force_index_by_date=1，ClickHouse 将检查查询是否具有可以用来限制数据范围的日期键条件。如果没有合适的条件，它将抛出异常。然而，它不会检查条件是否减少了要读取的数据量。例如，条件 Date != ' 2000-01-01 ' 是可接受的，即使它匹配了表中的所有数据（即，运行查询要求进行完全扫描）。有关 MergeTree 表中的数据范围的更多信息，请参见 MergeTree。

force_optimize_projection​

启用或禁用在启用投影优化时 SELECT 查询强制使用 投影。

可能的值：

• 0 — 投影优化不是强制性的。
• 1 — 投影优化是强制性的。

force_optimize_projection_name​

如果设置为非空字符串，则检查此投影是否至少在查询中使用一次。

可能的值：

• 字符串：在查询中使用的投影名称。

force_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））取决于分布式查询的嵌套级别（例如，当你有 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。

force_remove_data_recursively_on_drop​

在 DROP 查询中递归地删除数据。避免“目录不空”错误，但可能会默默删除已分离的数据。

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。默认为启用。

如果服务器有数百万个持续创建和销毁的小表，禁用它是合理的。

function_date_trunc_return_type_behavior​

允许更改 dateTrunc 函数结果类型的行为。

可能的值：

• 0 - 当第二个参数为 DateTime64/Date32 时，返回类型为 DateTime64/Date32，与第一个参数中的时间单位无关。
• 1 - 对于 Date32，结果始终为 Date。对于 DateTime64，如果时间单位为 second 及更高，结果为 DateTime。

function_implementation​

选择特定目标或变体（实验性）的函数实现。如果为空则启用所有实现。

function_json_value_return_type_allow_complex​

控制 json_value 函数是否允许返回复杂类型（例如：结构、数组、映射）。

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。

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 中参数的顺序。

可能的值：

• 0 — 函数 locate 接受参数 (haystack, needle[, start_pos])。
• 1 — 函数 locate 接受参数 (needle, haystack, [, start_pos])（与 MySQL 兼容的行为）。

function_range_max_elements_in_block​

设置函数 range 生成的数据量的安全阈值。定义每个数据块生成的最大值数量（每块每行数组大小的总和）。

可能的值：

• 正整数。

另见

• max_block_size
• min_insert_block_size_rows

function_sleep_max_microseconds_per_block​

函数 sleep 允许每块暂停的最大微秒数。如果用户使用更大的值调用它，抛出异常。这是一个安全阈值。

function_visible_width_behavior​

visibleWidth 行为的版本。0 - 仅计算代码点数量；1 - 正确计算零宽字符和组合字符，将全宽字符计为两个，估算制表符宽度，计算删除字符。

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_max_buckets​

宽松哈希连接桶的数量限制。

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 子句 如何对聚合键的类型进行处理。 当使用 ROLLUP、CUBE 或 GROUPING SETS 指定器时，一些聚合键可能不会被用于生成某些结果行。 这些键对应的列根据此设置用默认值或 NULL 填充。

可能的值：

• 0 — 使用聚合键类型的默认值来生成缺失值。
• 1 — ClickHouse 按照 SQL 标准的方式执行 GROUP BY。聚合键的类型被转换为 Nullable。对于未使用的行，对应聚合键的列填充 NULL。

另见：

• GROUP BY 子句

h3togeo_lon_lat_result_order​

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

handshake_timeout_ms​

握手期间接收 Hello 数据包的超时时间（毫秒）。

hdfs_create_new_file_on_insert​

启用或禁用在 HDFS 引擎表中的每次插入时创建新文件。如果启用，在每次插入时将创建一个新 HDFS 文件，其名称类似于以下模式：

初始：data.Parquet.gz -> data.1.Parquet.gz -> data.2.Parquet.gz 等等。

可能的值：

• 0 — INSERT 查询将新数据附加到文件末尾。
• 1 — INSERT 查询创建一个新文件。

hdfs_ignore_file_doesnt_exist​

在读取某些键时，如果文件不存在，则忽略文件不存在的情况。

可能的值：

• 1 — SELECT 返回空结果。
• 0 — SELECT 抛出异常。

hdfs_replication​

创建 hdfs 文件时可以指定实际的复制数量。

hdfs_skip_empty_files​

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

可能的值：

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

hdfs_throw_on_zero_files_match​

如果根据 glob 扩展规则匹配到零个文件则抛出错误。

可能的值：

• 1 — SELECT 抛出异常。
• 0 — SELECT 返回空结果。

hdfs_truncate_on_insert​

启用或禁用在 hdfs 引擎表中插入之前进行截断。如果禁用，如果 HDFS 中已存在文件，则在尝试插入时将抛出异常。

可能的值：

• 0 — INSERT 查询将新数据附加到文件末尾。
• 1 — INSERT 查询用新数据替换文件的现有内容。

hedged_connection_timeout_ms​

为 Hedged 请求建立与副本的连接的超时。

hnsw_candidate_list_size_for_search​

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

hsts_max_age​

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

http_connection_timeout​

HTTP 连接超时（以秒为单位）。

可能的值：

• 任何正整数。
• 0 - 禁用（无限超时）。

http_headers_progress_interval_ms​

在每个指定间隔内不要更频繁地发送 HTTP 头 X-ClickHouse-Progress。

http_make_head_request​

http_make_head_request 设置允许在从 HTTP 读取数据时执行 HEAD 请求，以检索要读取的文件的信息，例如其大小。由于默认启用，因此在服务器不支持 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 参数解析，应该在用户配置文件中设置。请注意，在查询执行开始之前，会解析内容并在内存中创建外部表。这是唯一对该阶段有效的限制（最大内存使用量和最大执行时间的限制在读取 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 接口说明。

可能的值：

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

http_receive_timeout​

HTTP 接收超时（以秒为单位）。

可能的值：

• 任何正整数。
• 0 - 禁用（无限超时）。

http_response_buffer_size​

在向客户端发送 HTTP 响应或刷新到磁盘（当 http_wait_end_of_query 启用时）之前要缓冲的字节数。

http_response_headers​

允许添加或覆盖服务器在成功查询结果的响应中返回的 HTTP 头。这只影响 HTTP 接口。

如果头已经默认设置，提供的值将覆盖它。如果头没有默认设置，它将被添加到头列表中。由服务器默认设置而未被此设置覆盖的头将保留。

该设置允许你将头设置为常量值。目前还没有办法将头设置为动态计算的值。

名称和值都不能包含 ASCII 控制字符。

如果你实现了允许用户修改设置的 UI 应用程序，同时根据返回的头做出决策，建议将此设置限制为只读。

示例：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 - 禁用（无限超时）。

http_skip_not_found_url_for_globs​

对具有 HTTP_NOT_FOUND 错误的 glob 跳过 URL。

http_wait_end_of_query​

在服务器端启用 HTTP 响应缓冲。

http_write_exception_in_output_format​

在输出格式中写入异常以生成有效输出。适用于 JSON 和 XML 格式。

http_zlib_compression_level​

设置对 HTTP 请求的响应中数据压缩的级别，如果 enable_http_compression = 1。

可能的值：数字 1 到 9。

iceberg_delete_data_on_drop​

在删除时是否删除所有 iceberg 文件。

iceberg_insert_max_bytes_in_data_file​

插入操作中 iceberg parquet 数据文件的最大字节数。

iceberg_insert_max_rows_in_data_file​

插入操作中 iceberg parquet 数据文件的最大行数。

iceberg_metadata_compression_method​

压缩 .metadata.json 文件的方法。

iceberg_metadata_log_level​

控制 Iceberg 表的元数据日志记录级别到 system.iceberg_metadata_log。通常此设置可以为调试目的进行修改。

可能的值：

• none - 无元数据日志。
• metadata - 根 metadata.json 文件。
• manifest_list_metadata - 上述所有 + 来自与快照对应的 avro 清单列表的元数据。
• manifest_list_entry - 上述所有 + avro 清单列表条目。
• manifest_file_metadata - 上述所有 + 来源于已遍历的 avro 清单文件的元数据。
• manifest_file_entry - 上述所有 + 已遍历的 avro 清单文件条目。

iceberg_snapshot_id​

使用特定快照 ID 查询 Iceberg 表。

iceberg_timestamp_ms​

使用在特定时间戳时的快照查询 Iceberg 表。

idle_connection_timeout​

在指定时间（以秒为单位）后关闭空闲 TCP 连接的超时。

可能的值：

• 正整数（0 - 立即关闭，0 秒后）。

ignore_cold_parts_seconds​

仅在 ClickHouse Cloud 中生效。将新数据片排除在 SELECT 查询之外，直到它们被预热（请参见 cache_populated_by_fetch）或此多秒钟旧。仅适用于 Replicated-/SharedMergeTree。

ignore_data_skipping_indices​

如果查询中使用指定的数据跳过索引，则忽略这些索引。

考虑以下示例：

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=''; -- query will produce CANNOT_PARSE_TEXT error.
SELECT * FROM data SETTINGS ignore_data_skipping_indices='x_idx'; -- Ok.
SELECT * FROM data SETTINGS ignore_data_skipping_indices='na_idx'; -- Ok.

SELECT * FROM data WHERE x = 1 AND y = 1 SETTINGS ignore_data_skipping_indices='xy_idx',force_data_skipping_indices='xy_idx' ; -- query will produce INDEX_NOT_USED error, since xy_idx is explicitly ignored.
SELECT * FROM data WHERE x = 1 AND y = 2 SETTINGS ignore_data_skipping_indices='xy_idx';

查询未忽略任何索引：

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 索引：

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​

如果启用，服务器将忽略具有指定概率的所有 DROP 表查询（对于 Memory 和 JOIN 引擎，将 DROP 替换为 TRUNCATE）。用于测试目的。

ignore_materialized_views_with_dropped_target_table​

在推送到视图期间忽略有目标表被删除的物化视图。

ignore_on_cluster_for_replicated_access_entities_queries​

忽略复制访问实体管理查询的 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​

如果启用且尚未在事务中，则将查询包装在完整事务中（开始 + 提交或回滚）。

input_format_parallel_parsing​

启用或禁用数据格式的顺序保持并行解析。仅支持 TSV、TSKV、CSV 和 JSONEachRow 格式。

可能的值：

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

insert_allow_materialized_columns​

如果设置启用，允许在 INSERT 中使用物化列。

insert_deduplicate​

启用或禁用 INSERT 的块去重（对于 Replicated* 表）。

可能的值：

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

默认情况下，通过 INSERT 语句插入到复制表中的块会被去重（请参阅 数据复制）。对于复制表，默认情况下，每个分区仅去重最近的 100 个块（请参阅 replicated_deduplication_window、replicated_deduplication_window_seconds）。对于未复制的表，请参见 non_replicated_deduplication_window。

insert_deduplication_token​

该设置允许用户在 MergeTree/ReplicatedMergeTree 中提供自己的去重语义。例如，通过在每个 INSERT 语句中提供一个唯一值，用户可以避免重复插入的数据被去重。

可能的值：

• 任何字符串

insert_deduplication_token 仅在非空时用于去重。

对于复制表，默认情况下，每个分区仅去重最近的 100 个插入（请参阅 replicated_deduplication_window、replicated_deduplication_window_seconds）。对于未复制的表，请参见 non_replicated_deduplication_window。

示例：

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);

-- the next insert won't be deduplicated because insert_deduplication_token is different
INSERT INTO test_table SETTINGS insert_deduplication_token = 'test1' VALUES (1);

-- the next insert will be deduplicated because insert_deduplication_token
-- is the same as one of the previous
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​

该设置设置在插入到复制 MergeTree 时 ClickHouse Keeper（或 ZooKeeper）请求的最大重试次数。仅考虑因网络错误、Keeper 会话超时或请求超时而失败的 Keeper 请求。

可能的值：

• 正整数。
• 0 — 禁用重试。

云默认值：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。

除了容错，重试旨在提供更好的用户体验 - 例如，允许在 INSERT 执行期间避免返回错误，如果 Keeper 由于升级而重新启动。

insert_keeper_retry_initial_backoff_ms​

执行 INSERT 查询时重试失败的 Keeper 请求的初始超时（以毫秒为单位）。

可能的值：

• 正整数。
• 0 — 无超时。

insert_keeper_retry_max_backoff_ms​

执行 INSERT 查询时重试失败的 Keeper 请求的最大超时（以毫秒为单位）。

可能的值：

• 正整数。
• 0 — 最大超时没有限制。

insert_null_as_default​

启用或禁用在非 nullable 数据类型的列中插入 默认值 而不是 NULL。如果列类型非空且此设置禁用，则插入 NULL 会导致异常。如果列类型可为空，则无论此设置如何，NULL 值都是原样插入的。

此设置适用于 INSERT ... SELECT 查询。请注意，SELECT 子查询可以与 UNION ALL 子句连接。

可能的值：

• 0 — 在非空列中插入 NULL 导致异常。
• 1 — 插入默认列值而不是 NULL。

insert_quorum​

启用 quorum 写入。

• 如果 insert_quorum < 2，则禁用 quorum 写入。
• 如果 insert_quorum >= 2，则启用 quorum 写入。
• 如果 insert_quorum = 'auto'，则使用多数数（number_of_replicas / 2 + 1）作为 quorum 数。

quorum 写入

INSERT 仅在 ClickHouse 成功地将数据写入到 insert_quorum 的副本中，并在 insert_quorum_timeout 内成功完成时才成功。如果由于任何原因，成功写入的副本数量未达到 insert_quorum，则视为写入失败，ClickHouse 将从所有已写入数据的副本中删除插入的块。

当 insert_quorum_parallel 被禁用时，quorum 中的所有副本都保持一致，即它们包含所有先前 INSERT 查询的数据（INSERT 序列是线性化的）。在读取使用 insert_quorum 和 insert_quorum_parallel 禁用时写入的数据时，可以通过使用 select_sequential_consistency 开启 SELECT 查询的顺序一致性。

ClickHouse 会生成异常：

• 如果查询时可用副本的数量少于 insert_quorum。
• 禁用 insert_quorum_parallel 时，如果尝试在上一个块尚未在 insert_quorum 的副本中插入时写入数据。这种情况可能发生在用户尝试在上一个带有 insert_quorum 的查询完成之前对同一表执行另一个 INSERT 查询时。

另请参见：

• insert_quorum_timeout
• insert_quorum_parallel
• select_sequential_consistency

insert_quorum_parallel​

启用或禁用 quorum INSERT 查询的并行性。如果启用，可以在先前查询尚未完成的情况下发送额外的 INSERT 查询。如果禁用，将拒绝对同一表的额外写入。

可能的值：

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

另请参见：

• insert_quorum
• insert_quorum_timeout
• select_sequential_consistency

insert_quorum_timeout​

以毫秒为单位的对 quorum 写入的超时。如果超时已过而尚未进行任何写入，ClickHouse 将生成异常，客户必须重复查询以将同一块写入同一或其他副本。

另请参见：

• insert_quorum
• insert_quorum_parallel
• select_sequential_consistency

insert_shard_id​

如果不为 0，则指定将数据同步插入的 Distributed 表的分片。

如果 insert_shard_id 值不正确，服务器将抛出异常。

要获取 requested_cluster 上的分片数量，您可以检查服务器配置或使用以下查询：

SELECT uniq(shard_num) FROM system.clusters WHERE cluster = 'requested_cluster';

可能的值：

• 0 — 禁用。
• 从 1 到相应的 Distributed 表的 shards_num 的任何数字。

示例

查询：

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;

结果：

┌─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​

在追踪日志中收集 jemalloc 分配和释放样本。

jemalloc_enable_profiler​

为查询启用 jemalloc 个人分析器。jemalloc 将采样分配及所有已采样分配的释放。可以使用 SYSTEM JEMALLOC FLUSH PROFILE 刷新配置，这可以用于分配分析。样本也可以使用配置 jemalloc_collect_global_profile_samples_in_trace_log 存储在 system.trace_log 中，或使用查询设置 jemalloc_collect_profile_samples_in_trace_log。有关更多信息，请参阅 分配分析。

join_algorithm​

指定使用哪个 JOIN 算法。

可以指定多个算法，并且会根据类型/严格性和表引擎为特定查询选择可用的算法。

可能的值：

• grace_hash

使用 Grace hash join。Grace hash 提供了一种算法选项，能够在限制内存使用时提高复杂连接的性能。

配置哈希桶的个数（N），根据关键列的哈希值将右表分割成 N 个桶。每个桶可以独立处理。第一阶段会读取右表并分割，若哈希表超出内存限制（例如，由 max_bytes_in_join 限制），则增大桶的个数并重新分配每行。

支持 INNER/LEFT/RIGHT/FULL ALL/ANY JOIN。

• hash

使用 Hash join algorithm。最通用的实现，支持所有的类型和严格性、多个用 OR 结合的连接键的组合。

使用 hash 算法时，连接的右侧部分会上传到内存。

• parallel_hash

hash 连接的一种变体，将数据分割成多个桶并同时构建多个哈希表，以加快此过程。

使用 parallel_hash 算法时，连接的右侧部分会上传到内存。

• partial_merge

sort-merge algorithm 的变体，只有右表是完全排序的。

仅支持 RIGHT JOIN 和 FULL JOIN，且必须采用 ALL 的严格性（不支持 SEMI、ANTI、ANY 和 ASOF）。

ClickHouse 会按连接键的顺序对右表进行排序，然后将其转储到磁盘，以保证 order 和 min-max 索引的块排序。左侧的数据会被分块排序后，将其与右侧表进行 join。在此操作的过程中，也利用 min-max 索引以跳过右边无需的块。

• direct

此算法可以在右表存储支持键值请求时应用。

此 direct 算法会使用来自左表的行作为键，在右表中进行查找。仅支持特殊存储，如 Dictionary 或 EmbeddedRocksDB，并仅支持 LEFT 和 INNER JOIN。

• auto

设置为 auto 时，首先尝试使用 hash 进行连接，并在内存限制被违反时动态切换到其他算法。

• full_sorting_merge

Sort-merge algorithm 在加入之前对连接的表进行完全排序。

• prefer_partial_merge

ClickHouse 始终尝试使用 partial_merge 连接，如果不可能，则使用 hash。*不推荐使用，与 partial_merge,hash 相同。

• default (deprecated)

遗留值，请勿再使用。与 direct,hash 相同，也就是说，尝试使用 direct join 和 hash join（按此顺序）。

join_any_take_last_row​

更改 ANY 严格性的连接操作行为。

可能的值：

• 0 — 如果右表有多个匹配行，则仅连接找到的第一条。
• 1 — 如果右表有多个匹配行，则连接找到的最后一条。

另请参见：

• JOIN 子句
• Join 表引擎
• join_default_strictness

join_default_strictness​

为 JOIN 子句 设置默认严格性。

可能的值：

• ALL — 如果右表有多个匹配行，ClickHouse 会从匹配行中创建一个 笛卡尔积。这是标准 SQL 的正常 JOIN 行为。
• ANY — 如果右表有多个匹配行，则仅连接找到的第一条。如果右表仅有一行匹配，则 ANY 和 ALL 的结果是相同的。
• ASOF — 用于连接具有不确定匹配的序列。
• 空字符串 — 如果查询中未指定 ALL 或 ANY，ClickHouse 将抛出异常。

join_on_disk_max_files_to_merge​

限制在 MergeJoin 操作时允许在磁盘上并行排序的文件数量。

设置的值越大，使用的 RAM 越多，磁盘 I/O 需求越少。

可能的值：

• 任何正整数，起始值为 2。

join_output_by_rowlist_perkey_rows_threshold​

右表中每个键的平均行数的下限，以确定在哈希连接中是否按行列表输出。

join_overflow_mode​

定义 ClickHouse 在达到以下任意连接限制时执行的操作：

• max_bytes_in_join
• max_rows_in_join

可能的值：

• THROW — ClickHouse 抛出异常并中断操作。
• BREAK — ClickHouse 中断操作而不抛出异常。

默认值：THROW。

另请参见

• JOIN 子句
• Join 表引擎

join_runtime_bloom_filter_bytes​

作为 JOIN 运行时过滤器使用的布隆过滤器的大小（以字节为单位）（请参见 enable_join_runtime_filters 设置）。

join_runtime_bloom_filter_hash_functions​

作为 JOIN 运行时过滤器使用的布隆过滤器中的哈希函数数量（请参见 enable_join_runtime_filters 设置）。

join_to_sort_maximum_table_rows​

右表中的最大行数，用于确定在左连接或内连接中是否按键重新排列右表。

join_to_sort_minimum_perkey_rows​

右表中每个键的平均行数的下限，用于确定在左连接或内连接中是否按键重新排列右表。此设置确保优化不应用于稀疏表键。

join_use_nulls​

设置JOIN行为的类型。在合并表时，可能会出现空单元格。ClickHouse根据此设置以不同的方式填充它们。

可能的值：

• 0 — 空单元格用相应字段类型的默认值填充。
• 1 — JOIN的行为与标准SQL相同。相应字段的类型被转换为Nullable，并且空单元格用NULL填充。

joined_subquery_requires_alias​

强制连接子查询和表函数具有别名以进行正确的名称限定。

kafka_disable_num_consumers_limit​

禁用依赖于可用CPU核心数量的kafka_num_consumers限制。

kafka_max_wait_ms​

从Kafka读取消息前的等待时间（以毫秒为单位）。

可能的值：

• 正整数。
• 0 — 无限超时。

另见：

• Apache Kafka

keeper_map_strict_mode​

在KeeperMap操作中强制执行额外检查。例如：在插入已存在键时抛出异常。

keeper_max_retries​

通用keeper操作的最大重试次数。

keeper_retry_initial_backoff_ms​

通用keeper操作的初始退避超时时间。

keeper_retry_max_backoff_ms​

通用keeper操作的最大退避超时时间。

least_greatest_legacy_null_behavior​

如果启用，函数'least'和'greatest'在其参数之一为NULL时返回NULL。

legacy_column_name_of_tuple_literal​

将大型元组文字的所有元素名称列在它们的列名称中，而不是哈希。此设置仅出于兼容性原因存在。在将集群从低于21.7版本逐步更新到更高版本时，将其设置为'true'是有意义的。

lightweight_delete_mode​

轻量级删除的一种内部更新查询模式。

可能的值：

• alter_update - 运行创建较重突变的ALTER UPDATE查询。
• lightweight_update - 在可能的情况下运行轻量级更新，否则运行ALTER UPDATE。
• lightweight_update_force - 若可能则运行轻量级更新，否则抛出异常。

lightweight_deletes_sync​

与mutations_sync相同，但仅控制轻量级删除的执行。

可能的值：

另见

• ALTER 查询的同步性
• 突变

limit​

设置从查询结果中获取的最大行数。它会调整由LIMIT子句设置的值，以确保查询中指定的限制不能超过该设置所设定的限制。

可能的值：

• 0 — 行数没有限制。
• 正整数。

live_view_heartbeat_interval​

心跳间隔（以秒为单位），以指示实时查询存活。

load_balancing​

指定用于分布式查询处理的副本选择算法。

ClickHouse支持以下副本选择算法：

• 随机（默认）
• 最近主机名
• 主机名的levenshtein距离
• 按顺序
• 第一个或随机
• 轮询

另见：

• distributed_replica_max_ignored_errors

随机（默认）​

load_balancing = random

为每个副本计算错误数量。查询发送到错误最少的副本，如果有多个这样的副本，则发送到任意一个。 缺点：不考虑服务器的接近性；如果副本具有不同的数据，您将获得不同的数据。

最近主机名​

load_balancing = nearest_hostname

为每个副本计算错误数量。每5分钟，错误数量会被整除以2。因此，错误数量是根据近期时间计算的，带有指数平滑。如果只有一个副本具有最少的错误（即最近在其他副本上发生了错误），查询会发送到该副本。如果有多个副本具有相同数量的最少错误，则查询发送到与配置文件中服务器的主机名最相似的副本（在相同位置不同字符的数量，直到两个主机名的最小长度）。

例如，example01-01-1和example01-01-2在一个位置不同，而example01-01-1和example01-02-2在两个位置不同。 这种方法可能看起来原始，但它不需要网络拓扑的外部数据，并且不比较IP地址，这对于我们的IPv6地址来说是复杂的。

因此，如果存在等效副本，按名称最接近的副本会被优先选择。 我们还可以假设，当向同一个服务器发送查询时，在没有失败的情况下，分布式查询也会发到相同的服务器上。因此，即使副本上放置了不同的数据，查询也会返回大致相同的结果。

主机名的levenshtein距离​

load_balancing = hostname_levenshtein_distance

与nearest_hostname相似，但以levenshtein距离的方式比较主机名。例如：

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

按顺序​

load_balancing = in_order

访问具有相同错误数的副本的顺序与它们在配置中的说明顺序相同。 此方法适用于确切知道哪个副本更可取的情况。

第一个或随机​

load_balancing = first_or_random

此算法选择集合中的第一个副本，如果第一个不可用，则选择随机副本。在交叉复制拓扑设置中有效，但在其他配置中无用。

first_or_random算法解决了in_order算法的问题。使用in_order时，如果一个副本宕机，接下来的副本会负担双重负载，而其余副本处理正常的流量。使用first_or_random算法时，负载在仍然可用的副本之间均匀分配。

可以通过使用设置load_balancing_first_offset显式定义第一个副本。这使得在副本之间重新平衡查询负载有了更多的控制。

轮询​

load_balancing = round_robin

此算法采用轮询策略在具有相同错误数的副本间进行分配（只有使用round_robin策略的查询才被计算）。

load_balancing_first_offset​

在使用FIRST_OR_RANDOM负载均衡策略时，优先发送查询的副本。

load_marks_asynchronously​

异步加载MergeTree标记。

local_filesystem_read_method​

从本地文件系统读取数据的方法：read, pread, mmap, io_uring, pread_threadpool。

'io_uring'方法为实验性，且在存在并发读取和写入的情况下，不能用于Log, TinyLog, StripeLog, File, Set和Join等表。 如果您在互联网上查看关于'io_uring'的各种文章，请不要被其所蒙蔽。它并不是读取文件的更好方法，除非在大量小IO请求的情况下，而这在ClickHouse中并不适用。没有理由启用'io_uring'。

local_filesystem_read_prefetch​

在从本地文件系统读取数据时应使用预读取。

lock_acquire_timeout​

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

锁定超时旨在在执行读/写表操作时防止死锁。当超时到期并且锁定请求失败时，ClickHouse服务器抛出异常“锁定尝试超时！可能已避免死锁。客户端应重试。”错误代码为DEADLOCK_AVOIDED。

可能的值：

• 正整数（以秒为单位）。
• 0 — 没有锁定超时。

log_comment​

指定system.query_log表中log_comment字段的值以及服务器日志的注释文本。

它可以用来提高服务器日志的可读性。此外，它有助于选择与测试相关的查询，从而可以在运行clickhouse-test后从system.query_log中筛选。

可能的值：

• 任何不超过max_query_size的字符串。如果超出max_query_size，服务器将抛出异常。

示例

查询：

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;

结果：

┌─type────────┬─query─────┐
│ QueryStart  │ SELECT 1; │
│ QueryFinish │ SELECT 1; │
└─────────────┴───────────┘

log_formatted_queries​

允许将格式化查询记录到system.query_log系统表中（填充formatted_query列）。

可能的值：

• 0 — 系统表中不记录格式化查询。
• 1 — 系统表中记录格式化查询。

log_processors_profiles​

记录处理器在执行/等待数据期间花费的时间到system.processors_profile_log表。

另见：

• system.processors_profile_log
• EXPLAIN PIPELINE

log_profile_events​

将查询性能统计信息记录到query_log、query_thread_log和query_views_log中。

log_queries​

设置查询日志记录。

根据query_log服务器配置参数中的规则，借助此设置发送到ClickHouse的查询将被记录。

示例：

log_queries=1

log_queries_cut_to_length​

如果查询长度超过指定阈值（以字节为单位），则在写入查询日志时截断查询。同时限制普通文本日志中打印查询的长度。

log_queries_min_query_duration_ms​

如果启用（非零），则比该设置值快的查询将不会被记录（可以将其视为MySQL慢查询日志的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：

log_queries_min_type='EXCEPTION_WHILE_PROCESSING'

log_queries_probability​

允许用户将查询写入query_log、query_thread_log和query_views_log系统表中，仅根据指定概率随机选择一部分查询。这有助于减少每秒查询量大的负载。

可能的值：

• 0 — 查询不记录在系统表中。
• 正浮点数，范围在[0..1]内。例如，如果设置值为0.5，则大约一半的查询将记录在系统表中。
• 1 — 所有查询记录在系统表中。

log_query_settings​

将查询设置记录到query_log和OpenTelemetry跨度日志中。

log_query_threads​

设置查询线程日志记录。

查询线程记录到system.query_thread_log表中。当log_queries为true时，此设置有效。通过ClickHouse运行的查询线程在此设置下将根据query_thread_log服务器配置参数中的规则被记录。

可能的值：

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

示例

log_query_threads=1

log_query_views​

设置查询视图日志记录。

当ClickHouse以此设置启用的方式运行查询时，如果有关联的视图（物化或实时视图），则会在query_views_log服务器配置参数中记录。

示例：

log_query_views=1

low_cardinality_allow_in_native_format​

允许或限制在NATIVE格式中使用LowCardinality数据类型。

如果限制使用LowCardinality，ClickHouse服务器会在SELECT查询中将LowCardinality列转换为普通列，并在INSERT查询中将普通列转换为LowCardinality列。

此设置主要针对不支持LowCardinality数据类型的第三方客户端。

可能的值：

• 1 — 不限制使用LowCardinality。
• 0 — 限制使用LowCardinality。

low_cardinality_max_dictionary_size​

设置可写入存储文件系统的LowCardinality数据类型的共享全局字典的最大行数。此设置防止在字典无限增长的情况下出现内存问题。所有由于最大字典大小限制而无法编码的数据，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构建并存储跳过索引。如果禁用，则跳过索引仅在合并或通过显式MATERIALIZE INDEX构建和存储。

另见exclude_materialize_skip_indexes_on_insert。

materialize_statistics_on_insert​

如果INSERT构建并插入统计信息。如果禁用，则统计信息将在合并期间或通过显式MATERIALIZE STATISTICS构建和存储。

materialize_ttl_after_modify​

应用旧数据的TTL，后跟ALTER MODIFY TTL查询。

materialized_views_ignore_errors​

允许忽略MATERIALIZED VIEW的错误，无论MV仍将原始块传递给表。

materialized_views_squash_parallel_inserts​

压缩来自平行插入的单个INSERT查询到物化视图目标表的插入，减少生成的部分数量。 如果设置为false并且parallel_view_processing启用，INSERT查询将为每个max_insert_thread在目标表中生成部分。

max_analyze_depth​

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

max_ast_depth​

查询语法树的最大嵌套深度。如果超过，则抛出异常。

max_ast_elements​

查询语法树中元素的最大数量。如果超过，则抛出异常。

max_autoincrement_series​

由generateSeriesID函数创建的系列数的限制。

由于每个系列表示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​

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

启用或禁用在外部内存中执行GROUP BY子句。 （参见在外部内存中的GROUP BY）

可能的值：

• 单个GROUP BY操作可以使用的最大RAM量（以字节为单位）。
• 0 — 在外部内存中禁用GROUP BY。

max_bytes_before_external_sort​

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

启用或禁用在外部内存中执行ORDER BY子句。参见ORDER BY实现细节 如果ORDER BY操作期间的内存使用超过该阈值（以字节为单位），则激活“外部排序”模式（将数据溢出到磁盘）。

可能的值：

• 单个ORDER BY操作可以使用的最大RAM量（以字节为单位）。 推荐值为可用系统内存的一半
• 0 — 在外部内存中禁用ORDER BY。

max_bytes_before_remerge_sort​

在ORDER BY与LIMIT的情况下，当内存使用高于指定阈值时，在最终合并之前执行额外的合并步骤，以仅保持顶级LIMIT行。

max_bytes_in_distinct​

用于DISTINCT时，状态在内存中最大使用的字节数（以未压缩字节为单位），通过哈希表使用。

max_bytes_in_join​

表连接时使用的哈希表的最大字节数。

此设置适用于SELECT ... JOIN操作和Join表引擎。

如果查询包含连接，ClickHouse会检查每个中间结果的此设置。

当达到限制时，ClickHouse可以执行不同的一步。使用join_overflow_mode设置来选择行动方案。

可能的值：

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

max_bytes_in_set​

由子查询创建的IN子句中的集合使用的最大字节数（未压缩数据）。

max_bytes_ratio_before_external_group_by​

允许用于GROUP BY的可用内存的比率。一旦达到，将使用外部内存进行聚合。

例如，设置为0.6，GROUP BY将允许在执行开始时使用60%的可用内存（用于服务器/用户/合并），之后将开始使用外部聚合。

max_bytes_ratio_before_external_sort​

允许用于ORDER BY的可用内存的比率。一旦达到，将使用外部排序。

例如，设置为0.6，ORDER BY将允许在执行开始时使用60%的可用内存（用于服务器/用户/合并），之后将开始使用外部排序。

注意，max_bytes_before_external_sort仍然会被尊重，只有当排序块大于max_bytes_before_external_sort时，才会进行溢出到磁盘。

max_bytes_to_read​

执行查询时从表中可以读取的最大字节数（未压缩数据）。 对每个处理的数据块进行限制，仅适用于最深的表表达式，并且在从远程服务器读取时，仅对远程服务器进行检查。

max_bytes_to_read_leaf​

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

例如，集群由两个分片组成，每个分片包含100字节数据。一个计划从两个表中读取所有数据的分布式查询，如果设置为max_bytes_to_read=150将会失败，因为总共会有200字节的数据。设置为max_bytes_to_read_leaf=150的查询将会成功，因为叶节点最多将读取100字节。

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

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）。指定较小的块大小通常会导致压缩比略有降低，压缩和解压缩速度略有提高，因为缓存局部性较好，并且内存消耗降低。

不要将用于压缩的块（一个由字节组成的内存块）与查询处理块（表中的一组行）混淆。

max_concurrent_queries_for_all_users​

如果此设置的值小于或等于当前正在处理的查询数量，则抛出异常。

示例：可以将max_concurrent_queries_for_all_users设置为99，所有用户的数据库管理员可以将其设置为100，以便在服务器过载时也能够运行查询进行调查。

对单个查询或用户的设置修改不会影响其他查询。

可能的值：

• 正整数。
• 0 — 没有限制。

示例

<max_concurrent_queries_for_all_users>99</max_concurrent_queries_for_all_users>

另见

• max_concurrent_queries

max_concurrent_queries_for_user​

每个用户同时处理的查询的最大数量。

可能的值：

• 正整数。
• 0 — 没有限制。

示例

<max_concurrent_queries_for_user>5</max_concurrent_queries_for_user>

max_distributed_connections​

用于分布式处理单个查询到单个Distributed表的远程服务器的最大同时连接数。我们建议将值设置为不低于集群中服务器的数量。

max_distributed_depth​

限制递归查询的最大深度，适用于 Distributed 表。

如果超过该值，服务器将抛出异常。

可能的值：

• 正整数。
• 0 — 无限深度。

max_download_buffer_size​

每个线程用于并行下载的最大缓冲区大小（例如，用于 URL 引擎）。

max_download_threads​

下载数据的最大线程数（例如，用于 URL 引擎）。

max_estimated_execution_time​

查询估算的最大执行时间（以秒为单位）。在 timeout_before_checking_execution_speed 过期时检查每个数据块。

max_execution_speed​

每秒执行的最大行数。在 timeout_before_checking_execution_speed 过期时检查每个数据块。如果执行速度过快，将降低执行速度。

max_execution_speed_bytes​

每秒执行的最大字节数。在 timeout_before_checking_execution_speed 过期时检查每个数据块。如果执行速度过快，将降低执行速度。

max_execution_time​

查询的最大执行时间（以秒为单位）。

max_execution_time 参数可能有点难以理解。 它根据当前查询的执行速度进行插值操作（这种行为由 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 相似，但仅适用于分布式或远程查询的叶节点。

例如，如果我们想将叶节点上的执行时间限制为 10s，但不对初始节点限制，而不在嵌套子查询设置中设置 max_execution_time：

SELECT count()
FROM cluster(cluster, view(SELECT * FROM t SETTINGS max_execution_time = 10));

我们可以将 max_execution_time_leaf 用作查询设置：

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​

设置 SELECT 查询数据读取阶段的最大并行线程数，适用于 FINAL 修饰符。

可能的值：

• 正整数。
• 0 或 1 — 禁用。SELECT 查询在单线程中执行。

max_http_get_redirects​

允许的最大 HTTP GET 重定向跳转次数。确保采取额外的安全措施，以防恶意服务器将您的请求重定向到意外服务。\n\n在外部服务器重定向到另一个地址时，即使该地址看似是公司基础设施内部的，通过向内部服务器发送 HTTP 请求，您可能会请求来自内部网络的内部 API，绕过身份验证，甚至查询其他服务，如 Redis 或 Memcached。当您没有内部基础设施（包括在本地主机上运行的东西），或者您信任服务器时，允许重定向是安全的。不过请记住，如果 URL 使用 HTTP 而不是 HTTPS，您不仅需要信任远程服务器，还需要信任您的 ISP 以及中间的每一个网络。

max_hyperscan_regexp_length​

定义 hyperscan 多匹配函数 中每个正则表达式的最大长度。

可能的值：

• 正整数。
• 0 - 长度不受限制。

示例

查询：

SELECT multiMatchAny('abcd', ['ab','bcd','c','d']) SETTINGS max_hyperscan_regexp_length = 3;

结果：

┌─multiMatchAny('abcd', ['ab', 'bcd', 'c', 'd'])─┐
│                                              1 │
└────────────────────────────────────────────────┘

查询：

SELECT multiMatchAny('abcd', ['ab','bcd','c','d']) SETTINGS max_hyperscan_regexp_length = 2;

结果：

Exception: Regexp length too large.

另见

• max_hyperscan_regexp_total_length

max_hyperscan_regexp_total_length​

设置每个 hyperscan 多匹配函数 中所有正则表达式的最大总长度。

可能的值：

• 正整数。
• 0 - 长度不受限制。

示例

查询：

SELECT multiMatchAny('abcd', ['a','b','c','d']) SETTINGS max_hyperscan_regexp_total_length = 5;

结果：

┌─multiMatchAny('abcd', ['a', 'b', 'c', 'd'])─┐
│                                           1 │
└─────────────────────────────────────────────┘

查询：

SELECT multiMatchAny('abcd', ['ab','bc','c','d']) SETTINGS max_hyperscan_regexp_total_length = 5;

结果：

Exception: Total regexp lengths too large.

另见

• max_hyperscan_regexp_length

max_insert_block_size​

用于插入表的块大小（以行数为单位）。 此设置仅适用于服务器形成块的情况。 例如，通过 HTTP 接口进行的 INSERT，服务器解析数据格式并形成指定大小的块。 但使用 clickhouse-client 时，客户端自己解析数据，服务器上的 max_insert_block_size 设置不影响插入块的大小。 在使用 INSERT SELECT 时，该设置也没有作用，因为数据是使用在 SELECT 后形成的相同块插入的。

默认值略大于 max_block_size。原因是某些表引擎（*MergeTree）对每个插入的块在磁盘上形成一个数据部分，这是一个相当大的实体。同样，*MergeTree 表在插入时对数据进行排序，足够大的块大小允许在内存中排序更多数据。

max_insert_delayed_streams_for_parallel_write​

延迟最终部分刷新操作的最大流数（列）。默认值 - 自动（如果基础存储支持并行写入，则为 100，其他情况禁用）。

max_insert_threads​

执行 INSERT SELECT 查询的最大线程数。

可能的值：

• 0（或 1） — INSERT SELECT 不支持并行执行。
• 正整数，大于 1。

云默认值：

• 8 GiB 内存的节点为 1
• 16 GiB 内存的节点为 2
• 更大的节点为 4

并行 INSERT SELECT 仅在 SELECT 部分并行执行时有效，请参见 max_threads 设置。 更高的值将导致更高的内存使用。

max_joined_block_size_bytes​

JOIN 结果的最大块大小（以字节为单位）（如果连接算法支持）。0 表示无限制。

max_joined_block_size_rows​

JOIN 结果的最大块大小（以行数为单位）（如果连接算法支持）。0 表示无限制。

max_limit_for_vector_search_queries​

对于 LIMIT 大于此设置的 SELECT 查询，无法使用向量相似度索引。帮助防止向量相似度索引中的内存溢出。

max_live_view_insert_blocks_before_refresh​

限制插入块的最大数量，在此之后可合并的块被丢弃并重新执行查询。

max_local_read_bandwidth​

本地读取的最大速度（以字节为单位）。

max_local_write_bandwidth​

本地写入的最大速度（以字节为单位）。

max_memory_usage​

云默认值：取决于副本的 RAM 数量。

在单个服务器上运行查询时可以使用的最大 RAM 量。 值为 0 表示无限制。

此设置并不考虑可用内存的容量或机器上的总内存容量。限制适用于单个服务器上的单个查询。

您可以使用 SHOW PROCESSLIST 查看每个查询的当前内存消耗。 每个查询的峰值内存消耗会被跟踪并记录到日志中。

以下聚合函数的状态的内存使用未完全跟踪：

• min
• max
• any
• anyLast
• argMin
• argMax

内存消耗还受以下参数 max_memory_usage_for_user 和 max_server_memory_usage 的限制。

max_memory_usage_for_user​

在单个服务器上运行用户查询时可以使用的最大 RAM 量。值为 0 表示无限制。

默认情况下，数量不受限制（max_memory_usage_for_user = 0）。

另见 max_memory_usage 的描述。

例如，如果您想将 max_memory_usage_for_user 设置为 1000 字节给名为 clickhouse_read 的用户，您可以使用以下语句：

ALTER USER clickhouse_read SETTINGS max_memory_usage_for_user = 1000;

您可以通过注销客户端，再次登录，然后使用 getSetting 函数验证其是否生效：

SELECT getSetting('max_memory_usage_for_user');

max_network_bandwidth​

限制网络数据交换的速度（以字节为单位）。此设置适用于每个查询。

可能的值：

• 正整数。
• 0 — 禁用带宽控制。

max_network_bandwidth_for_all_users​

限制网络数据交换的速度（以字节为单位）。此设置适用于所有并发运行的查询。

可能的值：

• 正整数。
• 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​

在 OSCPUWaitMicroseconds 指标和 OSCPUVirtualTimeMicroseconds 指标之间考虑拒绝查询的最大比率。使用最小和最大比率之间的线性插值计算概率，在这一点上概率为 1。

max_parallel_replicas​

执行查询时每个分片的最大副本数。

可能的值：

• 正整数。

附加信息

此选项将根据使用的设置产生不同的结果。

使用 SAMPLE 键进行并行处理​

如果在多个服务器上并行执行查询，查询可能会更快处理。但是，在以下情况下查询性能可能会下降：

• 采样键在分区键中的位置不允许有效的范围扫描。
• 将采样键添加到表会使通过其他列进行过滤的效率降低。
• 采样键是一个计算开销大的表达式。
• 集群延迟分布具有较长尾巴，因此查询更多服务器会增加整体延迟。

使用 parallel_replicas_custom_key 进行并行处理​

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

max_parser_backtracks​

最大解析器回溯次数（在递归下降解析过程中尝试不同选择的次数）。

max_parser_depth​

限制递归下降解析器的最大递归深度。允许控制堆栈大小。

可能的值：

• 正整数。
• 0 — 递归深度不限。

max_parsing_threads​

解析支持并行解析的输入格式数据的最大线程数。默认情况下，自动确定。

max_partition_size_to_drop​

查询时删除分区的限制。值 0 表示可以删除分区而没有任何限制。

云默认值：1 TB。

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' 设置控制。 大量分区是一个常见的误解。它将导致严重的负性能影响，包括服务器启动缓慢、INSERT 查询缓慢和 SELECT 查询缓慢。建议的表分区总数应少于 1000 至 10000。请注意，分区并不是为了加速 SELECT 查询（ORDER BY 键足以使范围查询快速）。 分区用于数据操作（DROP PARTITION 等）。"

max_partitions_to_read​

限制在单个查询中可以访问的最大分区数。

在创建表时指定的设置值可以通过查询级别设置覆盖。

可能的值：

• 正整数
• -1 - 无限制（默认）

max_parts_to_move​

限制在一个查询中可以移动的部分的数量。零表示无限制。

max_query_size​

SQL 解析器解析的查询字符串的最大字节数。 INSERT 查询中的 VALUES 子句中的数据由单独的流解析器处理（消耗 O(1) 的 RAM），不受此限制的影响。

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​

对于分布式查询，禁用滞后副本。请参见 Replication。

设置以秒为单位。如果副本的滞后时间大于或等于设定值，则不使用该副本。

可能的值：

• 正整数。
• 0 — 不检查副本的滞后时间。

要防止使用任何滞后时间不为零的副本，请将此参数设置为 1。

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

max_result_bytes​

限制结果大小（以字节为单位，未经压缩）。如果处理数据块时达到阈值，查询将停止，但不会截断结果的最后一个块，因此结果大小可能超过阈值。

注意事项

内存中的结果大小被纳入此阈值。 即使结果大小很小，它仍可以引用内存中的更大数据结构，代表低基数列的字典和聚合函数列的区域，因此尽管结果大小较小，阈值仍可能被超出。

max_result_rows​

云默认值：0。

限制结果中的行数。对于子查询和在远程服务器上运行分布式查询的一部分时也进行检查。 当值为 0 时不应用限制。

如果处理数据块时达到阈值，查询将停止，但不会截断结果的最后一个块，因此结果大小可能大于阈值。

max_rows_in_distinct​

使用 DISTINCT 时不同的最大行数。

max_rows_in_join​

限制连接表时使用的哈希表中的行数。

此设置适用于 SELECT ... JOIN 操作和 Join 表引擎。

如果查询包含多个连接，ClickHouse 将对每个中间结果检查此设置。

当达到限制时，ClickHouse 可以执行不同的操作。使用 join_overflow_mode 设置选择操作。

可能的值：

• 正整数。
• 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 行。

对每个处理的数据块进行检查。

max_rows_to_sort​

排序前的最大行数。这允许您在排序时限制内存消耗。 如果ORDER BY操作需要处理的记录数超过指定数量，则行为将由 sort_overflow_mode 确定，默认设置为 throw。

max_rows_to_transfer​

在执行 GLOBAL IN/JOIN 部分时，传递给远程服务器或保存到临时表的最大大小（以行数为单位）。

max_sessions_for_user​

每个已认证用户与 ClickHouse 服务器的最大同时会话数。

示例：

<profiles>
    <single_session_profile>
        <max_sessions_for_user>1</max_sessions_for_user>
    </single_session_profile>
    <two_sessions_profile>
        <max_sessions_for_user>2</max_sessions_for_user>
    </two_sessions_profile>
    <unlimited_sessions_profile>
        <max_sessions_for_user>0</max_sessions_for_user>
    </unlimited_sessions_profile>
</profiles>
<users>
    <!-- User Alice can connect to a ClickHouse server no more than once at a time. -->
    <Alice>
        <profile>single_session_user</profile>
    </Alice>
    <!-- User Bob can use 2 simultaneous sessions. -->
    <Bob>
        <profile>two_sessions_profile</profile>
    </Bob>
    <!-- User Charles can use arbitrarily many of simultaneous sessions. -->
    <Charles>
        <profile>unlimited_sessions_profile</profile>
    </Charles>
</users>

可能的值：

• 正整数
• 0 - 无限数量的同时会话（默认）

max_size_to_preallocate_for_aggregation​

在聚合之前，所有哈希表中允许预分配的元素的总数。

max_size_to_preallocate_for_joins​

在连接之前，所有哈希表中允许预分配的元素的总数。

max_streams_for_merge_tree_reading​

如果不为零，限制 MergeTree 表的读取流数量。

max_streams_multiplier_for_merge_tables​

在从合并表读取时请求更多流。流将分布在合并表将使用的表上。这允许更均匀地分配线程间的工作，并在合并表之间尺寸不同的情况下特别有帮助。

max_streams_to_max_threads_ratio​

允许您使用的来源数超过线程数——以更均匀地分配线程之间的工作。假设这是一个临时解决方案，因为将来将能够使源的数量等于线程数量，但对于每个源动态选择可用的工作。

max_subquery_depth​

如果查询的嵌套子查询数超过指定数量，则抛出异常。

max_table_size_to_drop​

查询时删除表的限制。值 0 表示可以删除所有表而没有任何限制。

云默认值：1 TB。

max_temporary_columns​

在运行查询时需要同时保留在内存中的临时列的最大数量，包括常量列。如果查询由于中间计算生成的临时列超过指定数量，则将抛出异常。

0 值表示无限制。

max_temporary_data_on_disk_size_for_query​

所有并发运行查询的临时文件在磁盘上消耗的数据的最大字节数。

可能的值：

• 正整数。
• 0 — 无限制（默认）。

max_temporary_data_on_disk_size_for_user​

所有并发运行的用户查询的临时文件在磁盘上消耗的数据的最大字节数。

可能的值：

• 正整数。
• 0 — 无限制（默认）。

max_temporary_non_const_columns​

与 max_temporary_columns 类似，在运行查询时需要同时保留在内存中的临时列的最大数量，但不计算常量列。

max_threads​

查询处理线程的最大数量，不包括从远程服务器检索数据的线程（请参见 'max_distributed_connections' 参数）。

此参数适用于在查询处理管道中并行执行相同阶段的线程。 例如，在从表中读取时，如果可以使用至少 'max_threads' 数量的线程并行评估函数的表达式、使用 WHERE 进行筛选和为 GROUP BY 进行预聚合，则将使用 'max_threads'。

对于因 LIMIT 快速完成的查询，可以设置较低的 'max_threads'。例如，如果必要数量的条目位于每个块中，且 max_threads = 8，则将检索 8 个块，尽管只需读取一个就够了。

max_threads 值越小，消耗的内存越少。

云默认值：auto(3)。

max_threads_for_indexes​

处理索引的最大线程数。

max_untracked_memory​

小的分配和解除分配被归为线程局部变量，仅在其绝对值超过指定值时才进行跟踪或分析。如果该值高于 'memory_profiler_step'，它将有效地降低到 'memory_profiler_step'。

memory_overcommit_ratio_denominator​

它表示当全局级别的硬限制达到时的软内存限制。 此值用于计算查询的过量使用比率。 零表示跳过查询。 有关 内存过量使用 的更多信息。

memory_overcommit_ratio_denominator_for_user​

它表示当用户级别的硬限制达到时的软内存限制。 此值用于计算查询的过量使用比率。 零表示跳过查询。 有关 内存过量使用 的更多信息。

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​

收集随机分配和释放，并将其写入 system.trace_log，跟踪类型为 'MemorySample'。该概率适用于每个分配/释放，无论分配的大小如何（可以通过 memory_profiler_sample_min_allocation_size 和 memory_profiler_sample_max_allocation_size 进行更改）。请注意，只有当未跟踪内存的数量超过 'max_untracked_memory' 时，才会进行采样。您可能希望将 'max_untracked_memory' 设置为 0 以实现更细粒度的采样。

memory_profiler_step​

设置内存分析器的步骤。每当查询内存使用量超过以字节为单位的每个后续步骤时，内存分析器将收集分配堆栈跟踪并将其写入 trace_log。

可能值：

• 一个正整数的字节数。

• 0 表示关闭内存分析器。

memory_tracker_fault_probability​

用于测试 exception safety - 每次分配内存时按指定概率抛出异常。

memory_usage_overcommit_max_wait_microseconds​

在用户级别内存过度分配的情况下，线程等待内存释放的最长时间。如果达到超时而内存未释放，将抛出异常。了解更多关于 memory overcommit 的信息。

merge_table_max_tables_to_look_for_schema_inference​

在创建 Merge 表时没有显式架构或者使用 merge 表函数时，推导出不超过指定数量匹配表的联合架构。如果表的数量更大，则只从前面指定数量的表中推导架构。

merge_tree_coarse_index_granularity​

在搜索数据时，ClickHouse 会检查索引文件中的数据标记。如果 ClickHouse 发现所需的键在某个范围内，它会将该范围划分为 merge_tree_coarse_index_granularity 个子范围，并在其中递归搜索所需的键。

可能值：

• 任何正偶数。

merge_tree_compact_parts_min_granules_to_multibuffer_read​

仅在 ClickHouse Cloud 中生效。MergeTree 表的紧凑部分条带中使用多缓冲读取器的最小粒度数，该读取器支持并行读取和预取。在从远程文件系统读取时，使用多缓冲读取器会增加读取请求的数量。

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 服务器设置定义未压缩块的缓存大小。

可能值：

• 任何正整数。

merge_tree_max_rows_to_use_cache​

如果 ClickHouse 在一个查询中应读取超过 merge_tree_max_rows_to_use_cache 行，则不使用未压缩块的缓存。

未压缩块缓存存储为查询提取的数据。ClickHouse 使用此缓存以加快对重复小查询的响应。此设置保护缓存免受读取大量数据的查询破坏。uncompressed_cache_size 服务器设置定义未压缩块的缓存大小。

可能值：

• 任何正整数。

merge_tree_min_bytes_for_concurrent_read​

如果从一个 MergeTree 引擎表中读取的字节数超过 merge_tree_min_bytes_for_concurrent_read，则 ClickHouse 尝试在多个线程中并发读取该文件。

可能值：

• 正整数。

merge_tree_min_bytes_for_concurrent_read_for_remote_filesystem​

从一个文件中读取的最小字节数，才能在读取远程文件系统时， MergeTree 引擎可以并行化读取。我们不建议使用此设置。

可能值：

• 正整数。

merge_tree_min_bytes_for_seek​

如果在一个文件中要读取的两个数据块之间的距离小于 merge_tree_min_bytes_for_seek 字节，则 ClickHouse 顺序读取包含这两个块的文件范围，从而避免额外的寻道。

可能值：

• 任何正整数。

merge_tree_min_bytes_per_task_for_remote_reading​

每个任务要读取的最小字节数。

merge_tree_min_read_task_size​

任务大小的硬下限（即使粒度数量较低，且可用线程数量较高，我们也不会分配较小的任务）。

merge_tree_min_rows_for_concurrent_read​

如果要从一个 MergeTree 表的文件中读取超过 merge_tree_min_rows_for_concurrent_read 行，则 ClickHouse 尝试在多个线程中对该文件进行并发读取。

可能值：

• 正整数。

merge_tree_min_rows_for_concurrent_read_for_remote_filesystem​

从一个文件读取的最小行数，才能在读取远程文件系统时，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 中宽部分的前缀读取的线程池进行并行化。该线程池的大小由服务器设置 max_prefixes_deserialization_thread_pool_size 控制。

merge_tree_use_v1_object_and_dynamic_serialization​

启用时，将在 MergeTree 中使用 JSON 和动态类型的 V1 序列化版本，而不是 V2。更改此设置只在服务器重启后生效。

metrics_perf_events_enabled​

如果启用，则在查询执行过程中将测量某些性能事件。

metrics_perf_events_list​

以逗号分隔的性能指标列表，将在查询执行期间进行测量。为空表示所有事件。有关可用事件的信息，请参阅源中的 PerfEventInfo。

min_bytes_to_use_direct_io​

使用直接 I/O 访问存储磁盘所需的最小数据量。

ClickHouse 在从表中读取数据时使用此设置。如果要读取的所有数据的总存储量超过 min_bytes_to_use_direct_io 字节，则 ClickHouse 将使用 O_DIRECT 选项从存储磁盘读取数据。

可能值：

• 0 — 禁用直接 I/O。
• 正整数。

min_bytes_to_use_mmap_io​

这是一个实验性设置。设置读取大文件而不从内核复制数据到用户空间所需的最小内存量。推荐阈值约为 64 MB，因为 mmap/munmap 速度较慢。它仅在大文件时有意义，并且仅在数据位于页面缓存中时才有效。

可能值：

• 正整数。
• 0 — 大文件仅通过从内核复制数据到用户空间读取。

min_chunk_bytes_for_parallel_parsing​

• 类型：无符号整数
• 默认值：1 MiB

每个线程并行解析的最小块大小（以字节为单位）。

min_compress_block_size​

对于 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 列（平均每值 60 字节）。写入 8192 行时，平均将略低于 500 KB 的数据。由于这大于 65,536，将为每个标记形成一个压缩块。在这种情况下，从磁盘读取单个标记范围时，不会解压缩额外的数据。

min_count_to_compile_aggregate_expression​

开始 JIT 编译的最小相同聚合表达式数量。仅在启用 compile_aggregate_expressions 设置时有效。

可能值：

• 正整数。
• 0 — 相同的聚合表达式始终 JIT 编译。

min_count_to_compile_expression​

执行同一表达式之前的最小计数，以便进行编译。

min_count_to_compile_sort_description​

在 JIT 编译之前需要的相同排序描述的数量。

min_execution_speed​

每秒最低执行速度（以行计）。在 timeout_before_checking_execution_speed 到期时检查每个数据块。如果执行速度较低，则会抛出异常。

min_execution_speed_bytes​

每秒最低执行字节数（以字节计）。在 timeout_before_checking_execution_speed 到期时检查每个数据块。如果执行速度较低，则会抛出异常。

min_external_table_block_size_bytes​

如果块不够大，则将传递给外部表的块压缩到指定的字节大小。

min_external_table_block_size_rows​

如果块不够大，则将传递给外部表的块压缩到指定的行数。

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​

设置可以通过 INSERT 查询插入到表中的块的最小字节数。较小的块会被压缩成较大的块。

可能值：

• 正整数。
• 0 — 禁用压缩。

min_insert_block_size_bytes_for_materialized_views​

设置可以通过 INSERT 查询插入到表中的块的最小字节数。较小的块会被压缩成较大的块。此设置仅适用于插入到 物化视图 的块。通过调整此设置，您可以控制推送到物化视图时的块压缩，并避免过度使用内存。

可能值：

• 任何正整数。
• 0 — 禁用压缩。

另见

• min_insert_block_size_bytes

min_insert_block_size_rows​

设置可以通过 INSERT 查询插入到表中的块的最小行数。较小的块会被压缩成较大的块。

可能值：

• 正整数。
• 0 — 禁用压缩。

min_insert_block_size_rows_for_materialized_views​

设置可以通过 INSERT 查询插入到表中的块的最小行数。较小的块会被压缩成较大的块。此设置仅适用于插入到 物化视图 的块。通过调整此设置，您可以控制推送到物化视图时的块压缩，并避免过度使用内存。

可能值：

• 任何正整数。
• 0 — 禁用压缩。

另见

• min_insert_block_size_rows

min_joined_block_size_bytes​

JOIN 输入和输出块的最小块大小（以字节为单位）（如果连接算法支持）。小块将被压缩。0 表示无限制。

min_joined_block_size_rows​

JOIN 输入和输出块的最小行数（如果连接算法支持）。小块将被压缩。0 表示无限制。

min_os_cpu_wait_time_ratio_to_throw​

考虑拒绝查询的操作系统 CPU 等待（OSCPUWaitMicroseconds 指标）和繁忙（OSCPUVirtualTimeMicroseconds 指标）时间的最小比例。使用线性插值在最小和最大比率之间计算概率，该点时概率为 0。

min_outstreams_per_resize_after_split​

指定在生成管道过程中执行拆分时，Resize 或 StrictResize 处理器的最小输出流数量。如果生成的流数少于此值，拆分操作将不会发生。

什么是 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 节点，允许它们保留原始结构，而不会拆分成更小的节点。

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​

在多个连接重写时，不在顶层表达式列表中添加别名。

mutations_execute_nondeterministic_on_initiator​

如果为真常量非确定性函数（例如函数 now()）在发起者上执行并在 UPDATE 和 DELETE 查询中替换为文字。这有助于在执行常量非确定性函数的突变时保持副本中的数据同步。默认值：false。

mutations_execute_subqueries_on_initiator​

如果为真标量子查询在发起者上执行，并在 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 查询（突变）。

可能值：

mysql_datatypes_support_level​

定义 MySQL 类型如何转换为相应的 ClickHouse 类型。以逗号分隔的列表，可以为 decimal、datetime64、date2Date32 或 date2String 的任意组合。

• 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​

如果启用，FixedString ClickHouse 数据类型将显示为 SHOW COLUMNS中的 TEXT。

仅在通过 MySQL 线协议建立连接时有效。

• 0 - 使用 BLOB。
• 1 - 使用 TEXT。

mysql_map_string_to_text_in_show_columns​

如果启用，String ClickHouse 数据类型将显示为 SHOW COLUMNS中的 TEXT。

仅在通过 MySQL 线协议建立连接时有效。

• 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​

调整 ZSTD 压缩级别。仅在将 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 桥中每个连接设置字符串的连接池大小。

odbc_bridge_use_connection_pooling​

在 ODBC 桥中使用连接池。如果设置为 false，则每次都会创建新连接。

offset​

设置在开始返回查询结果之前要跳过的行数。它调整由 OFFSET 子句设置的偏移量，使这两个值相加。

可能值：

• 0 — 不跳过任何行。
• 正整数。

示例

输入表：

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

查询：

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

结果：

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

opentelemetry_start_trace_probability​

设置 ClickHouse 在执行查询时可以启动跟踪的概率（前提是没有提供父级 跟踪上下文）。

可能值：

• 0 — 禁用所有执行查询的跟踪（如果没有提供父级跟踪上下文）。
• 在 [0..1] 范围内的正浮点数。例如，如果设置值为 0.5，则 ClickHouse 可以平均启动一半查询的跟踪。
• 1 — 启用所有执行查询的跟踪。

opentelemetry_trace_cpu_scheduling​

为工作负载抢占式 CPU 调度收集 OpenTelemetry 跨度。

opentelemetry_trace_processors​

收集 OpenTelemetry 跨度以获取处理器。

optimize_aggregation_in_order​

启用在 SELECT 查询中的 GROUP BY 优化，以便在 MergeTree 表中按相应顺序聚合数据。

可能值：

• 0 — 禁用 GROUP BY 优化。
• 1 — 启用 GROUP BY 优化。

另见

• GROUP BY 优化

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​

使用 constraints 来附加索引条件。默认值为 false。

可能的值：

• true, false

optimize_arithmetic_operations_in_aggregate_functions​

将算术运算移出聚合函数。

optimize_count_from_files​

启用或禁用从不同输入格式的文件中计算行数的优化。适用于表函数/引擎 file/s3/url/hdfs/azureBlobStorage。

可能的值：

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

optimize_distinct_in_order​

如果 DISTINCT 中的一些列形成排序的前缀，则启用 DISTINCT 优化。例如，merge tree 中的排序键前缀或 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_push_down_limit
• optimize_skip_unused_shards

optimize_empty_string_comparisons​

将 col = '' 或 '' = col 的表达式转换为 empty(col)，并将 col != '' 或 '' != col 转换为 notEmpty(col)，仅当 col 的类型为 String 或 FixedString 时。

optimize_extract_common_expressions​

允许从 WHERE、PREWHERE、ON、HAVING 和 QUALIFY 表达式中的析取中提取共同表达式。逻辑表达式如 (A AND B) OR (A AND C) 可以重写为 A AND (B OR C)，这可能有助于利用：

• 简单过滤表达式中的索引
• 交叉到内部连接的优化

optimize_functions_to_subcolumns​

启用或禁用通过将某些函数转换为读取子列的优化。这减少了读取的数据量。

以下函数可以被转换：

• length 读取 size0 子列。
• empty 读取 size0 子列。
• notEmpty 读取 size0 子列。
• isNull 读取 null 子列。
• isNotNull 读取 null 子列。
• count 读取 null 子列。
• mapKeys 读取 keys 子列。
• mapValues 读取 values 子列。

可能的值：

• 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 中将字符串类型参数替换为枚举。默认禁用，因为这可能会导致分布式查询中的不一致变化，进而导致失败。

optimize_injective_functions_in_group_by​

在 GROUP BY 部分中用其参数替换注射函数。

optimize_injective_functions_inside_uniq​

删除 uniq*() 函数内部的单个参数注射函数。

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 查询中自动 PREWHERE 优化。

仅适用于 *MergeTree 表。

可能的值：

• 0 — 自动 PREWHERE 优化禁用。
• 1 — 自动 PREWHERE 优化启用。

optimize_move_to_prewhere_if_final​

启用或禁用在带有 FINAL 修饰符的 SELECT 查询中自动 PREWHERE 优化。

仅适用于 *MergeTree 表。

可能的值：

• 0 — 在带有 FINAL 修饰符的 SELECT 查询中自动 PREWHERE 优化禁用。
• 1 — 在带有 FINAL 修饰符的 SELECT 查询中自动 PREWHERE 优化启用。

另见

• optimize_move_to_prewhere 设置。

optimize_multiif_to_if​

将仅具有一个条件的 'multiIf' 替换为 'if'。

optimize_normalize_count_variants​

将语义上等同于 count() 的聚合函数重写为 count()。

optimize_on_insert​

启用或禁用在插入前对数据进行转换，仿佛在该块上进行了合并（根据表引擎）。

可能的值：

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

示例

启用和禁用之间的区别：

查询：

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;

结果：

┌─FirstTable─┐
│          0 │
│          1 │
└────────────┘

┌─SecondTable─┐
│           0 │
│           0 │
│           0 │
│           1 │
│           1 │
└─────────────┘

注意，此设置会影响 Materialized view 的行为。

optimize_or_like_chain​

将多个 OR LIKE 优化为 multiMatchAny。此优化不应默认启用，因为它在某些情况下会违反索引分析。

optimize_qbit_distance_function_reads​

将 QBit 数据类型的距离函数替换为等效函数，仅从存储中读取计算所需的列。

optimize_read_in_order​

在 SELECT 查询中启用 ORDER BY 优化，以从 MergeTree 表中读取数据。

可能的值：

• 0 — ORDER BY 优化禁用。
• 1 — ORDER BY 优化启用。

另见

• ORDER BY Clause

optimize_read_in_window_order​

启用窗口子句中的 ORDER BY 优化，以在 MergeTree 表中以相应顺序读取数据。

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 表达式的聚合函数重写为参数。例如，avg(if(cond, col, null)) 可以重写为 avgOrNullIf(cond, col)。这可能提高性能。

optimize_rewrite_array_exists_to_has​

将数组存在函数重写为 has()，当逻辑上等价时。例如，arrayExists(x -> x = 1, arr) 可以重写为 has(arr, 1)。

optimize_rewrite_regexp_functions​

将正则表达式相关函数重写为更简单和更高效的形式。

optimize_rewrite_sum_if_to_count_if​

当逻辑上等价时，将 sumIf() 和 sum(if()) 函数重写为 countIf() 函数。

optimize_skip_merged_partitions​

启用或禁用针对 OPTIMIZE TABLE ... FINAL 查询的优化，如果只有一个级别 > 0 的部分，并且没有过期的 TTL。

• OPTIMIZE TABLE ... FINAL SETTINGS optimize_skip_merged_partitions=1

默认情况下，即使只有一个部分，OPTIMIZE TABLE ... FINAL 查询也会重写这一部分。

可能的值：

• 1 - 启用优化。
• 0 - 禁用优化。

optimize_skip_unused_shards​

启用或禁用在 WHERE/PREWHERE 中具有分片键条件的 SELECT 查询中跳过未使用的分片（假设数据是根据分片键分布的，否则查询将产生不正确的结果）。

可能的值：

• 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）取决于分布式查询的嵌套级别（假设您有 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​

使用 constraints 来替换列。默认值为 false。

可能的值：

• true, false

optimize_syntax_fuse_functions​

启用通过相同参数融合聚合函数。它重写查询中至少包含两个具有相同参数的聚合函数的查询，来自 sum, count 或 avg 重写为 sumCount。

可能的值：

• 0 — 不融合具有相同参数的函数。
• 1 — 融合具有相同参数的函数。

示例

查询：

CREATE TABLE fuse_tbl(a Int8, b Int8) Engine = Log;
SET optimize_syntax_fuse_functions = 1;
EXPLAIN SYNTAX SELECT sum(a), sum(b), count(b), avg(b) from fuse_tbl FORMAT TSV;

结果：

SELECT
    sum(a),
    sumCount(b).1,
    sumCount(b).2,
    (sumCount(b).1) / (sumCount(b).2)
FROM fuse_tbl

optimize_throw_if_noop​

启用或禁用如果 OPTIMIZE 查询没有执行合并，则抛出异常。

默认情况下，OPTIMIZE 即使没有进行任何操作也会成功返回。此设置使您能够区分这些情况，并在异常消息中获取原因。

可能的值：

• 1 — 启用抛出异常。
• 0 — 禁用抛出异常。

optimize_time_filter_with_preimage​

通过将函数转换为等效比较来优化日期和日期时间谓词，而不进行转换（例如 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_trivial_insert_select​

优化简单的 'INSERT INTO table SELECT ... FROM TABLES' 查询。

optimize_uniq_to_count​

将 uniq 及其变体（除 uniqUpTo 外）重写为 count，如果子查询有 distinct 或 group by 子句。

optimize_use_implicit_projections​

自动选择隐式投影来执行 SELECT 查询。

optimize_use_projection_filtering​

启用使用投影在执行 SELECT 查询时过滤部分范围，即使在选择查询时未选中投影。

optimize_use_projections​

启用或禁用在处理 SELECT 查询时的 projection 优化。

可能的值：

• 0 — 投影优化禁用。
• 1 — 投影优化启用。

optimize_using_constraints​

使用 constraints 进行查询优化。默认值为 false。

可能的值：

• true, false

os_threads_nice_value_materialized_view​

Linux 物化视图线程的优先级值。较低的值意味着更高的 CPU 优先级。

需要 CAP_SYS_NICE 权限，否则不会生效。

可能的值： -20 到 19。

os_threads_nice_value_query​

Linux 查询处理线程的优先级值。较低的值意味着更高的 CPU 优先级。

需要 CAP_SYS_NICE 权限，否则不会生效。

可能的值： -20 到 19。

output_format_compression_level​

如果查询输出被压缩，则默认压缩级别。当 SELECT 查询具有 INTO OUTFILE 时或写入表函数 file、url、hdfs、s3 或 azureBlobStorage 时应用此设置。

可能的值：从 1 到 22。

output_format_compression_zstd_window_log​

可以在输出压缩方法为 zstd 时使用。如果大于 0，此设置明确设置压缩窗口大小（2 的幂），并启用 zstd 压缩的长范围模式。这可以帮助实现更好的压缩率。

可能的值：非负数。请注意，如果值过小或过大，zstdlib 将抛出异常。典型值为从 20（窗口大小 = 1MB）到 30（窗口大小 = 1GB）。

output_format_parallel_formatting​

启用或禁用数据格式的并行格式化。仅支持 TSV、TSKV、CSV 和 JSONEachRow 格式。

可能的值：

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

page_cache_block_size​

存储在用户空间页缓存中的文件块大小，以字节为单位。所有通过缓存的读取将被舍入为该大小的倍数。

此设置可以在每个查询级别进行调整，但具有不同块大小的缓存条目不能重用。改变此设置实际上会使缓存中现有条目失效。

较高的值，如 1 MiB 适用于高吞吐量查询，而较低的值，如 64 KiB 适用于低延迟的点查询。

page_cache_inject_eviction​

用户空间页缓存有时会随机失效某些页面。用于测试。

page_cache_lookahead_blocks​

在用户空间页缓存缺失时，从底层存储一次读取最多此数量的连续块，如果它们也不在缓存中。每个块是 page_cache_block_size 字节。

较高的值适用于高吞吐量查询，而低延迟的点查询在没有预读取的情况下会更好。

parallel_distributed_insert_select​

启用并行分布式 INSERT ... SELECT 查询。

如果我们执行 INSERT INTO distributed_table_a SELECT ... FROM distributed_table_b 查询并且两个表使用相同的集群，并且两个表都是 replicated 或非复制的，那么此查询将在每个分片上本地处理。

可能的值：

• 0 — 禁用。
• 1 — SELECT 将在分布式引擎的基础表的每个分片上执行。
• 2 — SELECT 和 INSERT 将在分布式引擎的基础表的每个分片上执行。

使用此设置需要将 enable_parallel_replicas 设置为 1。

parallel_hash_join_threshold​

当应用基于哈希的连接算法时，此阈值帮助决定使用 hash 还是 parallel_hash（仅在可用右表大小估计的情况下）。

前者在我们知道右表大小低于阈值时使用。

parallel_replica_offset​

这是一个内部设置，不应直接使用，表示“并行副本”模式的实现细节。此设置将由发起服务器自动为分布式查询设置为参与查询处理的副本索引。

parallel_replicas_allow_in_with_subquery​

如果为真，IN 的子查询将在每个跟随副本上执行。

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_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_upper] 平均分配工作。

注意：此设置不会在查询处理期间造成额外的数据过滤，而是更改了范围过滤器在进行并行处理时将范围 [0, INT_MAX] 划分的点。

parallel_replicas_for_cluster_engines​

将表函数引擎替换为其 -Cluster 替代品。

parallel_replicas_for_non_replicated_merge_tree​

如果为真，ClickHouse 将对非复制的 MergeTree 表使用并行副本算法。

parallel_replicas_index_analysis_only_on_coordinator​

仅在副本协调器上执行索引分析，其他副本则省略。仅在启用 parallel_replicas_local_plan 时有效。

parallel_replicas_insert_select_local_pipeline​

在分布式 INSERT SELECT 中的并行副本中使用本地管道。

parallel_replicas_local_plan​

为本地副本构建本地计划。

parallel_replicas_mark_segment_size​

部分虚拟地划分为要在副本之间分发的段。此设置控制这些段的大小。在完全确定您在做什么之前，不建议更改。值应在 [128; 16384] 范围内。

parallel_replicas_min_number_of_rows_per_replica​

限制查询中使用的副本数量为（估计读取行数 / min_number_of_rows_per_replica）。最大值仍然受 'max_parallel_replicas' 的限制。

parallel_replicas_mode​

用于具有自定义键的并行副本的过滤器类型。默认值 - 使用自定义键的模运算，范围 - 对自定义键使用范围过滤器，使用自定义键值类型的所有可能值。

parallel_replicas_only_with_analyzer​

必须启用分析器才能使用并行副本。在禁用分析器时，查询执行回落到本地执行，即使启用了从副本并行读取。禁用分析器不支持使用并行副本。

parallel_replicas_prefer_local_join​

如果为真，并且 JOIN 可以使用并行副本算法执行，并且右 JOIN 部分的所有存储都是 *MergeTree，则将使用本地 JOIN，而不是 GLOBAL JOIN。

parallel_replicas_support_projection​

可以在并行副本中应用投影的优化。仅在启用 parallel_replicas_local_plan 且 aggregation_in_order 不激活时有效。

parallel_view_processing​

启用同步推送到附加视图，而不是顺序推送。

parallelize_output_from_storages​

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

parsedatetime_e_requires_space_padding​

格式化器 %e 在函数 'parseDateTime' 中期望单数字的日期为填充空格，例如，接受 ' 2'，但 '2' 会引发错误。

parsedatetime_parse_without_leading_zeros​

格式化器 %c、%l 和 %k 在函数 'parseDateTime' 中解析月份和小时时不使用前导零。

partial_merge_join_left_table_buffer_bytes​

如果不为 0，在部分合并连接中将左表块组合为较大的块。它每个连接线程最多使用指定内存的 2 倍。

partial_merge_join_rows_in_right_blocks​

限制在部分合并连接算法中用于 JOIN 查询的右侧连接数据块的大小。

ClickHouse 服务器:

1. 将右侧连接数据分成最多指定行数的块。
2. 用每个块的最小和最大值为其建立索引。
3. 如果可能，将准备好的块卸载到磁盘。

可能的值：

• 任何正整数。推荐的值范围: [1000, 100000]。

partial_result_on_first_cancel​

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

parts_to_delay_insert​

如果目标表在单个分区中至少包含如此多的活动部分，则人为地减慢插入到表的速度。

parts_to_throw_insert​

如果目标表的单个分区中活动部分超过此数量，则抛出 'Too many parts ...' 异常。

per_part_index_stats​

记录每部分的索引统计信息

periodic_live_view_refresh​

在该间隔后强制刷新定期更新的物化视图。

poll_interval​

在服务器上阻塞查询等待循环，持续指定的秒数。

postgresql_connection_attempt_timeout​

单次尝试连接 PostgreSQL 端点的超时时间（秒）。 该值作为连接 URL 的 connect_timeout 参数传递。

postgresql_connection_pool_auto_close_connection​

在将连接返回到连接池之前关闭连接。

postgresql_connection_pool_retries​

PostgreSQL 表引擎和数据库引擎的连接池推送/获取重试次数。

postgresql_connection_pool_size​

PostgreSQL 表引擎和数据库引擎的连接池大小。

postgresql_connection_pool_wait_timeout​

PostgreSQL 表引擎和数据库引擎的空连接池推送/获取超时。默认情况下，在空池上将阻塞。

postgresql_fault_injection_probability​

内部（用于复制）PostgreSQL 查询失败的近似概率。有效值在区间 [0.0f, 1.0f] 之间。

prefer_column_name_to_alias​

启用或禁用在查询表达式和子句中使用原始列名而不是别名。尤其是在别名与列名相同的情况下，这一设置尤其重要，见 表达式别名。启用该设置可使 ClickHouse 中的别名语法规则与大多数其他数据库引擎更加兼容。

可能的值：

• 0 — 列名将被别名替换。
• 1 — 列名不被别名替换。

示例

已启用和已禁用之间的差异：

查询：

SET prefer_column_name_to_alias = 0;
SELECT avg(number) AS number, max(number) FROM numbers(10);

结果：

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.

查询：

SET prefer_column_name_to_alias = 1;
SELECT avg(number) AS number, max(number) FROM numbers(10);

结果：

┌─number─┬─max(number)─┐
│    4.5 │           9 │
└────────┴─────────────┘

prefer_external_sort_block_bytes​