会话设置

system.settings 表中的设置。

以下所有设置也可在表 system.settings 中查看。这些设置由 源文件 自动生成。

​

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_function_input_format

INSERT 操作期间 AggregateFunction 输入的格式。

可能的值：

• state — 包含序列化状态的二进制字符串 (默认值) 。这是默认行为，此时 AggregateFunction 值应以二进制数据形式提供。
• value — 该格式要求提供聚合函数参数的单个值；如果有多个参数，则提供由这些值组成的 Tuple。它们将使用相应的 IDataType 或 DataTypeTuple 进行反序列化，然后聚合形成状态。
• array — 该格式要求提供一个值的 Array，如上文 value 选项所述。数组中的所有元素都会被聚合形成状态。

示例

对于一个具有以下结构的表：

CREATE TABLE example (
    user_id UInt64,
    avg_session_length AggregateFunction(avg, UInt32)
);

当 aggregate_function_input_format = 'value' 时：

INSERT INTO example FORMAT CSV
123,456

当 aggregate_function_input_format = 'array' 时：

INSERT INTO example FORMAT CSV
123,"[456,789,101]"

注意：value 和 array 格式比默认的 state 格式更慢，因为它们需要在插入时创建并聚合值。

​

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 相同。

​

ai_function_max_api_calls_per_query

AI 函数每个查询最多可发起的 HTTP 请求数。设置为 0 可禁用。

​

ai_function_max_input_tokens_per_query

单个查询中所有 AI 函数 API 调用的输入 (prompt) 标记总数上限。该值会根据提供商的响应进行累计统计。请注意，由于单次调用的输入标记数无法预先得知，因此该限制可能会被某一次调用的输入标记数超出。设置为 0 可禁用。

​

ai_function_max_output_tokens_per_query

单次查询中所有 AI 函数 API 调用的最大总输出 (completion) 标记数。根据提供商的响应累计统计。请注意，由于单次调用的输出标记数无法预先得知，因此该限制可能会被一次调用产生的输出标记数超出。设置为 0 可禁用。

​

ai_function_max_retries

每个 API 请求在发生瞬时错误时允许的最大重试次数。每次重试都会采用指数退避机制，初始延迟从 ai_function_retry_initial_delay_ms 开始。

​

ai_function_request_timeout_sec

AI 函数发起的单个 HTTP 请求 (AI 聊天补全和 embedding API 调用) 的超时时间，单位为秒。如果请求未在该时间内完成，则视为失败，并且可根据 ai_function_max_retries 进行重试。

​

ai_function_retry_initial_delay_ms

失败的 AI 函数 API 请求在首次重试前的初始延迟 (以毫秒为单位) 。此后每次重试时，延迟都会翻倍 (指数退避) 。例如，在默认设置下：1000ms、2000ms、4000ms。

​

ai_function_throw_on_error

如果为 true (默认值) ，AI 函数调用在用尽所有重试次数后仍发生永久性失败时，将以异常终止查询。如果为 false，失败的行会使用该列类型的默认值 (String 为空字符串) ，并继续处理。

​

ai_function_throw_on_quota_exceeded

如果为 true (默认值) ，当超出 AI 函数配额限制 (ai_function_max_input_tokens_per_query、ai_function_max_output_tokens_per_query 或 ai_function_max_api_calls_per_query) 时，查询将因异常而中止。如果为 false，则其余行将使用该列类型的默认值 (String 类型为空字符串) 。

​

allow_aggregate_partitions_independently

当分区键适用于 group by 键时，允许在不同线程上对各个分区独立进行聚合。当分区数量接近 CPU 核心数且各分区大小大致相同时，此设置效果更佳

​

allow_archive_path_syntax

如果归档文件具有正确的扩展名，File/S3 引擎/表函数会将带有 ’::’ 的路径解析为 <archive> :: <file>。

​

allow_asynchronous_read_from_io_pool_for_merge_tree

使用后台 I/O 池从 MergeTree 表中读取数据。此设置可能会提高受 I/O 限制的查询性能

​

allow_calculating_subcolumns_sizes_for_merge_tree_reading

启用后，ClickHouse 将计算读取每个子列所需文件的大小，以便更准确地计算任务大小和块大小。

​

allow_changing_replica_until_first_data_packet

如果启用此项，在对冲请求中，即使已经有了一些 Progress，也可以在收到第一个数据包之前发起新的 connection (但在 receive_data_timeout 超时内，Progress 没有更新) ；否则，在第一次取得 Progress 后，就会禁止切换副本。

​

allow_create_index_without_type

允许执行不带 TYPE 的 CREATE INDEX 查询。该查询会被忽略。此设置用于 SQL 兼容性测试。

​

allow_custom_error_code_in_throwif

允许在函数 throwIf() 中使用自定义错误码。如果为 true，抛出的异常可能带有非预期的错误码。

​

allow_ddl

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

​

allow_deprecated_database_ordinary

允许使用已弃用的 Ordinary engine 创建数据库。

​

allow_deprecated_error_prone_window_functions

允许使用已弃用的易出错窗口函数 (neighbor、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 连接键中使用 Dynamic 类型。此设置是为兼容性而添加的。不建议在 JOIN 连接键中使用 Dynamic 类型，因为与其他类型比较时可能会产生异常结果。

​

allow_execute_multiif_columnar

允许以列式方式执行 multiIf 函数

​

allow_experimental_ai_functions

启用 Experimental AI 函数 (例如 aiGenerateContent) 。这些函数会向 AI 提供商发起外部 HTTP 调用。

​

allow_experimental_analyzer

别名: enable_analyzer

允许启用新的查询分析器。

​

allow_experimental_cleanup_old_data_files_compaction

允许在 Iceberg 合并整理期间清理旧数据文件。

​

allow_experimental_codecs

如果将其设置为 true，则允许指定 Experimental 压缩编解码器 (但目前还没有这类编解码器，因此此选项实际上不起作用) 。

​

allow_experimental_correlated_subqueries

允许执行关联子查询。

​

allow_experimental_database_glue_catalog

别名: allow_database_glue_catalog

允许使用 catalog_type = 'glue' 的实验性数据库引擎 DataLakeCatalog

Cloud 默认值：1。

​

allow_experimental_database_hms_catalog

允许使用实验性的数据库引擎 DataLakeCatalog，且 catalog_type = ‘hms’

​

allow_experimental_database_iceberg

别名: allow_database_iceberg

允许使用 catalog_type = 'iceberg' 的实验性数据库引擎 DataLakeCatalog

Cloud 默认值：1。

​

allow_experimental_database_materialized_postgresql

允许创建使用 Engine=MaterializedPostgreSQL(…) 的 database。

​

allow_experimental_database_paimon_rest_catalog

允许使用 catalog_type = 'paimon_rest' 的 Experimental 数据库引擎 DataLakeCatalog

​

allow_experimental_database_unity_catalog

别名: allow_database_unity_catalog

允许实验性数据库引擎 DataLakeCatalog 使用 catalog_type = ‘unity’

Cloud 默认值：1。

​

allow_experimental_delta_kernel_rs

允许使用实验性的 delta-kernel-rs 实现。

​

allow_experimental_delta_lake_writes

启用 delta-kernel 写入功能。

​

allow_experimental_expire_snapshots

允许执行实验性的 Iceberg 命令 ALTER TABLE ... EXECUTE expire_snapshots。

​

allow_experimental_funnel_functions

启用漏斗分析的 Experimental 函数。

​

allow_experimental_geo_types_in_iceberg

允许将 Iceberg 的 geometry 和 geography 字段类型解析为 ClickHouse Geometry (Variant) 类型。

​

allow_experimental_hash_functions

启用实验性哈希函数

​

allow_experimental_iceberg_compaction

允许显式对 Iceberg 表使用 ‘OPTIMIZE’。

​

allow_experimental_join_right_table_sorting

如果将其设置为 true，且满足 join_to_sort_minimum_perkey_rows 和 join_to_sort_maximum_table_rows 的条件，则按键对右表重新排序，以提升 left 或 inner hash join 的性能。

​

allow_experimental_json_lazy_type_hints

启用 JSON 类型的实验性惰性类型提示。此功能可通过延后对类型提示的求值来优化 JSON 类型转换。

​

allow_experimental_kafka_offsets_storage_in_keeper

允许通过 Experimental 功能将与 Kafka 相关的偏移量存储在 ClickHouse Keeper 中。启用后，可以为 Kafka table engine 指定 ClickHouse Keeper 路径和副本名称。这样，系统将不再使用常规的 Kafka 引擎，而会使用一种新的存储引擎类型，其主要将已提交的偏移量存储在 ClickHouse Keeper 中

​

allow_experimental_kusto_dialect

启用 Kusto 查询语言 (KQL) ，作为 SQL 的一种替代方案。

​

allow_experimental_materialized_postgresql_table

允许使用 MaterializedPostgreSQL 表引擎。此功能默认为禁用状态，因为它仍处于 Experimental 阶段

​

allow_experimental_nlp_functions

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

​

allow_experimental_nullable_tuple_type

允许在表中创建 Nullable Tuple 列。

此设置不控制提取出的 Tuple 子列是否可以为 Nullable (例如从 Dynamic、Variant、JSON 或 Tuple 列中提取出的子列) 。 如需控制提取出的 Tuple 子列是否可以为 Nullable，请使用 allow_nullable_tuple_in_extracted_subcolumns。

​

allow_experimental_object_storage_queue_hive_partitioning

允许在 S3Queue/AzureQueue 引擎中使用 Hive 分区

​

allow_experimental_paimon_storage_engine

允许创建使用 Paimon* 表引擎的表。

​

allow_experimental_parallel_reading_from_replicas

别名: enable_parallel_replicas

执行 SELECT 查询时，每个分片最多可使用 max_parallel_replicas 个副本。读取会并行执行，并进行动态协调。0 - 禁用，1 - 启用，若发生故障则静默禁用，2 - 启用，若发生故障则抛出异常

​

allow_experimental_polyglot_dialect

启用 polyglot SQL transpiler，可将 30 多种方言 (MySQL、PostgreSQL、SQLite、Snowflake、DuckDB 等) 的 SQL 转译为 ClickHouse SQL。

​

allow_experimental_prql_dialect

启用 PRQL，这是一种可替代 SQL 的语言。

​

allow_experimental_query_deduplication

基于分片 UUID 的 SELECT 查询实验性去重

​

allow_experimental_time_series_aggregate_functions

别名: allow_experimental_ts_to_grid_aggregate_function

用于 Prometheus 风格的时间序列重采样、rate 和 delta 计算的实验性 timeSeries* 聚合函数。

​

allow_experimental_time_series_table

允许创建使用 TimeSeries 表引擎的表。可选值：

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

​

allow_experimental_unique_key

允许在 MergeTree 家族引擎上创建带有 UNIQUE KEY 子句的表。

​

allow_experimental_window_view

启用 WINDOW VIEW。该功能尚不够成熟。

​

allow_experimental_ytsaurus_dictionary_source

用于集成 YTsaurus 的 Experimental 字典源。

​

allow_experimental_ytsaurus_table_engine

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

​

allow_experimental_ytsaurus_table_function

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

​

allow_fuzz_query_functions

启用 fuzzQuery 函数，该函数会对查询字符串的 AST 随机执行变更。

​

allow_general_join_planning

允许使用更通用的 JOIN 规划算法来处理更复杂的条件，但仅适用于 hash join。如果未启用 hash join，则无论此设置的值如何，都会使用常规的 JOIN 规划算法。

​

allow_get_client_http_header

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

​

allow_hyperscan

允许使用 Hyperscan 库的函数。禁用此项可避免潜在的长时间编译和过高的资源占用。

​

allow_iceberg_remove_orphan_files

允许对 Iceberg 表使用 ALTER TABLE ... EXECUTE remove_orphan_files()。

​

allow_insert_into_iceberg

别名: allow_experimental_insert_into_iceberg

允许向 Iceberg 执行 insert 查询。

​

allow_introspection_functions

启用或禁用用于查询分析的内部信息函数。

可能的值：

• 1 — 已启用内部信息函数。
• 0 — 已禁用内部信息函数。

另请参见

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

​

allow_key_condition_coalesce_rewrite

在索引分析之前，将形如 coalesce(a_1, ..., a_N) <op> const 的谓词 (以及等价的 ifNull 形式，或常量位于左侧的情况) 重写为析取表达式 (a_1 <op> const) OR (a_1 IS NULL AND a_2 <op> const) OR ... OR (a_1 IS NULL AND ... AND a_{N-1} IS NULL AND a_N <op> const)，以便使用每个 a_i 上的主键和跳过索引。还会处理部分常量形式，例如 coalesce(a, 42, b) 和 coalesce(a, b, 42)：参数列表会像 coalesce 本身一样先做归一化处理 (删除 NULL 字面量，并丢弃第一个非 Nullable 参数之后的参数) ，如果存在末尾的非 NULL 常量，则将其作为最后一个分支输出。该重写仅用于增强索引剪枝；运行时过滤仍使用原始谓词。

​

allow_materialized_view_with_bad_select

允许使用引用不存在表或列的 SELECT 查询来 CREATE MATERIALIZED VIEW。该查询在语法上仍必须有效。不适用于可刷新的 MV。如果需要根据 SELECT 查询来 infer MV 的 schema，则也不适用 (即 CREATE 没有列列表，且没有 TO 表时) 。可用于在 source table 创建之前先创建 MV。

​

allow_named_collection_override_by_default

默认允许覆盖命名集合中的字段。

​

allow_non_metadata_alters

允许执行不仅会影响表元数据、还会影响磁盘上数据的 alter 操作

​

allow_nonconst_timezone_arguments

允许在某些与时间相关的函数中使用非常量时区参数，例如 toTimeZone()、fromUnixTimestamp*()、snowflakeToDateTime*()。 此设置仅为兼容性而保留。在 ClickHouse 中，时区是数据类型的属性，准确地说，也是列的属性。 启用此设置会给人一种错误印象，仿佛同一列中的不同值可以具有不同的时区。 因此，请不要启用此设置。

​

allow_nondeterministic_mutations

允许在复制表的变更中使用非确定性函数 (如 dictGet) 的用户级设置。

例如，字典在各节点之间可能存在不同步的情况，因此默认不允许复制表上的变更从字典中获取值。启用此设置后将允许这种行为，但用户需自行确保所使用的数据在所有节点之间保持同步。

示例

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

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

    <!-- ... -->

</profiles>

​

allow_nondeterministic_optimize_skip_unused_shards

允许在分片键中使用非确定性函数 (例如 rand 或 dictGet；后者在更新时有一些注意事项) 。

可能的值：

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

​

allow_nullable_tuple_in_extracted_subcolumns

控制类型为 Tuple(...) 的提取子列是否可以具有 Nullable(Tuple(...)) 类型。

• false：返回 Tuple(...)，并对缺失该子列的行使用默认 Tuple 值。
• true：返回 Nullable(Tuple(...))，并对缺失该子列的行使用 NULL。

此设置仅控制提取子列的行为。 它不控制是否可以在表中创建 Nullable(Tuple(...)) 列；这一点由 allow_experimental_nullable_tuple_type 控制。

ClickHouse 使用服务器启动时为此设置加载的值。 通过 SET 或查询级 SETTINGS 所做的更改不会改变提取子列的行为。 若要更改提取子列的行为，请在启动时加载的 profile 配置 (例如 users.xml) 中更新 allow_nullable_tuple_in_extracted_subcolumns，然后重启服务器。

​

allow_prefetched_read_pool_for_local_filesystem

如果所有 parts 都在本地文件系统上，则优先使用预取线程池

​

allow_prefetched_read_pool_for_remote_filesystem

当所有 parts 均位于远程文件系统上时，优先使用预取线程池

​

allow_push_predicate_ast_for_distributed_subqueries

允许在启用分析器的情况下，对分布式子查询在 AST 层级下推谓词

​

allow_push_predicate_when_subquery_contains_with

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

​

allow_rank_dense_rank_arguments

允许向 RANK 和 DENSE_RANK 窗口函数传递参数，以保持向后兼容。

按照 SQL 标准，RANK 和 DENSE_RANK 不接受任何参数——它们仅基于 OVER (ORDER BY ...) 窗口对行进行排名。在 26.5 之前的 ClickHouse 版本中，类似 RANK(x) OVER (...) 的查询会静默接受并忽略该参数，这容易让用户产生困惑 (显式写出的参数看起来似乎会影响排名，但实际上并不会) 。

当此设置为 false (默认值) 时，RANK 和 DENSE_RANK 会拒绝任何参数，并抛出 NUMBER_OF_ARGUMENTS_DOESNT_MATCH。当设为 true 时，将恢复旧版的宽松行为—— 参数会被静默忽略，与 26.5 之前的行为一致。

​

allow_reorder_prewhere_conditions

将条件从 WHERE 移至 PREWHERE 时，允许重新排序这些条件以优化过滤效果

​

allow_settings_after_format_in_insert

控制是否允许在 INSERT 查询中于 FORMAT 之后使用 SETTINGS。不建议使用此设置，因为这可能会将 SETTINGS 的一部分解释为值。

示例：

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

如果支持 AVX2 指令，则允许在 ‘JSON*’ 函数中使用 simdjson 库。禁用时将使用 rapidjson。

​

allow_special_serialization_kinds_in_output_formats

允许直接输出采用 Sparse 和 Replicated 等特殊序列化类型的列，而无需将其转换为普通列表示。 这有助于避免在格式化过程中发生不必要的数据复制。

​

allow_statistics

别名: allow_experimental_statistics

允许为列定义统计信息，并管理统计信息。

​

allow_statistics_optimize

别名: allow_statistic_optimize

允许使用统计信息优化查询

​

allow_suspicious_codecs

如果将其设置为 true，则允许指定无实际意义的压缩编解码器。

​

allow_suspicious_fixed_string_types

在 CREATE TABLE 语句中，允许创建类型为 FixedString(n) 且 n > 256 的列。长度 >= 256 的 FixedString 值得警惕，通常说明用法有误

​

allow_suspicious_indices

拒绝主索引/次级索引和排序键使用相同的表达式

​

allow_suspicious_low_cardinality_types

允许或限制将 LowCardinality 用于固定大小为 8 字节或更小的数据类型：数值数据类型和 FixedString(8_bytes_or_less)。

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

• 磁盘空间占用可能增加。
• RAM 占用可能更高，具体取决于字典大小。
• 由于额外的编码/解码操作，某些函数的执行速度可能变慢。

由于上述原因，在 MergeTree 引擎表中，合并时间也可能增加。

Possible values:

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

​

allow_suspicious_primary_key

允许在 MergeTree 中使用可疑的 PRIMARY KEY/ORDER BY (即 SimpleAggregateFunction) 。

​

allow_suspicious_ttl_expressions

拒绝不依赖表中任何列的生存时间 (TTL) 表达式。这在大多数情况下表明是用户错误。

​

allow_suspicious_types_in_group_by

允许或禁止将 Variant 和 Dynamic 类型用作 GROUP BY 键。

​

allow_suspicious_types_in_order_by

控制是否允许在 ORDER BY 键中使用 Variant 和 Dynamic 类型。

​

allow_suspicious_variant_types

在 CREATE TABLE statement 中，允许指定包含相近 Variant 类型的 Variant 类型 (例如，不同的数值类型或日期类型) 。启用此设置后，在处理类型相近的值时可能会带来一定的歧义。

​

allow_unrestricted_reads_from_keeper

允许从 system.zookeeper 表进行不受限制的读取 (即不对 path 添加条件) ，这样做虽然方便，但对 ZooKeeper 并不安全

​

alter_move_to_space_execute_async

以异步方式执行 ALTER TABLE MOVE … TO [DISK|VOLUME]

​

alter_partition_verbose_result

启用或禁用显示有关分区和 parts 操作已成功应用到哪些 parts 的信息。 适用于 ATTACH PARTITION|PART 和 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

别名: replication_alter_partitions_sync

用于指定由 ALTER、OPTIMIZE 或 TRUNCATE 查询触发、需在副本上执行的操作的等待行为。

可能的值：

• 0 — 不等待。
• 1 — 等待本副本执行完成。
• 2 — 等待所有副本执行完成。
• 3 - 仅等待活跃副本。

Cloud 默认值：0。

alter_sync 仅适用于 Replicated 和 SharedMergeTree 表，对非 Replicated 或 Shared 表不起作用。

​

alter_update_mode

用于包含 UPDATE 命令的 ALTER 查询的模式。

可能的值：

• heavy - 执行常规变更。
• lightweight - 如果可以，则执行轻量级更新；否则执行常规变更。
• lightweight_force - 如果可以，则执行轻量级更新；否则抛出异常。

​

analyze_index_with_space_filling_curves

如果某个表的索引使用了空间填充曲线，例如 ORDER BY mortonEncode(x, y) 或 ORDER BY hilbertEncode(x, y)，且查询中包含其参数的条件，例如 x >= 10 AND x <= 20 AND y >= 20 AND y <= 30，则使用该空间填充曲线进行索引分析。

​

analyzer_compatibility_allow_compound_identifiers_in_unflatten_nested

允许向 nested 结构添加复合标识符。这是一个兼容性设置，因为它会改变查询结果。禁用时，SELECT a.b.c FROM table ARRAY JOIN a 将无法使用，而 SELECT a FROM table 的结果中也不会将 a.b.c 列包含在 Nested a 内。

​

analyzer_compatibility_join_using_top_level_identifier

强制在 JOIN USING 中从投影解析标识符 (例如，在 SELECT a + 1 AS b FROM t1 JOIN t2 USING (b) 中，join 将按 t1.a + 1 = t2.b 执行，而不是按 t1.b = t2.b 执行) 。

​

analyzer_inline_views

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

​

any_join_distinct_right_table_keys

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

只有在你的使用场景依赖旧版 JOIN 行为时，才应出于向后兼容目的使用此设置。

启用旧版行为时：

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

禁用旧版行为时：

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

可能的值：

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

另请参见：

• JOIN strictness

​

apply_deleted_mask

启用后，会过滤掉通过轻量级删除标记删除的行。如果禁用，查询仍可读取这些行。这对于调试和“取消删除”场景很有用

​

apply_mutations_on_fly

如果为 true，尚未在数据分区片段中 materialized 的变更 (UPDATE 和 DELETE) 会在 SELECT 时生效。

​

apply_patch_parts

如果为 true，则会在 SELECT 查询时应用补丁分区片段 (用于表示轻量级更新) 。

​

apply_patch_parts_join_cache_buckets

在 Join 模式下应用补丁分区片段时，临时缓存中的桶数量。

​

apply_prewhere_after_final

启用后，对于 ReplacingMergeTree 及类似引擎，会在 FINAL 处理完成后应用 PREWHERE 条件。 当 PREWHERE 引用了在重复行之间可能取值不同的列时， 如果你希望 FINAL 先选出最终保留的行再进行过滤，这个设置会很有用。禁用时，PREWHERE 会在读取期间应用。 注意：如果启用了 apply_row_level_security_after_final，且行策略使用了非排序键列，PREWHERE 也会 被延后，以保持正确的执行顺序 (必须先应用行策略，再应用 PREWHERE) 。

​

apply_row_policy_after_final

启用后，行策略和 PREWHERE 会在 *MergeTree 表完成 FINAL 处理后再应用。 (尤其是对 ReplacingMergeTree) 禁用后，行策略会在 FINAL 之前应用；如果策略 过滤掉了本应在 ReplacingMergeTree 或类似引擎中用于去重的行，则可能导致结果不同。

如果行策略表达式仅依赖于 ORDER BY 中的列，出于优化考虑，它仍会在 FINAL 之前应用， 因为这种过滤不会影响去重结果。

可能的值：

• 0 — 在 FINAL 之前应用行策略和 PREWHERE (默认) 。
• 1 — 在 FINAL 之后应用行策略和 PREWHERE。

​

apply_settings_from_server

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

这只会影响在客户端执行的操作，尤其是 INSERT 输入数据的解析和查询结果的格式化。查询执行的大部分工作都发生在服务器端，因此不受此设置影响。

通常，此设置应在用户 profile 中设置 (通过 users.xml 或 ALTER USER 这类查询) ，而不是通过客户端进行设置 (客户端命令行参数、SET 查询或 SELECT 查询中的 SETTINGS 部分) 。通过客户端可以将其改为 false，但不能改为 true (因为如果用户 profile 中设置了 apply_settings_from_server = false，服务器就不会发送这些设置) 。

请注意，在最初的 24.12 版本中，这里有一个 server setting (send_settings_to_client) ，但后来为了提升易用性，它被这个 client setting 取代了。

​

archive_adaptive_buffer_max_size_bytes

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

​

arrow_flight_request_descriptor_type

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

可能的值：

• ‘path’ — 使用 FlightDescriptor::Path (默认值，适用于大多数 Arrow Flight 服务器)
• ‘command’ — 使用带有 SELECT 查询的 FlightDescriptor::Command (Dremio 必需)

​

ast_fuzzer_any_query

当值为 false (默认值) 时，由 ast_fuzzer_runs 控制的服务器端 AST fuzzer 仅对只读查询 (SELECT、EXPLAIN、SHOW、DESCRIBE、EXISTS) 进行模糊测试。当值为 true 时，则会对包括 DDL 和 INSERT 在内的所有查询类型进行模糊测试。

​

ast_fuzzer_runs

启用服务端 AST fuzzer。它会在每次正常查询后运行随机生成的查询，并丢弃其结果。

• 0：禁用 (默认) 。
• 大于 0 且小于 1 的值：运行单个模糊查询的概率。
• 值 >= 1：每次正常查询要运行的模糊查询数量。

该 fuzzer 会从所有会话中的所有查询中累积 AST 片段，随着时间推移产生越来越有意思的变异。执行失败的模糊查询会被静默丢弃；结果也绝不会返回给客户端。

​

asterisk_include_alias_columns

在通配符查询 (SELECT *) 中包含 ALIAS 列。

可选值：

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

​

asterisk_include_materialized_columns

在通配符查询 (SELECT *) 中包含 MATERIALIZED 列。

可能的值：

• 0 - 禁用
• 1 - 启用

​

asterisk_include_virtual_columns

在通配符查询 (SELECT *) 中包含虚拟列。

可选值：

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

​

async_insert

如果为 true，INSERT 查询中的数据会先存储在队列中，随后在后台写入表中。如果 wait_for_async_insert 为 false，INSERT 查询几乎会立即处理完成；否则，客户端会等待，直到数据被写入表中

​

async_insert_busy_timeout_decrease_rate

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

​

async_insert_busy_timeout_increase_rate

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

​

async_insert_busy_timeout_max_ms

别名: async_insert_busy_timeout_ms

自首条数据出现起，每个查询在转储已收集数据前的最长等待时间。

Cloud 默认值：1000 (1s)。

​

async_insert_busy_timeout_min_ms

如果通过 async_insert_use_adaptive_busy_timeout 启用了自动调整，则该值表示自首次出现数据起，每个查询在转储已收集数据之前的最短等待时间。它也用作自适应算法的初始值

​

async_insert_deduplicate

对于副本表中的 async INSERT 查询，指定是否对插入块执行去重

​

async_insert_max_data_size

每个查询在插入前可收集的未解析数据的最大字节数

Cloud 默认值：104857600 (100 MiB) 。

​

async_insert_max_query_number

数据实际写入前可累积的最大 INSERT 查询数。 仅当设置 async_insert_deduplicate 为 1 时生效。

​

async_insert_poll_timeout_ms

从异步插入队列中轮询数据的超时时间

​

async_insert_use_adaptive_busy_timeout

如果设置为 true，则异步插入将使用自适应忙碌超时

​

async_query_sending_for_remote

在执行远程查询时，启用异步创建连接和发送查询。

默认启用。

​

async_socket_for_remote

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

默认启用。

​

automatic_parallel_replicas_min_bytes_per_replica

自动启用并行副本所需的每个副本读取字节数阈值 (仅在 automatic_parallel_replicas_mode=1 时适用) 。0 表示无阈值。 待读取的总字节数会根据已收集的统计信息进行估算。

​

automatic_parallel_replicas_mode

根据已收集的统计信息，启用自动切换为使用并行副本执行。要求 enable_analyzer = 1、enable_parallel_replicas != 0、parallel_replicas_local_plan = 1，并提供 cluster_for_parallel_replicas。 0 - 禁用，1 - 启用，2 - 仅启用统计信息收集 (禁用切换为使用并行副本执行) 。

​

azure_allow_parallel_part_upload

使用多个线程执行 Azure 分段上传。

​

azure_check_objects_after_upload

检查 Azure Blob 存储中的每个已上传对象，确认上传是否成功

​

azure_connect_timeout_ms

连接到 azure disks 主机时的超时时间。

​

azure_create_new_file_on_insert

启用或禁用在 Azure engine 表中每次 insert 时创建新文件的功能

​

azure_ignore_file_doesnt_exist

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

可能的值：

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

​

azure_list_object_keys_size

ListObject 请求单个批次可返回的最大文件数

​

azure_max_blocks_in_multipart_upload

Azure 分段上传的最大块数。

​

azure_max_get_burst

在达到每秒请求数限制前，可同时发出的最大请求数。默认值 (0) 等于 azure_max_get_rps

​

azure_max_get_rps

Azure 每秒 GET 请求速率在触发限流前的上限。0 表示不限制。

​

azure_max_inflight_parts_for_one_file

分段上传请求中可并发上传的分片最大数量。0 表示不受限制。

​

azure_max_put_burst

达到每秒请求数限制前，可同时发出的最大请求数。默认值为 0 时，等同于 azure_max_put_rps

​

azure_max_put_rps

Azure PUT 请求每秒速率的限制，超过后会触发限流。0 表示不限制。

​

azure_max_redirects

允许的 Azure 重定向跳转次数上限。

​

azure_max_single_part_copy_size

使用单个分片复制到 Azure Blob 存储时，对象的最大可复制大小。

​

azure_max_single_part_upload_size

使用单分片上传到 Azure Blob 存储时，对象的最大大小。

​

azure_max_single_read_retries

单次 Azure Blob 存储读取的最大重试次数。

​

azure_max_unexpected_write_error_retries

Azure Blob 存储写入期间发生意外错误时的最大重试次数

​

azure_max_upload_part_size

向 Azure Blob 存储执行分段上传时，单个上传分段的最大大小。

​

azure_min_upload_part_size

向 Azure Blob 存储进行分段上传时，单个上传分段的最小大小。

​

azure_request_timeout_ms

向 Azure 发送和从 Azure 接收数据时的空闲超时时间。如果单次 TCP 读取或写入调用阻塞超过该时长，则会失败。

​

azure_sdk_max_retries

Azure SDK 的最大重试次数

​

azure_sdk_retry_initial_backoff_ms

Azure SDK 中两次重试之间的最小退避时间

​

azure_sdk_retry_max_backoff_ms

Azure SDK 中两次重试之间的最大退避间隔

​

azure_skip_empty_files

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

可选值：

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

​

azure_strict_upload_part_size

向 Azure Blob 存储执行分段上传时，每个分段的精确大小。

​

azure_throw_on_zero_files_match

如果根据 glob 展开规则未匹配到任何文件，则抛出错误。

可能的值：

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

​

azure_truncate_on_insert

启用或禁用在 Azure engine 表中 insert 前先执行 truncate。

​

azure_upload_part_size_multiply_factor

每当单次写入 Azure Blob 存储上传的分片数达到 azure_multiply_parts_count_threshold 时，就将 azure_min_upload_part_size 乘以该因子。

​

azure_upload_part_size_multiply_parts_count_threshold

每当上传到 Azure Blob 存储的分片数量达到该值时，azure_min_upload_part_size 就会乘以 azure_upload_part_size_multiply_factor。

​

azure_use_adaptive_timeouts

当设置为 true 时，所有 azure 请求的前两次尝试都会使用较短的发送和接收超时时间。 当设置为 false 时，所有尝试都会使用相同的超时时间。

​

backup_restore_batch_size_for_keeper_multi

在备份或恢复期间，向 [Zoo]Keeper 发起多重请求时的最大批次大小

​

backup_restore_batch_size_for_keeper_multiread

在备份或恢复期间，向 [Zoo]Keeper 发起 multiread 请求时的最大批次大小

​

backup_restore_failure_after_host_disconnected_for_seconds

如果某个主机在执行 BACKUP ON CLUSTER 或 RESTORE ON CLUSTER 期间，持续这段时间都未能在 ZooKeeper 中重新创建其临时 “alive” 节点，则整个 backup 或 restore 会被视为失败。 该值应大于主机发生故障后重新连接到 ZooKeeper 所需的任何合理时长。 0 表示不受限制。

​

backup_restore_finish_timeout_after_error_sec

在当前 BACKUP ON CLUSTER 或 RESTORE ON CLUSTER 操作中，发起节点在 'error' 节点出现后，等待其他主机作出响应并停止当前工作的时长。

​

backup_restore_keeper_fault_injection_probability

在备份或恢复期间，Keeper 请求发生故障的近似概率。有效值范围为 [0.0f, 1.0f]

​

backup_restore_keeper_fault_injection_seed

0 - 随机种子，否则为该设置值

​

backup_restore_keeper_max_retries

BACKUP 或 RESTORE 操作过程中，[Zoo]Keeper 操作的最大重试次数。 该值应足够大，以确保整个操作不会因临时的 [Zoo]Keeper 故障而失败。

​

backup_restore_keeper_max_retries_while_handling_error

处理 BACKUP ON CLUSTER 或 RESTORE ON CLUSTER 操作期间发生的错误时，[Zoo]Keeper 操作的最大重试次数。

​

backup_restore_keeper_max_retries_while_initializing

初始化 BACKUP ON CLUSTER 或 RESTORE ON CLUSTER 操作时，[Zoo]Keeper 操作的最大重试次数。

​

backup_restore_keeper_retry_initial_backoff_ms

用于备份或恢复期间 [Zoo]Keeper 操作的初始退避超时时间

​

backup_restore_keeper_retry_max_backoff_ms

在备份或恢复期间，[Zoo]Keeper 操作的最大退避超时时长

Cloud 默认值：60000。

​

backup_restore_keeper_value_max_size

备份期间 [Zoo]Keeper 节点数据的最大大小

​

backup_restore_s3_retry_attempts

Aws::Client::RetryStrategy 的设置项。Aws::Client 会自行重试，0 表示不重试。仅对备份/恢复生效。

​

backup_restore_s3_retry_initial_backoff_ms

在备份和恢复过程中，首次重试前的初始 backoff 延迟，单位为毫秒。此后的每次重试都会按指数方式增加延迟，直到达到 backup_restore_s3_retry_max_backoff_ms 指定的最大值

​

backup_restore_s3_retry_jitter_factor

在备份和恢复操作期间，此项用于为 Aws::Client::RetryStrategy 中的重试退避延迟应用抖动系数。计算出的退避延迟会乘以一个位于 [1.0, 1.0 + jitter] 范围内的随机系数，且最大不超过 backup_restore_s3_retry_max_backoff_ms。其值必须在 [0.0, 1.0] 区间内

​

backup_restore_s3_retry_max_backoff_ms

备份和恢复操作期间，重试之间的最大延迟 (以毫秒为单位) 。

​

backup_slow_all_threads_after_retryable_s3_error

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

​

cache_warmer_threads

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

​

calculate_text_stack_trace

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

​

cancel_http_readonly_queries_on_client_close

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

Cloud 默认值：1。

​

cast_ipv4_ipv6_default_on_conversion_error

将 CAST 运算符转换为 IPv4、将 CAST 运算符转换为 IPv6 类型，以及 toIPv4、toIPv6 函数，在转换错误时会返回默认值，而不是抛出异常。

​

cast_keep_nullable

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

启用此设置后，如果 CAST 函数的参数为 Nullable，结果也会转换为 Nullable 类型。禁用此设置时，结果始终严格为目标数据类型。

Possible values:

• 0 — CAST 结果严格为指定的目标数据类型。
• 1 — 如果参数类型为 Nullable，则 CAST 结果会转换为 Nullable(DestinationDataType)。

Examples

以下查询的结果严格为目标数据类型：

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

允许在从 String 进行转换时，选择日期和时间文本表示的解析器。

可能的值：

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

在将 String 转换为 Dynamic 时使用类型推断

​

cast_string_to_variant_use_inference

在从 String 转换为 Variant 时使用类型推断。

​

check_named_collection_dependencies

检查 DROP NAMED COLLECTION 不会导致依赖它的表失效

​

check_query_single_value_result

定义 MergeTree 家族引擎中 CHECK TABLE 查询结果的详细程度。

Possible values:

• 0 — 查询会显示表中每个数据分区片段各自的检查状态。
• 1 — 查询会显示表的整体检查状态。

​

check_referential_table_dependencies

检查 DDL 查询 (如 DROP TABLE 或 RENAME) 是否会破坏引用依赖关系

​

check_table_dependencies

检查 DDL 查询 (如 DROP TABLE 或 RENAME) 是否会破坏依赖关系

​

checksum_on_read

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

​

cloud_mode

Cloud 模式

Cloud 默认值：1。

​

cloud_mode_database_engine

Cloud 中允许的数据库引擎。1 - 将 DDL 重写为使用 Replicated 数据库，2 - 将 DDL 重写为使用 Shared 数据库

Cloud 默认值：2。

​

cloud_mode_engine

Cloud 中允许使用的引擎家族。

• 0 - 允许所有引擎
• 1 - 将 DDLs 重写为使用 *ReplicatedMergeTree
• 2 - 将 DDLs 重写为使用 SharedMergeTree
• 3 - 将 DDLs 重写为使用 SharedMergeTree，但显式指定远程磁盘时除外
• 4 - 与 3 相同，另外使用 Alias 而不是 Distributed (Alias 表将指向 Distributed 表的目标表，因此会使用对应的本地表)

使用 UInt64 以尽量减少公开部分

Cloud 默认值：2。

​

cluster_for_parallel_replicas

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

Cloud 默认值：default。

​

cluster_function_process_archive_on_multiple_nodes

如果设置为 true，可提高 cluster functions 中处理归档的性能。若要保持兼容性，并避免在使用带归档的 cluster functions 从较早版本升级到 25.7+ 时出错，则应将其设置为 false。

​

cluster_table_function_buckets_batch_size

定义在采用 bucket 拆分粒度的 cluster 表函数中进行任务分布式处理时所使用的批次近似大小 (以字节为单位) 。系统会持续累积数据，直到至少达到该大小。为与数据边界对齐，实际大小可能会略大一些。

​

cluster_table_function_split_granularity

控制在执行 CLUSTER TABLE FUNCTION 时，如何将数据拆分为任务。

此设置定义了工作在集群中的分发粒度：

• file — 每个任务处理整个文件。
• bucket — 任务按文件内部的数据块创建 (例如 Parquet 行组) 。

选择更细的粒度 (如 bucket) 时，在处理少量大文件的场景下可以提升并行度。 例如，如果一个 Parquet 文件包含多个行组，启用 bucket 粒度后，每个行组都可以由不同的工作线程独立处理。

​

collect_hash_table_stats_during_aggregation

启用哈希表统计信息收集，以优化内存分配

​

collect_hash_table_stats_during_joins

启用收集哈希表统计信息，以优化内存分配

​

compatibility

compatibility 设置会使 ClickHouse 使用由该设置指定的 ClickHouse 早期版本的默认设置。

如果某些设置已被设为非默认值，则这些设置会被保留 (只有未修改的设置才会受 compatibility 设置影响) 。

此设置接受一个以字符串形式表示的 ClickHouse 版本号，例如 22.3、22.8。空值表示此设置已禁用。

默认处于禁用状态。

在 ClickHouse Cloud 中，服务级默认的 compatibility 设置必须由 ClickHouse Cloud Support 配置。请提交工单进行设置。 不过，也可以使用标准的 ClickHouse 设置机制，在用户、Role、profile、查询或 session 级别覆盖 compatibility 设置，例如在 session 中使用 SET compatibility = '22.3'，或在查询中使用 SETTINGS compatibility = '22.3'。

​

compatibility_ignore_auto_increment_in_create_table

如果为 true，则忽略列声明中的 AUTO_INCREMENT 关键字；否则返回错误。这有助于简化从 MySQL 的迁移

​

compatibility_ignore_collation_in_create_table

兼容性：在 CREATE TABLE 中忽略排序规则

​

compatibility_s3_presigned_url_query_in_path

兼容性：启用后，会将预签名 URL 的查询参数 (如 X-Amz-*) 并入 S3 键中 (旧版行为) ， 因此路径中的 ’?’ 会被当作通配符。禁用时 (默认) ，预签名 URL 的查询参数将保留在 URL 查询字符串中， 以避免把 ’?’ 解释为通配符。

​

compile_aggregate_expressions

启用或禁用将聚合函数 JIT 编译为原生代码。启用此设置可提升性能。

可能的值：

• 0 — 聚合在不使用 JIT 编译的情况下进行。
• 1 — 聚合使用 JIT 编译进行。

另请参见

• min_count_to_compile_aggregate_expression

​

compile_expressions

将部分标量函数和运算符编译为原生代码。

​

compile_sort_description

将排序描述编译成原生代码。

​

connect_timeout

没有副本时的连接超时时间。

​

connect_timeout_with_failover_ms

如果在集群定义中使用了 ‘shard’ 和 ‘replica’ 部分，则此参数表示 Distributed 表引擎连接远程服务器时的超时时间 (以毫秒为单位) 。 如果连接失败，系统会尝试连接其他副本多次。

​

connect_timeout_with_failover_secure_ms

在安全连接中，用于选择第一个健康副本的连接超时时间。

​

connection_pool_max_wait_ms

当连接池已满时，连接可等待的时间 (毫秒) 。

可能的值：

• 正整数。
• 0 — 无限等待。

​

connections_with_failover_max_tries

Distributed 表引擎中，对每个副本进行连接尝试的最大次数。

​

convert_query_to_cnf

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

例如，注意以下 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_default_join_kind

控制去相关查询计划中使用的 JOIN 类型。默认值为 right，这意味着去相关后的查询计划将包含 RIGHT JOIN，且子查询输入位于右侧。

可选值：

• left - 去相关过程将生成 LEFT JOIN，输入表将出现在左侧。
• right - 去相关过程将生成 RIGHT JOIN，输入表将出现在右侧。

​

correlated_subqueries_substitute_equivalent_expressions

使用过滤器表达式推断等价表达式，并用其替代，而不是创建 CROSS JOIN。

​

correlated_subqueries_use_in_memory_buffer

使用内存缓冲区处理关联子查询的输入，以避免重复求值。

​

count_distinct_implementation

指定执行 COUNT(DISTINCT …) 时应使用哪个 uniq* 函数。

可能的值：

• uniq
• uniqCombined
• uniqCombined64
• uniqHLL12
• uniqExact

​

count_distinct_optimization

将 count distinct 重写为 group by 子查询

​

count_matches_stop_at_empty_match

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

​

create_if_not_exists

默认对 CREATE 语句启用 IF NOT EXISTS。如果指定了此设置或 IF NOT EXISTS，且给定名称的表已存在，则不会抛出异常。

​

create_index_ignore_unique

忽略 CREATE UNIQUE INDEX 中的 UNIQUE 关键字。此设置用于 SQL 兼容性测试。

​

create_replicated_merge_tree_fault_injection_probability

在 ZooKeeper 中创建元数据后，创建表过程中发生故障注入的概率

​

create_table_empty_primary_key_by_default

允许在未指定 ORDER BY 和 PRIMARY KEY 时，为 *MergeTree 表创建空主键

​

cross_join_min_bytes_to_compress

在 CROSS JOIN 中，对块进行压缩的最小大小。值为 0 表示禁用此阈值。当达到两个阈值 (按行数或按字节) 中的任意一个时，该块将被压缩。

​

cross_join_min_rows_to_compress

在 CROSS JOIN 中压缩块的最小行数。值为 0 表示禁用此阈值。当达到两个阈值 (按行数或按字节数) 中的任意一个时，就会压缩该块。

​

cross_to_inner_join_rewrite

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

​

data_type_default_nullable

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

可能的值：

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

​

database_atomic_wait_for_drop_and_detach_synchronously

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

可能的值：

• 0 — 查询将延后执行。
• 1 — 查询将立即执行。

​

database_datalake_require_metadata_access

如果没有权限获取数据库引擎 DataLakeCatalog 中表的元数据，是否抛出错误。

​

database_replicated_allow_explicit_uuid

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

​

database_replicated_allow_heavy_create

允许在 Replicated 数据库引擎中执行耗时较长的 DDL 查询 (CREATE AS SELECT 和 POPULATE) 。请注意，这可能会使 DDL 队列长时间阻塞。

​

database_replicated_allow_only_replicated_engine

仅允许在使用 Replicated 引擎的数据库中创建 Replicated 表

Cloud 默认值：1。

​

database_replicated_allow_replicated_engine_arguments

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

​

database_replicated_always_detach_permanently

如果数据库引擎为 Replicated，则以 DETACH TABLE PERMANENTLY 的方式执行 DETACH TABLE

​

database_replicated_enforce_synchronous_settings

对某些查询强制进行同步等待 (另请参见 database_atomic_wait_for_drop_and_detach_synchronously、mutations_sync、alter_sync) 。不建议启用这些设置。

​

database_replicated_initial_query_timeout_sec

设置初始 DDL 查询等待 Replicated 数据库处理之前 DDL 队列条目的时长，单位为秒。

可能的值：

• 正整数。
• 0 — 无限。

​

database_shared_drop_table_delay_seconds

已删除的表在 Shared 数据库中被实际移除前的延迟时间 (以秒为单位) 。在此期间，可以使用 UNDROP TABLE 语句恢复该表。

​

decimal_check_overflow

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

​

deduplicate_blocks_in_dependent_materialized_views

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

可能的值：

0 — 禁用。 1 — 启用。

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

另请参见

• IN 运算符中的 NULL 处理

​

deduplicate_insert

启用或禁用 INSERT INTO 的块去重 (适用于 Replicated* 表) 。 此设置会覆盖 insert_deduplicate 和 async_insert_deduplicate 设置。 该设置有三个可能值：

• disable — 对 INSERT INTO 查询禁用去重。
• enable — 对 INSERT INTO 查询启用去重。
• backward_compatible_choice — 如果特定插入类型启用了 insert_deduplicate 或 async_insert_deduplicate，则启用去重。

​

deduplicate_insert_select

启用或禁用 INSERT SELECT 的块去重 (适用于 Replicated* 表) 。 对于 INSERT SELECT 查询，此设置会覆盖 insert_deduplicate 和 deduplicate_insert。 该设置有四个可能值：

• disable — 对 INSERT SELECT 查询禁用去重。
• force_enable — 对 INSERT SELECT 查询启用去重。如果 SELECT 结果不稳定，则会抛出异常。
• enable_when_possible — 如果 insert_deduplicate 已启用且 SELECT 结果稳定，则启用去重；否则禁用。
• enable_even_for_bad_queries - 如果 insert_deduplicate 已启用，则启用去重。如果 SELECT 结果不稳定，则会记录警告，但查询仍会在启用去重的情况下执行。此选项用于向后兼容。建议改用其他选项，因为它可能导致意外结果。

​

default_materialized_view_sql_security

允许在创建 materialized view 时，为 SQL SECURITY 选项设置默认值。更多关于 SQL security 的信息。

默认值为 DEFINER。

​

default_max_bytes_in_join

当需要施加限制但未设置 max_bytes_in_join 时，右侧表允许的最大大小。

​

default_normal_view_sql_security

允许在创建普通视图时设置默认的 SQL SECURITY 选项。了解更多 SQL security。

默认值为 INVOKER。

​

default_table_engine

当 CREATE statement 中未设置 ENGINE 时，使用的默认表引擎。

可能的值：

• 表示任意有效表引擎名称的字符串

Cloud 默认值：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 security 的更多信息。

默认值为 CURRENT_USER。

​

defer_partition_pruning_after_final

启用时 (默认) ，对于分区键列不属于排序键的表，FINAL 查询会跳过分区裁剪。这是 26.3 中引入的安全正确行为：FINAL 可能需要对主键相同但位于不同分区中的行进行去重，而分区裁剪会静默地将这类行排除在 去重输入之外。

禁用时，即使使用 FINAL 也会应用分区裁剪，从而恢复 26.3 之前的 行为。对于在分区列上带有 WHERE 谓词的查询，这样通常会快得多， 但只有在相同主键的行不可能出现在不同分区中时才是正确的——例如分区列在 insert 时设定且之后从不变化的事件日志表。

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

可能的值：

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

​

delta_lake_enable_engine_predicate

启用 delta-kernel 的内部数据裁剪。

​

delta_lake_enable_expression_visitor_logging

启用 DeltaLake 表达式访问器的测试级别日志。即使在测试日志中，这些日志也可能过于冗长。

​

delta_lake_insert_max_bytes_in_data_file

定义 delta lake 中单个插入数据文件的字节数上限。

​

delta_lake_insert_max_rows_in_data_file

定义 Delta Lake 中单个插入数据文件的行数上限。

​

delta_lake_log_metadata

启用后，会将 Delta Lake 元数据文件记录到系统表中。

​

delta_lake_reload_schema_for_consistency

如果启用，则会在每次执行查询前从 DeltaLake 元数据中重新加载 schema，以确保查询分析期间使用的 schema 与执行期间使用的 schema 一致。

​

delta_lake_snapshot_end_version

要读取的 Delta Lake snapshot 的结束版本。值为 -1 表示读取最新版本 (值 0 是有效的 snapshot version) 。

​

delta_lake_snapshot_start_version

要读取的 delta lake snapshot 的起始版本。值为 -1 表示读取最新版本 (值 0 是有效的 snapshot version) 。

​

delta_lake_snapshot_version

要读取的 Delta Lake 快照版本号。值为 -1 表示读取最新版本 (值 0 也是有效的快照版本) 。

​

delta_lake_throw_on_engine_predicate_error

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

​

describe_compact_output

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

​

describe_include_subcolumns

启用在 DESCRIBE 查询中显示子列。例如，Tuple 的成员，或 Map、Nullable 和 Array 数据类型的子列。

可能的值：

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

示例

请参阅 DESCRIBE 语句示例。

​

describe_include_virtual_columns

如果为 true，则表的虚拟列也会包含在 DESCRIBE 查询结果中

​

方言

用于解析查询的方言

​

dictionary_use_async_executor

使用多个线程执行读取字典源的管道。仅支持字典源为本地 CLICKHOUSE 的字典。

​

dictionary_validate_primary_key_type

验证字典的主键类型。默认情况下，简单布局的 id 类型会隐式转换为 UInt64。

​

distinct_overflow_mode

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

可能的值：

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

​

distributed_aggregation_memory_efficient

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

​

distributed_background_insert_batch

别名: distributed_directory_monitor_batch_inserts

启用/禁用按批次发送已插入的数据。

启用批次发送后，Distributed 表引擎会尝试在一次操作中发送多个已插入数据文件，而不是分别发送。批次发送能更高效地利用服务器和网络资源，从而提升集群性能。

可能值：

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

​

distributed_background_insert_max_sleep_time_ms

别名: distributed_directory_monitor_max_sleep_time_ms

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

可能的值：

• 以毫秒为单位的正整数。

​

distributed_background_insert_sleep_time_ms

别名: distributed_directory_monitor_sleep_time_ms

Distributed 表引擎发送数据时使用的基础时间间隔。发生错误时，实际时间间隔会以指数级增长。

可能的值：

• 以毫秒为单位的正整数。

​

distributed_background_insert_split_batch_on_failure

别名: distributed_directory_monitor_split_batch_on_failure

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

有时，向远程分片发送某个批次可能会失败，原因是在后续的复杂管道中 (例如带有 GROUP BY 的 MATERIALIZED VIEW) 触发了 Memory limit exceeded 或类似错误。在这种情况下，重试也无济于事 (而且会导致该表的分布式发送卡住) ；但如果将该批次中的文件逐个发送，则可能成功执行 INSERT。

因此，将此设置设为 1 后，会对这类批次禁用批处理 (即临时对失败批次禁用 distributed_background_insert_batch) 。

可能的值：

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

此设置也会影响损坏的批次 (这类批次可能是由于服务器 (机器) 异常终止，且 Distributed 表引擎未启用 fsync_after_insert/fsync_directories 而产生的) 。

不应依赖自动批次拆分，因为这可能会影响性能。

​

distributed_background_insert_timeout

别名: insert_distributed_timeout

向 Distributed 表执行插入查询的超时时间。该设置仅在启用 insert_distributed_sync 时生效。值为 0 表示不超时。

​

distributed_cache_alignment

仅在 ClickHouse Cloud 中生效。此设置仅供测试使用，请勿更改

​

distributed_cache_bypass_connection_pool

仅在 ClickHouse Cloud 中生效。允许绕过分布式缓存连接池

​

distributed_cache_connect_backoff_max_ms

仅在 ClickHouse Cloud 中生效。设置创建分布式缓存连接时的最大退避毫秒数。

​

distributed_cache_connect_backoff_min_ms

仅在 ClickHouse Cloud 中生效。创建分布式缓存连接时的最小退避时间 (毫秒) 。

​

distributed_cache_connect_max_tries

仅在 ClickHouse Cloud 中生效。连接分布式缓存失败时，允许重试的次数。

​

distributed_cache_connect_timeout_ms

仅在 ClickHouse Cloud 中生效。连接分布式缓存服务器时的连接超时时间。

​

distributed_cache_credentials_refresh_period_seconds

仅在 ClickHouse Cloud 中生效。凭证刷新周期。

​

distributed_cache_data_packet_ack_window

仅在 ClickHouse Cloud 中生效。用于在单个分布式缓存读取请求中为 DataPacket 序列发送 ACK 的窗口大小

​

distributed_cache_discard_connection_if_unread_data

仅在 ClickHouse Cloud 中生效。如果存在未读取的数据，则丢弃连接。

​

distributed_cache_fetch_metrics_only_from_current_az

仅在 ClickHouse Cloud 中生效。在 system.distributed_cache_metrics 和 system.distributed_cache_events 中，仅拉取当前可用区的指标。

​

distributed_cache_file_cache_name

仅在 ClickHouse Cloud 中生效。此设置仅用于 CI 测试——指定在分布式缓存中使用的文件系统缓存名称。

​

distributed_cache_log_mode

仅在 ClickHouse Cloud 中生效。用于写入 system.distributed_cache_log 的模式

​

distributed_cache_max_unacked_inflight_packets

仅在 ClickHouse Cloud 中生效。单个分布式缓存读取请求中未确认的在途数据包最大数量

​

distributed_cache_min_bytes_for_seek

仅在 ClickHouse Cloud 中生效。在分布式缓存中执行寻道操作的最小字节数。

​

distributed_cache_pool_behaviour_on_limit

仅在 ClickHouse Cloud 中生效。指定分布式缓存连接在达到连接池限制时的行为

​

distributed_cache_prefer_bigger_buffer_size

仅在 ClickHouse Cloud 中有效。与 filesystem_cache_prefer_bigger_buffer_size 相同，但适用于分布式缓存。

​

distributed_cache_read_only_from_current_az

仅在 ClickHouse Cloud 中生效。只允许从当前可用区读取；如果禁用，则会从所有可用区的所有缓存服务器读取。

​

distributed_cache_read_request_max_tries

仅在 ClickHouse Cloud 中生效。分布式缓存读取请求失败后的重试次数

​

distributed_cache_receive_response_wait_milliseconds

仅在 ClickHouse Cloud 中生效。表示从分布式缓存接收请求数据的等待时间，单位为毫秒

​

distributed_cache_receive_timeout_milliseconds

仅在 ClickHouse Cloud 中生效。等待从分布式缓存接收任何类型响应的时间，单位为毫秒

Cloud 默认值：20000。

​

distributed_cache_receive_timeout_ms

仅在 ClickHouse Cloud 中生效。表示从分布式缓存服务器接收数据的超时时间，单位为毫秒。如果在此时间间隔内未收到任何字节，则会抛出异常。

​

distributed_cache_send_timeout_ms

仅在 ClickHouse Cloud 中生效。向分布式缓存服务器发送数据的超时时间，单位为毫秒。如果客户端需要发送数据，但在该时间间隔内一个字节都无法发送出去，则会抛出异常。

​

distributed_cache_tcp_keep_alive_timeout_ms

仅在 ClickHouse Cloud 中生效。该值表示连接到分布式缓存服务器后，在 TCP 开始发送 keepalive 探测之前，连接可保持空闲的时间 (以毫秒为单位) 。

​

distributed_cache_throw_on_error

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

​

distributed_cache_use_clients_cache_for_read

仅在 ClickHouse Cloud 中生效。读取请求使用客户端缓存。

​

distributed_cache_use_clients_cache_for_write

仅在 ClickHouse Cloud 中生效。对写入请求使用客户端缓存。

​

distributed_cache_wait_connection_from_pool_milliseconds

仅在 ClickHouse Cloud 中生效。如果 distributed_cache_pool_behaviour_on_limit 设置为 wait，则此项表示从连接池获取连接的等待时间 (毫秒) 。

​

distributed_cache_write_request_max_tries

仅在 ClickHouse Cloud 中生效。分布式缓存写请求失败时的重试次数

​

distributed_connections_pool_size

针对单个 Distributed 表的所有查询，在进行分布式处理时与远程服务器建立的最大同时连接数。建议将该值设置为不小于集群中的服务器数量。

​

distributed_ddl_entry_format_version

分布式 DDL (ON CLUSTER) 查询的兼容性版本

Cloud 默认值：6。

​

distributed_ddl_output_mode

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

可能的值：

• throw — 返回结果集，其中包含查询已完成的所有主机上的查询执行状态。如果查询在某些主机上失败，则会重新抛出第一个异常。如果查询在某些主机上尚未完成，且已超过 distributed_ddl_task_timeout，则会抛出 TIMEOUT_EXCEEDED 异常。
• none — 与 throw 类似，但分布式 DDL 查询不返回结果集。
• null_status_on_timeout — 如果查询在对应主机上尚未完成，则在结果集的某些行中返回 NULL 作为执行状态，而不是抛出 TIMEOUT_EXCEEDED。
• never_throw — 如果查询在某些主机上失败，则不会抛出 TIMEOUT_EXCEEDED，也不会重新抛出异常。
• none_only_active - 与 none 类似，但不会等待 Replicated 数据库的非活动副本。注意：在此模式下，无法判断查询是否未在某个副本上执行，以及它是否会在后台执行。
• null_status_on_timeout_only_active — 与 null_status_on_timeout 类似，但不会等待 Replicated 数据库的非活动副本
• throw_only_active — 与 throw 类似，但不会等待 Replicated 数据库的非活动副本

Cloud 默认值：none_only_active。

​

distributed_ddl_task_timeout

设置集群中所有主机返回 DDL 查询响应的超时时间。如果某个 DDL 请求尚未在所有主机上执行完成，响应将包含超时错误，并且该请求将以异步模式执行。负值表示无限等待。

可能的值：

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

​

distributed_foreground_insert

别名: insert_distributed_sync

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

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

可能的值：

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

Cloud 默认值：1。

另请参见

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

​

distributed_group_by_no_merge

在分布式查询处理中，不合并来自不同服务器的聚合状态；当能够确定不同分片上的键各不相同时，可使用此设置

可能的值：

• 0 — 禁用 (最终查询处理在 initiator 节点上完成) 。
• 1 - 在分布式查询处理中，不合并来自不同服务器的聚合状态 (查询完全在分片上处理，initiator 仅负责代理数据) ；当能够确定不同分片上的键各不相同时，可使用此设置。
• 2 - 与 1`` 相同，但会在 initiator 上应用 ORDER BY和LIMIT（对于像 distributed_group_by_no_merge=1这样在远程节点上完全处理的查询，这是无法实现的）；可用于带有ORDER BY和/或LIMIT` 的查询。

示例

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_index_analysis

索引分析将在各副本间分布式执行。 这对于共享存储以及 cluster 中海量数据的场景很有帮助。 使用 cluster_for_parallel_replicas 中的副本。

另请参见

• distributed_index_analysis_for_non_shared_merge_tree
• distributed_index_analysis_min_parts_to_activate
• distributed_index_analysis_min_indexes_bytes_to_activate

​

distributed_index_analysis_for_non_shared_merge_tree

即使对非 SharedMergeTree (仅 Cloud 提供的引擎) 也启用分布式索引分析。

​

distributed_index_analysis_only_on_coordinator

如果启用，分布式索引分析将仅在协调器上执行。 当谓词包含子查询 (例如 IN (SELECT ...)) 时，这可以避免生成 O(N^2) 的查询， 因为否则每个 follower 副本都会各自触发自己的分布式索引分析； 但如果子查询中使用了大表，也会降低分布式索引分析的效率。

​

distributed_insert_skip_read_only_replicas

启用后，对 Distributed 执行 INSERT 查询时会跳过只读副本。

可选值：

• 0 — INSERT 与往常一样；如果发送到只读副本，则会失败
• 1 — 发起节点会在将数据发送到分片之前跳过只读副本。

​

distributed_plan_default_reader_bucket_count

分布式查询中并行读取的默认任务数。任务会分散到各个副本之间。

​

distributed_plan_default_shuffle_join_bucket_count

分布式 shuffle-hash-join 的默认桶数。

​

distributed_plan_execute_locally

在本地执行分布式查询计划的所有任务。适用于测试和调试。

​

distributed_plan_force_exchange_kind

强制指定分布式查询各阶段之间使用的 Exchange 算子类型。

可能的值：

• ” - 不强制使用任何类型的 Exchange 算子，由优化器自行选择，
• ‘Persisted’ - 在对象存储中使用临时 File，
• ‘Streaming’ - 通过网络流式传输 Exchange 数据。

​

distributed_plan_force_shuffle_aggregation

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

​

distributed_plan_max_rows_to_broadcast

在分布式查询计划中，使用广播 join 而非 shuffle join 的最大行数。

​

distributed_plan_optimize_exchanges

移除分布式查询计划中不必要的 exchange。如需调试，请将其禁用。

​

distributed_plan_prefer_replicas_over_workers

将分布式查询计划序列化，以便在副本上执行。

​

distributed_product_mode

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

当查询包含分布式表的乘积时，也就是针对某个分布式表的查询中包含该分布式表的非 GLOBAL 子查询时，ClickHouse 会应用此设置。

限制：

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

可能的值：

• deny — 默认值。禁止使用这类子查询 (返回 “Double-distributed in/JOIN subqueries is denied” 异常) 。
• local — 将子查询中的数据库和表替换为目标服务器 (分片) 的本地数据库和表，同时保留普通的 IN/JOIN。
• global — 将 IN/JOIN 查询替换为 GLOBAL IN/GLOBAL JOIN。
• allow — 允许使用这类子查询。

​

distributed_push_down_limit

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

这有助于避免：

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

从 21.9 版本开始，将不再出现不准确的结果，因为 distributed_push_down_limit 只有在至少满足以下一个条件时才会更改查询执行方式：

• distributed_group_by_no_merge > 0。
• 查询不包含 GROUP BY/DISTINCT/LIMIT BY，但包含 ORDER BY/LIMIT。
• 查询包含带有 ORDER BY/LIMIT 的 GROUP BY/DISTINCT/LIMIT BY，并且：
  • optimize_skip_unused_shards 已启用。
  • optimize_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

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

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

​

dynamic_disk_allow_from_env

允许在动态磁盘配置中使用 from_env 替换 (即在 disk() 函数的参数中使用) 。 默认禁用，以防止用户在定义表存储时读取任意环境变量。

​

dynamic_disk_allow_from_zk

允许在动态磁盘配置中使用 from_zk 替换 (即在 disk() 函数参数中使用) 。 默认禁用。

​

dynamic_disk_allow_include

允许在动态磁盘配置中使用 include (即在 disk() 函数参数中) 。 默认禁用。

​

dynamic_throw_on_type_mismatch

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

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

​

empty_result_for_aggregation_by_constant_keys_on_empty_set

在空集上按常量键聚合时，返回空结果。

​

empty_result_for_aggregation_by_empty_set

对空集进行无键聚合时，返回空结果。

​

enable_adaptive_memory_spill_scheduler

触发处理器将数据自适应落盘到外部存储。目前仅支持 grace join。

​

enable_add_distinct_to_in_subqueries

在 IN 子查询中启用 DISTINCT。这是一个需要权衡的设置：启用后，通过确保只发送唯一值，可以大幅减小为分布式 IN 子查询传输的临时表大小，并显著加快分片之间的数据传输。 不过，启用此设置会给每个节点带来额外的合并开销，因为必须执行去重 (DISTINCT) 。当网络传输成为瓶颈，且可以接受额外的合并成本时，可使用此设置。

​

enable_automatic_decision_for_merging_across_partitions_for_final

如果启用此项，当分区键表达式具有确定性，且分区键表达式中使用的所有列都包含在主键中时，ClickHouse 会自动启用此优化。 这种自动推导可确保具有相同主键值的行始终属于同一分区，因此可以安全地避免跨分区合并。

​

enable_blob_storage_log

将 blob 存储操作信息写入 system.blob_storage_log 表

​

enable_blob_storage_log_for_read_operations

将 blob 存储读取操作的信息写入 system.blob_storage_log 表。 还需要同时启用 enable_blob_storage_log。

​

enable_early_constant_folding

启用查询优化：分析函数和子查询的结果；如果其中包含常量，则重写查询

​

enable_extended_results_for_datetime_functions

启用或禁用返回扩展范围的 Date32 类型结果 (相较于 Date 类型) ， 或返回扩展范围的 DateTime64 类型结果 (相较于 DateTime 类型) 。

Possible values:

• 0 — 对于所有类型的参数，函数均返回 Date 或 DateTime。
• 1 — 对于 Date32 或 DateTime64 参数，函数返回 Date32 或 DateTime64；否则返回 Date 或 DateTime。

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

函数	enable_extended_results_for_datetime_functions = 0	enable_extended_results_for_datetime_functions = 1
toStartOfYear	返回 Date 或 DateTime	对于 Date/DateTime 类型的输入，返回 Date/DateTime 对于 Date32/DateTime64 类型的输入，返回 Date32/DateTime64
toStartOfISOYear	返回 Date 或 DateTime	对于 Date/DateTime 类型的输入，返回 Date/DateTime 对于 Date32/DateTime64 类型的输入，返回 Date32/DateTime64
toStartOfQuarter	返回 Date 或 DateTime	对于 Date/DateTime 类型的输入，返回 Date/DateTime 对于 Date32/DateTime64 类型的输入，返回 Date32/DateTime64
toStartOfMonth	返回 Date 或 DateTime	Date/DateTime 输入时，返回 Date/DateTime Date32/DateTime64 输入时，返回 Date32/DateTime64
toStartOfWeek	返回 Date 或 DateTime	对于 Date/DateTime 类型的输入，返回 Date/DateTime 对于 Date32/DateTime64 类型的输入，返回 Date32/DateTime64
toLastDayOfWeek	返回 Date 或 DateTime	对于 Date/DateTime 类型的输入，返回 Date/DateTime 对于 Date32/DateTime64 类型的输入，返回 Date32/DateTime64
toLastDayOfMonth	返回 Date 或 DateTime	对于 Date/DateTime 类型的输入，返回 Date/DateTime 对于 Date32/DateTime64 类型的输入，返回 Date32/DateTime64
toMonday	返回 Date 或 DateTime	对于 Date/DateTime 类型的输入，返回 Date/DateTime 对于 Date32/DateTime64 类型的输入，返回 Date32/DateTime64
toStartOfDay	返回 DateTime 注意：对于超出 1970-2149 范围的值，会返回错误结果	对于 Date/DateTime 类型的输入，返回 DateTime 对于 Date32/DateTime64 类型的输入，返回 DateTime64
toStartOfHour	返回 DateTime 注意：对于超出 1970–2149 范围的值，结果会不正确	对于 Date/DateTime 类型的输入，返回 DateTime 对于 Date32/DateTime64 类型的输入，返回 DateTime64
toStartOfFifteenMinutes	返回 DateTime 注意：对于超出 1970-2149 范围的值，结果会不正确。	对于 Date/DateTime 类型的输入，返回 DateTime 对于 Date32/DateTime64 类型的输入，返回 DateTime64
toStartOfTenMinutes	返回 DateTime 注意：对于超出 1970-2149 范围的值，结果可能不正确	对于 Date/DateTime 类型的输入，返回 DateTime 对于 Date32/DateTime64 类型的输入，返回 DateTime64
toStartOfFiveMinutes	返回 DateTime 注意：对于超出 1970-2149 范围的值，结果会不正确	对于 Date/DateTime 类型的输入，返回 DateTime 对于 Date32/DateTime64 类型的输入，返回 DateTime64
toStartOfMinute	返回 DateTime 注意：对于超出 1970-2149 范围的值，结果会不正确	对于 Date/DateTime 类型的输入，返回 DateTime 对于 Date32/DateTime64 类型的输入，返回 DateTime64
timeSlot	返回 DateTime 注意：对于超出 1970-2149 范围的值，结果会不正确。	对于 Date/DateTime 类型的输入，返回 DateTime 对于 Date32/DateTime64 类型的输入，返回 DateTime64

​

enable_filesystem_cache

对远程文件系统使用缓存。此设置不会为磁盘启用/禁用缓存 (必须通过 disk 配置完成) ，但如果需要，它允许某些查询绕过缓存

​

enable_filesystem_cache_log

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

​

enable_filesystem_cache_on_write_operations

启用或禁用 write-through 缓存。若设置为 false，则对写入操作禁用 write-through 缓存。若设置为 true，则只要在 server config 的 cache disk configuration 部分启用了 cache_on_write_operations，就会启用 write-through 缓存。 更多详情请参见“使用本地缓存”。

Cloud 默认值：1。

​

enable_filesystem_read_prefetches_log

在查询期间向 system.filesystem prefetch_log 记录日志。仅应用于测试或调试，不建议默认启用

​

enable_full_text_index

别名: allow_experimental_full_text_index

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

​

enable_global_with_statement

将 WITH 语句应用于 UNION 查询及所有子查询

​

enable_hdfs_pread

启用或禁用 HDFS 文件的 pread。默认使用 hdfsPread。如果禁用，则会使用 hdfsRead 和 hdfsSeek 来读取 HDFS 文件。

​

enable_http_compression

启用或禁用 HTTP 请求响应中的数据压缩。

更多信息，请参阅 HTTP 接口说明。

可能的值：

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

​

enable_job_stack_trace

当 job 导致异常时，输出 job 创建者的堆栈跟踪。默认禁用，以避免性能开销。

​

enable_join_fixed_hash_table_conversion

当键为值域较小的单个整数时，启用将用于 join 的哈希表转换为扁平数组。

​

enable_join_runtime_filters

在运行时，根据从右侧收集的 JOIN 连接键集合对左侧进行过滤。

​

enable_join_transitive_predicates

根据现有 JOIN 条件推断传递性的等值 JOIN 谓词。 例如，给定 A.x = B.x 和 B.x = C.x，会额外添加一个 A.x = C.x 谓词， 以便 JOIN 顺序优化器能够考虑直接的 (A JOIN C) 执行计划。

​

enable_lazy_columns_replication

启用 JOIN 和 ARRAY JOIN 中的惰性列复制，可避免在内存中多次重复复制相同的行。

​

enable_lightweight_delete

别名: allow_experimental_lightweight_delete

启用 MergeTree 表的轻量级 DELETE 变更功能。

​

enable_lightweight_update

别名: allow_experimental_lightweight_update

允许使用轻量级更新。

​

enable_materialized_cte

启用物化公共表表达式；其优先级高于 enable_global_with_statement

​

enable_memory_bound_merging_of_aggregation_results

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

​

enable_multiple_prewhere_read_steps

如果存在多个以 AND 连接的条件，则将更多条件从 WHERE 移至 PREWHERE，并分多步执行磁盘读取和过滤

​

enable_named_columns_in_function_tuple

当所有名称都唯一且可视为不带引号的标识符时，在 tuple() 函数中生成命名元组。

​

enable_optimize_predicate_expression

在 SELECT 查询中启用谓词下推。

对于分布式查询，谓词下推可显著减少网络流量。

可能的值：

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

用法

请参考以下查询：

1. SELECT count() FROM test_table WHERE date = '2018-10-10'
2. SELECT count() FROM (SELECT * FROM test_table) WHERE date = '2018-10-10'

如果 enable_optimize_predicate_expression = 1，这两个查询的执行时间相同，因为 ClickHouse 在处理子查询时会将 WHERE 条件下推到子查询中。

如果 enable_optimize_predicate_expression = 0，那么第二个查询的执行时间会长得多，因为只有在子查询完成后，WHERE 子句才会应用到所有数据上。

​

enable_optimize_predicate_expression_to_final_subquery

允许将谓词下推到 FINAL 子查询。

​

enable_order_by_all

启用或禁用 ORDER BY ALL 排序语法，参见 ORDER BY。

可能的值：

• 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; -- 返回错误，提示 ALL 存在歧义

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

如果为 true，则可根据从表中获取的序列化提示，将数据直接解析到采用自定义序列化 (例如 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_positional_arguments_for_projections

启用或禁用在 PROJECTION 定义中使用位置参数。另请参阅 enable_positional_arguments 设置。

这是一个专家级设置；如果你刚开始使用 ClickHouse，则不应更改它。

可能的值：

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

​

enable_producing_buckets_out_of_order_in_aggregation

允许内存高效的聚合 (参见 distributed_aggregation_memory_efficient) 乱序生成桶。 当聚合中的桶大小分布不均时，此设置可允许副本在仍处理一些较重的低 ID 桶时，向发起节点发送更高 ID 的桶，从而提升性能。 缺点是可能会增加内存使用量。

​

enable_reads_from_query_cache

启用后，将从查询缓存中读取 SELECT 查询结果。

可能的值：

• 0 - 禁用
• 1 - 启用

​

enable_s3_requests_logging

启用非常详细的 S3 请求日志记录。仅建议在调试时使用。

​

enable_scalar_subquery_optimization

如果将其设置为 true，则可防止标量子查询对大型标量值进行 (反) 序列化，并且还可能避免重复执行同一子查询。

​

enable_scopes_for_with_statement

如果禁用此设置，父级 WITH 子句中的声明将与在当前作用域中声明时具有相同的作用域行为。

请注意，这是 analyzer 的兼容性设置，用于允许运行一些旧 analyzer 可以执行的无效查询。

​

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
)

如果没有启用此设置，外层查询和内层查询可能会基于不同的数据快照执行，从而导致结果不正确。

启用此设置后，会禁用这样一项优化：在规划阶段完成后，从快照中移除不必要的数据分区片段。 因此，长时间运行的查询可能会在整个耗时期间一直保留已过时的数据分区片段，从而延迟分区片段清理并增加存储压力。

此设置当前仅适用于 MergeTree 家族的表。

可选值：

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

​

enable_sharing_sets_for_mutations

允许在同一变更的不同任务之间共享为 IN 子查询构建的 Set 对象。这将减少内存占用和 CPU 消耗

​

enable_software_prefetch_in_aggregation

启用在聚合过程中使用软件预取

​

enable_software_prefetch_in_join

启用在哈希连接探测阶段使用软件预取，以掩盖大型哈希表的内存访问延迟。

​

enable_time_time64_type

别名: allow_experimental_time_time64_type

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

​

enable_unaligned_array_join

允许对多个长度不同的数组执行 ARRAY JOIN。启用此设置后，数组会调整为与最长数组相同的长度。

​

enable_url_encoding

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

默认禁用。

​

enable_vertical_final

如果启用，则会在 FINAL 期间通过将行标记为已删除并在后续过滤掉这些行来移除重复行，而不是合并这些行

​

enable_writes_to_query_cache

启用后，SELECT 查询的结果会存储在查询缓存中。

可能的值：

• 0 - 禁用
• 1 - 启用

​

enforce_strict_identifier_format

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

​

engine_file_allow_create_multiple_files

对于 File 表引擎的表，如果格式带有后缀 (JSON、ORC、Parquet 等) ，此设置用于启用或禁用每次插入时创建新文件的行为。如果启用，则每次插入都会按以下模式创建一个新文件：

data.Parquet -> data.1.Parquet -> data.2.Parquet，等等。

可能的值：

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

​

engine_file_empty_if_not_exists

允许在文件不存在时从 File 表引擎表中查询数据。

可能的值：

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

​

engine_file_skip_empty_files

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

可能的值：

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

​

engine_file_truncate_on_insert

启用或禁用在 File 表引擎 表中执行插入前截断。

可能的值：

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

​

engine_url_skip_empty_files

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

可能的值：

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

​

exact_rows_before_limit

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

​

except_default_mode

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

​

exclude_materialize_skip_indexes_on_insert

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

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

示例：

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

SET exclude_materialize_skip_indexes_on_insert='idx_a'; -- idx_a 在插入时不会被更新
--SET exclude_materialize_skip_indexes_on_insert='idx_a, idx_b'; -- 两个索引在插入时均不会被更新

INSERT INTO tab SELECT number, number / 50 FROM numbers(100); -- 仅 idx_b 会被更新

-- 由于这是会话级设置，可以在单次查询时单独指定
INSERT INTO tab SELECT number, number / 50 FROM numbers(100, 100) SETTINGS exclude_materialize_skip_indexes_on_insert='idx_b';

ALTER TABLE tab MATERIALIZE INDEX idx_a; -- 可通过此查询显式物化该索引

SET exclude_materialize_skip_indexes_on_insert = DEFAULT; -- 将设置重置为默认值

​

execute_exists_as_scalar_subquery

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

Cloud 默认值：0。

​

external_storage_connect_timeout_sec

连接超时时间 (秒) 。目前仅支持 MySQL

​

external_storage_max_read_bytes

限制使用 external engine 的表在刷新历史数据时可读取的最大字节数。当前仅支持 MySQL table engine、database engine 和字典。如果该值等于 0，则禁用此设置。

​

external_storage_max_read_rows

当使用 external engine 的表需要刷新历史数据时，限制可读取的最大行数。目前仅支持 MySQL table engine、database engine 和字典。如果等于 0，则此设置禁用

​

external_storage_rw_timeout_sec

读写超时时间 (秒) 。目前仅支持 MySQL

​

external_table_functions_use_nulls

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

可能的值：

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

用法

如果将该设置设为 0，表函数不会生成 Nullable 列，而是插入默认值来代替 NULL。这同样适用于数组中的 NULL 值。

​

external_table_strict_query

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

​

extract_key_value_pairs_max_pairs_per_row

别名: extract_kvp_max_pairs_per_row

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

​

极值

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

​

fallback_to_stale_replicas_for_distributed_queries

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

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

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

默认值为 1 (已启用) 。

​

filesystem_cache_allow_background_download

允许文件系统缓存将从远程存储读取的数据加入后台下载队列。禁用后，当前查询/会话的下载将继续在前台进行。

​

filesystem_cache_boundary_alignment

文件系统缓存的边界对齐。此设置仅适用于非磁盘读取 (例如远程表引擎 / 表函数的缓存，而不适用于 MergeTree 表的存储配置) 。值为 0 表示不对齐。

​

filesystem_cache_enable_background_download_during_fetch

仅在 ClickHouse Cloud 中生效。为在文件系统缓存中预留空间而锁定缓存时的等待时间

​

filesystem_cache_enable_background_download_for_metadata_files_in_packed_storage

仅在 ClickHouse Cloud 中生效。在文件系统缓存中为预留空间而获取缓存锁的等待时间

​

filesystem_cache_max_download_size

单个查询可下载的远程文件系统缓存最大大小

​

filesystem_cache_name

用于无状态表引擎或数据湖的文件系统缓存名称

​

filesystem_cache_prefer_bigger_buffer_size

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

​

filesystem_cache_reserve_space_wait_lock_timeout_milliseconds

在文件系统缓存中为预留空间而等待获取缓存锁的时间

​

filesystem_cache_segments_batch_size

读取缓冲区单次可从缓存请求的 File 段批次大小上限。值过低会导致向缓存发起过多请求，值过高则可能减慢缓存的淘汰速度

​

filesystem_cache_skip_download_if_exceeds_per_query_cache_write_limit

别名: skip_download_if_exceeds_query_cache

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

​

filesystem_prefetch_max_memory_usage

预取操作的最大内存用量。

Cloud 默认值：总内存的 10%。

​

filesystem_prefetch_step_bytes

预取步长，单位为字节。零表示 auto——系统会自动推导出大致最佳的预取步长，但可能并非 100% 最优。由于受设置 filesystem_prefetch_min_bytes_for_single_read_task 的影响，实际值可能会有所不同

​

filesystem_prefetch_step_marks

以标记为单位的预取步长。零表示 auto —— 系统会自动推导出一个近似最优的预取步长，但不一定是 100% 最优。由于受设置 filesystem_prefetch_min_bytes_for_single_read_task 的影响，实际值可能有所不同

​

filesystem_prefetches_limit

预取操作的最大数量。0 表示不受限制。如果你想限制预取数量，建议优先使用设置 filesystem_prefetches_max_memory_usage

​

final

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

可能的值：

• 0 - 禁用
• 1 - 启用

示例：

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

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

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

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

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

​

finalize_projection_parts_synchronously

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

​

flatten_nested

设置 nested 列的数据格式。

可能的值：

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

用法

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

示例

查询：

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

SHOW CREATE TABLE t_nest;

结果：

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

查询：

SET flatten_nested = 0;

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

SHOW CREATE TABLE t_nest;

结果：

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

​

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=''; -- 查询将产生 CANNOT_PARSE_TEXT 错误。
SELECT * FROM data_01515 SETTINGS force_data_skipping_indices='d1_idx'; -- 查询将产生 INDEX_NOT_USED 错误。
SELECT * FROM data_01515 WHERE d1 = 0 SETTINGS force_data_skipping_indices='d1_idx'; -- 正常。
SELECT * FROM data_01515 WHERE d1 = 0 SETTINGS force_data_skipping_indices='`d1_idx`'; -- 正常（完整解析器示例）。
SELECT * FROM data_01515 WHERE d1 = 0 SETTINGS force_data_skipping_indices='`d1_idx`, d1_null_idx'; -- 查询将产生 INDEX_NOT_USED 错误，因为 d1_null_idx 未被使用。
SELECT * FROM data_01515 WHERE d1 = 0 AND assumeNotNull(d1_null) = 0 SETTINGS force_data_skipping_indices='`d1_idx`, d1_null_idx'; -- 正常。

​

force_grouping_standard_compatibility

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

​

force_index_by_date

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

适用于 MergeTree 家族中的表。

如果 force_index_by_date=1，ClickHouse 会检查查询是否包含可用于限制数据范围的日期键条件。如果没有合适的条件，则会抛出异常。不过，它不会检查该条件是否能减少需要读取的数据量。例如，即使条件 Date != ' 2000-01-01 ' 与表中的所有数据都匹配 (即运行该查询需要全表扫描) ，该条件也是可接受的。有关 MergeTree 表中数据范围的更多信息，请参见 MergeTree。

​

force_optimize_projection

在启用投影优化时 (请参见 optimize_use_projections 设置) ，控制是否在 SELECT 查询中强制使用投影。

可能的值：

• 0 — 不强制使用投影优化。
• 1 — 强制使用投影优化。

​

force_optimize_projection_name

如果将其设置为非空字符串，则会检查查询中是否至少使用过一次该投影。

可能的值：

• string：查询中使用的投影名称

​

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) 。例如，一个 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 查询时递归删除数据。可避免出现“Directory not empty”错误，但也可能静默删除 detached 数据

​

formatdatetime_e_with_space_padding

函数 formatDateTime 中的格式说明符 ‘%e’ 会在个位数日期前补一个空格，例如输出 ’ 2’，而不是 ‘2’。

​

formatdatetime_f_prints_scale_number_of_digits

函数 formatDateTime 中的格式说明符 %f 对于 DateTime64 只会输出与标度相对应位数的数字，而不是固定输出 6 位数字。

​

formatdatetime_f_prints_single_zero

函数 formatDateTime 中的格式说明符 %f 在格式化值不含秒的小数部分时，会输出单个零，而不是六个零。

​

formatdatetime_format_without_leading_zeros

函数 formatDateTime 中的格式说明符 %c、%l 和 %k 在输出月份和小时时不会补前导零。

​

formatdatetime_parsedatetime_m_is_month_name

函数 formatDateTime 和 parseDateTime 中的格式说明符 %M 会输出/解析月份名称，而不是分钟。

​

fsync_metadata

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

如果 server 中有数百万个持续创建和删除的小型表，禁用它会更合适。

​

function_date_trunc_return_type_behavior

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

Possible values:

• 0 - 当第二个参数为 DateTime64/Date32 时，返回类型将为 DateTime64/Date32，不受第一个参数中时间单位的影响。
• 1 - 对于 Date32，结果始终为 Date。对于 DateTime64，当时间单位为 second 及以上时，结果为 DateTime。

​

function_implementation

为特定目标或 Variant 选择函数实现 (Experimental) 。如果留空，则启用全部实现。

​

function_json_value_return_type_allow_complex

控制是否允许 json_value 函数返回复杂类型 (例如 struct、array、map) 。

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 - 正确统计零宽字符和组合字符，将全宽字符按两个字符计数，估算制表符宽度，并统计删除字符。

​

functions_h3_default_if_invalid

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

​

geo_distance_returns_float64_on_float64_arguments

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

​

geotoh3_argument_order

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

​

glob_expansion_max_elements

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

​

grace_hash_join_initial_buckets

grace hash join 的初始桶数量

​

grace_hash_join_max_buckets

grace hash join 的桶数量上限

​

group_by_overflow_mode

设置当用于聚合的唯一键数量超过限制时的行为：

• throw：抛出异常
• break：停止执行查询并返回部分结果
• any：继续对已进入集合的键进行聚合，但不再向集合中添加新键。

使用 any 值可以运行 GROUP BY 的近似计算。该近似结果的质量 取决于数据的统计特性。

​

group_by_two_level_threshold

键的数量从多少开始时启用两级聚合。0 表示未设置该阈值。

​

group_by_two_level_threshold_bytes

当聚合状态的大小达到多少字节时，开始使用两级聚合。0 表示未设置阈值。当任一阈值被触发时，即会使用两级聚合。

​

group_by_use_nulls

更改 GROUP BY 子句 处理聚合键类型的方式。 使用 ROLLUP、CUBE 或 GROUPING SETS 指定器时，某些聚合键可能不会参与生成某些结果行。 这些键对应的列会根据此设置，在相应行中填充默认值或 NULL。

可能的值：

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

另请参见：

• GROUP BY 子句

​

h3togeo_lon_lat_result_order

当值为 true 时，函数 h3ToGeo 返回 (lon, lat)；否则返回 (lat, lon)。

​

handshake_timeout_ms

握手期间，从副本接收 Hello 数据包的超时时间，单位为毫秒。

​

hdfs_create_new_file_on_insert

用于启用或禁用在 HDFS engine 表中每次 insert 时创建新文件。如果启用，则每次 insert 都会创建一个新的 HDFS 文件，文件名类似以下模式：

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

Possible values:

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

​

hdfs_ignore_file_doesnt_exist

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

可能的值：

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

​

hdfs_replication

实际的副本数可在创建 HDFS 文件时指定。

​

hdfs_skip_empty_files

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

可能的值：

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

​

hdfs_throw_on_zero_files_match

如果按 glob 展开规则未匹配到任何文件，则抛出错误。

可能的值：

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

​

hdfs_truncate_on_insert

控制是否在 HDFS engine 表中执行 insert 前先截断文件。若禁用，当 HDFS 中的文件已存在时，尝试插入将抛出异常。

可能的值：

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

​

hedged_connection_timeout_ms

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

​

highlight_max_matches_per_row

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

可能的值：

• 正整数。

​

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_headers_read_timeout

读取全部 HTTP 请求头的最长时间 (以秒为单位) 。这是整个请求头解析阶段的总时限，而不是单次读取的超时时间。它可防范 slowloris 类攻击：客户端以极慢的速度持续发送请求头数据，从而让连接长时间保持打开状态。

​

http_make_head_request

http_make_head_request 设置允许在通过 HTTP 读取数据时发送 HEAD 请求，以获取待读取文件的信息，例如文件大小。该设置默认启用，因此如果 server 不支持 HEAD 请求，可能需要将其禁用。

​

http_max_field_name_size

HTTP 请求头中字段名称的最大长度

​

http_max_field_value_size

HTTP 请求头中字段值的最大长度

​

http_max_fields

HTTP 请求头中的最大字段数

​

http_max_multipart_form_data_size

multipart/form-data 内容大小限制。此设置无法通过 URL 参数解析，应在用户 profile 中设置。请注意，在查询开始执行前，内容会先被解析，并在内存中创建外部表。此外，这是该阶段唯一生效的限制 (读取 HTTP form data 时，最大内存使用和最大执行时间限制均不生效) 。

​

http_max_request_header_size

所有 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 时) 刷新到磁盘之前，在 server 内存中缓冲的字节数。

​

http_response_headers

允许添加或覆盖服务器在查询成功时随响应返回的 HTTP 请求头。 这仅影响 HTTP 接口。

如果该请求头默认已设置，则提供的值会覆盖它。 如果该请求头默认未设置，则会将其添加到请求头列表中。 服务器默认设置且未被此设置覆盖的请求头将保持不变。

此设置允许你将请求头设为常量值。目前还无法将请求头设为动态计算的值。

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

如果你实现了一个允许用户修改设置、但同时又会基于返回的请求头做出决策的 UI 应用程序，建议将此设置限制为 readonly。

示例：SET http_response_headers = '{"Content-Type": "image/png"}'

​

http_retry_initial_backoff_ms

通过 HTTP 重试读取时的最小退避时间 (毫秒)

​

http_retry_max_backoff_ms

通过 HTTP 重试读取时的最大退避时间 (毫秒)

​

http_send_timeout

HTTP 发送超时时间 (以秒为单位) 。

可能的取值：

• 任意正整数。
• 0 - 已禁用 (超时无限制) 。

仅适用于默认 profile。更改生效需要重启服务器。

​

http_skip_not_found_url_for_globs

跳过因 HTTP_NOT_FOUND 错误而未找到的通配符 URL

​

http_wait_end_of_query

启用服务端 HTTP 响应缓冲。

​

http_write_exception_in_output_format

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

​

http_zlib_compression_level

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

可能的值：1 到 9 的数字。

​

iceberg_compaction_data_cleanup

超过此时间后，数据将被删除。

​

iceberg_compaction_delay_bias

两次后台合并整理操作之间的最短延迟时间。

​

iceberg_data_file_size_lower_threshold_compaction

Iceberg 中数据文件合并整理的阈值。

​

iceberg_data_file_size_upper_threshold_compaction

Iceberg 中数据文件合并整理的阈值。

​

iceberg_delete_data_on_drop

是否在执行 drop 时删除所有 Iceberg 文件。

​

iceberg_expire_default_max_ref_age_ms

当 Iceberg 表属性 history.expire.max-ref-age-ms 不存在时，expire_snapshots 使用的默认值。

​

iceberg_expire_default_max_snapshot_age_ms

当未设置该属性时，expire_snapshots 使用的 Iceberg 表属性 history.expire.max-snapshot-age-ms 的默认值。

​

iceberg_expire_default_min_snapshots_to_keep

当该属性不存在时，expire_snapshots 使用的 Iceberg 表属性 history.expire.min-snapshots-to-keep 的默认值。

​

iceberg_insert_max_bytes_in_data_file

插入操作时 Iceberg Parquet 数据文件的最大字节数。

​

iceberg_insert_max_partitions

Iceberg 表引擎中单次插入操作允许的最大分区数。

​

iceberg_insert_max_rows_in_data_file

插入操作时 Iceberg Parquet 数据文件的最大行数上限。

​

iceberg_max_number_datafiles_to_compact

Iceberg 中触发数据文件合并整理的阈值。

​

iceberg_metadata_compression_method

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

​

iceberg_metadata_log_level

控制写入 system.iceberg_metadata_log 的 Iceberg 表元数据日志级别。 通常仅在调试时修改此设置。

可选值：

• none - 不记录元数据日志。
• metadata - 根 metadata.json 文件。
• manifest_list_metadata - 包含以上全部内容，外加与某个快照对应的 avro manifest 列表中的元数据。
• manifest_list_entry - 包含以上全部内容，外加 avro manifest 列表条目。
• manifest_file_metadata - 包含以上全部内容，外加已遍历的 avro manifest 文件中的元数据。
• manifest_file_entry - 包含以上全部内容，外加已遍历的 avro manifest 文件条目。

​

iceberg_metadata_staleness_ms

如果该值非零，且存在比给定 staleness 窗口更新的缓存元数据快照，则跳过从远程 catalog 拉取 Iceberg 元数据。值为零表示始终从远程 catalog 拉取最新的元数据版本。将此项设为非零，会以一定的陈旧性为代价来降低读操作延迟。

​

iceberg_orphan_files_older_than_seconds

Iceberg 表中删除孤立文件时使用的默认年龄阈值 (以秒为单位) 。比该阈值更新的文件不会被视为孤立文件。当调用 remove_orphan_files() 过程时，如果省略 older_than 参数，则使用该值。默认值为 259200 (3 天) 。

​

iceberg_snapshot_id

使用指定的快照 ID 查询 Iceberg 表。

​

iceberg_timestamp_ms

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

​

idle_connection_timeout

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

可能的值：

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

​

ignore_cold_parts_seconds

仅在 ClickHouse Cloud 中生效。在新的数据分区片段被预热 (参见 cache_populated_by_fetch) 或已存在达到这么多秒之前，将其从 SELECT 查询中排除。仅适用于 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=''; -- 该查询将产生 CANNOT_PARSE_TEXT 错误。
SELECT * FROM data SETTINGS ignore_data_skipping_indices='x_idx'; -- 正常。
SELECT * FROM data SETTINGS ignore_data_skipping_indices='na_idx'; -- 正常。

SELECT * FROM data WHERE x = 1 AND y = 1 SETTINGS ignore_data_skipping_indices='xy_idx',force_data_skipping_indices='xy_idx' ; -- 该查询将产生 INDEX_NOT_USED 错误，因为 xy_idx 已被显式忽略。
SELECT * FROM data WHERE x = 1 AND y = 2 SETTINGS ignore_data_skipping_indices='xy_idx';

未忽略任何索引时的查询：

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

启用后，server 将按指定概率忽略所有 DROP 表查询 (对于 Memory 和 JOIN 引擎，会将 DROP 替换为 TRUNCATE) 。用于测试

​

ignore_format_null_for_explain

如果启用，EXPLAIN 查询中的 FORMAT Null 将被忽略，转而使用默认输出格式。 如果禁用，带有 FORMAT Null 的 EXPLAIN 查询将不会产生任何输出 (这是向后兼容的行为) 。

​

ignore_materialized_views_with_dropped_target_table

在向视图推送时，忽略目标表已删除的 materialized view

​

ignore_on_cluster_for_replicated_access_entities_queries

对于复制访问实体的管理查询，忽略 ON CLUSTER 子句。

​

ignore_on_cluster_for_replicated_database

始终忽略针对 Replicated 数据库的 DDL 查询中的 ON CLUSTER 子句。

​

ignore_on_cluster_for_replicated_named_collections_queries

在复制的命名集合管理查询中忽略 ON CLUSTER 子句。

​

ignore_on_cluster_for_replicated_udf_queries

在复制 UDF 的管理查询中忽略 ON CLUSTER 子句。

​

implicit_select

允许编写不以 SELECT 关键字开头的简单 SELECT 查询，便于计算器式用法；例如，1 + 2 也会成为有效查询。

在 clickhouse-local 中，此设置默认启用，也可显式禁用。

​

implicit_table_at_top_level

如果该设置非空，顶层不带 FROM 的查询将从此表读取，而不是从 system.one 读取。

这用于 clickhouse-local 中的输入数据处理。 用户可以显式设置此设置，但它并非为这种用法而设计。

子查询不受此设置影响 (无论是标量子查询、FROM 子查询还是 IN 子查询) 。 UNION、INTERSECT、EXCEPT 链中顶层的 SELECT 都会被统一处理，并受此设置影响，而不受其括号分组方式影响。 此设置如何影响视图和分布式查询，未作规定。

该设置接受表名 (此时会从当前数据库解析该表) ，也接受形如 ‘database.table’ 的限定名称。 数据库名和表名都不能加引号——只允许使用简单标识符。

​

implicit_transaction

如果启用此设置且当前尚未处于事务中，则会将该查询放入一个完整的事务中 (begin + commit 或 rollback)

​

inject_random_order_for_select_without_order_by

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

​

insert_allow_materialized_columns

启用此设置后，允许在 INSERT 中插入 materialized 列。

​

insert_deduplicate

启用或禁用 INSERT 的块去重功能 (适用于 Replicated* 表) 。

可能的值：

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

默认情况下，通过 INSERT 语句插入到复制表中的块会执行去重 (参见 数据复制) 。 对于复制表，默认情况下每个分区仅对最近的 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。

insert_deduplication_token 在分区级别生效 (与 insert_deduplication checksum 相同) 。多个分区可以使用相同的 insert_deduplication_token。

示例：

CREATE TABLE test_table
( A Int64 )
ENGINE = MergeTree
ORDER BY A
SETTINGS non_replicated_deduplication_window = 100;

INSERT INTO test_table SETTINGS insert_deduplication_token = 'test' VALUES (1);

-- 下一次插入不会被去重，因为 insert_deduplication_token 不同
INSERT INTO test_table SETTINGS insert_deduplication_token = 'test1' VALUES (1);

-- 下一次插入将被去重，因为 insert_deduplication_token
-- 与之前某次插入的值相同
INSERT INTO test_table SETTINGS insert_deduplication_token = 'test' VALUES (2);

SELECT * FROM test_table

┌─A─┐
│ 1 │
└───┘
┌─A─┐
│ 1 │
└───┘

​

insert_keeper_fault_injection_probability

插入期间 Keeper 请求发生故障的大致概率。有效值范围为 [0.0f, 1.0f]

​

insert_keeper_fault_injection_seed

0 - 使用随机种子，否则使用该设置的值

​

insert_keeper_max_retries

此设置用于指定向 Replicated MergeTree 执行 insert 期间，ClickHouse Keeper (或 ZooKeeper) 请求的最大重试次数。只有因网络错误、Keeper 会话超时或请求超时而失败的 Keeper 请求才会被重试。

可能的值：

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

Cloud 默认值：20。

Keeper 请求会在经过一定超时后进行重试。该超时由以下设置控制：insert_keeper_retry_initial_backoff_ms、insert_keeper_retry_max_backoff_ms。 第一次重试会在 insert_keeper_retry_initial_backoff_ms 指定的超时后执行。后续超时将按如下方式计算：

timeout = min(insert_keeper_retry_max_backoff_ms, latest_timeout * 2)

例如，如果 insert_keeper_retry_initial_backoff_ms=100、insert_keeper_retry_max_backoff_ms=10000 且 insert_keeper_max_retries=8，那么超时时间将依次为 100, 200, 400, 800, 1600, 3200, 6400, 10000。

除了提供容错能力外，重试机制也旨在带来更好的用户体验——例如，当 Keeper 因升级而重启时，它可以避免在执行 INSERT 期间返回错误。

​

insert_keeper_retry_initial_backoff_ms

执行 INSERT 查询期间，重试失败的 Keeper 请求的初始超时时间 (毫秒)

可选值：

• 正整数。
• 0 — 无超时

​

insert_keeper_retry_max_backoff_ms

执行 INSERT 查询期间，重试失败的 Keeper 请求时的最大超时时间 (以毫秒为单位)

可能的值：

• 正整数。
• 0 — 最大超时时间不受限制

​

insert_null_as_default

启用或禁用在向非 Nullable 数据类型的列中插入数据时，用默认值替代 NULL。 如果列类型不是 Nullable 且此设置被禁用，则插入 NULL 会导致异常。如果列类型是 Nullable，则无论此设置如何，NULL 值都会按原样插入。

此设置适用于 INSERT … SELECT 查询。请注意，SELECT 子查询可以通过 UNION ALL 子句进行拼接。

可能的值：

• 0 — 向非 Nullable 列插入 NULL 会导致异常。
• 1 — 插入列的默认值而不是 NULL。

​

insert_quorum

此设置不适用于 SharedMergeTree，更多信息请参见 SharedMergeTree 一致性。

启用仲裁写入。

• 如果 insert_quorum < 2，则禁用仲裁写入。
• 如果 insert_quorum >= 2，则启用仲裁写入。
• 如果 insert_quorum = 'auto'，则使用多数值 (number_of_replicas / 2 + 1) 作为仲裁数。

仲裁写入

只有当 ClickHouse 在 insert_quorum_timeout 期间成功将数据写入 insert_quorum 个副本时，INSERT 才会成功。如果由于任何原因，成功写入的副本数未达到 insert_quorum，则此次写入会被视为失败，ClickHouse 会从所有已写入数据的副本中删除已插入的块。

当禁用 insert_quorum_parallel 时，仲裁中的所有副本都是一致的，也就是说，它们都包含此前所有 INSERT 查询的数据 (INSERT 序列会被线性化) 。读取通过 insert_quorum 写入的数据时，如果 insert_quorum_parallel 已禁用，可以使用 select_sequential_consistency 为 SELECT 查询启用顺序一致性。

在以下情况下，ClickHouse 会抛出异常：

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

另请参见：

• insert_quorum_timeout
• insert_quorum_parallel
• select_sequential_consistency

​

insert_quorum_parallel

此设置不适用于 SharedMergeTree，更多信息请参见 SharedMergeTree 一致性。

启用或禁用 quorum INSERT 查询的并行执行。启用后，在先前查询尚未完成时，仍可发送额外的 INSERT 查询。禁用后，对同一表的额外写入将被拒绝。

可能的值：

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

另请参见：

• insert_quorum
• insert_quorum_timeout
• select_sequential_consistency

​

insert_quorum_timeout

写入达到法定副本数的超时时间 (以毫秒为单位) 。如果超时时间已过但仍未完成写入，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

在 trace 日志中收集 jemalloc 的分配和释放样本。

​

jemalloc_enable_profiler

为该查询启用 jemalloc profiler。jemalloc 会对内存分配进行采样，并记录这些已采样分配的所有释放。 可以使用 SYSTEM JEMALLOC FLUSH PROFILE 刷新 profile，以用于分配分析。 还可以通过 config jemalloc_collect_global_profile_samples_in_trace_log，或通过查询设置 jemalloc_collect_profile_samples_in_trace_log，将样本存储到 system.trace_log 中。 请参阅 分配分析

​

jemalloc_profile_text_collapsed_use_count

使用 jemalloc 堆内存剖析的 ‘collapsed’ 输出格式时，按分配次数而非字节数聚合。为 false (默认值) 时，每个栈按存活字节数加权；为 true 时，则按存活分配次数加权。

​

jemalloc_profile_text_output_format

system.jemalloc_profile_text 表中 jemalloc 堆内存剖析的输出格式。可取值为：‘raw’ (原始剖析) 、‘symbolized’ (带符号的 jeprof 格式) 或 ‘collapsed’ (FlameGraph 格式) 。

​

jemalloc_profile_text_symbolize_with_inline

控制在对 jemalloc 堆内存剖析进行符号化时是否包含内联帧。启用后会包含内联帧，这可能会显著拖慢符号化过程；禁用后则会跳过它们。仅影响 symbolized 和 collapsed 输出格式。

​

join_algorithm

指定使用哪种 JOIN 算法。

可以指定多种算法，系统会根据具体查询的 kind/strictness 和表引擎选择可用的一种。

可能的值：

• grace_hash

使用 Grace hash join。Grace hash 提供了一种算法选项，可在限制内存使用的同时高效执行复杂 JOIN。

grace join 的第一阶段会读取右表，并根据键列的哈希值将其拆分为 N 个桶 (初始时，N 为 grace_hash_join_initial_buckets) 。这样可以确保每个桶都能独立处理。第一个桶中的行会加入内存中的哈希表，其余行则保存到磁盘。如果哈希表增长超出内存限制 (例如由 max_bytes_in_join 设置) ，则会增加桶的数量，并重新确定每一行所属的桶。凡是不属于当前桶的行，都会被刷写并重新分配。

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

• hash

使用 Hash join algorithm。这是最通用的实现，支持所有 kind 和 strictness 的组合，以及在 JOIN ON 部分通过 OR 组合的多个连接键。

使用 hash 算法时，JOIN 的右侧部分会加载到 RAM 中。

• parallel_hash

这是 hash join 的一种变体：它会将数据拆分为多个桶，并并发构建多个哈希表而不是一个，以加快这一过程。

使用 parallel_hash 算法时，JOIN 的右侧部分会加载到 RAM 中。

• partial_merge

这是 sort-merge algorithm 的一种变体，其中只有右表会被完全排序。

RIGHT JOIN 和 FULL JOIN 仅支持 ALL strictness (不支持 SEMI、ANTI、ANY 和 ASOF) 。

使用 partial_merge 算法时，ClickHouse 会对数据进行排序并将其转储到磁盘。ClickHouse 中的 partial_merge 算法与经典实现略有不同。首先，ClickHouse 会按连接键对右表按块排序，并为已排序的块创建 min-max 索引。然后，它会按 join key 对左表的各个部分进行排序，并将其与右表连接。min-max 索引也会用于跳过不需要的右表块。

• direct

direct (也称为 nested loop) 算法使用左表中的行作为键，在右表中执行查找。 它适用于 Dictionary、EmbeddedRocksDB 和 MergeTree 表等特殊存储。

对于 MergeTree 表，该算法会将连接键过滤器直接下推到存储层。如果该键可以利用表的主键索引进行查找，则效率会更高；否则，它会对左表的每个块都对右表执行全表扫描。

支持 INNER 和 LEFT joins，并且仅支持不带其他条件的单列等值连接键。

• auto

当设置为 auto 时，会先尝试 hash join；如果超出内存限制，则会动态切换到另一种算法。

• full_sorting_merge

在执行连接前，对参与连接的表进行完全排序的 Sort-merge algorithm。

• prefer_partial_merge

如果可能，ClickHouse 总是尝试使用 partial_merge join，否则使用 hash。已弃用，等同于 partial_merge,hash。

• default (deprecated)

旧版取值，请不要再使用。 与 direct,hash 相同，即尝试使用 direct join 和 hash join (按此顺序) 。

​

join_any_take_last_row

更改 ANY strictness 的 join 操作行为。

此设置仅适用于右表使用 Join 表引擎的 JOIN 操作。

可能的值：

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

另请参见：

• JOIN 子句
• Join 表引擎
• join_default_strictness

​

join_default_strictness

设置 JOIN 子句的默认 strictness。

Possible values:

• ALL — 如果右表有多行匹配，ClickHouse 会基于这些匹配行创建笛卡尔积。这是标准 SQL 中 JOIN 的常规行为。
• ANY — 如果右表有多行匹配，则只连接找到的第一行。如果右表只有一行匹配，则 ANY 和 ALL 的结果相同。
• ASOF — 用于连接匹配关系不确定的序列。
• Empty string — 如果查询中未指定 ALL 或 ANY，ClickHouse 会抛出异常。

​

join_on_disk_max_files_to_merge

限制在磁盘上执行 MergeJoin 操作时，并行排序可合并的文件数量。

该设置值越大，占用的 RAM 越多，所需的磁盘 I/O 就越少。

可能的值：

• 从 2 开始的任意正整数。

​

join_output_by_rowlist_perkey_rows_threshold

在 hash join 中，用于判断是否按行列表输出时，右表中每个键平均行数的下限。

​

join_overflow_mode

定义当达到以下任一 join 限制时，ClickHouse 将执行的操作：

• max_bytes_in_join
• 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_runtime_bloom_filter_max_ratio_of_set_bits

如果运行时布隆过滤器中的置位占比超过该比值，则会完全禁用该过滤器，以降低开销。

​

join_runtime_filter_blocks_to_skip_before_reenabling

在尝试动态重新启用先前因过滤效果不佳而被禁用的运行时过滤器之前，需要跳过的块数。

​

join_runtime_filter_exact_values_limit

运行时过滤器中以原样存储在集合里的元素数量上限；超过该阈值后，会切换为 bloom filter。

​

join_runtime_filter_pass_ratio_threshold_for_disabling

如果通过的行数与已检查行数的比率超过此阈值，则认为运行时过滤器效果不佳，并会在接下来的 join_runtime_filter_blocks_to_skip_before_reenabling 个块内将其禁用，以降低开销。

​

join_to_sort_maximum_table_rows

在 LEFT JOIN 或 INNER JOIN 中，判断是否需要按键对右表重新排序时，右表的最大行数。

​

join_to_sort_minimum_perkey_rows

右侧表中每个键平均行数的下限，用于确定在 LEFT JOIN 或 INNER JOIN 中，是否需要按键对右侧表重新排序。此设置可确保在表键较为稀疏时不会应用该优化

​

join_use_nulls

用于设置 JOIN 的行为。在合并表时，可能会出现空单元。ClickHouse 会根据此设置以不同方式对其进行填充。

可能的值：

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

​

joined_block_split_single_row

允许按左表中单行对应的行来切分哈希 join 结果。 当左表中的某一行在右表中有大量匹配项时，这可以减少内存使用，但也可能增加 CPU 使用率。 请注意，必须设置 max_joined_block_size_rows != 0，此设置才会生效。 将 max_joined_block_size_bytes 与此设置结合使用，有助于避免在数据倾斜、且某些大行在右表中有大量匹配项时出现过高的内存使用。

​

joined_subquery_requires_alias

强制要求参与 join 的子查询和表函数必须使用别名，以确保名称限定正确。

​

kafka_disable_num_consumers_limit

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

​

kafka_max_wait_ms

重试前，从 Kafka 读取消息时的等待时间 (以毫秒为单位) 。

可选值：

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

另请参阅：

• Apache Kafka

​

keeper_map_strict_mode

在对 KeeperMap 执行操作时启用额外检查。例如，对已存在的键执行 insert 时会抛出异常

​

keeper_max_retries

常规 Keeper 操作的最大重试次数

​

keeper_retry_initial_backoff_ms

用于常规 Keeper 操作的初始 backoff 超时时间

​

keeper_retry_max_backoff_ms

常规 Keeper 操作的最大退避超时

​

least_greatest_legacy_null_behavior

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

​

legacy_column_name_of_tuple_literal

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

​

lightweight_delete_mode

轻量级删除过程中执行的内部更新查询模式。

可能的值：

• alter_update - 运行 ALTER UPDATE 查询，这会创建重量级变更。
• lightweight_update - 如果可以，则运行轻量级更新；否则运行 ALTER UPDATE。
• lightweight_update_force - 如果可以，则运行轻量级更新；否则抛出异常。

​

lightweight_deletes_sync

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

可能的值：

值	说明
0	变更将异步执行。
1	查询会等待当前服务器上的轻量级删除完成。
2	查询会等待所有副本 (如果存在) 上的轻量级删除完成。
3	查询仅等待活跃副本。仅支持 SharedMergeTree。对于 ReplicatedMergeTree，其行为与 mutations_sync = 2 相同。

另请参见

• ALTER 查询的同步性
• 变更

Cloud 默认值：1。

​

limit

设置可从查询结果中获取的最大行数。它会调整 LIMIT 子句设置的值，因此查询中指定的 limit 不能超过此设置所规定的 limit。

Possible values:

• 0 — 行数不受限制。
• 正整数。

​

load_balancing

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

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

• Random (默认)
• 最近的主机名
• 主机名 Levenshtein 距离
• 按顺序
• 第一个或随机
• Round robin

另请参见：

• distributed_replica_max_ignored_errors

​

Random (默认)

load_balancing = random

会分别统计每个副本的错误数。查询会发送到错误数最少的副本；如果有多个这样的副本，则会从中任意选择一个。 缺点：不会考虑服务器的远近；如果各副本中的数据不同，得到的数据也会不同。

​

最近的主机名

load_balancing = nearest_hostname

每个副本都会统计错误次数。每隔 5 分钟，错误次数都会整除 2。因此，最近一段时间内的错误次数是通过指数平滑计算得出的。如果某个副本的错误次数最少 (即其他副本最近出现过错误) ，查询就会发送到该副本。如果有多个副本的最小错误次数相同，则会将查询发送到主机名与配置文件中服务器主机名最相似的那个副本 (根据相同位置上不同字符的数量计算，只比较到两个主机名中的较短长度为止) 。

例如，example01-01-1 和 example01-01-2 只有 1 个位置不同，而 example01-01-1 和 example01-02-2 则有 2 个位置不同。 这种方法看起来可能有些原始，但它不需要额外的网络拓扑数据，也不比较 IP 地址，而对于我们的 IPv6 地址来说，比较 IP 地址会很复杂。

因此，如果存在等效的副本，就会优先选择名称最接近的那个。 我们还可以认为，在没有故障的情况下，当查询发送到同一台服务器时，Distributed 查询也会转发到相同的服务器。因此，即使各副本上存放的数据不同，查询返回的结果也大多相同。

​

主机名 Levenshtein 距离

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 标记文件

Cloud 默认值：1。

​

local_filesystem_read_method

从本地文件系统读取数据的方法，可选值包括：read、pread、mmap、io_uring、pread_threadpool。

‘io_uring’ 方法处于 Experimental 状态，在存在并发读写时，不适用于 Log、TinyLog、StripeLog、File 表引擎、Set、Join 以及其他使用可追加文件的表。 如果你在互联网上读过各种关于 ‘io_uring’ 的文章，不要被它们带偏。除了存在大量小型 IO 请求的场景外，它并不是更好的文件读取方法，而 ClickHouse 并不属于这种场景。因此，没有理由启用 ‘io_uring’。

​

local_filesystem_read_prefetch

从本地文件系统读取数据时，是否使用预取。

​

lock_acquire_timeout

定义锁定请求在失败前会等待多少秒。

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

可能的值：

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

​

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 系统表中 (即填充 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

设置是否记录查询日志。

发送到 ClickHouse 的查询在启用此设置时，会根据服务器配置参数 query_log 中的规则进行记录。

示例：

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 span 日志。

​

log_query_threads

配置查询线程日志记录。

查询线程的日志会写入 system.query_thread_log 表。仅当 log_queries 为 true 时，此设置才会生效。启用此设置后，ClickHouse 运行的查询线程会按照服务器配置参数 query_thread_log 中的规则进行记录。

可能的值：

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

示例

log_query_threads=1

​

log_query_views

设置查询视图日志记录。

当 ClickHouse 在启用此设置的情况下运行某个查询，且该查询关联了视图 (materialized 或 live views) 时，这些视图会被记录到服务器配置参数 query_views_log 中。

示例：

log_query_views=1

​

low_cardinality_allow_in_native_format

允许或禁止在 Native 格式中使用 LowCardinality 数据类型。

如果禁止使用 LowCardinality，ClickHouse server 会在 SELECT 查询中将 LowCardinality 列转换为普通列，并在 INSERT 查询中将普通列转换为 LowCardinality 列。

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

可能的值：

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

​

low_cardinality_max_dictionary_size

为可写入存储文件系统的 LowCardinality 数据类型的共享全局字典设置最大行数。此设置可防止字典无限增长而导致 RAM 相关问题。对于因字典大小达到上限而无法编码的数据，ClickHouse 会以普通方式写入。

可能的值：

• 任意正整数。

​

low_cardinality_use_single_dictionary_for_part

控制是否对数据分区片段使用单个字典。

默认情况下，ClickHouse 服务器会监控字典的大小；如果某个字典溢出，服务器就会开始写入下一个字典。要禁止创建多个字典，请设置 low_cardinality_use_single_dictionary_for_part = 1。

可能的值：

• 1 — 禁止为数据分区片段创建多个字典。
• 0 — 不禁止为数据分区片段创建多个字典。

​

low_priority_query_wait_time_ms

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

​

make_distributed_plan

生成分布式查询计划。

​

materialize_skip_indexes_on_insert

是否在 INSERT 时构建并存储跳过索引。若禁用，则仅会在合并期间构建并存储跳过索引，或者通过显式执行 MATERIALIZE INDEX 来构建并存储。

另请参见 exclude_materialize_skip_indexes_on_insert。

​

materialize_statistics_on_insert

是否在 INSERT 时构建并插入统计信息。如果禁用，统计信息将在合并期间或通过显式执行 MATERIALIZE STATISTICS 进行构建并存储

​

materialize_ttl_after_modify

执行 ALTER MODIFY TTL 查询后，对旧数据应用 TTL

​

materialized_views_ignore_errors

允许忽略 MATERIALIZED VIEW 的错误，并且无论 MVs 是否出错，都会将原始块传递到表中

​

materialized_views_squash_parallel_inserts

将单个 INSERT 查询中并行插入到 materialized view 目标表的数据块进行合并，以减少生成的 parts 数量。 如果设置为 false 且启用了 parallel_view_processing，则 INSERT 查询会在目标表中为每个 max_insert_thread 生成一个 part。

​

max_analyze_depth

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

​

max_ast_depth

查询语法树的最大嵌套深度。超过该限制时，将抛出异常。

目前，这一项不会在解析过程中检查，而只会在查询解析完成后检查。 这意味着，在解析过程中可能会创建出过深的语法树， 但查询会失败。

​

max_ast_elements

查询语法树中的最大元素数量。超过时会抛出异常。

目前不会在解析期间进行检查，而只会在查询解析完成后检查。 这意味着，解析期间仍可能创建出过深的语法树， 但查询会失败。

​

max_autoincrement_series

由 generateSerialID 函数创建的序列数量上限。

由于每个序列都对应 Keeper 中的一个节点，建议其数量不要超过几百万个。

​

max_backup_bandwidth

服务器上特定备份的最大读取速度，单位为每秒字节数。零表示不受限制。

​

max_block_size

在 ClickHouse 中，数据以块为单位进行处理，块是列分片的集合。单个块的内部处理流程效率很高，但处理每个块时都会产生明显的开销。

max_block_size 设置表示从表中加载数据时，单个块建议包含的最大行数。从表中加载的块并不总是会达到 max_block_size：如果 ClickHouse 判断只需读取较少的数据，就会处理更小的块。

块大小不应过小，以避免处理每个块时产生明显开销；也不应过大，以确保带有 LIMIT 子句的查询在处理完第一个块后能够快速执行。设置 max_block_size 时，目标应是避免在多线程提取大量列时占用过多内存，并尽可能保留一定的缓存局部性。

​

max_bytes_before_external_group_by

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

启用或禁用在外部内存中执行 GROUP BY 子句的功能。 (请参见 外部内存中的 GROUP BY)

可选值：

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

如果 GROUP BY 操作期间的内存使用量超过此阈值 (以字节为单位) ， 则会启用“外部聚合”模式 (将数据落盘) 。

建议值为可用系统内存的一半。

​

max_bytes_before_external_join

如果将其设为非零值，且 join_algorithm 为 hash、parallel_hash、default 或 auto，当右侧数据超过该字节数时，hash join 会自动转换为 grace hash join，以支持落盘到 disk。设为 0 (默认值) 时，此绝对字节阈值会被禁用，但仍可能通过 max_bytes_ratio_before_external_join (默认值为 0.5) 触发自动落盘；将两者都设为 0 可完全禁用自动落盘。它会阻止通过 join 进行按顺序读取优化。

​

max_bytes_before_external_sort

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

启用或禁用在外部内存中执行 ORDER BY 子句。请参见 ORDER BY 实现细节。 如果 ORDER BY 操作期间的内存使用量超过此阈值 (以字节为单位) ，则会启用“外部排序”模式 (将数据落盘) 。

可能的值：

• 单个 ORDER BY 操作可使用的最大 RAM 容量 (以字节为单位) 。 建议值为可用系统内存的一半
• 0 — 禁用在外部内存中执行 ORDER BY。

​

max_bytes_before_remerge_sort

对于带有 LIMIT 的 ORDER BY，当内存使用量高于指定阈值时，会在最终合并之前额外执行块合并步骤，以仅保留前 LIMIT 行。

​

max_bytes_for_lazy_final

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

​

max_bytes_in_distinct

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

​

max_bytes_in_join

执行表连接时所用哈希表的最大大小，以字节数表示。

此设置适用于 SELECT … JOIN 操作以及 Join table engine。

如果查询包含 JOIN，ClickHouse 会针对每个中间结果检查此设置。

达到该限制时，ClickHouse 可以采取不同的操作。请使用 join_overflow_mode 设置来选择处理方式。

可能的值：

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

​

max_bytes_in_set

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

​

max_bytes_ratio_before_external_group_by

允许 GROUP BY 使用的可用内存比例。达到该比例后， 聚合将使用外部内存。

例如，如果设置为 0.6，则 GROUP BY 在执行开始时最多可使用 60% 的可用内存 (相对于 server/user/merges 可用的内存) ，之后将 开始使用外部聚合。

​

max_bytes_ratio_before_external_join

允许 JOIN 使用的可用内存占比。达到该比例后，hash join 会转换为 grace hash join，并将右侧数据落盘。

例如，如果设置为 0.6，则 JOIN 在执行开始时允许右侧哈希表使用可用内存 (对 server/user/merges 可用) 的 60%；之后将开始落盘。

如果同时设置了 max_bytes_before_external_join 和 max_bytes_ratio_before_external_join，则使用两者计算结果中较小的阈值。如果该比例为 0，则仅应用绝对值设置。

仅当 join_algorithm 为 hash、parallel_hash、default 或 auto，且已配置临时数据路径时，此设置才会生效。

​

max_bytes_ratio_before_external_sort

允许 ORDER BY 使用的可用内存占比。达到该比例后，将使用外部排序。

例如，如果设置为 0.6，则 ORDER BY 在执行开始时最多可使用 60% 的可用内存 (相对于 server/user/merges) ，之后将开始使用外部排序。

请注意，max_bytes_before_external_sort 仍然有效；只有当排序块大于 max_bytes_before_external_sort 时，才会落盘。

​

max_bytes_to_read

运行查询时，从表中可读取的最大字节数 (以未压缩数据计) 。 该限制会对每个已处理的数据块进行检查，仅应用于最深层的表表达式；从远程服务器读取时，也只会在远程服务器上进行检查。

​

max_bytes_to_read_leaf

运行分布式查询时，叶子节点上从本地表中可读取的最大字节数 (按未压缩数据计) 。

尽管分布式查询可以向每个分片 (叶子) 发出多个子查询，但该限制只会在叶子节点的读取阶段进行检查，而在根节点的结果合并阶段会被忽略。

例如，一个集群由 2 个分片组成，每个分片都包含一张有 100 字节数据的表。某个分布式查询需要读取这两张表中的全部数据，如果设置 max_bytes_to_read=150，则会失败，因为总读取量会达到 200 字节。而设置 max_bytes_to_read_leaf=150 的查询会成功，因为叶子节点最多只会读取 100 字节。

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

此设置在 prefer_localhost_replica=1 时不稳定。

​

max_bytes_to_sort

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

​

max_bytes_to_transfer

执行 GLOBAL IN/JOIN 部分时，可传输到远程服务器或保存到临时表中的最大字节数 (未压缩数据) 。

​

max_columns_to_read

单个查询从表中可读取的最大列数。 如果查询需要读取的列数超过指定数量， 则会抛出异常。

此设置可用于防止查询过于复杂。

0 表示不受限制。

​

max_compress_block_size

写入表时，压缩前未压缩数据块的最大大小。默认值为 1,048,576 (1 MiB) 。指定较小的块大小通常会使压缩率略有下降；但由于缓存局部性更好，压缩和解压速度会略有提升，同时内存消耗也会降低。

这是一个专家级设置；如果你刚开始使用 ClickHouse，不建议更改它。

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

​

max_concurrent_queries_for_all_users

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

示例：可将 max_concurrent_queries_for_all_users 为所有用户设置为 99，而数据库管理员可将其自身的值设为 100，以便即使在 server 过载时也能运行用于调查的查询。

为单个查询或用户修改此设置，不会影响其他查询。

可能的值：

• 正整数。
• 0 — 不限制。

示例

<max_concurrent_queries_for_all_users>99</max_concurrent_queries_for_all_users>

另请参阅

• max_concurrent_queries

Cloud 默认值：1000。

​

每个用户的最大并发查询数

每个用户可同时处理的查询数量上限。

可能的值：

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

示例

<max_concurrent_queries_for_user>5</max_concurrent_queries_for_user>

​

max_consume_snapshots

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

​

max_distributed_connections

对单个 Distributed 表执行单次查询的分布式处理时，与远程服务器之间允许建立的最大并发连接数。建议将该值设置为不小于集群中的服务器数量。

以下参数仅在创建 Distributed 表时 (以及服务器启动时) 使用，因此没有必要在运行时更改它们。

​

max_distributed_depth

限制 Distributed 表递归查询的最大深度。

如果超过该值，server 会抛出异常。

Possible values:

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

​

max_download_buffer_size

每个线程用于并行下载 (例如 URL engine) 的缓冲区最大大小。

​

max_download_threads

下载数据时可使用的最大线程数 (例如用于 URL engine) 。

​

max_estimated_execution_time

查询的最大预计执行时间 (秒) 。当 timeout_before_checking_execution_speed 到期时，会在每个数据块上检查。

​

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

设置带有 FINAL 修饰符的 SELECT 查询在数据读取阶段可使用的最大并行线程数。

可能的值：

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

​

max_http_get_redirects

允许的 HTTP GET 重定向跳转次数上限。该设置可提供额外的安全保障，防止恶意服务器将你的请求重定向到非预期的服务。\n\n例如，外部服务器可能会将请求重定向到另一个地址，而该地址看起来属于公司内部基础设施。这样一来，向该内部服务器发送 HTTP 请求时，你就可能从内部网络访问内部 API，绕过身份验证，甚至查询其他服务，例如 Redis 或 Memcached。如果你没有内部基础设施 (包括在 localhost 上运行的任何服务) ，或者你信任该服务器，则允许重定向是安全的。但请注意，如果 URL 使用的是 HTTP 而非 HTTPS，那么你不仅需要信任远程服务器，还需要信任你的 ISP 以及中间经过的所有网络。

Cloud default value: 10.

​

max_hyperscan_regexp_length

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

可能的值：

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

别名: max_insert_block_size_rows

为插入表而生成的块的最大大小 (按行数计) 。

此设置在以下两种场景中控制块的生成：

1. 格式解析：当服务器通过任意接口 (HTTP、带内联数据的 clickhouse-client、gRPC、PostgreSQL wire protocol) 解析基于行的输入格式 (CSV、TSV、JSONEachRow 等) 时，会在以下情况下输出块：

   • 同时达到 min_insert_block_size_rows AND min_insert_block_size_bytes，OR
   • 达到 max_insert_block_size_rows OR max_insert_block_size_bytes 中的任意一个

   注意：使用 clickhouse-client 或 clickhouse-local 从文件读取时，数据由客户端自身解析，因此此设置在客户端侧生效。

2. INSERT 操作：在执行 INSERT queries 期间，以及数据流经 materialized views 时，此设置的行为取决于 use_strict_insert_block_limits：

   • 启用时：会在以下情况下输出块：

     • 最小阈值 (AND) ：同时达到 min_insert_block_size_rows AND min_insert_block_size_bytes
     • 最大阈值 (OR) ：达到 max_insert_block_size_rows OR max_insert_block_size_bytes 中的任意一个

   • 禁用时：达到 min_insert_block_size_rows OR min_insert_block_size_bytes 时就会输出块。max_insert_block_size 设置不会生效。

可能的值：

• 正整数。

​

max_insert_block_size_bytes

为插入表而生成的块的最大大小 (以字节为单位) 。

此设置与 max_insert_block_size_rows 配合使用，并在相同上下文中控制块的生成。有关这些设置会在何时以及如何生效的详细信息，请参见 max_insert_block_size_rows。

Possible values:

• 正整数。
• 0 — 该设置不参与块的生成。

​

max_insert_delayed_streams_for_parallel_write

延迟最终分片刷写的最大流 (列) 数。默认值为自动 (如果底层存储支持并行写入，例如 S3，则为 100；否则为禁用)

Cloud 默认值：50。

​

max_insert_threads

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

可能的值：

• 0 (或 1) — INSERT SELECT 不会并行执行。
• 大于 1 的正整数。

Cloud 默认值：

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

只有当 SELECT 部分并行执行时，并行 INSERT SELECT 才会生效，请参见 max_threads 设置。 值越大，内存使用量越高。

​

max_insert_threads_min_free_memory_per_thread

与 max_threads_min_free_memory_per_thread 相同，但它作用于 max_insert_threads，而不是 max_threads。默认值更高，因为插入管道通常比读取管道为每个线程保留更大的缓冲区 (MergeTree parts、压缩块) 。

如果空闲内存小于 max_insert_threads 与该值的乘积，则会下调 max_insert_threads 以适应可用内存，最少降至 1。

将其设为 0 可禁用此限制。

​

max_joined_block_size_bytes

JOIN 结果的最大块大小 (以字节为单位，前提是 JOIN 算法支持) 。0 表示无限制。

​

max_joined_block_size_rows

JOIN 结果的最大块大小 (如果所用的 join 算法支持) 。0 表示无限制。

​

max_limit_for_vector_search_queries

LIMIT 大于此设置值的 SELECT 查询不能使用向量相似度索引。这有助于防止向量相似度索引发生内存溢出。

​

max_local_read_bandwidth

本地读取的最高速度，以每秒字节数为单位。

​

max_local_write_bandwidth

本地写入的最大速度，单位为每秒字节数。

​

max_memory_usage

Cloud 默认值：取决于副本上的 RAM 大小。

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

此设置不考虑可用内存大小，也不考虑机器上的 总内存大小。该限制仅适用于单台 服务器上的单个查询。

你可以使用 SHOW PROCESSLIST 查看每个查询当前的内存占用。 系统会跟踪每个查询的峰值内存占用，并将其写入日志。

对于以下使用 String 和 Array 参数的聚合函数状态， 内存占用无法被完全跟踪：

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

内存占用还受参数 max_memory_usage_for_user 和 max_server_memory_usage 的限制。

​

max_memory_usage_for_user

在单台服务器上执行某个用户的查询时，允许使用的最大 RAM 量。0 表示不受限制。

默认情况下，该值不受限制 (max_memory_usage_for_user = 0) 。

另请参阅 max_memory_usage 的说明。

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

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

限制通过网络交换数据的速率，单位为字节/秒。此设置适用于 server 上所有并发运行的查询。

可能的值：

• 正整数。
• 0 — 禁用数据速率控制。

​

max_network_bandwidth_for_user

限制网络数据交换速度，单位为字节/秒。此设置适用于单个用户执行的所有并发查询。

可能的值：

• 正整数。
• 0 — 禁用数据传输速率控制。

​

max_network_bytes

限制执行查询时通过网络接收或传输的数据量 (以字节为单位) 。此设置适用于每个单独的查询。

可能的值：

• 正整数。
• 0 — 禁用数据量限制。

​

max_number_of_partitions_for_independent_aggregation

表中可应用此优化的最大分区数

​

max_os_cpu_wait_time_ratio_to_throw

将 OS CPU 等待时间 (OSCPUWaitMicroseconds 指标) 与忙碌时间 (OSCPUVirtualTimeMicroseconds 指标) 之间的最大比率，作为判断是否拒绝查询的依据。概率通过最小比率与最大比率之间的线性插值计算；在该点处，概率为 1。

​

max_parallel_replicas

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

可能的值：

• 正整数。

附加信息

此选项会因所使用的设置不同而产生不同的结果。

​

使用 SAMPLE 键进行并行处理

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

• 采样键在分区键中的位置不利于高效的范围扫描。
• 向表中添加采样键会降低按其他列过滤的效率。
• 采样键是一个计算开销较高的表达式。
• 集群延迟分布存在长尾，因此查询更多服务器会增加查询的整体延迟。

​

使用 parallel_replicas_custom_key 进行并行处理

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

​

max_parser_backtracks

解析器最大回溯次数 (即在递归下降解析过程中尝试不同备选方案的次数) 。

​

max_parser_depth

限制递归下降解析器的最大递归深度，可用于控制栈大小。

可能的值：

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

​

max_parsing_threads

用于解析支持并行解析的输入格式数据时可使用的最大线程数。默认情况下，该值会自动确定。

​

max_partition_size_to_drop

对查询时执行删除分区操作的限制。值 0 表示可以不受任何限制地删除分区。

Cloud 默认值：1 TB。

此查询设置会覆盖对应的服务器级设置，参见 max_partition_size_to_drop

​

max_partitions_per_insert_block

限制单个插入块中的最大分区数； 如果该块包含的分区过多，则会抛出异常。

• 正整数。
• 0 — 分区数量不受限制。

详情

插入数据时，ClickHouse 会计算插入块中的分区数。如果分区数超过 max_partitions_per_insert_block，ClickHouse 会根据 throw_on_max_partitions_per_insert_block 记录警告或抛出异常。异常文本如下：

“单个 INSERT 块中的分区过多 (partitions_count 个分区，限制为 ” + toString(max_partitions) + ”) 。 该限制由 ‘max_partitions_per_insert_block’ 设置控制。 使用大量分区是一种常见误区。这会对性能造成严重负面影响，包括 server 启动缓慢、INSERT 查询缓慢 以及 SELECT 查询缓慢。对于一张表，建议分区总数控制在 1000..10000 以内。请注意， 分区并不是为了加速 SELECT 查询 (ORDER BY key 足以让范围查询保持较快) 。 分区是用于数据操作的 (DROP PARTITION 等) 。”

此设置是一个安全阈值，因为使用大量分区是一种常见误区。

​

max_partitions_to_read

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

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

可选值：

• 正整数
• -1 - 不限 (默认)

你也可以在表设置中指定 MergeTree 设置 max_partitions_to_read。

​

max_parts_to_move

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

​

max_projection_rows_to_use_projection_index

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

​

max_query_size

由 SQL 解析器解析的查询字符串的最大字节数。 INSERT 查询中 VALUES 子句里的数据由单独的 stream parser 处理 (其 RAM 占用为 O(1)) ，因此不受此限制影响。

max_query_size 不能在 SQL 查询内部设置 (例如 SELECT now() SETTINGS max_query_size=10000) ，因为 ClickHouse 需要先分配一个 buffer 来解析查询，而该 buffer 的大小由 max_query_size 设置决定；因此，它必须在查询执行前完成配置。

​

max_rand_distribution_parameter

randChiSquared、randStudentT 和 randFisherF 等 random distribution functions 的分布形态参数最大值。此设置可防止参数值过于极端时导致计算时间过长。

​

max_rand_distribution_trials

randBinomial 和 randNegativeBinomial 等随机分布函数允许的最大试验次数。这可以避免在试验次数很大时导致计算时间过长。

​

max_read_buffer_size

从文件系统读取时缓冲区的最大大小。

​

max_read_buffer_size_local_fs

从本地文件系统读取数据时，缓冲区的最大大小。如果设置为 0，则使用 max_read_buffer_size。

​

max_read_buffer_size_remote_fs

从远程文件系统读取数据时，缓冲区的最大大小。如果设置为 0，则使用 max_read_buffer_size。

​

max_recursive_cte_evaluation_depth

递归 CTE 求值深度上限

​

max_remote_read_network_bandwidth

读取时网络数据交换的最大速率，以字节/秒为单位。

​

max_remote_write_network_bandwidth

写入时网络数据交换的最大速度，以字节/秒为单位。

​

max_replica_delay_for_distributed_queries

对分布式查询禁用延迟过高的副本。请参阅 复制。

设置一个以秒为单位的时间值。如果某个副本的延迟大于或等于该值，则不会使用该副本。

可能的值：

• 正整数。
• 0 — 不检查副本延迟。

若要防止使用任何存在非零延迟的副本，请将此参数设置为 1。

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

​

max_result_bytes

限制结果大小 (以字节计，未压缩) 。如果达到阈值，查询会在处理完一个数据块后停止， 但不会截断结果的最后一个块，因此结果大小可能会超过该阈值。

注意事项

此阈值会将内存中的结果大小计算在内。 即使结果本身很小，它也可能引用内存中更大的数据结构， 例如 LowCardinality 列的字典，以及 AggregateFunction 列的 Arena， 因此即使结果较小，也可能超过该阈值。

该设置较为底层，应谨慎使用

​

max_result_rows

Cloud 默认值：0。

限制结果中的行数。此限制也会应用于子查询，以及在远程服务器上执行分布式查询的各个部分时。 当该值为 0 时，不作限制。

如果达到阈值，查询会在处理完一个数据块后停止， 但不会截断结果中的最后一个块，因此结果大小可能会 超过该阈值。

​

max_reverse_dictionary_lookup_cache_size_bytes

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

​

max_rows_for_lazy_final

用于 lazy FINAL 优化的集合最大行数。超过该值时，将回退到普通 FINAL。

​

max_rows_in_distinct

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

​

max_rows_in_join

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

此设置适用于 SELECT … JOIN 操作以及 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 行。

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

此设置在 prefer_localhost_replica=1 时属于不稳定状态。

​

max_rows_to_sort

排序前允许的最大行数。这有助于在排序时限制内存占用。 如果为执行 ORDER BY 操作而需要处理的记录数超过指定数量， 则其行为由 sort_overflow_mode 决定，该值默认设置为 throw。

​

max_rows_to_transfer

执行 GLOBAL IN/JOIN 部分时，可传递到远程服务器或保存到临时表中的最大行数。

​

max_sessions_for_user

每个已通过身份验证的用户在 ClickHouse server 上允许的最大并发会话数。

示例：

<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>
    <!-- 用户 Alice 每次最多只能与 ClickHouse server 建立一个连接。-->
    <Alice>
        <profile>single_session_user</profile>
    </Alice>
    <!-- 用户 Bob 最多可同时使用 2 个 session。-->
    <Bob>
        <profile>two_sessions_profile</profile>
    </Bob>
    <!-- 用户 Charles 可同时使用任意数量的 session。-->
    <Charles>
        <profile>unlimited_sessions_profile</profile>
    </Charles>
</users>

可选值：

• 正整数
• 0 - 并发会话数无限制 (默认)

​

max_size_to_preallocate_for_aggregation

在聚合之前，所有哈希表总共允许为多少个元素预分配空间

​

max_size_to_preallocate_for_joins

在 joi 之前，允许在所有哈希表中总共为多少个元素预分配空间

​

max_skip_unavailable_shards_num

启用 skip_unavailable_shards 时，该设置用于限制可静默跳过的分片最大数量。 如果不可用分片的数量超过此值，则不会静默跳过，而是抛出异常。

值为 0 表示不设限制 (默认行为——可跳过所有不可用分片) 。

​

max_skip_unavailable_shards_ratio

启用 skip_unavailable_shards 时，此设置用于限制可静默跳过的分片最大比例 (0 到 1) 。 如果不可用分片占总分片的比例超过此值，则不会静默跳过，而会抛出异常。

值为 0 表示不设限制 (默认行为——可跳过所有不可用分片) 。

​

max_streams_for_files_processing_in_cluster_functions

如果不为 0，则限制 *Cluster 表函数中从文件读取数据的线程数。

​

max_streams_for_merge_tree_reading

如果该值不为 0，则限制 MergeTree 表的读取流数量。

​

max_streams_for_union_step

限制 UNION 步骤中同时活跃的数据流数量 (适用于 UNION ALL 和 UNION DISTINCT，因为 UNION DISTINCT 的实现方式是先执行 UNION ALL 步骤，再执行 DISTINCT 步骤) 。当 UNION 查询包含大量子查询时，这些子查询会同时打开各自的读缓冲区，导致内存占用与子查询数量成正比。此设置会插入 Concat 处理器来收窄管道，使同时活跃的流数量最多不超过该值，从而显著降低峰值内存占用。实际限制为该值与 max_threads * max_streams_for_union_step_to_max_threads_ratio 两者中的较小值 (任一值为 0 都表示忽略该值) 。当两者都为 0 时，则不会进行收窄。

​

max_streams_for_union_step_to_max_threads_ratio

该比率乘以 max_threads 后，用于确定 UNION 步骤中同时活跃的流数上限 (同时适用于 UNION ALL 和 UNION DISTINCT) 。实际限制取该计算值与 max_streams_for_union_step 中的较小者 (任一值为 0 都表示忽略该值) 。例如，当 max_threads = 8 且该比率设置为 1 时，最多会有 8 个流同时活跃。将其设置为 0 可禁用基于该比率的限制。

​

max_streams_multiplier_for_merge_tables

从 Merge 表读取时请求更多流。这些流会分配到 Merge 表使用的各个表上。这样可以让工作在线程之间分布得更均衡，尤其适用于已合并表大小不一致的情况。

​

max_streams_to_max_threads_ratio

允许使用比线程数更多的流，以便在线程之间更均匀地分配工作。这里假定这只是一个临时方案，因为未来将能够使流的数量等于线程数，同时让每个流动态选择自己可用的工作。

​

max_subquery_depth

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

这样可以进行合理性检查，防止集群中的用户编写过于复杂的查询。

​

max_table_size_to_drop

对查询时删除表的限制。值 0 表示可以不受任何限制地删除所有表。

Cloud 默认值：1 TB。

此查询设置会覆盖对应的服务器设置，参见 max_table_size_to_drop

​

max_temporary_columns

执行查询时，包括常量列在内，同时保存在 RAM 中的临时列的最大数量。如果查询因中间计算在内存中生成的临时列数量超过指定值，则会抛出异常。

此设置有助于防止查询过于复杂。

0 表示不受限制。

​

max_temporary_data_on_disk_size_for_query

所有并发运行的查询在磁盘上使用的临时 File 数据总量上限，单位为字节。

可能的值：

• 正整数。
• 0 — 无限制 (默认)

​

max_temporary_data_on_disk_size_for_user

用户所有并发运行的查询在磁盘上的临时 File 所消耗的数据总量上限，单位为字节。

可能的值：

• 正整数。
• 0 — 不限制 (默认)

​

max_temporary_non_const_columns

与 max_temporary_columns 类似，它表示执行查询时需要同时保存在 RAM 中的临时列的最大数量，但不包括常量列。

执行查询时经常会生成常量列，但它们几乎不消耗计算资源。

​

max_threads

查询处理线程的最大数量，不包括用于从远程服务器获取数据的线程 (参见 ‘max_distributed_connections’ 参数) 。

此参数适用于并行执行查询处理管道中相同阶段的线程。 例如，从表中读取数据时，如果能够至少使用 ‘max_threads’ 个线程并行完成函数表达式求值、WHERE 过滤以及 GROUP BY 的预聚合，那么就会使用 ‘max_threads’。

对于因 LIMIT 而很快完成的查询，可以将 ‘max_threads’ 设置得更低。 例如，如果每个块中都包含所需数量的条目，且 max_threads = 8，那么会读取 8 个块，尽管实际上只读取 1 个块就足够了。 max_threads 的值越小，消耗的内存就越少。

默认情况下，max_threads 设置与 ClickHouse 可用的硬件线程数 (CPU 核心数) 一致。 不过有一种特殊情况：对于 CPU 核心数少于 32 且启用了 SMT (例如 Intel HyperThreading) 的 x86 处理器，ClickHouse 默认使用逻辑核心数 (= 2 x 物理核心数) 。

如果未启用 SMT (例如 Intel HyperThreading) ，则该值对应于 CPU 核心数。

对于 ClickHouse Cloud 用户，默认值会显示为 auto(N)，其中 N 与你的服务的 vCPU 规格一致，例如 2vCPU/8GiB、4vCPU/16GiB 等。 所有服务规格的列表可在 Cloud Console 的设置选项卡中查看。

​

max_threads_for_indexes

用于处理索引的最大线程数。

​

max_threads_min_free_memory_per_thread

当 server 面临内存压力时，会降低 max_threads，以避免启动很可能触及内存限制的高并行查询。

空闲内存的计算方式为：server 的 max_server_memory_usage 减去当前由全局 memory tracker 跟踪的内存。如果该空闲内存小于 max_threads 与此值的乘积，则会将 max_threads 降低为满足 N * value <= free_memory 的最大 N，且最小值为 1。

将其设置为 0 可禁用此限制。

例如，默认值为 1 GiB 且空闲内存为 32 GiB 时，max_threads 上限为 32；空闲内存为 1 GiB 时，则会回落到 1。

此设置适用于读取侧并行度 (SELECT、UNION、INTERSECT/EXCEPT，以及 INSERT ... SELECT 中的 SELECT 侧) 。对于写入侧，请参见 max_insert_threads_min_free_memory_per_thread。

​

max_untracked_memory

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

​

max_wkb_geometry_elements

通过 readWKB 及相关函数解析时，单个 WKB 几何元素中允许包含的点、Ring 或 Polygon 的最大数量。这可防止格式错误的 WKB 数据造成过量内存分配。设置为 0 可使用硬编码限制 (1 亿) 。

​

memory_overcommit_ratio_denominator

它表示在全局层面达到硬限制时的软内存限制。 该值用于计算查询的 overcommit 比率。 零表示跳过该查询。 更多信息，请参阅内存 overcommit。

​

memory_overcommit_ratio_denominator_for_user

它表示在用户级别达到硬内存限制时的软内存限制。 该值用于计算查询的 overcommit ratio。 值为 0 表示跳过该查询。 更多信息请参阅内存 overcommit。

​

memory_profiler_sample_max_allocation_size

以 memory_profiler_sample_probability 的概率收集大小小于或等于指定值的随机内存分配。0 表示禁用。你可能需要将 max_untracked_memory 设置为 0，以使该阈值按预期生效。

​

memory_profiler_sample_min_allocation_size

以 memory_profiler_sample_probability 指定的概率，对大小大于或等于指定值的随机内存分配进行采样收集。0 表示禁用。你可能需要将 max_untracked_memory 设为 0，才能使此阈值按预期生效。

​

memory_profiler_sample_probability

随机收集内存分配与释放事件，并以 ‘MemorySample’ trace_type 写入 system.trace_log。这里的概率适用于每一次 alloc/free，与分配大小无关 (可通过 memory_profiler_sample_min_allocation_size 和 memory_profiler_sample_max_allocation_size 调整) 。请注意，只有在未跟踪内存量超过 ‘max_untracked_memory’ 时才会进行采样。若要获得更细粒度的采样，你可能需要将 ‘max_untracked_memory’ 设置为 0。

​

memory_profiler_step

设置内存分析器的步长。每当查询的内存使用量超过下一个以字节数表示的步长阈值时，内存分析器都会收集分配时的 stacktrace，并将其写入 trace_log。

可能的值：

• 以字节为单位的正整数。

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

​

memory_tracker_fault_probability

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

​

memory_usage_overcommit_max_wait_microseconds

在用户级别发生内存 overcommit 时，线程等待内存释放的最长时间。 如果达到 timeout 且内存仍未释放，则会抛出异常。 有关内存 overcommit的更多信息，请参见。

​

merge_table_max_tables_to_look_for_schema_inference

创建未显式指定 schema 的 Merge 表，或使用 merge 表函数时，schema 会推断为匹配表中不超过指定数量的表的并集。 如果表的数量超过该值，则 schema 将根据前指定数量的表进行推断。

​

merge_tree_coarse_index_granularity

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

可能的值：

• 任意正偶数。

​

merge_tree_compact_parts_min_granules_to_multibuffer_read

仅在 ClickHouse Cloud 中生效。该设置指定在 MergeTree 表的 compact part 的 stripe 中，达到多少个粒度时使用 multibuffer reader；该读取器支持并行读取和预取。如果从远程文件系统读取，使用 multibuffer reader 会增加读取请求数量。

​

merge_tree_determine_task_size_by_prewhere_columns

是否仅根据 prewhere 列的大小来确定读取任务的大小。

​

merge_tree_max_bytes_to_use_cache

如果 ClickHouse 在一次查询中需要读取超过 merge_tree_max_bytes_to_use_cache 字节的数据，则不会使用未压缩块缓存。

未压缩块缓存用于存储查询提取出的数据。ClickHouse 使用此缓存来加快重复小型查询的响应速度。此设置可防止读取大量数据的查询挤占缓存。uncompressed_cache_size 服务器设置定义了未压缩块缓存的大小。

可能的值：

• 任意正整数。

​

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

从远程 filesystem 读取时，MergeTree 引擎在可并行读取之前，从单个文件中至少需要读取的字节数。我们不建议使用此设置。

可能的值：

• 正整数。

​

merge_tree_min_bytes_for_seek

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

可能的值：

• 任意正整数。

​

merge_tree_min_bytes_per_task_for_remote_reading

别名: filesystem_prefetch_min_bytes_for_single_read_task

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

​

merge_tree_min_read_task_size

任务大小的硬性最小值 (即使粒度数量较少且可用线程数较多，我们也不会分配更小的任务

​

merge_tree_min_rows_for_concurrent_read

如果从 MergeTree 表文件中读取的行数超过 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 中 Wide parts 的前缀。该线程池的大小由服务器设置 max_prefixes_deserialization_thread_pool_size 控制。

​

merge_tree_use_v1_object_and_dynamic_serialization

启用后，MergeTree 将对 JSON 和 Dynamic 类型使用 V1 序列化版本，而不是 V2。更改此设置仅在 server 重启后才会生效。

​

metrics_perf_events_enabled

启用后，将在查询执行期间测量部分 perf 事件。

​

metrics_perf_events_list

以逗号分隔的 perf 指标列表，会在查询执行过程中进行测量。为空表示所有事件。可用事件请参见源代码中的 PerfEventInfo。

​

min_bytes_to_use_direct_io

启用直接 I/O 访问存储磁盘所需的最小数据量。

ClickHouse 在从表中读取数据时会使用此设置。如果待读取的所有数据总量超过 min_bytes_to_use_direct_io 字节，ClickHouse 就会使用 O_DIRECT 选项从存储磁盘读取数据。

Possible values:

• 0 — 禁用直接 I/O。
• 正整数。

​

min_bytes_to_use_mmap_io

这是一个 Experimental 设置。它设置了读取大文件时，使用无需将数据从内核复制到用户空间的方式所需的最小内存量。由于 mmap/munmap 较慢，建议的阈值约为 64 MB。它只对大文件有意义，并且仅在数据位于页缓存中时才有帮助。

可能的值：

• 正整数。
• 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 列，类型为 String 类型 (每个值平均 60 字节) 。写入 8192 行时，平均数据量会略低于 500 KB。由于这大于 65,536，因此每个标记都会形成一个压缩块。在这种情况下，从磁盘读取单个标记范围内的数据时，不会额外解压其他数据。

这是一个专家级设置；如果你刚开始使用 ClickHouse，则不应更改它。

​

min_count_to_compile_aggregate_expression

开始 JIT 编译所需的相同聚合表达式的最小数量。仅在启用 compile_aggregate_expressions 设置时生效。

Possible values:

• 正整数。
• 0 — 始终对相同的聚合表达式进行 JIT 编译。

​

min_count_to_compile_expression

同一表达式在编译前需执行的最小次数。

​

min_count_to_compile_sort_description

在触发 JIT 编译前，相同排序描述出现的次数

​

min_execution_speed

最小执行速度，单位为每秒行数。在 timeout_before_checking_execution_speed 超时后，会对每个数据块进行检查。如果执行速度低于该值，则会抛出异常。

​

min_execution_speed_bytes

每秒执行的最小字节数。当 timeout_before_checking_execution_speed 超时后，会在每个数据块上检查一次。如果执行速度低于该值，则会抛出异常。

​

min_external_table_block_size_bytes

如果传递给外部表的块不够大，则将其压缩合并到指定的字节大小。

​

min_external_table_block_size_rows

如果传递给外部表的块不够大，则按指定的行数将其压缩合并到该大小。

​

min_filtered_ratio_for_lazy_final

索引分析为 lazy FINAL 优化过滤掉的标记的最小比例。如果过滤掉的标记比例低于该值，则回退为普通 FINAL。值为 0 时将禁用此检查。

​

min_free_disk_bytes_to_perform_insert

执行插入操作所需的最小空闲磁盘空间 (字节) 。

​

min_free_disk_ratio_to_perform_insert

执行插入操作所需的最小空闲磁盘空间比率。

​

min_free_disk_space_for_temporary_data

在写入外部排序和聚合所用的临时数据时，需要保留的最小磁盘空间。

​

min_hit_rate_to_use_consecutive_keys_optimization

为保持聚合中连续键优化处于启用状态，所使用缓存的最低命中率

​

min_insert_block_size_bytes

插入表时生成的块的最小大小 (以字节为单位) 。

此设置与 min_insert_block_size_rows 配合使用，并在相同的上下文中控制块的生成 (格式解析和 INSERT 操作) 。有关这些设置会在何时以及如何应用的详细信息，请参见 min_insert_block_size_rows。

可能的值：

• 正整数。
• 0 — 该设置不参与块的生成。

​

min_insert_block_size_bytes_for_materialized_views

设置可通过 INSERT 查询插入表中的块的最小字节数。较小的块会被合并为更大的块。此设置仅适用于插入到 materialized view 的块。调整此设置可以控制推送到 materialized view 时的块合并，并避免过高的内存占用。

可能的值：

• 任意正整数。
• 0 — 禁用合并。

另请参见

• min_insert_block_size_bytes

​

min_insert_block_size_rows

插入到表时生成块的最小大小 (按行数计算) 。

此设置在以下两种场景中控制块的生成：

1. 格式解析：当 server 通过任意 interface (HTTP、带内联数据的 clickhouse-client、gRPC、PostgreSQL wire protocol) 解析基于行的输入格式 (CSV、TSV、JSONEachRow 等) 时，会在以下情况下输出块：

   • 同时达到 min_insert_block_size_rows AND min_insert_block_size_bytes，或者
   • 达到 max_insert_block_size_rows OR max_insert_block_size_bytes 之一

   注意：使用 clickhouse-client 或 clickhouse-local 从文件读取时，数据由客户端自行解析，此设置在客户端侧生效。

2. INSERT 操作：在执行 INSERT 查询以及数据流经 materialized view 时，此设置的行为取决于 use_strict_insert_block_limits：

   • 启用时：会在以下情况下输出块：

     • 最小阈值 (AND) ：同时达到 min_insert_block_size_rows AND min_insert_block_size_bytes
     • 最大阈值 (OR) ：达到 max_insert_block_size_rows OR max_insert_block_size_bytes 之一

   • 禁用时 (默认) ：当达到 min_insert_block_size_rows OR min_insert_block_size_bytes 之一时，就会输出块。不强制应用 max_insert_block_size 设置。

可能的值：

• 正整数。
• 0 — 此设置不参与块的生成。

​

min_insert_block_size_rows_for_materialized_views

设置可通过 INSERT 查询插入到表中的块所需的最小行数。较小的块会合并成更大的块。此设置仅适用于插入到 materialized view 的块。调整此设置后，您可以控制推送到 materialized view 时的块合并，从而避免过高的内存使用量。

可能的值：

• 任意正整数。
• 0 — 禁用块合并。

另请参见

• min_insert_block_size_rows

​

min_joined_block_size_bytes

JOIN 输入块和输出块的最小块大小 (以字节为单位) (如果 JOIN 算法支持) 。较小的块会被合并。0 表示不受限制。

​

min_joined_block_size_rows

JOIN 输入块和输出块的最小行数 (如果 JOIN 算法支持) 。较小的块会被合并为更大的块。0 表示不受限制。

​

min_os_cpu_wait_time_ratio_to_throw

将 OS CPU 等待时间 (OSCPUWaitMicroseconds 指标) 与忙碌时间 (OSCPUVirtualTimeMicroseconds 指标) 之间的最小比率，作为考虑拒绝查询的阈值。系统会使用最小比率与最大比率之间的线性插值来计算概率，在该点处概率为 0。

​

min_outstreams_per_resize_after_split

指定在管道生成过程中执行 split 后，Resize 或 StrictResize 处理器的最小输出流数量。如果最终得到的流数量小于该值，则不会进行 split 操作。

​

什么是 Resize 节点

Resize 节点是查询管道中的一种处理器，用于调整管道中数据流的数量。它既可以增加，也可以减少流的数量，以便在多个线程或处理器之间平衡工作负载。例如，如果某个查询需要更高的并行度，Resize 节点可以将单个流拆分为多个流。反过来，它也可以将多个流合并为更少的流，以集中处理数据。

Resize 节点可确保数据在各个流之间均匀分布，同时保持数据块的结构。这有助于优化资源利用率并提升查询性能。

​

为什么需要拆分 Resize 节点

在管道执行过程中，作为中心枢纽的 Resize 节点，其 ExecutingGraph::Node::status_mutex 会发生严重争用，尤其是在高核心数环境下。这种争用会导致：

1. ExecutingGraph::updateNode 的延迟增加，直接影响查询性能。
2. 大量 CPU 周期浪费在自旋锁争用 (native_queued_spin_lock_slowpath) 上，导致效率下降。
3. CPU 利用率降低，从而限制并行度和吞吐量。

​

Resize 节点如何拆分

1. 首先会检查输出流的数量，以确保可以执行拆分：拆分后每个处理器的输出流数量都达到或超过 min_outstreams_per_resize_after_split 阈值。
2. Resize 节点会被拆分为多个更小的 Resize 节点，这些节点的端口数量相同，每个节点分别处理一部分输入流和输出流。
3. 每个组都会独立处理，从而减少锁竞争。

​

具有任意输入/输出的 Resize 节点拆分

在某些情况下，如果输入/输出无法被拆分后的 Resize 节点数量整除，部分输入会连接到 NullSource，部分输出会连接到 NullSink。这样就能在不影响整体数据流的情况下完成拆分。

​

设置的作用

min_outstreams_per_resize_after_split 设置可确保对 Resize 节点的拆分确有意义，并避免创建过少的流，否则可能导致并行处理效率低下。通过强制规定最少输出流数量，该设置有助于在并行度与开销之间保持平衡，从而在涉及流拆分与合并的场景中优化查询执行。

​

禁用此设置

要禁用 Resize 节点的拆分，请将此设置设为 0。这样可防止在生成管道时拆分 Resize 节点，使其保持原有结构，而不会再被拆分为更小的节点。

​

min_table_rows_to_use_projection_index

如果估算从表中读取的行数大于或等于此阈值，ClickHouse 会在查询执行时尝试使用投影索引。

​

mongodb_throw_on_unsupported_query

如果启用，当无法构建 MongoDB 查询时，MongoDB 表会返回错误。否则，ClickHouse 会读取整个表并在本地处理。allow_experimental_analyzer=0 时，此选项不适用。

​

move_all_conditions_to_prewhere

将 WHERE 中所有适用的条件移到 PREWHERE

​

move_primary_key_columns_to_end_of_prewhere

将包含主键列的 PREWHERE 条件移至 AND 事件链的末尾。这些条件很可能会在主键分析阶段就被考虑到，因此对 PREWHERE 过滤的额外作用不大。

​

multiple_joins_try_to_keep_original_names

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

​

mutations_execute_nondeterministic_on_initiator

如果为 true，常量非确定性函数 (例如 now() 函数) 会在 initiator 上执行，并在 UPDATE 和 DELETE 查询中替换为字面量。这有助于在使用常量非确定性函数执行变更时，保持各副本上的数据同步。默认值：false。

​

mutations_execute_subqueries_on_initiator

如果为 true，则在发起节点上执行标量子查询，并在 UPDATE 和 DELETE 查询中将其替换为字面量。默认值：false。

​

mutations_max_literal_size_to_replace

在 UPDATE 和 DELETE 查询中可用于替换的序列化字面量的最大大小 (以字节为单位) 。仅当上述两个设置中至少有一个启用时，此设置才会生效。默认值：16384 (16 KiB) 。

​

mutations_sync

允许同步执行 ALTER TABLE ... UPDATE|DELETE|MATERIALIZE INDEX|MATERIALIZE PROJECTION|MATERIALIZE COLUMN|MATERIALIZE STATISTICS 查询 (变更) 。

可能的值：

值	描述
0	变更将异步执行。
1	查询会等待当前服务器上的所有变更完成。
2	查询会等待所有副本 (如果存在) 上的全部变更完成。
3	查询仅等待活跃副本。仅 SharedMergeTree 支持。对于 ReplicatedMergeTree，其行为与 mutations_sync = 2 相同。

​

mysql_datatypes_support_level

定义 MySQL 类型如何转换为对应的 ClickHouse 类型。其值为一个逗号分隔列表，可由 decimal、datetime64、date2Date32 或 date2String 任意组合而成。默认启用所有现代映射 (decimal、datetime64、date2Date32) 。

• decimal：在精度允许的情况下，将 NUMERIC 和 DECIMAL 类型转换为 Decimal。
• datetime64：当精度不为 0 时，将 DATETIME 和 TIMESTAMP 类型转换为 DateTime64，而不是 DateTime。
• date2Date32：将 DATE 转换为 Date32，而不是 Date。其优先级高于 date2String。
• date2String：将 DATE 转换为 String，而不是 Date。会被 datetime64 覆盖。

​

mysql_map_fixed_string_to_text_in_show_columns

启用后，ClickHouse 的 FixedString 数据类型会在 SHOW COLUMNS 中显示为 TEXT。

仅在通过 MySQL wire 协议建立连接时生效。

• 0 - 使用 BLOB。
• 1 - 使用 TEXT。

​

mysql_map_string_to_text_in_show_columns

启用后，String ClickHouse 数据类型会在 SHOW COLUMNS 中显示为 TEXT。

仅在通过 MySQL wire 协议建立连接时生效。

• 0 - 使用 BLOB。
• 1 - 使用 TEXT。

​

mysql_max_rows_to_insert

MySQL 存储引擎执行 MySQL 批量插入时的最大行数

​

network_compression_method

用于压缩客户端/服务器以及服务器/服务器通信的编解码器。

可能的值：

• NONE — 不压缩。
• LZ4 — 使用 LZ4 编解码器。
• LZ4HC — 使用 LZ4HC 编解码器。
• ZSTD — 使用 ZSTD 编解码器。

另请参阅

• network_zstd_compression_level

​

network_zstd_compression_level

用于调整 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 bridge 中每个连接设置字符串对应的连接池大小。

​

odbc_bridge_use_connection_pooling

在 ODBC bridge 中启用连接池。如果设置为 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_keeper_trace_probability

为 ZooKeeper 请求启动 trace 的概率，无论是否存在父 trace。

可能的值：

• ‘auto’ - 等同于 opentelemetry_start_trace_probability 设置
• 0 — 禁用追踪
• 0 到 1 — 概率 (例如，1.0 = 始终启用)

​

opentelemetry_start_trace_probability

设置 ClickHouse 为已执行的查询启动 trace 的概率 (如果未提供父 trace context) 。

可能的值：

• 0 — 禁用所有已执行查询的 trace (如果未提供父 trace context) 。
• 范围为 [0..1] 的正浮点数。例如，如果该设置值为 0,5，则 ClickHouse 平均会为一半的查询启动 trace。
• 1 — 启用所有已执行查询的 trace。

​

opentelemetry_trace_cpu_scheduling

收集工作负载抢占式 CPU 调度的 OpenTelemetry span。

​

opentelemetry_trace_processors

收集处理器的 OpenTelemetry span。

​

optimize_aggregation_in_order

在 MergeTree 表中，启用对按相应顺序聚合数据的 SELECT 查询进行 GROUP BY 优化。

可能的值：

• 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

使用约束来附加索引条件。默认值为 false。

可能的值：

• true, false

​

optimize_arithmetic_operations_in_aggregate_functions

将算术运算从聚合函数中移出

​

optimize_const_name_size

替换为标量，并将哈希用作大型常量的名称 (大小按名称长度估算) 。

可能的值：

• 正整数 - 名称的最大长度，
• 0 — 始终，
• 负整数 - 从不。

​

optimize_count_from_files

启用或禁用从不同输入格式的文件中统计行数的优化功能。该设置适用于表函数/引擎 file/s3/url/hdfs/azureBlobStorage。

可能的值：

• 0 — 禁用该优化。
• 1 — 启用该优化。

​

optimize_dictget_tuple_element

将 tupleElement(dictGet('dict', ('a', 'b', 'c'), key), 2) 重写为 dictGet('dict', 'b', key)，以避免拉取不必要的字典属性。支持按位置 (.1、.2、…) 和按名称 (.b) 访问；也适用于 dictGetOrDefault，前提是默认参数为常量 Tuple，或由常量组成的 tuple(...)。

​

optimize_distinct_in_order

如果 DISTINCT 中的某些列构成排序前缀，则启用 DISTINCT 优化。例如，MergeTree 中排序键的前缀，或 ORDER BY 语句中的前缀。

​

optimize_distributed_group_by_sharding_key

通过避免在发起端服务器上执行高开销的聚合，来优化 GROUP BY sharding_key 查询 (这会减少该查询在发起端服务器上的内存使用量) 。

支持以下类型的查询 (以及它们的任意组合) ：

• SELECT DISTINCT [..., ]sharding_key[, ...] FROM dist
• SELECT ... FROM dist GROUP BY sharding_key[, ...]
• SELECT ... FROM dist GROUP BY sharding_key[, ...] ORDER BY x
• SELECT ... FROM dist GROUP BY sharding_key[, ...] LIMIT 1
• SELECT ... FROM dist GROUP BY sharding_key[, ...] LIMIT 1 BY x

不支持以下类型的查询 (其中部分查询后续可能会增加支持) ：

• SELECT ... GROUP BY sharding_key[, ...] WITH TOTALS
• SELECT ... GROUP BY sharding_key[, ...] WITH ROLLUP
• SELECT ... GROUP BY sharding_key[, ...] WITH CUBE
• SELECT ... GROUP BY sharding_key[, ...] SETTINGS extremes=1

可能的值：

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

另请参见：

• distributed_group_by_no_merge
• distributed_push_down_limit
• optimize_skip_unused_shards

目前它要求启用 optimize_skip_unused_shards (这是因为将来它可能会默认启用，而只有在数据通过 Distributed 表插入，即数据按照 sharding_key 分布时，它才能正确工作) 。

​

optimize_dry_run_check_part

启用后，OPTIMIZE ... DRY RUN 会使用 checkDataPart 验证生成的合并后分片。如果检查失败，则会抛出异常。

​

optimize_empty_string_comparisons

将 col = '' 或 '' = col 之类的表达式转换为 empty(col)，并将 col != '' 或 '' != col 转换为 notEmpty(col)， 仅在 col 为 String 或 FixedString 类型时执行此转换。

​

optimize_extract_common_expressions

允许从 WHERE、PREWHERE、ON、HAVING 和 QUALIFY 表达式的析取中提取公共表达式。像 (A AND B) OR (A AND C) 这样的逻辑表达式可以改写为 A AND (B OR C)，这可能有助于利用：

• 简单过滤表达式中的索引
• cross join 到 inner join 的优化

​

optimize_functions_to_subcolumns

启用或禁用一项优化：将某些函数转换为读取子列，从而减少需要读取的数据量。

这些函数可被转换：

• length 转换为读取 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 中的 String 类型参数替换为枚举。默认处于禁用状态，因为这可能导致分布式查询中出现不一致的更改，从而使查询失败。

​

optimize_injective_functions_in_group_by

将 GROUP BY 子句中的单射函数替换为其参数

​

optimize_injective_functions_inside_uniq

移除 uniq*() 函数中单参数的单射函数。

​

optimize_inverse_dictionary_lookup

通过更快地查找预先计算好的一组可能键值，避免重复进行反向字典查找。

​

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 表生效。

Possible values:

• 0 — 在带有 FINAL 修饰符的 SELECT 查询中，自动 PREWHERE 优化已禁用。
• 1 — 在带有 FINAL 修饰符的 SELECT 查询中，自动 PREWHERE 优化已启用。

See Also

• optimize_move_to_prewhere 设置

​

optimize_multiif_to_if

将仅有一个条件的 multiIf 替换为 if。

​

optimize_normalize_count_variants

将语义上等价于 count() 的聚合函数重写为 count()。

​

optimize_on_insert

启用或禁用在插入前对数据进行转换，效果如同已根据表引擎对该块执行了 merge。

可能的值：

• 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 子句

​

optimize_redundant_functions_in_order_by

如果函数的参数也在 ORDER BY 中，则将该函数从 ORDER BY 中移除

​

optimize_respect_aliases

如果设置为 true，则会在 WHERE/GROUP BY/ORDER BY 中遵循别名，这有助于分区裁剪、次级索引、optimize_aggregation_in_order、optimize_read_in_order 和 optimize_trivial_count

​

optimize_rewrite_aggregate_function_with_if

当逻辑上等价时，将参数为 if 表达式的 aggregate functions 进行重写。 例如，avg(if(cond, col, null)) 可以重写为 avgOrNullIf(cond, col)。这可能会提升性能。

仅在启用 analyzer (enable_analyzer = 1) 时支持。

​

optimize_rewrite_array_exists_to_has

当逻辑上等价时，将 arrayExists() 函数重写为 has()。例如，arrayExists(x -> x = 1, arr) 可以重写为 has(arr, 1)

​

optimize_rewrite_like_perfect_affix

将具有完整前缀或后缀的 LIKE 表达式 (例如 col LIKE 'ClickHouse%') 重写为 startsWith 或 endsWith 函数 (例如 startsWith(col, 'ClickHouse')) 。

​

optimize_rewrite_regexp_functions

将正则表达式相关函数重写为更简单且更高效的形式

​

optimize_rewrite_sum_if_to_count_if

当在逻辑上等价时，将 sumIf() 和 sum(if()) 函数重写为 countIf() 函数

​

optimize_skip_merged_partitions

如果只有一个 level > 0 的 part，且其生存时间 (TTL) 尚未过期，则控制是否对 OPTIMIZE TABLE … FINAL 查询启用优化。

• OPTIMIZE TABLE ... FINAL SETTINGS optimize_skip_merged_partitions=1

默认情况下，即使只有一个 part，OPTIMIZE TABLE ... FINAL 查询也会重写该 part。

可能的值：

• 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

使用约束进行列替换。默认值为 false。

可能的值：

• true, false

​

optimize_syntax_fuse_functions

启用将参数相同的聚合函数进行融合。它会将包含至少两个参数相同的 sum、count 或 avg 聚合函数的查询重写为 sumCount。

Possible values:

• 0 — 参数相同的函数不会融合。
• 1 — 参数相同的函数会融合。

示例

查询：

CREATE TABLE fuse_tbl(a Int8, b Int8) Engine = Log;
SET optimize_syntax_fuse_functions = 1;
EXPLAIN SYNTAX run_query_tree_passes = 1 SELECT sum(a), sum(b), count(b), avg(b) from fuse_tbl FORMAT TSV;

结果：

SELECT
    sum(__table1.a) AS `sum(a)`,
    tupleElement(sumCount(__table1.b), 1) AS `sum(b)`,
    tupleElement(sumCount(__table1.b), 2) AS `count(b)`,
    divide(tupleElement(sumCount(__table1.b), 1), toFloat64(tupleElement(sumCount(__table1.b), 2))) AS `avg(b)`
FROM default.fuse_tbl AS __table1

​

optimize_throw_if_noop

启用或禁用以下行为：如果 OPTIMIZE 查询未执行 merge，则抛出异常。

默认情况下，即使 OPTIMIZE 没有执行任何操作，也会成功返回。通过此设置，您可以区分这些情况，并在异常消息中获取原因。

可能的值：

• 1 — 启用抛出异常。
• 0 — 禁用抛出异常。

​

optimize_time_filter_with_preimage

通过将函数改写为无需转换的等价比较来优化 Date 和 DateTime 谓词 (例如 toYear(col) = 2023 -> col >= '2023-01-01' AND col <= '2023-12-31')

​

optimize_trivial_approximate_count_query

对于支持此类估算的存储 (例如 EmbeddedRocksDB) ，在简单计数优化中使用近似计数值。

可能的值：

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

​

optimize_trivial_count_query

启用或禁用基于 MergeTree 元数据对简单查询 SELECT count() FROM table 的优化。如果需要使用行级安全，请禁用此设置。

可能的值：

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

另请参阅：

• optimize_functions_to_subcolumns

​

optimize_trivial_group_by_limit_query

通过设置 max_rows_to_group_by = n + offset 和 group_by_overflow_mode = 'any'，启用或禁用对简单查询 SELECT key_expr FROM table GROUP BY key_expr LIMIT n 的优化 (即投影中不包含聚合函数、没有 HAVING/ORDER BY/LIMIT BY/窗口子句，且没有 GROUP BY 修饰符) 。生成 n + offset 个不同键后，聚合即会停止。

如果用户已显式将 group_by_overflow_mode 设为非 any 值 (以保留其显式指定的 throw/break 语义) ，或者用户已设置了更严格的 max_rows_to_group_by (此时该优化将成为空操作) ，则不会应用此优化。

可能的值：

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

​

optimize_trivial_insert_select

对简单的 ‘INSERT INTO table SELECT … FROM TABLES’ 查询进行优化

​

optimize_truncate_order_by_after_group_by_keys

当 ORDER BY 前缀已覆盖所有 GROUP BY 键时，移除末尾多余的 ORDER BY 元素。

​

optimize_uniq_to_count

如果子查询包含 distinct 或 group by 子句，则将 uniq 及其变体 (uniqUpTo 除外) 重写为 count。

​

optimize_use_implicit_projections

自动选择隐式投影来执行 SELECT 查询

​

optimize_use_projection_filtering

即使未选择使用投影来执行 SELECT 查询，也可利用投影过滤分片范围。

​

optimize_use_projections

别名: allow_experimental_projection_optimization

启用或禁用在处理 SELECT 查询时的投影优化。

可能的值：

• 0 — 投影优化已禁用。
• 1 — 投影优化已启用。

​

optimize_using_constraints

使用约束进行查询优化。默认值是 false。

可能的值：

• true, false

​

os_threads_nice_value_materialized_view

materialized view 线程的 Linux nice 值。值越低，CPU 优先级越高。

需要 CAP_SYS_NICE 能力，否则为​​空操作。

可能的值：-20 到 19。

​

os_threads_nice_value_query

别名: os_thread_priority

用于查询处理线程的 Linux nice 值。值越低，CPU 优先级越高。

需要具备 CAP_SYS_NICE 能力，否则为空操作。

可能的值：-20 到 19。

​

page_cache_block_size

存储在用户态页缓存中的文件块大小，单位为字节。所有通过缓存的读取都会向上取整到该大小的整数倍。

此设置可以按单个查询进行调整，但块大小不同的缓存条目无法复用。更改此设置实际上会使缓存中现有条目失效。

较大的值 (如 1 MiB) 适合高吞吐查询，较小的值 (如 64 KiB) 适合低延迟点查询。

​

page_cache_inject_eviction

用户态页缓存有时会随机使某些页失效。用于测试。

​

page_cache_lookahead_blocks

当用户态页缓存未命中时，如果后续连续的块也未命中缓存，则会一次性从底层存储中最多读取这么多个连续块。每个块的大小为 page_cache_block_size 字节。

较高的值适合高吞吐量查询，而低延迟的点查询则在不进行预读时效果更好。

​

page_cache_max_coalesced_bytes

当 readBigAt 填充用户态页缓存时，连续的缓存未命中会被合并为一次对底层存储的读取。此设置以字节为单位限制单次合并读取的大小；更长的未命中序列会被拆分为多次读取。它可限制并行冷读期间临时缓冲区的瞬时内存使用量。

较高的值可减少对象存储冷扫描时的 HTTP 请求数；较低的值可降低瞬时内存峰值占用。

​

paimon_target_snapshot_id

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

​

parallel_distributed_insert_select

启用并行分布式 INSERT ... SELECT 查询。

如果执行 INSERT INTO distributed_table_a SELECT ... FROM distributed_table_b 查询，且两个表使用同一个集群，并且两个表要么都是复制表，要么都是非复制表，则该查询会在每个分片上本地执行。

可选值：

• 0 — 禁用。
• 1 — SELECT 将在每个分片上针对分布式引擎的底层表执行。
• 2 — SELECT 和 INSERT 将在每个分片上分别针对分布式引擎的底层表执行读写。

从 v25.4 起，源表为 ReplicatedMergeTree 或 SharedMergeTree 的 INSERT ... SELECT 也可以在副本间并行执行。要启用此功能：

• parallel_distributed_insert_select = 2
• enable_parallel_replicas = 1

​

parallel_hash_join_threshold

当使用基于哈希的 JOIN 算法时，此阈值可帮助决定使用 hash 还是 parallel_hash (仅在能够估算右侧表大小时) 。 如果已知右侧表的大小低于该阈值，则使用前者。

​

parallel_non_joined_rows_processing

允许多个线程在 RIGHT 和 FULL JOIN 期间并行处理右表中未 JOIN 的行。 使用 parallel_hash join algorithm 处理大表时，这可以加快未 JOIN 阶段的处理速度。 禁用后，未 JOIN 的行将由单个线程处理。

​

parallel_replica_offset

这是一个内部设置，不应直接使用，表示“并行副本”模式的实现细节。对于分布式查询，此设置会由发起端服务器自动设为在并行副本中参与查询处理的副本索引。

​

parallel_replicas_allow_in_with_subquery

如果为 true，IN 的子查询会在每个 follower 副本上执行。

​

parallel_replicas_allow_materialized_views

允许并行副本使用 materialized views

​

parallel_replicas_allow_view_over_mergetree

允许并行副本对基于 MergeTree 表的简单视图执行外层查询 (而非视图的内层查询) ，从而提升跨节点并行执行的效果。此设置也适用于 UNION ALL 视图，前提是其所有分支都从不同的 MergeTree 表读取。

​

parallel_replicas_connect_timeout_ms

使用并行副本执行查询时，连接远程副本的超时时间，单位为毫秒。如果超时，则不会使用相应的副本执行查询

​

parallel_replicas_count

这是一个内部设置，不应直接使用，属于“并行副本”模式的实现细节。对于分布式查询，发起服务器会自动将此设置设为参与查询处理的并行副本数。

​

parallel_replicas_custom_key

一个任意的整数表达式，可用于在特定表的各个副本之间拆分工作。 其值可以是任何整数表达式。

建议优先使用基于主键的简单表达式。

如果该设置用于由单个分片和多个副本组成的集群，这些副本将被转换为虚拟分片。 否则，其行为与 SAMPLE 键相同，即会使用每个分片的多个副本。

​

parallel_replicas_custom_key_range_lower

允许 range 类型的过滤器基于自定义范围 [parallel_replicas_custom_key_range_lower, INT_MAX]，在各副本之间均匀分配工作。

与 parallel_replicas_custom_key_range_upper 结合使用时，该过滤器可针对范围 [parallel_replicas_custom_key_range_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_filter_pushdown

允许将过滤器下推到由并行副本选择执行的那部分查询

​

parallel_replicas_for_cluster_engines

将表函数引擎替换为对应的 -Cluster 版本

​

parallel_replicas_for_non_replicated_merge_tree

如果为 true，ClickHouse 也会对非复制的 MergeTree 表使用并行副本算法

​

parallel_replicas_index_analysis_only_on_coordinator

仅在副本协调器上执行索引分析，跳过其他副本。仅在启用 parallel_replicas_local_pla 时生效

​

parallel_replicas_insert_select_local_pipeline

在启用并行副本的分布式 INSERT SELECT 中使用本地管道

​

parallel_replicas_local_plan

为本地副本构建本地执行计划

​

parallel_replicas_mark_segment_size

parts 会在逻辑上划分为多个分段，以便在并行读取时分配给各个副本。此设置控制这些分段的大小。除非你完全确定自己在做什么，否则不建议更改。值应在 [128; 16384] 范围内

​

parallel_replicas_min_number_of_rows_per_replica

将查询中使用的副本数量限制为 (预估待读取行数 / 每个副本的最小行数) 。最大值仍然受 ‘max_parallel_replicas’ 限制。

​

parallel_replicas_mode

用于并行副本中自定义键的过滤器类型。default - 对自定义键使用取模运算；range - 使用自定义键值类型的所有可能值，对自定义键应用范围过滤器。

​

parallel_replicas_only_with_analyzer

必须启用 analyzer 才能使用并行副本。若未启用 analyzer，即使已启用从副本并行读取，查询执行也会回退到本地执行。不支持在未启用 analyzer 的情况下使用并行副本。

​

parallel_replicas_prefer_local_join

如果为 true，且 JOIN 可使用并行副本算法执行，并且 JOIN 右侧部分的所有存储均为 *MergeTree，则将使用本地 JOIN 而非 GLOBAL JOIN。

​

parallel_replicas_prefer_local_replica

启用时 (默认) ，本地副本始终会包含在用于并行读取的副本集合中。 禁用时，本地副本不会被优先考虑，副本将完全由负载均衡算法选择。 这样一来，带有 max_parallel_replicas = 1 的查询就可以被路由到其他主机；当大量短查询分布在集群中时，这有助于提升缓存局部性。

​

parallel_replicas_support_projection

投影优化可在并行副本中应用。仅在启用 parallel_replicas_local_plan 且 aggregation_in_order 未启用时生效。

​

parallel_view_processing

启用并发推送到已附加视图，而不是按顺序推送。

​

parallelize_output_from_storages

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

​

parsedatetime_e_requires_space_padding

函数 parseDateTime 中的格式说明符 ‘%e’ 要求个位数的日期以空格补齐，例如可接受 ’ 2’，而 ‘2’ 会报错。

​

parsedatetime_parse_without_leading_zeros

函数 parseDateTime 中的格式说明符 %c、%l 和 %k 可解析不带前导零的月份和小时。

​

partial_merge_join_left_table_buffer_bytes

如果不为 0，则会将 partial merge join 左侧表中的块合并成更大的块。每个连接线程最多会使用指定内存的 2 倍。

​

partial_merge_join_rows_in_right_blocks

限制 JOIN 查询中 partial merge join 算法右侧 join 数据块的大小。

ClickHouse server：

1. 将右侧 join 数据拆分为多个块，每个块最多包含指定数量的行。
2. 使用每个块的最小值和最大值为其建立索引。
3. 如果可能，将已准备好的块卸载到磁盘。

可能的值：

• 任意正整数。建议取值范围：[1000, 100000]。

​

partial_result_on_first_cancel

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

​

parts_to_delay_insert

如果目标表在单个分区中至少包含这么多活跃的 parts，则会人为降低向该表 insert 的速度。

​

parts_to_throw_insert

如果目标表中某个分区的活动 parts 数量超过此值，则抛出“parts 过多 …”异常。

​

per_part_index_stats

按分片记录日志索引统计信息

​

poll_interval

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

​

polyglot_dialect

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

​

postgresql_connection_attempt_timeout

单次连接 PostgreSQL 端点的连接超时时间 (以秒为单位) 。 该值会作为连接 URL 的 connect_timeout 参数传递。

​

postgresql_connection_pool_auto_close_connection

在将连接放回连接池之前关闭该连接。

​

postgresql_connection_pool_retries

用于 PostgreSQL 表引擎和数据库引擎的连接池 push/pop 重试次数。

​

postgresql_connection_pool_size

PostgreSQL 表引擎和数据库引擎的连接池大小。

​

postgresql_connection_pool_wait_timeout

PostgreSQL 表引擎和数据库引擎在连接池为空时，执行连接池 push/pop 操作的超时时间。默认情况下，连接池为空时会阻塞等待。

​

postgresql_fault_injection_probability

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

​

predicate_statistics_sample_rate

将谓词选择性统计数据收集到 system.predicate_statistics_log 中。设置为 N > 0 时，约有 1/N 的查询 (按查询 ID) 会被采样。0 表示禁用。

​

prefer_column_name_to_alias

启用或禁用在查询表达式和子句中使用原始列名而非别名。尤其是在别名与列名相同的情况下，这一点非常重要，参见 表达式别名。启用此设置后，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

外部排序时优先使用更大的块字节数，以降低合并过程中的内存使用量。

​

prefer_global_in_and_join

启用将 IN/JOIN 运算符替换为 GLOBAL IN/GLOBAL JOIN。

可能的值：

• 0 — 已禁用。IN/JOIN 运算符不会被替换为 GLOBAL IN/GLOBAL JOIN。
• 1 — 已启用。IN/JOIN 运算符会被替换为 GLOBAL IN/GLOBAL JOIN。

用法

虽然 SET distributed_product_mode=global 可以改变分布式表的查询行为，但它不适用于本地表或来自外部资源的表。这时，prefer_global_in_and_join 设置就派上用场了。

例如，我们有一些提供查询服务的节点，其中包含不适合做分布式处理的本地表。我们需要在分布式处理过程中借助 GLOBAL 关键字即时分散这些表中的数据——即使用 GLOBAL IN/GLOBAL JOIN。

prefer_global_in_and_join 的另一个使用场景是访问由 external engine 创建的表。该设置有助于减少连接这类表时对外部源的调用次数：每个查询只需调用一次。

另请参见：

• 分布式子查询 ，了解如何使用 GLOBAL IN/GLOBAL JOIN 的更多信息

​

prefer_localhost_replica

启用/禁用在处理分布式查询时优先使用 localhost 副本。

可能的值：

• 1 — 如果存在 localhost 副本，ClickHouse 始终会将查询发送到该副本。
• 0 — ClickHouse 使用 load_balancing 设置中指定的负载均衡策略。

如果你在未使用 parallel_replicas_custom_key 的情况下使用了 max_parallel_replicas，请禁用此设置。 如果设置了 parallel_replicas_custom_key，则只有在它用于包含多个分片且每个分片都有多个副本的集群时，才应禁用此设置。 如果它用于仅有一个分片但有多个副本的集群，禁用此设置会带来负面影响。

​

prefer_warmed_unmerged_parts_seconds

仅在 ClickHouse Cloud 中生效。如果某个 merged part 合并完成距今不足这么多秒，且尚未预热 (参见 cache_populated_by_fetch) ，但它的所有 source parts 都可用且已预热，则 SELECT 查询会转而从这些 parts 读取。仅适用于 Replicated-/SharedMergeTree。请注意，这里只会检查 CacheWarmer 是否处理过该 part；如果该 part 是被其他机制拉取到 cache 中的，那么在 CacheWarmer 处理到它之前，仍会被视为冷数据；如果它已经预热，之后又从 cache 中被驱逐，仍会被视为已预热。

​

preferred_block_size_bytes

此设置用于调整查询处理时的数据块大小，是对较为粗略的 max_block_size 设置的进一步微调。如果列较大，并且按 max_block_size 的行数生成的块大小很可能超过指定字节数，则会减小块大小，以提高 CPU 缓存局部性。

​

preferred_max_column_in_block_size_bytes

读取时，块中单列的最大大小限制。有助于减少缓存未命中的次数。应接近 L2 缓存大小。

​

preferred_optimize_projection_name

如果将其设置为非空字符串，ClickHouse 将尝试在查询中应用指定的投影。

可能的值：

• String：首选投影的名称

​

prefetch_buffer_size

从文件系统读取时，预取缓冲区的最大大小。

​

print_pretty_type_names

可在 DESCRIBE 查询和 toTypeName() 函数中，以带缩进的更易读方式输出深层嵌套的类型名称。

示例：

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

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

​

优先级

查询优先级。1 为最高优先级，数值越大优先级越低；0 表示不使用优先级。

​

promql_database

指定 promql 方言使用的数据库名称。空字符串表示当前数据库。

​

promql_evaluation_time

别名: evaluation_time

设置 promql 方言使用的求值时间。auto 表示当前时间。

​

promql_table

指定 promql 方言所使用的 TimeSeries 表名称。

​

push_external_roles_in_interserver_queries

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

​

query_cache_compress_entries

压缩查询缓存中的条目。这样可减少查询缓存的内存占用，但代价是向其中写入 / 从其中读取的速度会变慢。

可能值：

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

​

query_cache_for_subqueries

启用后，子查询结果可写入并从查询缓存中读取。这会将 use_query_cache 传递到所有子查询。

可能的值：

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

​

query_cache_max_entries

当前用户可在 query cache 中存储的查询结果的最大数量。0 表示不受限制。

可能的值：

• 大于或等于 0 的整数。

​

query_cache_max_size_in_bytes

当前用户可在 query cache 中分配的最大内存量 (以字节为单位) 。0 表示不受限制。

可能的值：

• 大于等于 0 的整数。

​

query_cache_min_query_duration

查询的运行耗时至少达到多少毫秒，其结果才会存储到 query cache 中。

可选值：

• 非负整数 >= 0。

​

query_cache_min_query_runs

SELECT 查询的结果在存储到 query cache 之前，至少需要运行的次数。

可能的值：

• 大于等于 0 的整数。

​

query_cache_nondeterministic_function_handling

控制查询缓存如何处理包含 rand() 或 now() 等非确定性函数的 SELECT 查询。

可选值：

• 'throw' - 抛出异常，并且不缓存查询结果。
• 'save' - 缓存查询结果。
• 'ignore' - 不缓存查询结果，也不抛出异常。

​

query_cache_share_between_users

如果开启此设置，缓存在查询缓存中的 SELECT 查询结果可被其他用户读取。 出于安全考虑，不建议启用此设置。

可能的值：

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

​

query_cache_squash_partial_results

将部分结果块合并为大小为 max_block_size 的块。这样会降低写入查询缓存的性能，但能提高缓存条目的可压缩性 (参见 query_cache_compress-entries) 。

可能的值：

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

​

query_cache_system_table_handling

控制 query cache 如何处理针对系统表的 SELECT 查询，即数据库 system.* 和 information_schema.* 中的表。

可能的值：

• 'throw' - 抛出异常，并且不缓存查询结果。
• 'save' - 缓存查询结果。
• 'ignore' - 不缓存查询结果，也不抛出异常。

​

query_cache_tag

一个 String 类型的字符串，用作查询缓存条目的标签。 相同的查询如果标签不同，在查询缓存中会被视为不同的查询。

可能的值：

• 任意字符串

​

query_cache_ttl

经过这么多秒后，查询缓存中的条目将变为过期。

可选值：

• 正整数 >= 0。

​

query_metric_log_interval

按毫秒计，为各个查询收集 query_metric_log 的时间间隔。

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

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

默认值：-1

​

query_plan_aggregation_in_order

控制按序聚合这一查询计划级别优化的开关。 仅在设置 query_plan_enable_optimizations 为 1 时生效。

这是一个专家级设置，仅应供开发人员用于调试。该设置未来可能会以不向后兼容的方式更改，或被移除。

可能的值：

• 0 - 禁用
• 1 - 启用

​

query_plan_convert_any_join_to_semi_or_anti_join

如果 JOIN 后的过滤器对未匹配行或已匹配行的计算结果始终为 false，则允许将 ANY JOIN 转换为 SEMI 或 ANTI JOIN

​

query_plan_convert_join_to_in

如果输出列仅来自左表，则允许将 JOIN 转换为带 IN 的子查询。对于非 ANY JOIN (例如默认的 ALL JOIN) ，这可能导致结果错误。

​

query_plan_convert_outer_join_to_inner_join

如果 JOIN 之后的过滤器始终会过滤掉默认值，则允许将 OUTER JOIN 转换为 INNER JOIN

​

query_plan_direct_read_from_text_index

允许在查询计划中仅使用倒排文本索引进行全文检索过滤。

​

query_plan_display_internal_aliases

显示 EXPLAIN PLAN 中的内部别名 (如 __table1) ，而非原始查询中指定的别名。

​

query_plan_enable_multithreading_after_window_functions

在计算完窗口函数后启用多线程，以支持并行流处理

​

query_plan_enable_optimizations

控制是否在查询计划层启用查询优化。

这是一个专家级设置，仅应由开发人员在调试时使用。该设置未来可能会以不向后兼容的方式发生变化，或被移除。

可能的值：

• 0 - 禁用查询计划层的所有优化
• 1 - 启用查询计划层的优化 (但各项单独优化仍可通过各自的设置禁用)

​

query_plan_execute_functions_after_sorting

控制一项查询计划级别的优化，该优化会将表达式移到排序步骤之后执行。 仅在设置 query_plan_enable_optimizations 为 1 时生效。

这是一个专家级设置，仅供开发人员在调试时使用。该设置未来可能会以不向后兼容的方式发生变化，或被移除。

可能的值：

• 0 - 禁用
• 1 - 启用

​

query_plan_filter_push_down

控制是否启用一种查询计划级别的优化，该优化会将过滤器下推到执行计划的更下层。 仅当设置 query_plan_enable_optimizations 为 1 时才生效。

这是一个专家级设置，仅应由开发人员用于调试。该设置今后可能会以不向后兼容的方式发生变化，或被移除。

可能的值：

• 0 - 禁用
• 1 - 启用

​

query_plan_join_shard_by_pk_ranges

如果两个表的连接键都包含 PRIMARY KEY 的前缀，则对 JOIN 进行分片。支持 hash、parallel_hash 和 full_sorting_merge 算法。通常不会提升查询速度，但可能会降低内存消耗。

​

query_plan_join_swap_table

确定在查询计划中，join 的哪一侧应作为构建表 (也称为 inner，即在 hash join 中插入哈希表的一侧) 。此设置仅支持 ALL join strictness 和 JOIN ON clause。可能的值为：

• ‘auto’：由 planner 决定使用哪张表作为构建表。
  • ‘false’：从不交换表 (右表为构建表) 。
  • ‘true’：始终交换表 (左表为构建表) 。

​

query_plan_lift_up_array_join

控制一项查询计划级别的优化，该优化会将 ARRAY JOIN 在执行计划中上提。 仅当设置 query_plan_enable_optimizations 为 1 时才会生效。

这是一个专家级设置，仅应供开发人员用于调试。该设置未来可能会发生不向后兼容的变更，也可能被移除。

可能的值：

• 0 - 禁用
• 1 - 启用

​

query_plan_lift_up_union

切换一项查询计划级别的优化。该优化会将查询计划中更大的子树提升到 union 中，以便进行进一步优化。 仅在设置 query_plan_enable_optimizations 为 1 时生效。

这是一个专家级设置，仅供开发人员在调试时使用。该设置未来可能会以不向后兼容的方式发生变更，或被移除。

可能的值：

• 0 - 禁用
• 1 - 启用

​

query_plan_max_limit_for_lazy_materialization

控制可使用查询计划进行延迟物化优化的最大阈值。为零表示不受限制。

​

query_plan_max_limit_for_top_k_optimization

控制借助 minmax 跳过索引和动态阈值过滤评估 TopK 优化查询计划时允许的最大 limit 值。如果为 0，则不受限制。

​

query_plan_max_optimizations_to_apply

限制可应用于查询计划的优化总次数，参见设置 query_plan_enable_optimizations。 这有助于避免复杂查询的优化耗时过长。 在 EXPLAIN PLAN 查询中，达到此限制后会停止应用优化，并按原样返回查询计划。 对于常规查询执行，如果实际优化次数超过此设置，则会抛出异常。

这是一个专家级设置，仅应由开发人员在调试时使用。该设置将来可能会以不向后兼容的方式发生变更，或者被移除。

​

query_plan_max_step_description_length

EXPLAIN PLAN 中步骤说明的最大长度。

​

query_plan_merge_expressions

切换一项查询计划级别的优化，该优化会合并连续的过滤器。 仅在设置 query_plan_enable_optimizations 为 1 时生效。

这是一个专家级设置，仅应供开发人员在调试时使用。该设置未来可能会以不向后兼容的方式更改，或被移除。

可能的值：

• 0 - 禁用
• 1 - 启用

​

query_plan_merge_filter_into_join_condition

允许将过滤器合并到 JOIN 条件中，并将 CROSS JOIN 转换为 INNER。

​

query_plan_merge_filters

支持在查询计划中合并过滤器。

​

query_plan_optimize_join_order_algorithm

指定在查询计划优化期间要尝试哪些 JOIN 顺序算法。可用算法如下：

• ‘greedy’ - 基础贪心算法 - 速度快，但不一定能生成最佳的 JOIN 顺序
• ‘dpsize’ - 实现了 DPsize 算法，目前仅适用于 Inner JOIN - 会考虑所有可能的 JOIN 顺序，并找出最优方案，但对于包含大量表和 JOIN 谓词的查询，速度可能较慢。 可以指定多个算法，例如 ‘dpsize,greedy’。

​

query_plan_optimize_join_order_limit

优化同一子查询内 JOIN 的顺序。目前仅支持非常有限的场景。 值表示要优化的表的最大数量。

​

query_plan_optimize_join_order_randomize

当该值为非零时，JOIN 顺序优化器会使用随机生成的基数和 NDV，而不使用真实统计信息。 当设置为 1 时，会生成一个随机种子；当设置为大于 1 的值时，则直接将该值用作种子。 此设置用于测试，以发现由不同 JOIN 顺序引发的错误。

​

query_plan_optimize_lazy_final

通过构建一组主键并将其用于索引分析，优化从 ReplacingMergeTree 使用 FINAL 的读取。

​

query_plan_optimize_lazy_materialization

使用查询计划进行惰性物化优化。

​

query_plan_optimize_prewhere

允许将过滤器下推到受支持存储的 PREWHERE 表达式中

​

query_plan_push_down_limit

控制一项查询计划级别的优化，该优化会将 LIMIT 下推到执行计划的更底层。 仅在设置 query_plan_enable_optimizations 为 1 时生效。

这是一个专家级设置，仅供开发人员在调试时使用。该设置未来可能会发生不向后兼容的变更，或被移除。

可能的值：

• 0 - 禁用
• 1 - 启用

​

query_plan_read_in_order

用于切换按序读取这一查询计划级别的优化。 仅在设置 query_plan_enable_optimizations 为 1 时生效。

这是一个专家级设置，仅应由开发者在调试时使用。该设置未来可能会以不向后兼容的方式变更，或被移除。

可能的值：

• 0 - 禁用
• 1 - 启用

​

query_plan_read_in_order_through_join

在 JOIN 操作中继续按顺序从左侧表读取，以便后续步骤加以利用。

​

query_plan_remove_redundant_distinct

用于启用或禁用一项查询计划级别的优化，该优化会移除冗余的 DISTINCT 步骤。 仅在设置 query_plan_enable_optimizations 为 1 时生效。

这是一个专家级设置，仅应由开发人员在调试时使用。该设置未来可能会以不向后兼容的方式变更，或被移除。

可能的值：

• 0 - 禁用
• 1 - 启用

​

query_plan_remove_redundant_sorting

控制一项查询计划级别的优化，用于移除冗余的排序步骤，例如子查询中的排序步骤。 仅在设置 query_plan_enable_optimizations 为 1 时生效。

这是一个专家级设置，仅供开发者用于调试。该设置未来可能会以不向后兼容的方式更改，或被移除。

可能的值：

• 0 - 禁用
• 1 - 启用

​

query_plan_remove_unused_columns

用于启用或禁用一项查询计划级别的优化，该优化会尝试从查询计划的各个步骤中移除未使用的列 (包括输入列和输出列) 。 仅在设置 query_plan_enable_optimizations 为 1 时生效。

这是一个专家级设置，仅应由开发人员用于调试。该设置未来可能会以不向后兼容的方式发生变化，或被移除。

可能的值：

• 0 - 禁用
• 1 - 启用

​

query_plan_reuse_storage_ordering_for_window_functions

别名：optimize_read_in_window_order

控制是否启用一项查询计划级别的优化：在为窗口函数进行排序时复用存储排序顺序。 仅在设置 query_plan_enable_optimizations 为 1 时生效。

这是一个专家级设置，仅供开发人员在调试时使用。该设置未来可能会以不向后兼容的方式变更，或被移除。

可能的值：

• 0 - 禁用
• 1 - 启用

​

query_plan_split_filter

这是一个专家级设置，仅应供开发人员在调试时使用。该设置未来可能会以不向后兼容的方式变更，或被移除。

控制一项查询计划级别的优化，该优化会将过滤器拆分为表达式。 仅在设置 query_plan_enable_optimizations 为 1 时生效。

可能的值：

• 0 - 禁用
• 1 - 启用

​

query_plan_text_index_add_hint

允许为查询计划中基于倒排文本索引构建的过滤器添加提示 (附加谓词) 。

​

query_plan_top_k_through_join

用于切换一项查询计划级别的优化：当排序键仅引用连接 (LEFT/RIGHT) 中保留侧的列时，将 ORDER BY ... LIMIT n 下推到连接之前。这会限制保留侧输入在执行连接前需要产生的行数。 仅当设置 query_plan_enable_optimizations 为 1 时才生效。

可能的值：

• 0 - 禁用
• 1 - 启用

​

query_plan_try_use_vector_search

控制是否启用一项会尝试使用向量相似度索引的查询计划级别的优化。 仅当设置 query_plan_enable_optimizations 为 1 时，此设置才会生效。

这是一个专家级设置，仅应供开发人员用于调试。该设置未来可能会发生不向后兼容的变更，或被移除。

可能的值：

• 0 - 禁用
• 1 - 启用

​

query_profiler_cpu_time_period_ns

设置 查询分析器 的 CPU 时钟计时器周期。此计时器仅统计 CPU 时间。

可能的值：

• 以纳秒为单位的正整数。

  推荐值：

  • 对于单个查询，建议设为 10000000 (每秒 100 次) 纳秒或更大。
  • 对于集群级性能分析，建议设为 1000000000 (每秒一次) 。

• 0 表示关闭计时器。

另请参见：

• 系统表 trace_log

​

query_profiler_real_time_period_ns

设置 查询分析器 的实时时钟计时器周期。实时时钟计时器统计挂钟时间。

可选值：

• 以纳秒为单位的正整数。

  推荐值：

  • 对于单个查询，10000000 (每秒 100 次) 纳秒及更低的值。
  • 对于集群级性能分析，1000000000 (每秒一次) 。

• 0 表示关闭计时器。

另请参阅：

• 系统表 trace_log

Cloud 默认值：3000000000。

​

queue_max_wait_ms

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

​

rabbitmq_max_wait_ms

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

​

read_backoff_max_throughput

用于在读取速度较慢时减少线程数的设置。当读取吞吐量低于该字节/秒阈值时，开始对事件进行计数。

​

read_backoff_min_concurrency

用于在读取速度较慢时尽量保持最小线程数的设置。

​

read_backoff_min_events

用于在读取速度较慢时减少线程数的设置。达到该事件次数后，线程数将减少。

​

read_backoff_min_interval_between_events_ms

在读取较慢时，用于减少线程数量的设置。如果距离上一个事件发生还不到某个时间间隔，则忽略该事件。

​

read_backoff_min_latency_ms

用于在读取速度较慢时减少线程数的设置。仅考虑耗时至少达到该时长的读取操作。

​

read_from_distributed_cache_if_exists_otherwise_bypass_cache

仅在 ClickHouse Cloud 中生效。与 read_from_filesystem_cache_if_exists_otherwise_bypass_cache 相同，但适用于分布式缓存。

​

read_from_filesystem_cache_if_exists_otherwise_bypass_cache

允许以被动模式使用文件系统缓存：利用现有的缓存条目，但不再向缓存中添加更多条目。如果对此设置为高负载的临时查询启用，而对短时实时查询保持禁用，则有助于避免重负载查询造成缓存抖动，并提高系统整体效率。

​

read_from_page_cache_if_exists_otherwise_bypass_cache

以被动模式使用用户态页缓存，类似于 read_from_filesystem_cache_if_exists_otherwise_bypass_cache。

​

read_in_order_two_level_merge_threshold

按主键顺序进行多线程读取时，执行 preliminary merge 步骤所需读取的最少 parts 数。

​

read_in_order_use_buffering

按主键顺序读取时，在合并前启用缓冲。它会提高查询执行的并行度

​

read_in_order_use_virtual_row

在按主键或其单调函数顺序读取时使用虚拟行。在跨多个 parts 搜索时，这很有用，因为只会访问相关的 parts。

​

read_in_order_use_virtual_row_per_block

当与 read_in_order_use_virtual_row 一起启用时，在读取完每个块后都会发出一个虚拟行 (而不只是每个 part 的开头) 。 这使 MergingSortedTransform 能够更频繁地重新调整数据源的优先级，这在下游过滤器丢弃了大量行，且数据在各个 part 之间分布不均时尤其有用。 请注意，这会禁用读取时的 read_in_order_use_buffering 优化和预合并 (read_in_order_two_level_merge_threshold) 。

​

read_overflow_mode

超出限制时的处理方式。

​

read_overflow_mode_leaf

设置当读取的数据量超过某个 leaf 限制之一时的处理方式。

可选项：

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

​

read_priority

从本地文件系统或远程文件系统读取数据时的优先级。仅支持本地文件系统的 ‘pread_threadpool’ method 和远程文件系统的 threadpool method。

​

read_through_distributed_cache

仅在 ClickHouse Cloud 中生效。允许从分布式缓存中读取

​

readonly

0 - 无只读限制。1 - 仅允许读取请求，以及修改显式允许的设置。2 - 仅允许读取请求，以及修改设置，但 readonly 设置除外。

​

receive_data_timeout_ms

接收首个数据包或来自副本的正进度数据包时的连接超时时间

​

receive_timeout

从网络接收数据的超时时间，单位为秒。如果在此时间间隔内未接收到任何字节，则会抛出异常。如果在客户端设置此项，套接字的 send_timeout 也会在服务器端对应连接的另一端设置。

​

recursive_cte_max_steps_in_type_inference

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

​

regexp_dict_allow_hyperscan

允许 regexp_tree 字典使用 Hyperscan 库。

​

regexp_dict_flag_case_insensitive

对 regexp_tree 字典启用不区分大小写的匹配。可在单个表达式中使用 (?i) 和 (?-i) 进行覆盖。

​

regexp_dict_flag_dotall

允许在 regexp_tree 字典中，. 匹配换行符。

​

regexp_max_matches_per_row

设置每行中单个 regular expression 的最大匹配次数。使用 extractAllGroupsHorizontal 函数中的贪婪 regular expression 时，可用此设置防止内存过载。

Possible values:

• 正整数。

​

reject_expensive_hyperscan_regexps

拒绝那些使用 hyperscan 评估时可能代价较高的模式 (由于 NFA 状态爆炸)

​

remerge_sort_lowered_memory_bytes_ratio

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

​

remote_filesystem_read_method

用于从远程文件系统读取数据的方法，可选值为：read、threadpool。

​

remote_filesystem_read_prefetch

从远程文件系统读取数据时，是否使用预取。

​

remote_fs_read_backoff_max_tries

采用退避机制读取时的最大重试次数

​

remote_fs_read_max_backoff_ms

从远程磁盘读取数据时的最长退避等待时间

​

remote_read_min_bytes_for_seek

远程读取 (url、S3) 时，执行寻道而不是带忽略的读取所需的最小字节数。

​

rename_files_after_processing

• 类型： String

• 默认值： 空字符串

此设置允许为由 file 表函数处理的文件指定重命名模式。设置此选项后，file 表函数读取的所有文件都会按包含占位符的指定模式重命名，但仅在文件处理成功时才会执行重命名。

​

占位符

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

​

示例

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

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

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

​

replace_running_query

使用 HTTP 接口时，可以传入 query_id 参数。它可以是任意字符串，用作查询标识符。 如果此时同一用户已存在具有相同 query_id 的查询，则其行为取决于 replace_running_query 参数。

0 (默认) – 抛出异常 (如果具有相同 query_id 的查询已在运行，则不允许该查询运行) 。

1 – 取消旧查询并开始运行新查询。

将此参数设置为 1，可用于实现分段条件建议功能。输入下一个字符后，如果旧查询尚未完成，则应将其取消。

​

replace_running_query_max_wait_ms

启用 replace_running_query 设置时，等待具有相同 query_id 的正在运行中的查询结束的时间。

可能的值：

• 正整数。
• 0 — 抛出异常；如果服务器已在执行具有相同 query_id 的查询，则不允许运行新的查询。

​

replication_wait_for_inactive_replica_timeout

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

可能的值：

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

​

restore_replace_external_dictionary_source_to_null

恢复时将外部字典源替换为 Null。适用于测试用途

​

restore_replace_external_engines_to_null

用于测试。将所有 external engine 替换为 Null，以避免发起外部连接。

​

restore_replace_external_table_functions_to_null

用于测试。将所有外部表函数替换为 Null，以防止发起外部连接。

​

restore_replicated_merge_tree_to_shared_merge_tree

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

Cloud 默认值：1。

​

result_overflow_mode

Cloud 默认值：throw

设置当结果量超过某一限制时应如何处理。

可能的值：

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

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

示例

Query

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

SELECT *
FROM numbers_mt(100000)
FORMAT Null;

Result

6666 rows in set. ...

​

rewrite_count_distinct_if_with_count_distinct_implementation

允许使用 count_distinct_implementation 设置来改写 countDistcintIf。

可能的值：

• true — 允许。
• false — 不允许。

​

rewrite_in_to_join

将类似 x IN subquery 的表达式重写为 JOIN。这可能有助于通过 JOIN 重排序优化整个查询。

​

rows_before_aggregation

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

​

s3_allow_multipart_copy

允许在 S3 中进行分片复制。

​

s3_allow_parallel_part_upload

使用多个线程执行 S3 分段上传。这可能会使内存占用略有增加

​

s3_check_objects_after_upload

对每个上传到 S3 的对象发起 head 请求，以确认上传是否成功

​

s3_connect_timeout_ms

S3 磁盘中主机的连接超时时间。

​

s3_create_new_file_on_insert

启用或禁用在 S3 引擎表中每次 insert 时创建新文件。如果启用，每次 insert 都会使用该键创建一个新的 S3 对象，模式类似如下：

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

可能的值：

• 0 — INSERT 查询会创建一个新文件；如果文件已存在且未设置 s3_truncate_on_insert，则会失败。
• 1 — 如果未设置 s3_truncate_on_insert，则 INSERT 查询会在每次 insert 时使用后缀 (从第二个文件开始) 创建一个新文件。

更多详情请参见此处。

​

s3_disable_checksum

向 S3 发送文件时不计算校验和。这样可避免对文件进行额外的处理，从而加快写入速度。通常来说，这样做基本是安全的，因为 MergeTree 表的数据本身就会由 ClickHouse 计算校验和；此外，通过 HTTPS 访问 S3 时，TLS 层也已经在网络传输过程中提供了完整性保护。不过，在 S3 上额外计算校验和仍然可以提供纵深防御。

​

s3_ignore_file_doesnt_exist

读取某些键时，如果文件不存在，则忽略该文件缺失。

可能的值：

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

​

s3_list_object_keys_size

ListObject 请求单个批次中可返回的最大文件数

​

s3_max_connections

每台服务器的最大连接数。

​

s3_max_get_burst

在达到每秒请求数限制之前，可同时发起的最大请求数。默认值 (0) 等于 s3_max_get_rps

​

s3_max_get_rps

在开始限流前，S3 GET 请求的每秒速率上限。0 表示不受限制。

​

s3_max_inflight_parts_for_one_file

分段上传请求中可同时上传的最大分片数。0 表示不受限制。

​

s3_max_part_number

S3 上传分片允许的最大分片编号。

​

s3_max_put_burst

在达到每秒请求数限制前，可同时发出的最大请求数。默认值为 (0) ，等同于 s3_max_put_rps

​

s3_max_put_rps

在触发限流之前，对 S3 PUT 请求的每秒速率进行限制。0 表示无限制。

​

s3_max_single_operation_copy_size

S3 中单次复制操作的最大大小。仅当 s3_allow_multipart_copy 为 true 时，此设置才会生效。

​

s3_max_single_part_upload_size

使用单分片方式上传到 S3 时，对象的最大上传大小。

​

s3_max_single_read_retries

单次 S3 读取的最大重试次数。

​

s3_max_unexpected_write_error_retries

在 S3 写入过程中发生意外错误时的最大重试次数。

​

s3_max_upload_part_size

向 S3 进行分段上传时，单个分段的最大大小。

​

s3_min_upload_part_size

向 S3 执行分段上传时，每个分片的最小大小。

​

s3_path_filter_limit

可从查询过滤器中提取并用于文件遍历、替代 glob 列表的 _path 值的最大数量。 0 表示禁用。

​

s3_request_timeout_ms

向 S3 发送和从 S3 接收数据时的空闲超时时间。如果单次 TCP 读取或写入调用阻塞时间达到这么久，则会失败。

​

s3_skip_empty_files

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

可能的值：

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

​

s3_slow_all_threads_after_network_error

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

​

s3_strict_upload_part_size

向 S3 进行分段上传时，单个上传分段的精确大小 (某些实现不支持大小可变的分片) 。

​

s3_throw_on_zero_files_match

当 ListObjects 请求未匹配到任何文件时，抛出错误

​

s3_truncate_on_insert

启用或禁用在 S3 引擎表中执行 insert 前先截断内容。如果禁用，当 S3 对象已存在时，尝试 insert 会抛出异常。

可能的值：

• 0 — INSERT 查询会创建新文件；如果文件已存在且未设置 s3_create_new_file_on_insert，则会失败。
• 1 — INSERT 查询会用新数据替换文件中的现有内容。

更多详情请参见此处。

​

s3_upload_part_size_multiply_factor

当单次写入到 S3 上传的 parts 数达到 s3_multiply_parts_count_threshold 时，就将 s3_min_upload_part_size 乘以该因子。

​

s3_upload_part_size_multiply_parts_count_threshold

每当上传到 S3 的分片数量达到这个值时，s3_min_upload_part_size 就会乘以 s3_upload_part_size_multiply_factor。

​

s3_uri_style

强制指定 S3 端点样式。可选值：auto、virtual_hosted、path。

​

s3_use_adaptive_timeouts

设置为 true 时，所有 S3 请求的前两次尝试都会使用较短的发送和接收超时时间。 设置为 false 时，所有尝试都会使用相同的超时时间。

​

s3_validate_request_settings

启用 S3 请求设置校验。 可能的值：

• 1 — 校验设置。
• 0 — 不校验设置。

​

s3queue_default_zookeeper_path

S3Queue 引擎的默认 ZooKeeper 路径前缀

​

s3queue_enable_logging_to_s3queue_log

启用向 system.s3queue_log 写入日志。该值可通过表设置针对各个表进行覆盖

​

s3queue_keeper_fault_injection_probability

S3Queue 的 Keeper 故障注入概率。

​

s3queue_migrate_old_metadata_to_buckets

将 S3Queue 表的旧元数据结构迁移到新结构

​

schema_inference_cache_require_modification_time_for_url

对带有最后修改时间校验的 URL 使用缓存中的 schema (适用于带有 Last-Modified 请求头的 URL)

​

schema_inference_use_cache_for_azure

使用 Azure 表函数时，在 schema 推断期间使用缓存

​

schema_inference_use_cache_for_file

使用 file 表函数时，在 schema 推断过程中使用缓存

​

schema_inference_use_cache_for_hdfs

在使用 hdfs 表函数时，在 schema 推断过程中使用缓存

​

schema_inference_use_cache_for_s3

使用 S3 表函数时，在 schema 推断过程中使用缓存

​

schema_inference_use_cache_for_url

使用 url 表 functio 进行 schema 推断时使用缓存

​

secondary_indices_enable_bulk_filtering

启用索引的批量过滤算法。按预期，它应当始终表现更好；不过，为了兼容性和便于控制，我们仍保留了此设置。

​

select_sequential_consistency

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

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

可能的值：

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

用法

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

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

另请参见：

• insert_quorum
• insert_quorum_timeout
• insert_quorum_parallel

​

send_logs_level

将服务器文本日志中不低于指定级别的日志发送给客户端。有效值：‘trace’、‘debug’、‘information’、‘warning’、‘error’、‘fatal’、‘none’

​

send_logs_source_regexp

使用指定的正则表达式匹配日志源名称，并发送服务器文本日志。留空表示所有来源。

​

send_profile_events

启用或禁用向客户端发送 ProfileEvents 数据包的功能。

对于不需要 profile events 的客户端，可以禁用此设置以减少网络流量。

可选值：

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

​

send_progress_in_http_headers

在 clickhouse-server 的响应中启用或禁用 X-ClickHouse-Progress HTTP 响应头。

如需了解更多信息，请参阅 HTTP interface 说明。

可能的值：

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

​

send_table_structure_on_insert_with_inline_data

如果禁用此设置，且 INSERT 查询包含内联数据，服务器将不会通过原生协议向客户端返回表结构和列默认值。相反，服务器会自行解析内联数据。这可以提升通过原生协议执行大量小型插入操作时的性能。

​

send_timeout

发送数据到网络的超时时间，单位为秒。如果客户端需要发送数据，但在此时间间隔内无法发送任何字节，则会抛出异常。如果你在客户端设置了此项，那么服务器端对应连接上的套接字 receive_timeout 也会一并设置。

​

serialize_query_plan

对分布式处理的查询计划进行序列化

​

serialize_string_in_memory_with_zero_byte

在聚合期间序列化 String 值时，在末尾附加一个零字节。启用此设置可在查询版本不兼容的集群时保持兼容性。

​

session_timezone

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

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

可能的值：

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

示例：

SELECT timeZone(), serverTimeZone() FORMAT CSV

"Europe/Berlin","Europe/Berlin"

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

"Asia/Novosibirsk","Europe/Berlin"

将会话时区 ‘America/Denver’ 应用于未显式指定时区的内部 DateTime：

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

1999-12-13 07:23:23.123

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

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

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

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

这是由于采用了不同的解析管道：

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

另请参见

• timezone

​

set_overflow_mode

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

可能的值：

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

​

shared_merge_tree_sequential_consistency_initial_parts_update_backoff_ms

使用 select_sequential_consistency 和 SharedMergeTree 时，parts 更新的初始退避时间 (毫秒) 。仅在 ClickHouse Cloud 中可用。

​

shared_merge_tree_sequential_consistency_max_parts_update_backoff_ms

在将 select_sequential_consistency 与 SharedMergeTree 配合使用时，parts 更新的最大退避时间 (毫秒) 。仅在 ClickHouse Cloud 中可用。

​

shared_merge_tree_sequential_consistency_parts_update_max_retries

在将 select_sequential_consistency 与 SharedMergeTree 一起使用时，parts 更新的最大重试次数。仅在 ClickHouse Cloud 中可用。

​

shared_merge_tree_sync_parts_on_partition_operations

在 SMT 表中执行 MOVE|REPLACE|ATTACH 分区操作后，自动同步一组数据分区片段。仅限 Cloud

​

short_circuit_function_evaluation

允许按照短路求值方式计算 if、multiIf、and 和 or 函数。这有助于优化这些函数中复杂表达式的执行，并防止可能出现的异常 (例如在不应发生时出现除零) 。

可能的值：

• enable — 为适合使用短路求值的函数启用短路函数求值 (即可能抛出异常或计算开销较大的函数) 。
• force_enable — 为所有函数启用短路函数求值。
• disable — 禁用短路函数求值。

​

short_circuit_function_evaluation_for_nulls

用于优化这类函数的求值：只要任一参数为 NULL，函数就会返回 NULL。当函数参数中的 NULL 值占比超过 short_circuit_function_evaluation_for_nulls_threshold 时，系统将跳过对该函数的逐行求值，而是直接为所有行返回 NULL，从而避免不必要的计算。

​

short_circuit_function_evaluation_for_nulls_threshold

NULL 值占比的阈值。对于具有 Nullable 参数的函数，仅在所有参数值都非 NULL 的行上执行。仅在启用设置 short_circuit_function_evaluation_for_nulls 时适用。 当包含 NULL 值的行数占总行数的比例超过此阈值时，这些包含 NULL 值的行将不会被计算。

​

show_data_lake_catalogs_in_system_tables

启用在系统表中显示数据湖目录。

​

show_processlist_include_internal

在 SHOW PROCESSLIST 查询输出中显示内部辅助进程。

内部进程包括字典重新加载、可刷新materialized view 重新加载、在 SHOW ... 查询中执行的辅助 SELECT、为处理损坏表而在内部执行的辅助 CREATE DATABASE ... 查询等。

​

show_table_uuid_in_table_create_query_if_not_nil

设置 SHOW TABLE 查询的显示内容。

可选值：

• 0 — 查询显示时不包含表 UUID。
• 1 — 查询显示时包含表 UUID。

​

single_join_prefer_left_table

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

​

skip_redundant_aliases_in_udf

为简化使用，用户自定义函数中不会使用 (替换) 冗余别名。

可能的值：

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

示例

启用与禁用的区别：

查询：

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

EXPLAIN SYNTAX SELECT test_03274(4 + 2);

结果：

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

查询：

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

EXPLAIN SYNTAX SELECT test_03274(4 + 2);

结果：

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

​

skip_unavailable_shards

启用或禁用静默跳过不可用分片。

如果某个分片的所有副本都不可用，则认为该分片不可用。副本在以下情况下会被视为不可用：

• ClickHouse 因任何原因无法连接到副本。

  连接副本时，ClickHouse 会进行多次尝试。如果这些尝试全部失败，则该副本会被视为不可用。

• 无法通过 DNS 解析副本主机名。

  如果无法通过 DNS 解析副本的主机名，可能意味着以下情况：

  • 副本所在主机没有 DNS 记录。这可能发生在使用动态 DNS 的系统中，例如 Kubernetes。在这类系统中，节点在停机期间可能无法解析，这并不属于错误。

  • 配置错误。ClickHouse 配置文件中包含错误的主机名。

可能的值：

• 1 — 启用跳过。

  如果某个分片不可用，ClickHouse 会基于部分数据返回结果，并且不会报告节点可用性问题。

• 0 — 禁用跳过。

  如果某个分片不可用，ClickHouse 会抛出异常。

​

sleep_after_receiving_query_ms

在 TCPHandler 中接收到查询后睡眠的时间

​

sleep_in_send_data_ms

TCPHandler 发送数据时的休眠时间

​

sleep_in_send_tables_status_ms

TCPHandler 发送表状态响应前的休眠时间

​

sort_overflow_mode

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

可能的值：

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

​

split_intersecting_parts_ranges_into_layers_final

在 FINAL 优化期间按层拆分相交的 parts 范围

​

split_parts_ranges_into_intersecting_and_non_intersecting_final

在 FINAL 优化期间将 parts 的范围拆分为相交部分和不相交部分

​

splitby_max_substrings_includes_remaining_string

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

可能的值：

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

​

stop_refreshable_materialized_views_on_startup

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

​

storage_file_read_method

从存储文件读取数据的方法，可选值包括：read、pread、mmap。mmap 方法不适用于 clickhouse-server (其适用对象是 clickhouse-local) 。

​

storage_system_stack_trace_pipe_read_timeout_ms

查询 system.stack_trace 表时，为接收来自线程的信息而从管道读取的最长等待时间。此设置仅用于测试，不建议用户更改。

​

stream_flush_interval_ms

适用于启用流式处理的表：在发生超时，或某个线程生成了 max_insert_block_size 行时生效。

默认值为 7500。

该值越小，数据刷写到表中的频率就越高。将该值设置得过低会导致性能下降。

​

stream_like_engine_allow_direct_select

允许直接对 Kafka、RabbitMQ、FileLog、Redis Streams、S3Queue、AzureQueue 和 NATS 引擎执行 SELECT 查询。如果存在已附加的 materialized view，即使启用此设置，也不允许执行 SELECT 查询。 如果不存在已附加的 materialized view，启用此设置后即可读取数据。请注意，读取的数据通常会从队列中移除。为避免移除已读取的数据，应正确配置相关引擎设置。

​

stream_like_engine_insert_queue

当流式引擎从多个队列中读取时，用户在写入数据时需要选择要插入的队列。Redis Streams 和 NATS 会用到此设置。

​

stream_poll_timeout_ms

从流式存储拉取数据/向其发送数据时的轮询超时时间。

​

system_events_show_zero_values

允许从 system.events 中选择值为 0 的事件。

某些监控系统要求在每个检查点都传递所有指标值，即使某个指标值为 0 也是如此。

可能的值：

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

示例

查询

SELECT * FROM system.events WHERE event='QueryMemoryLimitExceeded';

结果

Ok.

查询

SET system_events_show_zero_values = 1;
SELECT * FROM system.events WHERE event='QueryMemoryLimitExceeded';

结果

┌─event────────────────────┬─value─┬─description───────────────────────────────────────────┐
│ QueryMemoryLimitExceeded │     0 │ Number of times when memory limit exceeded for query. │
└──────────────────────────┴───────┴───────────────────────────────────────────────────────┘

​

system_metric_log_show_zero_values_in_histograms

控制是否将零值直方图数据写入 system.metric_log 的 histograms 嵌套列。

默认情况下，总观测 count 为 0 的直方图会被跳过；而在每个已输出的直方图中，没有任何观测的桶条目也会从 histogram map 中省略。启用此设置后，无论 count 如何，都会写入每个直方图和每个桶——这对于要求每个指标在每个检查点都出现的监控系统很有用。

可能的值：

• 0 — 已禁用。count = 0 的直方图不会输出；已输出的直方图仅包含至少有一次观测的桶。
• 1 — 已启用。所有直方图都会被写入，且每个桶边界都会出现在 histogram 中。

​

table_engine_read_through_distributed_cache

仅在 ClickHouse Cloud 中生效。允许通过表引擎 / 表函数 (s3、azure 等) 从分布式缓存中读取数据

​

table_function_remote_max_addresses

设置根据模式为 remote 函数生成的地址最大数量。

可能的值：

• 正整数。

​

tcp_keep_alive_timeout

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

​

temporary_data_in_cache_reserve_space_wait_lock_timeout_milliseconds

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

​

temporary_files_buffer_size

用于写入临时 File 的缓冲区大小。缓冲区越大，系统调用越少，但内存消耗也越高。

​

temporary_files_codec

设置在磁盘上执行排序和连接操作时所用临时 File 的压缩编解码器。

可能的值：

• LZ4 — 使用 LZ4 压缩。
• NONE — 不使用压缩。

​

text_index_hint_max_selectivity

使用基于倒排文本索引构建的提示时，过滤器允许的最大选择性。

​

text_index_like_max_postings_to_read

启用通过 dictionary scan 执行 text index LIKE 评估时，可读取的大型 postings 的最大数量。

需要启用 use_text_index_like_evaluation_by_dictionary_scan。

​

text_index_like_min_pattern_length

在 LIKE/ILIKE 模式中，若要使用通过 dictionary scan 进行的文本索引 LIKE 求值，字母数字 needle 必须达到的最小长度。 短于此阈值的模式会匹配过多的字典标记，因此会被跳过，以避免高成本扫描。

要求启用 use_text_index_like_evaluation_by_dictionary_scan。

​

throw_if_no_data_to_insert

允许或禁止空 INSERT，默认启用 (空插入时会报错) 。仅适用于通过 clickhouse-client 或 gRPC 接口 执行的 INSERT。

​

throw_on_error_from_cache_on_write_operations

在对写入操作 (INSERT、合并) 进行缓存时，忽略缓存错误

​

throw_on_max_partitions_per_insert_block

用于控制达到 max_partitions_per_insert_block 时的行为。

可能的值：

• true - 当插入块达到 max_partitions_per_insert_block 时，会抛出异常。
• false - 当达到 max_partitions_per_insert_block 时，会记录一条警告日志。

如果你想了解修改 max_partitions_per_insert_block 会对用户产生什么影响，此设置会很有帮助。

​

throw_on_unsupported_query_inside_transaction

如果在事务内使用了不受支持的查询，则会抛出异常

​

timeout_before_checking_execution_speed

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

​

timeout_overflow_mode

设置当查询运行时间超过 max_execution_time，或预计运行时间超过 max_estimated_execution_time 时的处理方式。

可选值：

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

​

timeout_overflow_mode_leaf

设置叶子节点上的查询运行时间超过 max_execution_time_leaf 时的行为。

可能的值：

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

​

totals_auto_threshold

totals_mode = 'auto' 的阈值。 参见“WITH TOTALS 修饰符”一节。

​

totals_mode

指定在存在 HAVING 时，以及在设置了 max_rows_to_group_by 且 group_by_overflow_mode = ‘any’ 时，如何计算 TOTALS。 请参见“WITH TOTALS 修饰符”一节。

​

trace_profile_events

启用或禁用以下功能：每次更新 profile events 时，收集 stacktraces，并连同 profile event 的名称和增量值一起发送到 trace_log。

可能的值：

• 1 — 启用 profile events 追踪。
• 0 — 禁用 profile events 追踪。

​

trace_profile_events_list

启用设置 trace_profile_events 后，会将被追踪的事件限制为指定的逗号分隔名称列表。 如果 trace_profile_events_list 为空字符串 (默认值) ，则会追踪所有 profile events。

示例值：‘DiskS3ReadMicroseconds,DiskS3ReadRequestsCount,SelectQueryTimeMicroseconds,ReadBufferFromS3Bytes’

使用此设置可以在查询量很大时更精确地收集数据，因为否则大量事件可能会撑爆内部系统日志队列，导致其中一部分事件被丢弃。

​

transfer_overflow_mode

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

可能的值：

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

​

transform_null_in

启用 IN 运算符中 NULL 值的相等比较。

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

可能的值：

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

示例

假设有一张 null_in 表：

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

查询：

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

结果：

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

查询：

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

结果：

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

另请参阅

• IN 运算符中的 NULL 处理

​

traverse_shadow_remote_data_paths

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

​

union_default_mode

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

可能的值：

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

示例请参见 UNION。

​

unknown_packet_in_send_data

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

​

update_parallel_mode

决定并发更新查询的行为。

可能的值：

• sync - 按顺序运行所有 UPDATE 查询。
• auto - 仅按顺序运行那些其更新列与另一查询表达式中使用的列之间存在依赖关系的 UPDATE 查询。
• async - 不对更新查询进行同步。

​

update_sequential_consistency

如果为 true，则会在执行更新前先将 parts 集合更新为最新版本。

​

url_base

在 url 表函数和 URL 表引擎中，用于解析相对 URL 的基准 URL。

设置后，相对 URL 将按以下方式解析：

• 路径相对 URL (例如 data.csv) ：根据 RFC 3986 与基准 URL 的路径合并。基准路径中最后一个 / 之后的所有内容都会被相对 URL 替换，因此末尾是否带斜杠很重要：https://example.com/dir/ + data.csv = https://example.com/dir/data.csv，而 https://example.com/dir + data.csv = https://example.com/data.csv。如果基准 URL 没有路径 (例如 https://example.com) ，则会插入一个 /：https://example.com/data.csv。相对 URL 中的点分段 (./ 和 ../) 会被归一化：https://example.com/dir/ + ../a.csv = https://example.com/a.csv。
• 主机相对 URL (例如 /test/data.csv) ：根据基准 URL 的 scheme 和主机解析。
• 协议相对 URL (例如 //other.com/test/data.csv) ：使用基准 URL 的协议进行解析。
• 仅包含查询字符串的引用 (例如 ?x=1) ：追加到基准 URL 的路径后 (替换现有的查询字符串/片段) 。
• 仅包含片段的引用 (例如 #frag) ：追加到基准 URL 后，并保留现有的查询字符串 (替换现有片段) 。
• 空引用：返回不带片段的基准 URL。

例如，如果 url_base 为 https://example.com/def/，则：

• data.csv 解析为 https://example.com/def/data.csv
• /test/data.csv 解析为 https://example.com/test/data.csv
• //other.com/test/data.csv 解析为 https://other.com/test/data.csv

​

use_async_executor_for_materialized_views

对 materialized view 查询使用异步且可能为多线程的执行方式，可加快 INSERT 期间的视图处理速度，但也会消耗更多内存。

​

use_cache_for_count_from_files

启用在表函数 file/s3/url/hdfs/azureBlobStorage 中对文件执行 count 时的行数缓存。

默认启用。

​

use_client_time_zone

使用客户端时区来解析 DateTime 字符串值，而不是使用服务器时区。

​

use_compact_format_in_distributed_parts_names

对于使用 Distributed 引擎的表，在后台 (distributed_foreground_insert) 执行 INSERT 时，使用紧凑格式存储块。

可能的值：

• 0 — 使用 user[:password]@host:port#default_database 目录格式。
• 1 — 使用 [shard{shard_index}[_replica{replica_index}]] 目录格式。

• 当 use_compact_format_in_distributed_parts_names=0 时，集群定义中的更改不会应用于后台 INSERT。
• 当 use_compact_format_in_distributed_parts_names=1 时，调整集群定义中节点的顺序会改变 shard_index/replica_index，请留意。

​

use_concurrency_control

遵循服务器的并发控制 (请参见全局服务器设置 concurrent_threads_soft_limit_num 和 concurrent_threads_soft_limit_ratio_to_cores) 。如果禁用，即使服务器已过载，也允许使用更多线程 (不建议在正常使用时这样做，主要仅用于测试) 。

Cloud 默认值：0。

​

use_hash_table_stats_for_join_reordering

启用在 join 重排序期间使用已收集的哈希表统计信息进行基数估计

​

use_hedged_requests

为远程查询启用 hedged requests 机制。它允许针对同一查询与不同副本建立多个连接。 如果与副本的现有连接未能在 hedged_connection_timeout 内建立，或者在 receive_data_timeout 内未收到任何数据，则会启用新连接。查询会使用第一个发送非空 Progress 数据包的连接 (如果启用了 allow_changing_replica_until_first_data_packet，则也可以是 Data 数据包) ； 其他连接会被取消。支持 max_parallel_replicas > 1 的查询。

默认启用。

Cloud 默认值：0。

​

use_hive_partitioning

启用后，ClickHouse 会在文件类表引擎 File 表引擎/S3/URL/HDFS/AzureBlobStorage 的路径 (/name=value/) 中检测 Hive 风格分区，并允许在查询中将分区列作为虚拟列使用。这些虚拟列的名称将与分区路径中的名称相同，但以下划线 _ 开头。

​

use_iceberg_metadata_files_cache

启用后，Iceberg 表函数和 Iceberg 存储可能会使用 Iceberg 元数据文件缓存。

可选值：

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

​

use_iceberg_partition_pruning

对 Iceberg 表启用 Iceberg 分区裁剪

​

use_index_for_in_with_subqueries

如果 IN 运算符右侧是子查询或表表达式，则尝试使用索引。

​

use_index_for_in_with_subqueries_max_values

IN 运算符右侧集合可使用表索引进行过滤时的最大大小。该设置可避免大查询因构建额外数据结构而导致性能下降和内存占用增加。0 表示不限制。

​

use_join_disjunctions_push_down

启用将 JOIN 条件中由 OR 连接的部分下推到对应的输入侧 (“部分下推”) 。 这样可使存储引擎更早进行过滤，从而减少读取的数据量。 该优化不会改变语义，且仅在每个顶层 OR 分支都至少为目标侧提供一个确定性 谓词时才会应用。

​

use_legacy_to_time

启用后，可使用旧版 toTime 函数。该函数会将日期时间转换为某个固定日期，同时保留时间部分。 否则，将使用新的 toTime 函数，它会将不同类型的数据转换为 Time 类型。 旧版函数也始终可通过 toTimeWithFixedDate 直接使用。

​

use_page_cache_for_disks_without_file_cache

对未启用文件系统缓存的远程磁盘使用用户态页缓存。

​

use_page_cache_for_local_disks

从本地磁盘读取时使用用户态页缓存。此设置主要用于测试，实际中不太可能提升性能。要求 local_filesystem_read_method = 'pread' 或 'read'。它不会禁用操作系统页缓存；如需禁用，可使用 min_bytes_to_use_direct_io。仅影响常规表，不影响 file() 表函数或 File() File 表引擎。

​

use_page_cache_for_object_storage

从对象存储表函数 (s3、azure、hdfs) 和表引擎 (S3、Azure、HDFS) 读取时，使用用户态页缓存。

​

use_page_cache_with_distributed_cache

使用分布式缓存时，启用用户态页缓存。

​

use_paimon_partition_pruning

对 Paimon 表函数启用 Paimon 分区裁剪

​

use_parquet_metadata_cache

启用后，Parquet format 可能会使用 Parquet 元数据缓存。

可能的值：

• 0 - 禁用
• 1 - 启用

​

use_partition_pruning

别名: use_partition_key

在 MergeTree 表的查询执行期间，使用分区键进行分区剪枝。

可能的值：

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

​

use_primary_key

对于 MergeTree 表，在查询执行期间使用主键进行粒度级剪枝。

可能的值：

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

​

use_query_cache

启用后，SELECT 查询可使用查询缓存。参数 enable_reads_from_query_cache 和 enable_writes_to_query_cache 可进一步控制缓存的使用方式。

可能的值：

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

​

use_query_condition_cache

启用查询条件缓存。该缓存会存储数据分区片段中不满足 WHERE 子句条件的粒度范围， 并将这些信息作为临时索引用于后续查询。

可能的值：

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

​

use_roaring_bitmap_iceberg_positional_deletes

对 Iceberg 的位置删除使用 roaring bitmap。

​

use_skip_indexes

在查询执行期间使用数据跳过索引。

可能的值：

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

​

use_skip_indexes_for_disjunctions

使用跳过索引来评估同时包含 AND 和 OR 的 WHERE 过滤条件。示例：WHERE A = 5 AND (B = 5 OR C = 5)。 如果禁用，跳过索引仍可用于评估 WHERE 条件，但这些条件只能包含用 AND 连接的子句。

可能的值：

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

​

use_skip_indexes_for_top_k

启用在 TopK 过滤中使用数据跳过索引。

启用后，如果 ORDER BY <column> LIMIT n 查询中的列上存在 minmax 跳过索引，优化器将尝试使用该 minmax 索引跳过与最终结果无关的粒度。这可以降低查询延迟。

可能的值：

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

​

use_skip_indexes_if_final

控制在使用 FINAL 修饰符执行查询时，是否使用跳过索引。

跳过索引可能会排除包含最新数据的行 (粒度) ，从而导致带有 FINAL 修饰符的查询结果不正确。启用此设置后，即使使用 FINAL 修饰符，也会应用跳过索引，这可能提升性能，但也存在遗漏最近更新的风险。此设置应与 use_skip_indexes_if_final_exact_mode 设置同步启用 (默认已启用) 。

可能的值：

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

​

use_skip_indexes_if_final_exact_mode

控制在使用 FINAL 修饰符执行查询时，是否需要在较新的 parts 中扩展跳过索引返回的粒度范围，以确保结果正确。

使用跳过索引时，可能会排除包含最新数据的行 (粒度) ，从而导致结果不正确。此设置会扫描与跳过索引返回范围重叠的较新 parts，以确保返回正确结果。只有在应用可以接受基于跳过索引查找得到的近似结果时，才应禁用此设置。

可能的值：

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

​

use_skip_indexes_on_data_read

启用在读取数据时使用数据跳过索引。

启用后，跳过索引会在读取每个数据粒度时动态进行评估，而不是在查询开始执行前预先分析。这有助于降低查询启动延迟。

可选值：

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

​

use_statistics

/// 出于与 use_primary_key 和 use_skip_indexes 保持一致的考虑，优先使用此名称而非 allow_statistics_optimize 允许使用统计信息优化查询

​

use_statistics_cache

在查询中使用统计信息缓存，以避免加载每个 part 的统计信息所带来的开销

​

use_statistics_for_part_pruning

在查询执行期间使用统计信息过滤 parts。

启用后，SELECT 查询中的 pruning 会使用列统计信息 (例如 MinMax 统计信息) ，在读取任何数据之前排除不可能包含匹配数据的 parts。

可能的值：

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

​

use_strict_insert_block_limits

启用后，会严格同时执行最小和最大插入块大小限制。

在以下情况下会生成一个块：

• 最小阈值 (与) ：当 min_insert_block_size_rows 和 min_insert_block_size_bytes 都达到时。
• 最大阈值 (或) ：当 max_insert_block_size_rows 或 max_insert_block_size_bytes 任一达到时。

禁用后，在以下情况下会生成一个块：

• 最小阈值 (或) ：当 min_insert_block_size_rows 或 min_insert_block_size_bytes 达到时。

注意：如果 max 设置小于 min 设置，则 max 限制优先，块会在达到最小阈值之前生成。

注意：对于异步插入，此设置会自动禁用，因为异步插入会附加按条目区分的去重标记，而这与强制执行严格限制所需的块拆分不兼容。

默认禁用。

​

use_structure_from_insertion_table_in_table_functions

使用插入表的结构，而不是根据数据进行 schema 推断。可能的值：0 - 已禁用，1 - 已启用，2 - 自动

​

use_text_index_header_cache

是否使用反序列化后的文本索引头部缓存。 处理大量文本索引查询时，使用文本索引头部缓存可显著降低延迟并提高吞吐量。

​

use_text_index_like_evaluation_by_dictionary_scan

启用通过扫描倒排文本索引字典来对 LIKE/ILIKE 查询进行求值。

​

use_text_index_postings_cache

是否使用已反序列化的文本索引倒排列表缓存。 对于大量文本索引查询，使用文本索引倒排列表缓存可显著降低延迟并提高吞吐量。

​

use_text_index_tokens_cache

是否使用反序列化后的文本索引标记信息缓存。 处理大量文本索引查询时，使用文本索引标记缓存可显著降低延迟并提高吞吐量。

​

use_top_k_dynamic_filtering

在执行 ORDER BY <column> LIMIT n 查询时启用动态过滤优化。

启用后，查询执行器会尝试跳过那些不会进入结果集中最终 top N 行的粒度和行。此优化是动态的，延迟改善效果取决于数据分布以及查询中是否存在其他谓词。

可能的值：

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

​

use_top_k_dynamic_filtering_for_variable_length_types

允许在排序列具有可变长度数据类型 (例如 String、Array、Map、包含可变长度元素的 Tuple) 时应用 use_top_k_dynamic_filtering。

对于这类类型，如果列中的字典序最小值占主导 (例如大多是空字符串) ，且只能跳过少量粒度，那么动态过滤器执行的逐行阈值比较所带来的开销可能会超过其节省的成本。在这种情况下，动态过滤器非但不能改善查询延迟，反而会使其变差。

当此设置为 0 时，动态过滤仅适用于值在内存中具有固定最大大小的列 (数值、Date、DateTime、FixedString、Enum、这些类型的 Nullable 以及这些类型的 Tuple) 。设置为 1 时，动态过滤也会应用于可变长度类型。

可能的值：

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

​

use_uncompressed_cache

是否使用未压缩块缓存。可接受 0 或 1。默认值为 0 (禁用) 。 使用未压缩缓存 (仅适用于 MergeTree 家族中的表) 可在处理大量短查询时显著降低延迟并提高吞吐量。对于频繁发送短请求的用户，建议启用此设置。同时还要注意 uncompressed_cache_size 配置参数 (只能在 config 文件中设置) ——它表示未压缩缓存块的大小。默认值为 8 GiB。未压缩缓存会按需填充，并自动删除最少使用的数据。

对于读取数据量较大的查询 (100 万行或更多) ，系统会自动禁用未压缩缓存，以便为真正的小查询节省空间。这意味着你可以始终将 use_uncompressed_cache 设为 1。

​

use_variant_as_common_type

当参数类型没有公共类型时，允许将 Variant 类型用作 if/multiIf/array/map 函数的结果类型。

示例：

SET use_variant_as_common_type = 1;
SELECT toTypeName(if(number % 2, number, range(number))) as variant_type FROM numbers(1);
SELECT if(number % 2, number, range(number)) as variant FROM numbers(5);

┌─variant_type───────────────────┐
│ Variant(Array(UInt64), UInt64) │
└────────────────────────────────┘
┌─variant───┐
│ []        │
│ 1         │
│ [0,1]     │
│ 3         │
│ [0,1,2,3] │
└───────────┘

SET use_variant_as_common_type = 1;
SELECT toTypeName(multiIf((number % 4) = 0, 42, (number % 4) = 1, [1, 2, 3], (number % 4) = 2, 'Hello, World!', NULL)) AS variant_type FROM numbers(1);
SELECT multiIf((number % 4) = 0, 42, (number % 4) = 1, [1, 2, 3], (number % 4) = 2, 'Hello, World!', NULL) AS variant FROM numbers(4);

─variant_type─────────────────────────┐
│ Variant(Array(UInt8), String, UInt8) │
└──────────────────────────────────────┘

┌─variant───────┐
│ 42            │
│ [1,2,3]       │
│ Hello, World! │
│ ᴺᵁᴸᴸ          │
└───────────────┘

SET use_variant_as_common_type = 1;
SELECT toTypeName(array(range(number), number, 'str_' || toString(number))) as array_of_variants_type from numbers(1);
SELECT array(range(number), number, 'str_' || toString(number)) as array_of_variants FROM numbers(3);

┌─array_of_variants_type────────────────────────┐
│ Array(Variant(Array(UInt64), String, UInt64)) │
└───────────────────────────────────────────────┘

┌─array_of_variants─┐
│ [[],0,'str_0']    │
│ [[0],1,'str_1']   │
│ [[0,1],2,'str_2'] │
└───────────────────┘

SET use_variant_as_common_type = 1;
SELECT toTypeName(map('a', range(number), 'b', number, 'c', 'str_' || toString(number))) as map_of_variants_type from numbers(1);
SELECT map('a', range(number), 'b', number, 'c', 'str_' || toString(number)) as map_of_variants FROM numbers(3);

┌─map_of_variants_type────────────────────────────────┐
│ Map(String, Variant(Array(UInt64), String, UInt64)) │
└─────────────────────────────────────────────────────┘

┌─map_of_variants───────────────┐
│ {'a':[],'b':0,'c':'str_0'}    │
│ {'a':[0],'b':1,'c':'str_1'}   │
│ {'a':[0,1],'b':2,'c':'str_2'} │
└───────────────────────────────┘

​

use_variant_default_implementation_for_comparisons

启用或禁用在比较函数中对 Variant 类型使用默认实现。

​

use_with_fill_by_sorting_prefix

在 ORDER BY 子句中，位于 WITH FILL 列之前的列构成排序前缀。排序前缀值不同的行会分别填充

​

validate_enum_literals_in_operators

如果启用，则会检查 IN、NOT IN、==、!= 等运算符中的枚举字面量是否符合枚举类型；如果字面量不是有效的枚举值，则会抛出异常。

​

validate_mutation_query

在接受变更查询之前先进行校验。变更会在后台执行，执行无效查询会导致变更卡住，并需要手动干预。

仅当遇到向后不兼容的 bug 时，才应更改此设置。

​

validate_polygons

如果多边形存在自相交或自切情况，则启用或禁用 pointInPolygon 函数抛出异常。

可能的值：

• 0 — 禁用抛出异常。pointInPolygon 接受无效多边形，并可能返回不正确的结果。
• 1 — 启用抛出异常。

​

variant_throw_on_type_mismatch

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

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

​

vector_search_filter_strategy

如果向量搜索查询带有 WHERE 子句，则此设置决定是先评估该子句 (前过滤) ，还是先检查向量相似度索引 (后过滤) 。可选值：

• ‘auto’ - 后过滤 (具体语义未来可能会变化) 。
• ‘postfilter’ - 使用向量相似度索引识别最近邻，然后再应用其他过滤条件
• ‘prefilter’ - 先评估其他过滤条件，再执行暴力搜索以识别最近邻。

​

vector_search_index_fetch_multiplier

别名: vector_search_postfilter_multiplier

将从向量相似度索引中拉取的最近邻数量乘以该值。仅在使用其他谓词进行后过滤时，或在设置 ‘vector_search_with_rescoring = 1’ 时生效。

​

vector_search_with_rescoring

控制 ClickHouse 是否对使用向量相似度索引的查询执行 rescoring。 不使用 rescoring 时，向量相似度索引会直接返回包含最佳匹配的行。 使用 rescoring 时，会将行扩展到粒度级别，并重新检查该粒度中的所有行。 在大多数情况下，rescoring 对准确性的提升微乎其微，但会显著降低向量搜索查询的性能。 注意：在不使用 rescoring 且启用了并行副本的情况下运行的查询，可能会回退到使用 rescoring。

​

wait_changes_become_visible_after_commit_mode

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

​

wait_for_async_insert

如果为 true，则等待异步插入处理完成

​

wait_for_async_insert_timeout

等待异步插入处理完成的超时时间

​

wait_for_window_view_fire_signal_timeout

在事件时间处理中等待 window view 触发信号的超时时间

​

webassembly_udf_max_fuel

每个 WebAssembly UDF 实例单次执行的 fuel 限制。每条 WebAssembly 指令都会消耗一定量的 fuel。 设为 0 表示不受限制。

​

webassembly_udf_max_input_block_size

单个块中传递给 WebAssembly UDF 的最大行数。设置为 0 表示一次处理所有行。

​

webassembly_udf_max_instances

每个函数可并行运行的 WebAssembly UDF 实例最大数量。

​

webassembly_udf_max_memory

每个 WebAssembly UDF 实例的内存上限 (以字节为单位) 。

​

window_view_clean_interval

window view 的清理间隔 (单位：秒) ，用于释放过期数据。

​

window_view_heartbeat_interval

用于指示 watch 查询仍处于活动状态的心跳间隔 (以秒为单位) 。

​

工作负载

用于访问资源的工作负载名称

​

write_full_path_in_iceberg_metadata

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

​

write_through_distributed_cache

仅在 ClickHouse Cloud 中生效。允许写入分布式缓存 (写入 S3 也将由分布式缓存执行)

​

write_through_distributed_cache_buffer_size

仅在 ClickHouse Cloud 中生效。设置写穿分布式缓存的缓冲区大小。如果为 0，则使用在没有分布式缓存时原本会使用的缓冲区大小。

​

zstd_window_log_max

允许选择 ZSTD 的最大窗口日志 (不用于 MergeTree 家族)