跳至主要内容
跳至主要内容
编辑此页

会话设置

以下所有设置也可在表 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 — 格式预期为聚合函数参数的单个值，或者在多个参数的情况下为它们的元组。它们将使用相应的 IDataType 或 DataTypeTuple 进行反序列化，然后聚合以形成状态。
  • 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' 相同。

allow_aggregate_partitions_independently​

当分区键符合 group by 键时，允许在单独的线程上对分区进行独立聚合。当分区数量接近核心数量且分区大小大致相同时，此功能非常有用。

allow_archive_path_syntax​

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

allow_asynchronous_read_from_io_pool_for_merge_tree​

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

allow_changing_replica_until_first_data_packet​

如果启用，在对冲请求（hedged requests）中，我们可以在收到第一个数据包之前启动新的连接，即使我们已经取得了一些进展（但在 receive_data_timeout 超时时间内进度未更新）；否则，在第一次取得进展后，我们将禁用更换副本。

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 引擎创建数据库。

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​

允许按列（columnar）执行 multiIf 函数。

allow_experimental_alias_table_engine​

实验性功能。 了解更多。

允许使用 Alias 引擎创建表。

allow_experimental_analyzer​

别名: enable_analyzer

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

allow_experimental_codecs​

实验性功能。 了解更多。

如果设置为 true，则允许指定实验性压缩编解码器（但目前还没有，此选项目前不起作用）。

allow_experimental_correlated_subqueries​

Beta 功能。了解更多。

允许执行关联子查询。

allow_experimental_database_glue_catalog​

Beta 功能。了解更多。

别名: allow_database_glue_catalog

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

allow_experimental_database_hms_catalog​

实验性功能。 了解更多。

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

allow_experimental_database_iceberg​

Beta 功能。了解更多。

别名: allow_database_iceberg

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

allow_experimental_database_materialized_postgresql​

实验性功能。 了解更多。

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

allow_experimental_database_paimon_rest_catalog​

实验性功能。 了解更多。

允许 catalog_type = 'paimon_rest' 的实验性数据库引擎 DataLakeCatalog。

allow_experimental_database_unity_catalog​

Beta 功能。了解更多。

别名: allow_database_unity_catalog

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

allow_experimental_delta_kernel_rs​

Beta 功能。了解更多。

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

allow_experimental_delta_lake_writes​

实验性功能。 了解更多。

启用 delta-kernel 写入功能。

allow_experimental_funnel_functions​

实验性功能。 了解更多。

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

allow_experimental_hash_functions​

实验性功能。 了解更多。

启用实验性哈希函数。

allow_experimental_iceberg_compaction​

实验性功能。 了解更多。

允许对 iceberg 表显式使用 'OPTIMIZE'。

allow_experimental_insert_into_iceberg​

实验性功能。 了解更多。

允许对 iceberg 执行 insert 查询。

allow_experimental_join_right_table_sorting​

实验性功能。 了解更多。

如果设置为 true，并且满足 join_to_sort_minimum_perkey_rows 和 join_to_sort_maximum_table_rows 条件，则按键重新排列右表，以提高左哈希连接或内哈希连接的性能。

allow_experimental_kafka_offsets_storage_in_keeper​

实验性功能。 了解更多。

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

allow_experimental_kusto_dialect​

实验性功能。 了解更多。

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

allow_experimental_materialized_postgresql_table​

实验性功能。 了解更多。

允许使用 MaterializedPostgreSQL 表引擎。默认禁用，因为此功能尚处于实验阶段。

allow_experimental_nlp_functions​

实验性功能。 了解更多。

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

allow_experimental_nullable_tuple_type​

实验性功能。 了解更多。

允许在表中创建 Nullable Tuple 列。

allow_experimental_object_storage_queue_hive_partitioning​

实验性功能。 了解更多。

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

allow_experimental_parallel_reading_from_replicas​

别名: enable_parallel_replicas

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

allow_experimental_prql_dialect​

实验性功能。 了解更多。

启用 PRQL —— 一种 SQL 的替代方案。

allow_experimental_query_deduplication​

实验性功能。 了解更多。

基于数据分片 (part) UUID 的 SELECT 查询实验性数据去重。

allow_experimental_statistics​

实验性功能。 了解更多。

别名: allow_experimental_statistic

允许定义包含 统计信息 的列并 操作统计信息。

allow_experimental_time_series_aggregate_functions​

实验性功能。 了解更多。

别名: allow_experimental_ts_to_grid_aggregate_function

实验性的 timeSeries* 聚合函数，用于类似 Prometheus 的时间序列重采样、速率 (rate) 和增量 (delta) 计算。

allow_experimental_time_series_table​

实验性功能。 了解更多。

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

allow_experimental_window_view​

实验性功能。 了解更多。

启用 WINDOW VIEW。尚不够成熟。

allow_experimental_ytsaurus_dictionary_source​

实验性功能。 了解更多。

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

allow_experimental_ytsaurus_table_engine​

实验性功能。 了解更多。

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

allow_experimental_ytsaurus_table_function​

实验性功能。 了解更多。

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

allow_general_join_planning​

允许更通用的连接规划算法，可以处理更复杂的条件，但仅适用于哈希连接。如果未启用哈希连接，则无论此设置的值如何，都将使用通常的连接规划算法。

allow_get_client_http_header​

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

allow_hyperscan​

允许使用 Hyperscan 库的函数。禁用以避免潜在的漫长编译时间和过度的资源消耗。

allow_introspection_functions​

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

可能的值

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

参见

allow_materialized_view_with_bad_select​

允许创建带有引用不存在的表或列的 SELECT 查询的 MATERIALIZED VIEW。它在语法上仍必须有效。不适用于可刷新的物化视图。如果物化视图架构需要从 SELECT 查询中推断（即 CREATE 语句没有列列表且没有 TO 表），则不适用。可用于在源表创建之前先创建物化视图。

allow_named_collection_override_by_default​

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

allow_non_metadata_alters​

允许执行不仅影响表元数据，还影响磁盘上数据的修改 (alter)。

allow_nonconst_timezone_arguments​

在某些与时间相关的函数中允许非常量时区参数，如 toTimeZone()、fromUnixTimestamp*()、snowflakeToDateTime*()。此设置仅出于兼容性原因而存在。在 ClickHouse 中，时区是数据类型（即列）的一个属性。启用此设置会产生一种错误印象，即列中的不同值可以具有不同的时区。因此，请不要启用此设置。

allow_nondeterministic_mutations​

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

考虑到字典等在节点间可能不同步，默认情况下禁止在复制表上执行从中提取值的变更。启用此设置允许此行为，此时由用户负责确保所使用的数据在所有节点上同步。

示例

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

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

    <!-- ... -->

</profiles>

allow_nondeterministic_optimize_skip_unused_shards​

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

可能的值

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

allow_prefetched_read_pool_for_local_filesystem​

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

allow_prefetched_read_pool_for_remote_filesystem​

如果所有分片都在远程文件系统上，则优先使用预取线程池。

allow_push_predicate_ast_for_distributed_subqueries​

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

allow_push_predicate_when_subquery_contains_with​

当子查询包含 WITH 子句时，允许谓词下推。

allow_reorder_prewhere_conditions​

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

allow_settings_after_format_in_insert​

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

示例

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

但以下查询仅在启用 allow_settings_after_format_in_insert 时有效。

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

可能的值

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

如果您的用例依赖于旧语法，请仅出于向后兼容性使用此设置。

allow_simdjson​

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

allow_special_serialization_kinds_in_output_formats​

允许输出具有特殊序列化类型（如 Sparse 和 Replicated）的列，而无需将其转换为完整列表示。这有助于避免格式化过程中不必要的数据复制。

allow_statistics_optimize​

Beta 功能。了解更多。

别名: allow_statistic_optimize

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

allow_suspicious_codecs​

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

allow_suspicious_fixed_string_types​

在 CREATE TABLE 语句中允许创建 n > 256 的 FixedString(n) 类型列。长度 >= 256 的 FixedString 是可疑的，很可能表示误用。

allow_suspicious_indices​

拒绝具有相同表达式的主/二级索引和排序键。

allow_suspicious_low_cardinality_types​

允许或限制对固定大小为 8 字节或更少的数据类型使用 LowCardinality：包括数值数据类型和 FixedString(8字节或更少)。

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

  • 磁盘空间使用量可能会上升。
  • RAM 消耗可能会更高，具体取决于字典大小。
  • 由于额外的编码/解码操作，某些函数的运行速度可能会变慢。

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

可能的值

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

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

allow_suspicious_types_in_order_by​

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

allow_suspicious_variant_types​

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

allow_unrestricted_reads_from_keeper​

允许不受限制地（没有路径条件）读取 system.zookeeper 表。这可能很方便，但对 zookeeper 来说是不安全的。

alter_move_to_space_execute_async​

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

alter_partition_verbose_result​

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

可能的值

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

示例

CREATE TABLE test(a Int64, d Date, s String) ENGINE = MergeTree PARTITION BY toYYYYMDECLARE(d) ORDER BY a;
INSERT INTO test VALUES(1, '2021-01-01', '');
INSERT INTO test VALUES(1, '2021-01-01', '');
ALTER TABLE test DETACH PARTITION ID '202101';

ALTER TABLE test ATTACH PARTITION ID '202101' SETTINGS alter_partition_verbose_result = 1;

┌─command_type─────┬─partition_id─┬─part_name────┬─old_part_name─┐
│ ATTACH PARTITION │ 202101       │ 202101_7_7_0 │ 202101_5_5_0  │
│ ATTACH PARTITION │ 202101       │ 202101_8_8_0 │ 202101_6_6_0  │
└──────────────────┴──────────────┴──────────────┴───────────────┘

ALTER TABLE test FREEZE SETTINGS alter_partition_verbose_result = 1;

┌─command_type─┬─partition_id─┬─part_name────┬─backup_name─┬─backup_path───────────────────┬─part_backup_path────────────────────────────────────────────┐
│ FREEZE ALL   │ 202101       │ 202101_7_7_0 │ 8           │ /var/lib/clickhouse/shadow/8/ │ /var/lib/clickhouse/shadow/8/data/default/test/202101_7_7_0 │
│ FREEZE ALL   │ 202101       │ 202101_8_8_0 │ 8           │ /var/lib/clickhouse/shadow/8/ │ /var/lib/clickhouse/shadow/8/data/default/test/202101_8_8_0 │
└──────────────┴──────────────┴──────────────┴─────────────┴───────────────────────────────┴─────────────────────────────────────────────────────────────┘

alter_sync​

别名: replication_alter_partitions_sync

允许您指定由 ALTER、OPTIMIZE 或 TRUNCATE 查询在副本上执行的操作的等待行为。

可能的值

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

云默认值：1。

注意

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

alter_update_mode​

具有 UPDATE 命令的 ALTER 查询的模式。

可能的值

  • heavy - 运行常规变更 (mutation)。
  • 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) 中，将通过 t1.a + 1 = t2.b 执行连接，而不是 t1.b = t2.b）。

any_join_distinct_right_table_keys​

在 ANY INNER|LEFT JOIN 操作中启用旧版 ClickHouse 服务器行为。

注意

仅当您的用例依赖于旧版 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 — 启用旧版行为。

参见

apply_deleted_mask​

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

apply_mutations_on_fly​

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

apply_patch_parts​

如果为 true，补丁分片 (patch parts)（代表轻量级更新）将在 SELECT 时应用。

apply_patch_parts_join_cache_buckets​

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

apply_prewhere_after_final​

启用后，对于 ReplacingMergeTree 和类似引擎，PREWHERE 条件将在 FINAL 处理后应用。当 PREWHERE 引用在重复行中可能具有不同值的列，且您希望 FINAL 在过滤前先选出胜出的行时，这很有用。禁用时，PREWHERE 在读取期间应用。注意：如果启用了 apply_row_level_security_after_final 且行策略使用非排序键列，则 PREWHERE 也会延迟以维持正确的执行顺序（行策略必须在 PREWHERE 之前应用）。

apply_row_policy_after_final​

启用后，行策略和 PREWHERE 会在 *MergeTree 表（尤其是 ReplacingMergeTree）的 FINAL 处理后应用。禁用时，行策略在 FINAL 之前应用，这可能导致不同的结果，因为策略可能会过滤掉 ReplacingMergeTree 或类似引擎在去重时本应使用的行。

如果行策略表达式仅依赖于 ORDER BY 中的列，由于此类过滤不会影响去重结果，作为一种优化，它仍将在 FINAL 之前应用。

可能的值

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

apply_settings_from_server​

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

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

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

注意，最初 (24.12) 有一个服务器设置 (send_settings_to_client)，但后来为了更好的易用性，它被此客户端设置取代。

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 需要此项）

asterisk_include_alias_columns​

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

可能的值

  • 0 - 禁用
  • 1 - 启用

asterisk_include_materialized_columns​

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

可能的值

  • 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

自第一条数据出现以来，每个查询在倾倒收集的数据之前等待的最大时间。

async_insert_busy_timeout_min_ms​

如果通过 async_insert_use_adaptive_busy_timeout 启用了自动调整，则为自第一条数据出现以来，每个查询在倾倒收集的数据之前等待的最小时间。它还用作自适应算法的初始值。

async_insert_deduplicate​

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

async_insert_max_data_size​

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

async_insert_max_query_number​

执行插入前的最大插入查询数量。仅在设置 async_insert_deduplicate 为 1 时生效。

async_insert_poll_timeout_ms​

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

async_insert_use_adaptive_busy_timeout​

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

async_query_sending_for_remote​

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

默认启用。

async_socket_for_remote​

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

默认启用。

automatic_parallel_replicas_min_bytes_per_replica​

实验性功能。 了解更多。

自动启用并行副本时每个副本读取的字节阈值（仅适用于 automatic_parallel_replicas_mode=1）。0 表示没有阈值。要读取的总字节数是根据收集的统计信息估算的。

automatic_parallel_replicas_mode​

实验性功能。 了解更多。

根据收集的统计信息启用自动切换到并行副本执行。需要启用 parallel_replicas_local_plan 并提供 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 磁盘主机的连接超时。

azure_create_new_file_on_insert​

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

azure_ignore_file_doesnt_exist​

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

可能的值

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

azure_list_object_keys_size​

ListObject 请求批量返回的最大文件数。

azure_max_blocks_in_multipart_upload​

Azure 分块上传中的最大块数。

azure_max_get_burst​

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

azure_max_get_rps​

限制 Azure GET 请求在限流之前的每秒速率。零表示无限制。

azure_max_inflight_parts_for_one_file​

分块上传请求中并发加载分块的最大数量。0 表示无限制。

azure_max_put_burst​

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

azure_max_put_rps​

限制 Azure PUT 请求在限流之前的每秒速率。零表示无限制。

azure_max_redirects​

允许的最大 azure 重定向跳数。

azure_max_single_part_copy_size​

使用单部分复制到 Azure blob 存储的对象最大大小。

azure_max_single_part_upload_size​

使用单部分上传到 Azure blob 存储的对象最大大小。

azure_max_single_read_retries​

单次 Azure blob 存储读取期间的最大重试次数。

azure_max_unexpected_write_error_retries​

Azure blob 存储写入过程中发生意外错误时的最大重试次数。

azure_max_upload_part_size​

Azure blob 存储分块上传期间分块的最大大小。

azure_min_upload_part_size​

Azure blob 存储分块上传期间分块的最小大小。

azure_request_timeout_ms​

向/从 azure 发送和接收数据的空闲超时。如果单个 TCP 读取或写入调用阻塞时间超过此值，则失败。

azure_sdk_max_retries​

azure sdk 中的最大重试次数。

azure_sdk_retry_initial_backoff_ms​

azure sdk 重试之间的最小退避时间。

azure_sdk_retry_max_backoff_ms​

azure sdk 重试之间的最大退避时间。

azure_skip_empty_files​

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

可能的值

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

azure_strict_upload_part_size​

Azure blob 存储分块上传期间分块的精确大小。

azure_throw_on_zero_files_match​

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

可能的值

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

azure_truncate_on_insert​

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

azure_upload_part_size_multiply_factor​

每当单次写入 Azure blob 存储上传了 azure_multiply_parts_count_threshold 个分块时，将 azure_min_upload_part_size 乘以该因子。

azure_upload_part_size_multiply_parts_count_threshold​

每当向 Azure blob 存储上传了此数量的分块时，azure_min_upload_part_size 将乘以 azure_upload_part_size_multiply_factor。

azure_use_adaptive_timeouts​

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

backup_restore_batch_size_for_keeper_multi​

备份或恢复期间，向 [Zoo]Keeper 发送多重 (multi) 请求的最大批次大小。

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' 节点，则整个备份或恢复操作将被视为失败。此值应大于主机在故障后重新连接到 ZooKeeper 的任何合理时间。零表示无限制。

backup_restore_finish_timeout_after_error_sec​

发起方应等待其他主机对 'error' 节点做出反应并停止其当前 BACKUP ON CLUSTER 或 RESTORE ON CLUSTER 操作的工作时间。

backup_restore_keeper_fault_injection_probability​

备份或恢复期间 keeper 请求失败的大致概率。有效值在 [0.0f, 1.0f] 区间内。

backup_restore_keeper_fault_injection_seed​

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

backup_restore_keeper_max_retries​

BACKUP 或 RESTORE 操作过程中 [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 操作的最大退避超时。

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​

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

仅在 ClickHouse Cloud 中有效。当启用 cache_populated_by_fetch 时，用于推测性地将新数据分片下载到文件系统缓存中的后台线程数。零表示禁用。

calculate_text_stack_trace​

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

cancel_http_readonly_queries_on_client_close​

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

云默认值：0。

cast_ipv4_ipv6_default_on_conversion_error​

CAST 到 IPv4 算子、CAST 到 IPV6 类型算子、toIPv4、toIPv6 函数在转换错误时将返回默认值而不是抛出异常。

cast_keep_nullable​

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

当该设置启用且 CAST 函数的参数为 Nullable 时，结果也会转换为 Nullable 类型。当该设置禁用时，结果始终准确地具有目标类型。

可能的值

  • 0 — CAST 结果准确地具有指定的目标类型。
  • 1 — 如果参数类型为 Nullable，CAST 结果将转换为 Nullable(目标数据类型)。

示例

以下查询产生准确的目标数据类型

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_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。

参见

cast_string_to_dynamic_use_inference​

在 String 到 Dynamic 转换期间使用类型推断

cast_string_to_variant_use_inference​

在 String 到 Variant 转换期间使用类型推断。

check_query_single_value_result​

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

可能的值

  • 0 — 查询显示表的每个单独数据分片的检查状态。
  • 1 — 查询显示表的总体检查状态。

check_referential_table_dependencies​

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

check_table_dependencies​

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

checksum_on_read​

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

cloud_mode​

云模式

cloud_mode_database_engine​

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

cloud_mode_engine​

云中允许的引擎系列。

  • 0 - 允许所有引擎
  • 1 - 重写 DDL 以使用 *ReplicatedMergeTree
  • 2 - 重写 DDL 以使用 SharedMergeTree
  • 3 - 重写 DDL 以使用 SharedMergeTree，除非显式指定了传递的远程磁盘
  • 4 - 与 3 相同，此外使用 Alias 代替 Distributed (Alias 表将指向 Distributed 表的目标表，因此它将使用相应的本地表)

UInt64 以最小化公共部分

cluster_for_parallel_replicas​

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

cluster_function_process_archive_on_multiple_nodes​

如果设置为 true，则提高集群函数中处理归档文件的性能。为了保持兼容性，以及如果要在早期版本上使用带有归档的集群函数来避免升级到 25.7+ 过程中的错误，应将其设置为 false。

cluster_table_function_buckets_batch_size​

定义在使用 bucket 拆分粒度的集群表函数分布式任务处理中使用的批次近似大小（以字节为单位）。系统累积数据直到至少达到此金额。实际大小可能会稍大，以与数据边界对齐。

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 使用之前版本的默认设置，该版本通过该设置项指定。

如果设置项已被设为非默认值，则这些设置将被保留（只有未修改过的设置才会受 compatibility 设置的影响）。

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

默认禁用。

注意

在 ClickHouse Cloud 中，服务级别的默认兼容性设置必须由 ClickHouse Cloud 支持人员设定。请 提交工单 进行设置。不过，兼容性设置可以在用户、角色、配置文件、查询或会话级别覆盖，使用标准的 ClickHouse 设置机制，例如在会话中使用 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​

在建表时兼容性忽略排序规则（collation）。

compatibility_s3_presigned_url_query_in_path​

兼容性设置：启用时，会将预签名 URL 的查询参数（例如 X-Amz-*）折叠到 S3 键中（旧版行为），因此 '?' 在路径中充当通配符。禁用时（默认值），预签名 URL 的查询参数保留在 URL 查询中，以避免将 '?' 解释为通配符。

compile_aggregate_expressions​

启用或禁用聚合函数到原生代码的 JIT 编译。启用此设置可以提高性能。

可能的值

  • 0 — 聚合时不使用 JIT 编译。
  • 1 — 聚合时使用 JIT 编译。

参见

compile_expressions​

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

compile_sort_description​

将排序描述（sort description）编译为原生代码。

connect_timeout​

在没有副本的情况下的连接超时时间。

connect_timeout_with_failover_ms​

在使用分布式表引擎且集群定义中包含 'shard' 和 'replica' 部分时，连接到远程服务器的超时时间（毫秒）。如果连接失败，将尝试多次连接各个副本。

connect_timeout_with_failover_secure_ms​

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

connection_pool_max_wait_ms​

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

可能的值

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

connections_with_failover_max_tries​

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

convert_query_to_cnf​

当设置为 true 时，SELECT 查询将被转换为合取范式 (CNF)。在某些情况下，以 CNF 重写查询可能会执行得更快（请参阅此 Github 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​

控制解相关查询计划中的连接类型。默认值为 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* 函数。

可能的值

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

cross_join_min_rows_to_compress​

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

cross_to_inner_join_rewrite​

如果 WHERE 部分存在连接表达式，则使用内连接（inner join）代替逗号/交叉连接（comma/cross join）。值：0 - 不重写，1 - 对逗号/交叉连接尽可能应用，2 - 强制重写所有逗号连接，cross - 尽可能应用。

data_type_default_nullable​

允许列定义中不带显式修饰符 NULL 或 NOT NULL 的数据类型默认为 Nullable。

可能的值

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

database_atomic_wait_for_drop_and_detach_synchronously​

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

可能的值

  • 0 — 查询将延迟执行。
  • 1 — 查询将立即同步执行。

database_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 类型的表。

database_replicated_allow_replicated_engine_arguments​

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

database_replicated_always_detach_permanently​

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

database_replicated_enforce_synchronous_settings​

对某些查询强制执行同步等待（另见 database_atomic_wait_for_drop_and_detach_synchronously, mutations_sync, alter_sync）。不建议开启这些设置。

database_replicated_initial_query_timeout_sec​

设置初始 DDL 查询应等待 Replicated 数据库处理先前 DDL 队列条目的时间（秒）。

可能的值

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

database_shared_drop_table_delay_seconds​

在 Shared 数据库中，已删除的表被实际移除前的延迟秒数。这允许在此时段内使用 UNDROP TABLE 语句恢复该表。

decimal_check_overflow​

检查 Decimal 算术/比较操作的溢出。

deduplicate_blocks_in_dependent_materialized_views​

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

可能的值

0 — 禁用。1 — 启用。

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

参见

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 查询启用去重。如果查询结果不稳定，则抛出异常。
  • enable_when_possible — 如果 insert_deduplicate 已启用且查询结果稳定，则启用去重，否则禁用。
  • enable_even_for_bad_queries - 如果 insert_deduplicate 已启用，则启用去重。如果查询结果不稳定，会记录警告，但查询仍带去重执行。此选项用于向后兼容。请考虑使用其他选项，因为它可能导致意外结果。

default_materialized_view_sql_security​

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

默认值为 DEFINER。

default_max_bytes_in_join​

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

default_normal_view_sql_security​

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

默认值为 INVOKER。

default_table_engine​

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

可能的值

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

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 安全性。

默认值为 CURRENT_USER。

delta_lake_enable_engine_predicate​

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

delta_lake_enable_expression_visitor_logging​

启用 DeltaLake 表达式访问器（expression visitor）的测试级日志。这些日志对于测试记录来说可能过于冗长。

delta_lake_insert_max_bytes_in_data_file​

定义 Delta Lake 中单个插入数据文件的字节限制。

delta_lake_insert_max_rows_in_data_file​

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

delta_lake_log_metadata​

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

delta_lake_snapshot_end_version​

要读取的 Delta Lake 快照的结束版本。值 -1 表示读取最新版本（值 0 是有效的快照版本）。

delta_lake_snapshot_start_version​

要读取的 Delta Lake 快照的开始版本。值 -1 表示读取最新版本（值 0 是有效的快照版本）。

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 查询的结果中。

dialect​

解析查询时使用的 SQL 方言。

dictionary_use_async_executor​

在多个线程中执行读取字典源的管道。仅支持具有本地 CLICKHOUSE 源的字典。

dictionary_validate_primary_key_type​

验证字典的主键类型。默认情况下，简单布局（simple layouts）的 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

向分布式表插入查询的超时时间。此设置仅在启用 insert_distributed_sync 时使用。零值表示无超时。

distributed_cache_alignment​

仅限 ClickHouse Cloud

仅在 ClickHouse Cloud 中生效。仅用于测试目的的设置，请勿修改。

distributed_cache_bypass_connection_pool​

仅限 ClickHouse Cloud

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

distributed_cache_connect_backoff_max_ms​

仅限 ClickHouse Cloud

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

distributed_cache_connect_backoff_min_ms​

仅限 ClickHouse Cloud

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

distributed_cache_connect_max_tries​

仅限 ClickHouse Cloud

仅在 ClickHouse Cloud 中生效。连接分布式缓存失败后的尝试次数。

distributed_cache_connect_timeout_ms​

仅限 ClickHouse Cloud

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

distributed_cache_credentials_refresh_period_seconds​

仅限 ClickHouse Cloud

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

distributed_cache_data_packet_ack_window​

仅限 ClickHouse Cloud

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

distributed_cache_discard_connection_if_unread_data​

仅限 ClickHouse Cloud

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

distributed_cache_fetch_metrics_only_from_current_az​

仅限 ClickHouse Cloud

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

distributed_cache_file_cache_name​

仅限 ClickHouse Cloud

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

distributed_cache_log_mode​

仅限 ClickHouse Cloud

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

distributed_cache_max_unacked_inflight_packets​

仅限 ClickHouse Cloud

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

distributed_cache_min_bytes_for_seek​

仅限 ClickHouse Cloud

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

distributed_cache_pool_behaviour_on_limit​

仅限 ClickHouse Cloud

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

distributed_cache_prefer_bigger_buffer_size​

仅限 ClickHouse Cloud

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

distributed_cache_read_only_from_current_az​

仅限 ClickHouse Cloud

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

distributed_cache_read_request_max_tries​

仅限 ClickHouse Cloud

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

distributed_cache_receive_response_wait_milliseconds​

仅限 ClickHouse Cloud

仅在 ClickHouse Cloud 中生效。从分布式缓存接收请求数据的等待时间（毫秒）。

distributed_cache_receive_timeout_milliseconds​

仅限 ClickHouse Cloud

仅在 ClickHouse Cloud 中生效。从分布式缓存接收任何响应的等待时间（毫秒）。

distributed_cache_receive_timeout_ms​

仅限 ClickHouse Cloud

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

distributed_cache_send_timeout_ms​

仅限 ClickHouse Cloud

仅在 ClickHouse Cloud 中生效。向分布式缓存服务器发送数据的超时时间（毫秒）。如果客户端需要发送数据但在此间隔内无法发送任何字节，将抛出异常。

distributed_cache_tcp_keep_alive_timeout_ms​

仅限 ClickHouse Cloud

仅在 ClickHouse Cloud 中生效。在 TCP 开始发送保持活跃（keepalive）探测之前，与分布式缓存服务器的连接需要保持空闲的时间（毫秒）。

distributed_cache_throw_on_error​

仅限 ClickHouse Cloud

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

distributed_cache_use_clients_cache_for_read​

仅限 ClickHouse Cloud

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

distributed_cache_use_clients_cache_for_write​

仅限 ClickHouse Cloud

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

distributed_cache_wait_connection_from_pool_milliseconds​

仅限 ClickHouse Cloud

仅在 ClickHouse Cloud 中生效。如果 distributed_cache_pool_behaviour_on_limit 为 wait，则从连接池获取连接的等待时间（毫秒）。

distributed_connections_pool_size​

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

distributed_ddl_entry_format_version​

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

distributed_ddl_output_mode​

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

可能的值

  • throw — 返回所有已完成查询主机上的查询执行状态结果集。如果查询在某些主机上失败，它将重新抛出第一个异常。如果查询在某些主机上尚未完成且超过了 distributed_ddl_task_timeout，则抛出 TIMEOUT_EXCEEDED 异常。
  • none — 类似于 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 默认值：throw。

distributed_ddl_task_timeout​

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

可能的值

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

distributed_foreground_insert​

别名: insert_distributed_sync

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

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

可能的值

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

云默认值：0。

参见

distributed_group_by_no_merge​

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

可能的值

  • 0 — 禁用（最终查询处理在发起节点上完成）。
  • 1 - 分布式查询处理时不合并来自不同服务器的聚合状态（查询在分片上完全处理，发起节点仅代理数据），当你确信不同分片上有不同的键时可以使用。
  • 2 - 与 1 相同，但在发起节点上应用 ORDER BY 和 LIMIT（当查询在远程节点完全处理时这是不可能的，例如 distributed_group_by_no_merge=1 时）。可用于带有 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_for_parallel_replicas 的副本。

参见

distributed_index_analysis_for_non_shared_merge_tree​

即使对于非 SharedMergeTree（仅限云端的引擎），也启用分布式索引分析。

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 的默认 bucket 数量。

distributed_plan_execute_locally​

实验性功能。 了解更多。

在本地运行分布式查询计划的所有任务。对测试和调试很有用。

distributed_plan_force_exchange_kind​

实验性功能。 了解更多。

在分布式查询阶段之间强制指定某种 Exchange 算子。

可能的值

  • '' - 不强制任何 Exchange 算子，由优化器选择，
  • 'Persisted' - 使用对象存储中的临时文件，
  • 'Streaming' - 通过网络流式传输交换数据。

distributed_plan_force_shuffle_aggregation​

实验性功能。 了解更多。

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

distributed_plan_max_rows_to_broadcast​

实验性功能。 了解更多。

在分布式查询计划中使用广播连接（broadcast join）而非混洗连接（shuffle join）的最大行数。

distributed_plan_optimize_exchanges​

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

distributed_product_mode​

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

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

限制

  • 仅适用于 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 才会改变查询执行：

可能的值

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

参见

distributed_replica_error_cap​

  • 类型：unsigned int
  • 默认值：1000

每个副本的错误计数上限为此值，防止单个副本累积过多错误。

参见

distributed_replica_error_half_life​

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

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

参见

distributed_replica_max_ignored_errors​

  • 类型：unsigned int
  • 默认值：0

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

参见

do_not_merge_across_partitions_select_final​

通过避免跨不同分区的合并来改进 FINAL 查询。

启用后，在执行 SELECT FINAL 查询期间，来自不同分区的数据部分（parts）将不会合并在一起。相反，合并仅在每个分区内部单独进行。这在处理分区表时可以显著提高查询性能。

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

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

enable_extended_results_for_datetime_functions​

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

可能的值

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

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

函数enable_extended_results_for_datetime_functions = 0enable_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​

对远程文件系统使用缓存。此设置不会开启/关闭磁盘缓存（必须通过磁盘配置完成），但允许根据需要对某些查询绕过缓存。

enable_filesystem_cache_log​

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

enable_filesystem_cache_on_write_operations​

启用或禁用 write-through（直写）缓存。如果设为 false，则对写操作禁用直写缓存。如果设为 true，只要在服务器配置的缓存磁盘配置部分开启了 cache_on_write_operations，则启用直写缓存。详情参阅 "使用本地缓存"。

enable_filesystem_read_prefetches_log​

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

enable_full_text_index​

Beta 功能。了解更多。

别名: 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​

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

enable_join_runtime_filters​

Beta 功能。了解更多。

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

enable_lazy_columns_replication​

在 JOIN 和 ARRAY JOIN 中启用惰性列复制，这可以避免在内存中多次不必要地复制相同的行。

enable_lightweight_delete​

别名: allow_experimental_lightweight_delete

为 MergeTree 表启用轻量级 DELETE 变更（mutations）。

enable_lightweight_update​

Beta 功能。了解更多。

别名: allow_experimental_lightweight_update

允许使用轻量级更新。

enable_memory_bound_merging_of_aggregation_results​

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

enable_multiple_prewhere_read_steps​

将更多条件从 WHERE 移动到 PREWHERE，如果有多个由 AND 连接的条件，则分多个步骤进行磁盘读取和过滤。

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

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

结果

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

enable_parallel_blocks_marshalling​

仅影响分布式查询。如果启用，在发送到发起节点之前/之后，数据块将在流水线线程上（即以比默认更高的并行度）进行序列化/反序列化和压缩/解压缩。

enable_parsing_to_custom_serialization​

如果为 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）乱序生成 bucket。当聚合 bucket 大小倾斜时，这可以提高性能，因为它允许副本在仍在处理某些较重的低 ID bucket 时，将具有较高 ID 的 bucket 发送给发起节点。缺点是可能会增加内存使用量。

enable_reads_from_query_cache​

如果开启，SELECT 查询的结果将从 查询缓存 中检索。

可能的值

  • 0 - 禁用
  • 1 - 启用

enable_s3_requests_logging​

启用非常详尽的 S3 请求日志。仅对调试有意义。

enable_scalar_subquery_optimization​

如果设置为 true，防止标量子查询对大型标量值进行序列化/反序列化，并可能避免多次运行相同的子查询。

enable_scopes_for_with_statement​

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

注意，这是分析器的一个兼容性设置，目的是允许运行一些旧版分析器可以执行的无效查询。

enable_shared_storage_snapshot_in_query​

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

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

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

如果没有此设置，外部和内部查询可能在不同的数据快照上运行，导致结果不正确。

注意

启用此设置会禁用“在规划阶段完成后从快照中移除不必要数据部分”的优化。因此，运行时间较长的查询可能会在其整个持续时间内持有过时的部分，从而延迟数据部分的清理并增加存储压力。

此设置目前仅适用于 MergeTree 系列的表。

可能的值

  • 0 - 禁用
  • 1 - 启用

enable_sharing_sets_for_mutations​

允许在同一变更（mutation）的不同任务之间共享为 IN 子查询构建的 set 对象。这减少了内存使用和 CPU 消耗。

enable_software_prefetch_in_aggregation​

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

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 查询的结果将存储在 查询缓存 (query cache) 中。

可能的值

  • 0 - 禁用
  • 1 - 启用

enforce_strict_identifier_format​

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

engine_file_allow_create_multiple_files​

在文件 (file) 引擎表中，如果格式带有后缀（如 JSON、ORC、Parquet 等），则启用或禁用在每次插入时创建新文件。如果启用，每次插入都会创建一个按照此模式命名的文件：

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

可能的值

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

engine_file_empty_if_not_exists​

允许从没有文件的文件 (file) 引擎表中查询数据。

可能的值

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

engine_file_skip_empty_files​

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

可能的值

  • 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 统计信息提供精确值，但代价是必须完整读取限制前的数据。

except_default_mode​

设置 EXCEPT 查询的默认模式。可选值：空字符串、'ALL'、'DISTINCT'。如果为空，不带模式的查询将抛出异常。

exclude_materialize_skip_indexes_on_insert​

在 INSERT 过程中，排除指定的跳过索引 (skip indexes) 的构建和存储。被排除的跳过索引仍会在 合并期间 或通过显式的 MATERIALIZE INDEX 查询进行构建和存储。

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

示例

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

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

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

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

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

SET exclude_materialize_skip_indexes_on_insert = DEFAULT; -- reset setting to default

execute_exists_as_scalar_subquery​

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

external_storage_connect_timeout_sec​

连接超时时间（以秒为单位）。目前仅 MySQL 支持此设置。

external_storage_max_read_bytes​

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

external_storage_max_read_rows​

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

external_storage_rw_timeout_sec​

读/写超时时间（以秒为单位）。目前仅 MySQL 支持此设置。

external_table_functions_use_nulls​

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

可能的值

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

用法

如果设置为 0，表函数不生成 Nullable 列，并插入默认值而不是 NULL。这也适用于数组内部的 NULL 值。

external_table_strict_query​

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

extract_key_value_pairs_max_pairs_per_row​

别名: extract_kvp_max_pairs_per_row

extractKeyValuePairs 函数可以生成的最大键值对数量。用作防止消耗过多内存的保护措施。

extremes​

是否计算极值（查询结果列中的最小值和最大值）。接受 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

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

filesystem_cache_enable_background_download_for_metadata_files_in_packed_storage​

仅限 ClickHouse Cloud

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

filesystem_cache_max_download_size​

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

filesystem_cache_name​

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

filesystem_cache_prefer_bigger_buffer_size​

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

filesystem_cache_reserve_space_wait_lock_timeout_milliseconds​

在文件系统缓存中锁定缓存以进行空间预留的等待时间

filesystem_cache_segments_batch_size​

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

filesystem_cache_skip_download_if_exceeds_per_query_cache_write_limit​

别名: skip_download_if_exceeds_query_cache

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

filesystem_prefetch_max_memory_usage​

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

filesystem_prefetch_step_bytes​

以字节为单位的预取步长。零表示 auto - 将自动推导近似最佳的预取步长，但可能不是 100% 最佳。由于设置了 filesystem_prefetch_min_bytes_for_single_read_task，实际值可能会有所不同。

filesystem_prefetch_step_marks​

以标记 (marks) 为单位的预取步长。零表示 auto - 将自动推导近似最佳的预取步长，但可能不是 100% 最佳。由于设置了 filesystem_prefetch_min_bytes_for_single_read_task，实际值可能会有所不同。

filesystem_prefetches_limit​

最大预取数量。零表示无限制。如果您想限制预取数量，更推荐使用 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 │
└─────┴────────┘

flatten_nested​

设置 嵌套 (nested) 列的数据格式。

可能的值

  • 1 — 嵌套列被扁平化为单独的数组。
  • 0 — 嵌套列保持为单一的元组数组。

用法

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

示例

查询

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

SHOW CREATE TABLE t_nest;

结果

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

查询

SET flatten_nested = 0;

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

SHOW CREATE TABLE t_nest;

结果

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

force_aggregate_partitions_independently​

当优化适用但启发式算法决定不使用它时，强制使用优化。

force_aggregation_in_order​

该设置由服务器自身用于支持分布式查询。请勿手动修改，否则会破坏正常运行。（强制在分布式聚合期间对远程节点按顺序使用聚合）。

force_data_skipping_indices​

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

考虑以下示例

CREATE TABLE data
(
    key Int,
    d1 Int,
    d1_null Nullable(Int),
    INDEX d1_idx d1 TYPE minmax GRANULARITY 1,
    INDEX d1_null_idx assumeNotNull(d1_null) TYPE minmax GRANULARITY 1
)
Engine=MergeTree()
ORDER BY key;

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

force_grouping_standard_compatibility​

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

force_index_by_date​

如果索引不能通过日期使用，则禁用查询执行。

适用于 MergeTree 系列的表。

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

force_optimize_projection​

当投影优化启用时（参见 optimize_use_projections 设置），启用或禁用 SELECT 查询中对 投影 (projections) 的强制使用。

可能的值

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

force_optimize_projection_name​

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

可能的值

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

force_optimize_skip_unused_shards​

如果启用了 optimize_skip_unused_shards 且无法跳过未使用的分片，则启用或禁用查询执行。如果无法跳过且启用了此设置，将抛出异常。

可能的值

  • 0 — 禁用。ClickHouse 不会抛出异常。
  • 1 — 启用。仅当表具有分片键时，才禁用查询执行。
  • 2 — 启用。无论是否为表定义了分片键，都禁用查询执行。

force_optimize_skip_unused_shards_nesting​

控制 force_optimize_skip_unused_shards（因此仍需要启用 force_optimize_skip_unused_shards）是否取决于分布式查询的嵌套级别（例如 Distributed 表查询另一个 Distributed 表的情况）。

可能的值

  • 0 - 禁用，force_optimize_skip_unused_shards 始终生效。
  • 1 — 仅对第一层启用 force_optimize_skip_unused_shards。
  • 2 — 对最高第二层启用 force_optimize_skip_unused_shards。

force_primary_key​

如果无法通过主键进行索引，则禁用查询执行。

适用于 MergeTree 系列的表。

如果 force_primary_key=1，ClickHouse 会检查查询是否具有可用于限制数据范围的主键条件。如果没有合适的条件，它会抛出异常。但是，它不会检查该条件是否减少了读取的数据量。有关 MergeTree 表中数据范围的更多信息，请参阅 MergeTree。

force_remove_data_recursively_on_drop​

在执行 DROP 查询时递归删除数据。避免“目录非空”错误，但可能会静默删除分离的数据

formatdatetime_e_with_space_padding​

'formatDateTime' 函数中的格式化符 '%e' 在打印个位数日期时带有前导空格，例如 ' 2' 而不是 '2'。

formatdatetime_f_prints_scale_number_of_digits​

'formatDateTime' 函数中的格式化符 '%f' 为 DateTime64 仅打印精度对应数量的数字，而不是固定的 6 位数字。

formatdatetime_f_prints_single_zero​

'formatDateTime' 函数中的格式化符 '%f' 在格式化值没有秒小数部分时打印单个零，而不是六个零。

formatdatetime_format_without_leading_zeros​

'formatDateTime' 函数中的格式化符 '%c'、'%l' 和 '%k' 在打印月份和小时时不带前导零。

formatdatetime_parsedatetime_m_is_month_name​

'formatDateTime' 和 'parseDateTime' 函数中的格式化符 '%M' 打印/解析月份名称而不是分钟。

fsync_metadata​

启用或禁用在写入 .sql 文件时的 fsync。默认启用。

如果服务器上有数百万个经常创建和销毁的微型表，则禁用它是有意义的。

function_date_trunc_return_type_behavior​

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

可能的值

  • 0 - 当第二个参数是 DateTime64/Date32 时，返回类型将是 DateTime64/Date32，无论第一个参数的时间单位是什么。
  • 1 - 对于 Date32，结果始终为 Date。对于 DateTime64，当时间单位为 second 或更高时，结果为 DateTime。

function_implementation​

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

function_json_value_return_type_allow_complex​

控制是否允许 json_value 函数返回复杂类型（如：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 函数生成的数据量设置安全阈值。定义每个数据块由该函数生成的最大值数量（一个块中每行数组大小的总和）。

可能的值

  • 正整数。

参见

function_sleep_max_microseconds_per_block​

允许 sleep 函数为每个块睡眠的最大微秒数。如果用户调用的值大于此值，将抛出异常。这是一个安全阈值。

function_visible_width_behavior​

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

geo_distance_returns_float64_on_float64_arguments​

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

geotoh3_argument_order​

Beta 功能。了解更多。

如果设置为 'lon_lat'，则 'geoToH3' 函数接受 (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 填充。

参见

h3togeo_lon_lat_result_order​

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

handshake_timeout_ms​

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

hdfs_create_new_file_on_insert​

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

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

可能的值

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

hdfs_ignore_file_doesnt_exist​

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

可能的值

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

hdfs_replication​

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

hdfs_skip_empty_files​

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

可能的值

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

hdfs_throw_on_zero_files_match​

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

可能的值

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

hdfs_truncate_on_insert​

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

可能的值

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

hedged_connection_timeout_ms​

对对冲请求 (Hedged requests) 与副本建立连接的超时时间

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

hsts_max_age​

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

http_connection_timeout​

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

可能的值

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

http_headers_progress_interval_ms​

发送 HTTP 头信息 X-ClickHouse-Progress 的频率不高于指定的间隔。

http_make_head_request​

http_make_head_request 设置允许在从 HTTP 读取数据时执行 HEAD 请求，以检索有关要读取的文件信息（例如文件大小）。由于默认启用，在服务器不支持 HEAD 请求的情况下，可能需要禁用此设置。

http_max_field_name_size​

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

http_max_field_value_size​

HTTP 头中字段值的最大长度

http_max_fields​

HTTP 头中字段的最大数量

http_max_multipart_form_data_size​

限制 multipart/form-data 内容的大小。此设置无法从 URL 参数解析，应在用户配置文件中设置。请注意，内容解析和外部表创建是在查询执行开始之前的内存中进行的。这是在该阶段唯一生效的限制（最大内存使用和最大执行时间限制在读取 HTTP 表单数据时无效）。

http_max_request_param_data_size​

在预定义 HTTP 请求中用作查询参数的请求数据大小限制。

http_max_tries​

通过 http 读取的最大尝试次数。

http_max_uri_size​

设置 HTTP 请求的最大 URI 长度。

可能的值

  • 正整数。

http_native_compression_disable_checksumming_on_decompress​

启用或禁用在解压缩来自客户端的 HTTP POST 数据时的校验和验证。仅用于 ClickHouse 原生压缩格式（不适用于 gzip 或 deflate）。

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

可能的值

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

http_receive_timeout​

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

可能的值

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

http_response_buffer_size​

在向客户端发送 HTTP 响应或刷新到磁盘之前，在服务器内存中缓冲的字节数（启用 http_wait_end_of_query 时）。

http_response_headers​

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

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

该设置允许您将头信息设置为常量值。目前无法将头信息设置为动态计算的值。

名称或值均不能包含 ASCII 控制字符。

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

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

http_retry_initial_backoff_ms​

通过 http 重试读取时的最小退避毫秒数

http_retry_max_backoff_ms​

通过 http 重试读取时的最大退避毫秒数

http_send_timeout​

HTTP 发送超时时间（以秒为单位）。

可能的值

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

它仅适用于默认配置文件。需要重启服务器才能使更改生效。

http_skip_not_found_url_for_globs​

跳过出现 HTTP_NOT_FOUND 错误的 glob 通配符 URL

http_wait_end_of_query​

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

http_write_exception_in_output_format​

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

http_zlib_compression_level​

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

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

iceberg_delete_data_on_drop​

在执行 drop 操作时是否删除所有 iceberg 文件。

iceberg_insert_max_bytes_in_data_file​

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

iceberg_insert_max_partitions​

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

iceberg_insert_max_rows_in_data_file​

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

iceberg_metadata_compression_method​

实验性功能。 了解更多。

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

iceberg_metadata_log_level​

控制 Iceberg 表到 system.iceberg_metadata_log 的元数据日志记录级别。通常此设置可用于调试目的。

可能的值

  • none - 无元数据日志。
  • metadata - 根 metadata.json 文件。
  • manifest_list_metadata - 以上所有内容 + 对应快照的 avro 清单列表中的元数据。
  • manifest_list_entry - 以上所有内容 + avro 清单列表项。
  • manifest_file_metadata - 以上所有内容 + 遍历的 avro 清单文件中的元数据。
  • manifest_file_entry - 以上所有内容 + 遍历的 avro 清单文件项。

iceberg_snapshot_id​

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

iceberg_timestamp_ms​

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

idle_connection_timeout​

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

可能的值

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

ignore_cold_parts_seconds​

仅限 ClickHouse Cloud

仅在 ClickHouse Cloud 中生效。在 SELECT 查询中排除新的数据部分，直到它们完成预热（参见 cache_populated_by_fetch）或达到此设置的秒数。仅适用于 Replicated-/SharedMergeTree。

ignore_data_skipping_indices​

如果查询中使用了指定的跳过索引，则忽略它们。

考虑以下示例

CREATE TABLE data
(
    key Int,
    x Int,
    y Int,
    INDEX x_idx x TYPE minmax GRANULARITY 1,
    INDEX y_idx y TYPE minmax GRANULARITY 1,
    INDEX xy_idx (x,y) TYPE minmax GRANULARITY 1
)
Engine=MergeTree()
ORDER BY key;

INSERT INTO data VALUES (1, 2, 3);

SELECT * FROM data;
SELECT * FROM data SETTINGS ignore_data_skipping_indices=''; -- query will produce CANNOT_PARSE_TEXT error.
SELECT * FROM data SETTINGS ignore_data_skipping_indices='x_idx'; -- Ok.
SELECT * FROM data SETTINGS ignore_data_skipping_indices='na_idx'; -- Ok.

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

不忽略任何索引的查询

EXPLAIN indexes = 1 SELECT * FROM data WHERE x = 1 AND y = 2;

Expression ((Projection + Before ORDER BY))
  Filter (WHERE)
    ReadFromMergeTree (default.data)
    Indexes:
      PrimaryKey
        Condition: true
        Parts: 1/1
        Granules: 1/1
      Skip
        Name: x_idx
        Description: minmax GRANULARITY 1
        Parts: 0/1
        Granules: 0/1
      Skip
        Name: y_idx
        Description: minmax GRANULARITY 1
        Parts: 0/0
        Granules: 0/0
      Skip
        Name: xy_idx
        Description: minmax GRANULARITY 1
        Parts: 0/0
        Granules: 0/0

忽略 xy_idx 索引

EXPLAIN indexes = 1 SELECT * FROM data WHERE x = 1 AND y = 2 SETTINGS ignore_data_skipping_indices='xy_idx';

Expression ((Projection + Before ORDER BY))
  Filter (WHERE)
    ReadFromMergeTree (default.data)
    Indexes:
      PrimaryKey
        Condition: true
        Parts: 1/1
        Granules: 1/1
      Skip
        Name: x_idx
        Description: minmax GRANULARITY 1
        Parts: 0/1
        Granules: 0/1
      Skip
        Name: y_idx
        Description: minmax GRANULARITY 1
        Parts: 0/0
        Granules: 0/0

适用于 MergeTree 系列的表。

ignore_drop_queries_probability​

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

ignore_format_null_for_explain​

如果启用，FORMAT Null 将被 EXPLAIN 查询忽略，并改为使用默认输出格式。禁用时，带有 FORMAT Null 的 EXPLAIN 查询将不产生输出（向后兼容行为）。

ignore_materialized_views_with_dropped_target_table​

在向视图推送数据期间，忽略目标表已被删除的物化视图 (MV)

ignore_on_cluster_for_replicated_access_entities_queries​

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

ignore_on_cluster_for_replicated_database​

对于复制数据库的 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 rand()' 注入到没有 ORDER BY 子句的 SELECT 查询中。仅适用于子查询深度 = 0 的情况。子查询和 INSERT INTO ... SELECT 不受影响。如果顶层结构是 UNION，'ORDER BY rand()' 将独立注入到所有子句中。仅对测试和开发有用（缺少 ORDER BY 是导致查询结果非确定性的来源）。

insert_allow_materialized_columns​

如果启用，允许在 INSERT 中对物化列赋值。

insert_deduplicate​

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

可能的值

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

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

insert_deduplication_token​

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

可能的值

  • 任何字符串

insert_deduplication_token 仅在非空时用于去重。

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

注意

insert_deduplication_token 在分区级别生效（与 insert_deduplicate 校验和相同）。多个分区可以具有相同的 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);

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

-- the next insert will be deduplicated because insert_deduplication_token
-- is the same as one of the previous
INSERT INTO test_table SETTINGS insert_deduplication_token = 'test' VALUES (2);

SELECT * FROM test_table

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

insert_keeper_fault_injection_probability​

插入期间 keeper 请求失败的近似概率。有效值在 [0.0f, 1.0f] 区间内。

insert_keeper_fault_injection_seed​

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

insert_keeper_max_retries​

该设置规定了在向复制的 MergeTree 插入期间，ClickHouse Keeper (或 ZooKeeper) 请求的最大重试次数。只有因网络错误、Keeper 会话超时或请求超时而失败的 Keeper 请求才会被考虑重试。

可能的值

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

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​

启用或禁用在不可为 null 的数据类型列中插入 默认值 而不是 NULL。如果列类型不可为 null 且此设置被禁用，则插入 NULL 会引起异常。如果列类型可为 null，则无论此设置如何，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_parallel​

注意

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

启用或禁用法定人数 INSERT 查询的并行性。如果启用，可以在之前的查询尚未完成时发送额外的 INSERT 查询。如果禁用，对同一表的额外写入将被拒绝。

可能的值

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

参见

insert_quorum_timeout​

法定人数写入的超时时间（毫秒）。如果超时已过且尚未完成写入，ClickHouse 将产生异常，客户端必须重复查询以将相同的块写入到相同或任何其他副本。

参见

insert_shard_id​

如果非 0，指定 Distributed 表中将数据同步插入的分片 ID。

如果 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 log) 中收集 jemalloc 分配和释放样本。

jemalloc_enable_profiler​

为查询启用 jemalloc 剖析器。Jemalloc 将采样分配，以及采样分配的所有释放。剖析文件可以使用 SYSTEM JEMALLOC FLUSH PROFILE 刷新，用于分配分析。样本还可以使用配置 jemalloc_collect_global_profile_samples_in_trace_log 或查询设置 jemalloc_collect_profile_samples_in_trace_log 存储在 system.trace_log 中。请参阅 分配剖析 (Allocation Profiling)

join_algorithm​

指定使用哪种 JOIN 算法。

可以指定多种算法，并根据连接类型/严格程度和表引擎为特定查询选择可用的算法。

可能的值

  • grace_hash

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

Grace join 的第一阶段读取右表，并根据键列的哈希值将其拆分为 N 个桶（初始 N 为 grace_hash_join_initial_buckets）。这样做是为了确保每个桶都可以独立处理。第一个桶的行被添加到内存哈希表中，而其他行则保存到磁盘。如果哈希表增长超过内存限制（例如由 max_bytes_in_join 设置），则增加桶的数量并重新分配每行的桶。任何不属于当前桶的行都会被刷新并重新分配。

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

  • hash

使用 Hash join 算法。这是支持所有连接类型和严格程度组合的最通用实现，也支持在 JOIN ON 部分使用 OR 组合的多个连接键。

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

  • parallel_hash

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

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

  • partial_merge

sort-merge 算法 的变体，其中只有右表被完全排序。

RIGHT JOIN 和 FULL JOIN 仅在 ALL 严格程度下受支持（不支持 SEMI, ANTI, ANY, 和 ASOF）。

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

  • direct

direct（也称为嵌套循环）算法使用左表中的行作为键在右表中执行查找。特殊存储如 Dictionary, EmbeddedRocksDB, 和 MergeTree 表支持此算法。

对于 MergeTree 表，该算法将连接键过滤器直接下推到存储层。当键可以使用表的主键索引进行查找时，这可能更有效，否则它会对每个左表块执行右表的全表扫描。

支持 INNER 和 LEFT 连接，且仅支持没有其他条件的单列等值连接键。

  • auto

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

  • full_sorting_merge

在连接之前对参与连接的表进行完全排序的 Sort-merge 算法。

  • prefer_partial_merge

ClickHouse 始终尝试尽可能使用 partial_merge 连接，否则使用 hash。已弃用，等同于 partial_merge,hash。

  • default (已弃用)

旧版本值，请勿再使用。等同于 direct,hash，即尝试按顺序使用直接连接和哈希连接。

join_any_take_last_row​

更改 ANY 严格程度下连接操作的行为。

注意

此设置仅适用于与 Join 引擎表进行的 JOIN 操作。

可能的值

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

参见

join_default_strictness​

为 JOIN 子句 设置默认严格程度。

可能的值

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

join_on_disk_max_files_to_merge​

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

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

可能的值

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

join_output_by_rowlist_perkey_rows_threshold​

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

join_overflow_mode​

定义当达到任何连接限制时 ClickHouse 执行的操作

可能的值

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

默认值：THROW。

参见

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​

实验性功能。 了解更多。

如果运行时布隆过滤器中置位（set bits）的比例超过此比例，该过滤器将完全禁用以减少开销。

join_runtime_filter_blocks_to_skip_before_reenabling​

实验性功能。 了解更多。

在尝试动态重新启用之前因过滤率过低而被禁用的运行时过滤器之前，要跳过的数据块数量。

join_runtime_filter_exact_values_limit​

实验性功能。 了解更多。

运行时过滤器中以集合形式原样存储的最大元素数量，当超过此阈值时将切换为布隆过滤器。

join_runtime_filter_pass_ratio_threshold_for_disabling​

实验性功能。 了解更多。

如果通过行数与检查行数的比例大于此阈值，则该运行时过滤器被视为性能不佳，并针对接下来的 join_runtime_filter_blocks_to_skip_before_reenabling 个数据块禁用，以减少开销。

join_to_sort_maximum_table_rows​

实验性功能。 了解更多。

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

join_to_sort_minimum_perkey_rows​

实验性功能。 了解更多。

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

join_use_nulls​

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

可能的值

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

joined_block_split_single_row​

允许按左表中单行对应的行来拆分哈希连接结果。这可以在右表中存在大量匹配行的情况下减少内存使用，但可能会增加 CPU 使用率。注意，max_joined_block_size_rows != 0 是此设置生效的必要条件。max_joined_block_size_bytes 结合此设置有助于避免在某些大行与右表有大量匹配的偏斜数据情况下消耗过多内存。

joined_subquery_requires_alias​

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

kafka_disable_num_consumers_limit​

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

kafka_max_wait_ms​

重试前从 Kafka 读取消息的等待时间（毫秒）。

可能的值

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

参见

keeper_map_strict_mode​

在对 KeeperMap 进行操作期间强制执行额外检查。例如，在插入已存在的键时抛出异常。

keeper_max_retries​

一般 Keeper 操作的最大重试次数

keeper_retry_initial_backoff_ms​

一般 Keeper 操作的初始退避（backoff）超时时间

keeper_retry_max_backoff_ms​

一般 Keeper 操作的最大退避（backoff）超时时间

least_greatest_legacy_null_behavior​

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

legacy_column_name_of_tuple_literal​

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

lightweight_delete_mode​

作为轻量级删除（lightweight delete）的一部分执行的内部更新查询的模式。

可能的值

  • alter_update - 运行 ALTER UPDATE 查询，创建一个重量级突变（mutation）。
  • lightweight_update - 如果可能则运行轻量级更新，否则运行 ALTER UPDATE。
  • lightweight_update_force - 如果可能则运行轻量级更新，否则抛举异常。

lightweight_deletes_sync​

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

可能的值

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

参见

limit​

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

可能的值

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

load_balancing​

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

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

参见

随机 (默认)​

load_balancing = random

计算每个副本的错误数量。查询被发送到错误最少的副本，如果有多个这样的副本，则发送到其中任何一个。缺点：未考虑服务器邻近性；如果副本的数据不同，你也将得到不同的数据。

最近的主机名​

load_balancing = nearest_hostname

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

例如，example01-01-1 和 example01-01-2 在一个位置上不同，而 example01-01-1 和 example01-02-2 在两个地方不同。这种方法看似原始，但它不需要关于网络拓扑的外部数据，也不比较 IP 地址（比较我们的 IPv6 地址会很复杂）。

因此，如果存在同等的副本，优先选择名称最接近的副本。我们还可以假设，在发送查询到同一台服务器且没有故障的情况下，分布式查询也将转到相同的服务器。因此，即使副本上放置了不同的数据，查询返回的结果也基本相同。

主机名莱文斯坦距离​

load_balancing = hostname_levenshtein_distance

与 nearest_hostname 类似，但它以 莱文斯坦距离 (Levenshtein distance) 方式比较主机名。例如

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 标记（marks）

local_filesystem_read_method​

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

'io_uring' 方法是实验性的，不适用于 Log、TinyLog、StripeLog、File、Set 和 Join 以及其他在存在并发读写时具有追加式文件的表。如果你在互联网上阅读了各种关于 'io_uring' 的文章，请不要被它们蒙蔽。它并不是一种更好的文件读取方法，除非存在大量的小型 IO 请求（ClickHouse 并非这种情况）。没有理由启用 'io_uring'。

local_filesystem_read_prefetch​

从本地文件系统读取数据时是否应使用预取（prefetching）。

lock_acquire_timeout​

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

锁定超时用于在对表执行读/写操作时防止死锁。当超时过期且锁定请求失败时，ClickHouse 服务器会抛出异常 "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 表。

参见

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 中。

log_query_threads​

设置查询线程日志记录。

查询线程记录到 system.query_thread_log 表中。此设置仅在 log_queries 为 true 时生效。在此设置下由 ClickHouse 运行的查询线程将根据 query_thread_log 服务器配置参数中的规则进行记录。

可能的值

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

示例

log_query_threads=1

log_query_views​

设置查询视图日志记录。

当启用此设置的 ClickHouse 运行的查询具有关联视图（物化视图或实时视图）时，它们将被记录在 query_views_log 服务器配置参数中。

示例

log_query_views=1

low_cardinality_allow_in_native_format​

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

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

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

可能的值

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

low_cardinality_max_dictionary_size​

为可写入存储文件系统的 LowCardinality 数据类型设置共享全局字典的最大行数。此设置可防止在字典无限增长的情况下出现 RAM 问题。所有因最大字典大小限制而无法编码的数据，ClickHouse 将以普通方法写入。

可能的值

  • 任何正整数。

low_cardinality_use_single_dictionary_for_part​

开启或关闭为数据分区（part）使用单个字典。

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

可能的值

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

low_priority_query_wait_time_ms​

Beta 功能。了解更多。

当采用查询优先级机制时（参见设置 priority），低优先级查询会等待高优先级查询完成。此设置指定了等待的持续时间。

make_distributed_plan​

实验性功能。 了解更多。

生成分布式查询计划。

materialize_skip_indexes_on_insert​

INSERT 是否构建并存储跳数索引（skip indexes）。如果禁用，跳数索引将仅在 合并期间 或通过显式的 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）的错误，并且无论 MV 如何，都将原始数据块交付给表。

materialized_views_squash_parallel_inserts​

将来自并行插入的单个 INSERT 查询中指向物化视图目标表的插入操作进行压实（squash），以减少生成的分区数量。如果设置为 false 且启用了 parallel_view_processing，则 INSERT 查询将为每个 max_insert_thread 在目标表中生成一个分区。

max_analyze_depth​

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

max_ast_depth​

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

注意

目前，它不在解析期间检查，而仅在解析查询后检查。这意味着在解析期间可能会创建一个过深的语法树，但查询会失败。

max_ast_elements​

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

注意

目前，它不在解析期间检查，而仅在解析查询后检查。这意味着在解析期间可能会创建一个过深的语法树，但查询会失败。

max_autoincrement_series​

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

由于每个序列代表 Keeper 中的一个节点，建议其数量不超过数百万个。

max_backup_bandwidth​

服务器上特定备份的最大读取速度（字节/秒）。零表示不受限制。

max_block_size​

在 ClickHouse 中，数据按块（block）处理，块是列分区的集合。单个块的内部处理循环非常高效，但在处理每个块时会存在明显的成本。

max_block_size 设置指示从表中加载数据时，单个块中建议包含的最大行数。大小为 max_block_size 的块并不总是从表中加载：如果 ClickHouse 确定需要检索的数据较少，则会处理较小的块。

块大小不应太小，以避免处理每个块时产生明显的成本。它也不应太大，以确保带有 LIMIT 子句的查询在处理第一个块后能快速执行。设置 max_block_size 时，目标应该是避免在多线程提取大量列时消耗过多内存，并至少保留一些缓存局部性。

max_bytes_before_external_group_by​

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

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

可能的值

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

如果 GROUP BY 操作期间的内存使用量超过此阈值（字节），则激活“外部聚合”模式（将数据溢出到磁盘）。

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

max_bytes_before_external_sort​

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

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

可能的值

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

max_bytes_before_remerge_sort​

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

max_bytes_in_distinct​

使用 DISTINCT 时，哈希表在内存中使用的状态最大字节数（未压缩字节）。

max_bytes_in_join​

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

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

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

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

可能的值

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

max_bytes_in_set​

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

max_bytes_ratio_before_external_group_by​

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

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

max_bytes_ratio_before_external_sort​

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

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

请注意，max_bytes_before_external_sort 仍然有效，只有当排序块大于 max_bytes_before_external_sort 时才会执行溢出到磁盘。

max_bytes_to_read​

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

max_bytes_to_read_leaf​

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

例如，一个集群由 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，以便即使在服务器过载时也能运行查询进行调查。

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

可能的值

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

示例

<max_concurrent_queries_for_all_users>99</max_concurrent_queries_for_all_users>

参见

max_concurrent_queries_for_user​

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

可能的值

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

示例

<max_concurrent_queries_for_user>5</max_concurrent_queries_for_user>

max_distributed_connections​

分布式处理对单个 Distributed 表的单个查询时，与远程服务器的最大同时连接数。我们建议设置一个不小于集群中服务器数量的值。

以下参数仅在创建 Distributed 表（以及启动服务器）时使用，因此在运行时更改它们没有意义。

max_distributed_depth​

限制 Distributed 表递归查询的最大深度。

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

可能的值

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

max_download_buffer_size​

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

max_download_threads​

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

max_estimated_execution_time​

最大查询预估执行时间（秒）。当 timeout_before_checking_execution_speed 到期时，会在每个数据块上进行检查。

max_execution_speed​

每秒最大执行行数。当 timeout_before_checking_execution_speed 到期时，会在每个数据块上进行检查。如果执行速度过快，执行速度将被降低。

max_execution_speed_bytes​

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

max_execution_time​

最大查询执行时间（秒）。

max_execution_time 参数可能有点难以理解。它基于相对于当前查询执行速度的插值来操作（此行为由 timeout_before_checking_execution_speed 控制）。

如果预计执行时间超过指定的 max_execution_time，ClickHouse 将中断查询。默认情况下，timeout_before_checking_execution_speed 设置为 10 秒。这意味着在查询执行 10 秒后，ClickHouse 将开始估算总执行时间。例如，如果 max_execution_time 设置为 3600 秒（1 小时），如果预估时间超过这 3600 秒的限制，ClickHouse 将终止查询。如果将 timeout_before_checking_execution_speed 设置为 0，ClickHouse 将使用实际钟表时间作为 max_execution_time 的依据。

如果查询运行时超过指定的秒数，其行为将由 'timeout_overflow_mode' 决定，默认设置为 throw。

注意

超时在数据处理期间的指定位置进行检查，且查询只能在这些位置停止。目前，它无法在聚合状态合并期间或查询分析期间停止，实际运行时间将高于此设置的值。

max_execution_time_leaf​

语义上与 max_execution_time 类似，但仅应用于分布式或远程查询的叶节点。

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

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

我们可以使用 max_execution_time_leaf 作为查询设置

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

max_expanded_ast_elements​

别名和星号展开后查询语法树中的最大节点数量。

max_fetch_partition_retries_count​

从另一个主机获取分区时的重试次数。

max_final_threads​

为带有 FINAL 修饰符的 SELECT 查询数据读取阶段设置最大并行线程数。

可能的值

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

max_http_get_redirects​

允许的最大 HTTP GET 重定向跳转次数。确保实施了额外的安全措施，以防止恶意服务器将你的请求重定向到非预期的服务。\n\n这主要用于防止外部服务器重定向到一个看似属于公司基础架构内部的地址，通过向内部服务器发送 HTTP 请求，你可能会从内部网络请求内部 API，从而绕过身份验证，甚至查询 Redis 或 Memcached 等其他服务。当你没有内部基础架构（包括运行在本地主机上的内容），或者你信任该服务器时，允许重定向是安全的。但请记住，如果 URL 使用 HTTP 而不是 HTTPS，你不仅必须信任远程服务器，还必须信任你的 ISP 以及中间的每个网络。

max_hyperscan_regexp_length​

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

可能的值

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

示例

查询

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

结果

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

查询

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

结果

Exception: Regexp length too large.

参见

max_hyperscan_regexp_total_length​

设置每个 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_insert_block_size​

别名: max_insert_block_size_rows

为插入表而形成的数据块的最大大小（按行数计算）。

此设置控制格式解析中的数据块形成。当服务器从任何接口（HTTP、带有内联数据的 clickhouse-client、gRPC、PostgreSQL 线协议）解析基于行的输入格式（CSV、TSV、JSONEachRow 等）或 Values 格式时，它会使用此设置来确定何时发出一个块。注意：当使用 clickhouse-client 或 clickhouse-local 从文件读取时，客户端本身会解析数据，此设置应用于客户端。

当满足以下任一条件时发出块

  • 最小阈值 (AND)：同时达到 min_insert_block_size_rows 且达到 min_insert_block_size_bytes
  • 最大阈值 (OR)：达到 max_insert_block_size 或达到 max_insert_block_size_bytes

默认值略大于 max_block_size。其原因在于某些表引擎 (*MergeTree) 会为每个插入的块在磁盘上形成一个数据分区，这是一个相当大的实体。同样，*MergeTree 表在插入期间会对数据进行排序，足够大的块大小允许在 RAM 中排序更多数据。

可能的值

  • 正整数。

max_insert_block_size_bytes​

为插入表而形成的数据块的最大大小（以字节为单位）。

此设置与 max_insert_block_size_rows 协同工作，并在相同背景下控制块形成。有关何时以及如何应用这些设置的详细信息，请参阅 max_insert_block_size_rows。

可能的值

  • 正整数。
  • 0 — 设置不参与块形成。

max_insert_delayed_streams_for_parallel_write​

延迟最终分区刷盘的最大流（列）数。默认值为 auto（在底层存储支持并行写入时为 100，例如 S3，否则禁用）。

max_insert_threads​

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

可能的值

  • 0 (或 1) — INSERT SELECT 不并行执行。
  • 正整数，大于 1。

云端默认值

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

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

max_joined_block_size_bytes​

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

max_joined_block_size_rows​

JOIN 结果的最大块大小（按行数计算，如果连接算法支持）。0 表示不受限制。

max_limit_for_vector_search_queries​

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

max_local_read_bandwidth​

本地读取的最大速度（字节/秒）。

max_local_write_bandwidth​

本地写入的最大速度（字节/秒）。

max_memory_usage​

云端默认值：取决于副本上的 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 容量。零表示不受限制。

默认情况下，该容量不受限制 (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​

限制通过网络进行数据交换的速度（字节/秒）。此设置适用于服务器上所有并发运行的查询。

可能的值

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

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

可能的值

  • 正整数。

附加信息

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

注意

当涉及连接或子查询，且所有表都不符合某些要求时，此设置会产生不正确的结果。有关更多详细信息，请参见 分布式子查询和 max_parallel_replicas。

使用 SAMPLE 键的并行处理​

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

  • 采样键（sampling key）在分区键（partitioning key）中的位置不允许进行高效的范围扫描。
  • 向表中添加采样键会使按其他列进行过滤的效率降低。
  • 采样键是一个计算成本很高的表达式。
  • 集群延迟分布具有长尾效应，因此查询更多服务器会增加查询的整体延迟。

使用 parallel_replicas_custom_key 的并行处理​

此设置对任何复制表都很有用。

max_parser_backtracks​

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

max_parser_depth​

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

可能的值

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

max_parsing_threads​

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

max_partition_size_to_drop​

查询时删除分区的限制。值 0 表示可以不受任何限制地删除分区。

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

注意

此设置是一个安全阈值，因为使用大量分区是一个常见的误解。

max_partitions_to_read​

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

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

可能的值

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

你还可以在表设置中指定 MergeTree 设置 max_partitions_to_read。

max_parts_to_move​

限制在一个查询中可以移动的分区（parts）数量。零表示不受限制。

max_projection_rows_to_use_projection_index​

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

max_query_size​

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

注意

max_query_size 不能在 SQL 查询中设置（例如 SELECT now() SETTINGS max_query_size=10000），因为 ClickHouse 需要分配一个缓冲区来解析查询，而该缓冲区的大小由 max_query_size 设置决定，该设置必须在查询执行前配置好。

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​

云默认值：0。

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

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

max_reverse_dictionary_lookup_cache_size_bytes​

由函数 dictGetKeys 使用的每个查询的反向字典查找缓存的最大字节数。该缓存为每个属性值存储序列化的键元组，以避免在同一查询中重新扫描字典。当达到限制时，使用 LRU 算法剔除条目。设置为 0 以禁用缓存。

max_rows_in_distinct​

使用 DISTINCT 时最大不同行数。

max_rows_in_join​

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

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

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

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

可能的值

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

max_rows_in_set​

从子查询创建的 IN 子句中数据集的最大行数。

max_rows_in_set_to_optimize_join​

在连接之前，通过彼此的行集过滤被连接表的最大集合大小。

可能的值

  • 0 — 禁用。
  • 任何正整数。

max_rows_to_group_by​

从聚合中接收到的最大唯一键数量。此设置允许你在聚合时限制内存消耗。

如果 GROUP BY 期间的聚合生成的行数（唯一 GROUP BY 键）超过指定数量，行为将由 'group_by_overflow_mode' 决定，默认值为 throw，但也可以切换到近似 GROUP BY 模式。

max_rows_to_read​

运行查询时可以从表中读取的最大行数。会对处理的每个数据块进行限制检查，仅应用于最深层的表表达式，且在从远程服务器读取时，仅在远程服务器上检查。

max_rows_to_read_leaf​

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

例如，一个集群由 2 个分片组成，每个分片包含一个具有 100 行的表。如果设置 max_rows_to_read=150，打算从这两个表中读取所有数据的分布式查询将会失败，因为总共会有 200 行。而设置 max_rows_to_read_leaf=150 的查询将会成功，因为叶节点最多读取 100 行。

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

注意

当 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 服务器的最大并发会话数。

示例

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

可能的值

  • 正整数
  • 0 - 无限并发会话数（默认）

max_size_to_preallocate_for_aggregation​

在聚合之前，允许在所有哈希表中总共预分配空间的最大元素数量

max_size_to_preallocate_for_joins​

在连接之前，允许在所有哈希表中总共预分配空间的最大元素数量

max_streams_for_files_processing_in_cluster_functions​

如果非零，限制在 *Cluster 表函数中从文件读取数据的线程数。

max_streams_for_merge_tree_reading​

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

max_streams_multiplier_for_merge_tables​

从 Merge 表读取时请求更多流。流将分布在 Merge 表将使用的各个表之间。这使得工作在线程之间的分配更加均匀，在合并后的表大小不一时特别有用。

max_streams_to_max_threads_ratio​

允许你使用比线程数更多的源，以便更均匀地在线程之间分配工作。假定这是一个临时解决方案，因为将来可以使源的数量等于线程的数量，但每个源可以动态地为其自身选择可用的工作。

max_subquery_depth​

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

提示

这允许你进行健全性检查，以保护你的集群用户免于编写过于复杂的查询。

max_table_size_to_drop​

查询时删除表的限制。值 0 表示可以不受任何限制地删除所有表。

云端默认值：1 TB。

注意

此查询设置会覆盖其对应的服务器设置，请参阅 max_table_size_to_drop

max_temporary_columns​

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

提示

此设置对于防止过于复杂的查询非常有用。

0 值表示不受限制。

max_temporary_data_on_disk_size_for_query​

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

可能的值

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

max_temporary_data_on_disk_size_for_user​

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

可能的值

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

max_temporary_non_const_columns​

与 max_temporary_columns 类似，即运行查询时必须同时保留在 RAM 中的临时列的最大数量，但不计算常量列。

注意

运行查询时形成常量列的情况相当普遍，但它们几乎不消耗计算资源。

max_threads​

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

此参数适用于并行执行查询处理流水线中相同阶段的线程。例如，在从表读取数据时，如果可以使用至少 'max_threads' 个线程并行评估带函数的表达式、使用 WHERE 进行过滤以及为 GROUP BY 进行预聚合，则将使用 'max_threads' 个线程。

对于因 LIMIT 而快速完成的查询，您可以设置较低的 'max_threads'。例如，如果每个数据块中都包含必要的条目数且 max_threads = 8，那么即使只需读取一个数据块就足够了，系统仍会检索 8 个数据块。max_threads 值越小，消耗的内存就越少。

默认情况下，max_threads 设置与 ClickHouse 可用的硬件线程数（CPU 核心数）相匹配。作为特殊情况，对于少于 32 个 CPU 核心并支持 SMT（例如 Intel 超线程）的 x86 处理器，ClickHouse 默认使用逻辑核心数（= 2 x 物理核心数）。

如果没有 SMT（例如 Intel 超线程），这对应于 CPU 核心数。

对于 ClickHouse Cloud 用户，默认值将显示为 auto(N)，其中 N 与您服务的 vCPU 大小匹配，例如 2vCPU/8GiB、4vCPU/16GiB 等。有关所有服务规格的列表，请参阅 Cloud 控制台中的设置选项卡。

max_threads_for_indexes​

处理索引的最大线程数。

max_untracked_memory​

较小的内存分配和释放会被组合在线程局部变量中，并且仅当金额（绝对值）大于指定值时才会进行跟踪或分析。如果该值高于 'memory_profiler_step'，它将被有效地降低到 'memory_profiler_step'。

memory_overcommit_ratio_denominator​

它表示当全局层面达到硬性限制时的软性内存限制。此值用于计算查询的超量使用比例（overcommit ratio）。零表示跳过该查询。阅读更多关于 内存超量使用 (memory overcommit) 的信息。

memory_overcommit_ratio_denominator_for_user​

它表示当用户层面达到硬性限制时的软性内存限制。此值用于计算查询的超量使用比例。零表示跳过该查询。阅读更多关于 内存超量使用 (memory overcommit) 的信息。

memory_profiler_sample_max_allocation_size​

以 memory_profiler_sample_probability 的概率收集大小小于或等于指定值的随机分配。0 表示禁用。您可能需要将 'max_untracked_memory' 设置为 0，以使此阈值按预期工作。

memory_profiler_sample_min_allocation_size​

以 memory_profiler_sample_probability 的概率收集大小大于或等于指定值的随机分配。0 表示禁用。您可能需要将 'max_untracked_memory' 设置为 0，以使此阈值按预期工作。

memory_profiler_sample_probability​

收集随机分配和释放，并以 'MemorySample' 跟踪类型写入 system.trace_log。该概率适用于每次分配/释放，无论分配的大小如何（可以通过 memory_profiler_sample_min_allocation_size 和 memory_profiler_sample_max_allocation_size 更改）。请注意，采样仅在未跟踪的内存量超过 'max_untracked_memory' 时发生。您可能需要将 'max_untracked_memory' 设置为 0 以进行超精细采样。

memory_profiler_step​

设置内存分析器的步长。每当查询内存使用量超过下一个字节步长时，内存分析器将收集分配堆栈跟踪并将其写入 trace_log。

可能的值

  • 正整数（字节数）。

  • 0 用于关闭内存分析器。

memory_tracker_fault_probability​

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

memory_usage_overcommit_max_wait_microseconds​

在用户级别内存超量使用的情况下，线程等待内存释放的最长时间。如果达到超时时间且内存未释放，则抛出异常。阅读更多关于 内存超量使用 (memory overcommit) 的信息。

merge_table_max_tables_to_look_for_schema_inference​

在创建没有显式模式的 Merge 表或使用 merge 表函数时，将模式推断为不超过指定数量的匹配表的并集。如果表的数量较多，则模式将根据前指定数量的表进行推断。

merge_tree_coarse_index_granularity​

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

可能的值

  • 任何正偶数。

merge_tree_compact_parts_min_granules_to_multibuffer_read​

仅限 ClickHouse Cloud

仅在 ClickHouse Cloud 中生效。MergeTree 表紧凑分区（compact part）的分条中，使用支持并行读取和预取的 multibuffer 读取器的颗粒（granule）数量。在从远程文件系统读取时，使用 multibuffer 读取器会增加读取请求的数量。

merge_tree_determine_task_size_by_prewhere_columns​

是否仅使用 prewhere 列的大小来确定读取任务的大小。

merge_tree_max_bytes_to_use_cache​

如果 ClickHouse 在单次查询中读取的字节数超过 merge_tree_max_bytes_to_use_cache，则不使用未压缩块的缓存。

未压缩块缓存存储为查询提取的数据。ClickHouse 使用此缓存来加速对重复性小查询的响应。此设置可防止读取大量数据的查询刷掉缓存中的有用信息。服务器设置 uncompressed_cache_size 定义了未压缩块缓存的大小。

可能的值

  • 任何正整数。

merge_tree_max_rows_to_use_cache​

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

未压缩块缓存存储为查询提取的数据。ClickHouse 使用此缓存来加速对重复性小查询的响应。此设置可防止读取大量数据的查询刷掉缓存中的有用信息。服务器设置 uncompressed_cache_size 定义了未压缩块缓存的大小。

可能的值

  • 任何正整数。

merge_tree_min_bytes_for_concurrent_read​

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

可能的值

  • 正整数。

merge_tree_min_bytes_for_concurrent_read_for_remote_filesystem​

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

可能的值

  • 正整数。

merge_tree_min_bytes_for_seek​

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

可能的值

  • 任何正整数。

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 分区中，启用线程池进行并行前缀读取。该线程池的大小由服务器设置 max_prefixes_deserialization_thread_pool_size 控制。

merge_tree_use_v1_object_and_dynamic_serialization​

启用后，MergeTree 中将使用 JSON 和 Dynamic 类型的 V1 序列化版本而非 V2。更改此设置仅在服务器重启后生效。

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 选项从存储磁盘读取数据。

可能的值

  • 0 — 禁用直接 I/O。
  • 正整数。

min_bytes_to_use_mmap_io​

这是一个实验性设置。设置读取大文件时无需将数据从内核拷贝到用户空间的最小内存量。推荐的阈值约为 64 MB，因为 mmap/munmap 较慢。它仅对大型文件有意义，并且只有在数据驻留在页面缓存中时才有帮助。

可能的值

  • 正整数。
  • 0 — 大文件读取时仅通过将数据从内核拷贝到用户空间进行。

min_chunk_bytes_for_parallel_parsing​

  • 类型：unsigned int
  • 默认值：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，因此每两个标记会形成一个压缩块。

我们正在写入一个 String 类型的 URL 列（平均每个值 60 字节）。写入 8192 行时，平均数据量略小于 500 KB。由于这超过了 65,536，因此会为每个标记形成一个压缩块。在这种情况下，当从磁盘读取单个标记范围内的数据时，多余的数据不会被解压缩。

注意

这是一项专家级设置，如果您刚开始使用 ClickHouse，不应更改它。

min_count_to_compile_aggregate_expression​

开始 JIT 编译所需的相同聚合表达式的最小数量。仅当启用了 compile_aggregate_expressions 设置时才有效。

可能的值

  • 正整数。
  • 0 — 相同的聚合表达式始终进行 JIT 编译。

min_count_to_compile_expression​

同一个表达式在编译前执行的最小次数。

min_count_to_compile_sort_description​

在 JIT 编译之前的相同排序描述的数量。

min_execution_speed​

最小执行速度（以每秒行数为单位）。每当 timeout_before_checking_execution_speed 到期时，都会在每个数据块上进行检查。如果执行速度较低，则抛出异常。

min_execution_speed_bytes​

每秒执行的最小字节数。每当 timeout_before_checking_execution_speed 到期时，都会在每个数据块上进行检查。如果执行速度较低，则抛出异常。

min_external_table_block_size_bytes​

如果数据块不够大，则将传递给外部表的数据块合并到指定的字节大小。

min_external_table_block_size_rows​

如果数据块不够大，则将传递给外部表的数据块合并到指定的行数大小。

min_free_disk_bytes_to_perform_insert​

执行插入所需的最小可用磁盘空间字节数。

min_free_disk_ratio_to_perform_insert​

执行插入所需的最小可用磁盘空间比例。

min_free_disk_space_for_temporary_data​

在写入用于外部排序和聚合的临时数据时保留的最小磁盘空间。

min_hit_rate_to_use_consecutive_keys_optimization​

在聚合中用于连续键优化的缓存的最小命中率，以使其保持启用状态。

min_insert_block_size_bytes​

为插入表而形成的块的最小大小（以字节为单位）。

此设置与 min_insert_block_size_rows 配合使用，并在相同的上下文（格式解析和 INSERT 操作）中控制块的形成。有关何时以及如何应用这些设置的详细信息，请参见 min_insert_block_size_rows。

可能的值

  • 正整数。
  • 0 — 设置不参与块形成。

min_insert_block_size_bytes_for_materialized_views​

设置可通过 INSERT 查询插入表的块中的最小字节数。较小的块将被合并为较大的块。此设置仅适用于插入到 物化视图 中的块。通过调整此设置，您可以控制推送到物化视图时的块合并，并避免过度的内存使用。

可能的值

  • 任何正整数。
  • 0 — 禁用合并。

参见

min_insert_block_size_rows​

为插入表而形成的块的最小大小（以行数为单位）。

此设置在两个上下文中控制块的形成：

  1. 格式解析：当服务器从任何接口（HTTP、带有内联数据的 clickhouse-client、gRPC、PostgreSQL 有线协议等）解析基于行的输入格式（CSV、TSV、JSONEachRow 等）时，它使用此设置来确定何时发出一个块。注意：使用 clickhouse-client 或 clickhouse-local 从文件读取时，客户端本身会解析数据，此设置在客户端应用。
  2. INSERT 操作：在 INSERT...SELECT 查询期间以及当数据流经物化视图时，在写入存储之前，会根据此设置合并块。

在格式解析中，当满足任一条件时就会发出一个块。

  • 最小阈值 (AND)：同时达到 min_insert_block_size_rows 且达到 min_insert_block_size_bytes
  • 最大阈值 (OR)：达到 max_insert_block_size 或达到 max_insert_block_size_bytes

用于插入操作的较小尺寸的块会被合并成较大的块，并在满足 min_insert_block_size_rows 或 min_insert_block_size_bytes 之一时发出。

可能的值

  • 正整数。
  • 0 — 设置不参与块形成。

min_insert_block_size_rows_for_materialized_views​

设置可通过 INSERT 查询插入表的块中的最小行数。较小的块将被合并为较大的块。此设置仅适用于插入到 物化视图 中的块。通过调整此设置，您可以控制推送到物化视图时的块合并，并避免过度的内存使用。

可能的值

  • 任何正整数。
  • 0 — 禁用合并。

参见

min_joined_block_size_bytes​

JOIN 输入和输出块的最小字节大小（如果连接算法支持）。小块将被合并。0 表示无限制。

min_joined_block_size_rows​

JOIN 输入和输出块的最小行数大小（如果连接算法支持）。小块将被合并。0 表示无限制。

min_os_cpu_wait_time_ratio_to_throw​

考虑拒绝查询的操作系统 CPU 等待时间（OSCPUWaitMicroseconds 指标）与繁忙时间（OSCPUVirtualTimeMicroseconds 指标）之间的最小比率。最小比率和最大比率之间的线性插值用于计算概率，该点处的概率为 0。

min_outstreams_per_resize_after_split​

指定管道生成期间执行拆分后，Resize 或 StrictResize 处理器的最小输出流数量。如果生成的流数量小于此值，则不会发生拆分操作。

什么是 Resize 节点​

Resize 节点是查询管道中的处理器，用于调整流经管道的数据流数量。它可以增加或减少流的数量，以平衡多个线程或处理器之间的工作负载。例如，如果查询需要更高的并行度，Resize 节点可以将单个流拆分为多个流。反之，它可以将多个流合并为较少的流，以巩固数据处理。

Resize 节点确保数据在流之间均匀分布，并维持数据块的结构。这有助于优化资源利用率并提高查询性能。

为什么 Resize 节点需要拆分​

在管道执行期间，中心集线式的 Resize 节点的 ExecutingGraph::Node::status_mutex 会发生严重竞争，尤其是在高核心数的环境中，这种竞争会导致：

  1. ExecutingGraph::updateNode 的延迟增加，直接影响查询性能。
  2. 在自旋锁竞争（native_queued_spin_lock_slowpath）中浪费过多的 CPU 周期，降低了效率。
  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​

在重写多个连接时不向顶层表达式列表添加别名。

mutations_execute_nondeterministic_on_initiator​

如果为 true，常量非确定性函数（例如函数 now()）将在发起者上执行，并在 UPDATE 和 DELETE 查询中替换为字面量。这有助于在执行带有常量非确定性函数的变动（mutations）时保持副本间的数据同步。默认值：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 查询（变动/mutations）。

可能的值

值描述
0突变异步执行。
1查询等待当前服务器上所有变动完成。
2查询等待所有副本（如果存在）上所有变动完成。
3查询仅等待活跃副本。仅 SharedMergeTree 支持。对于 ReplicatedMergeTree，其行为与 mutations_sync = 2 相同。

mysql_datatypes_support_level​

定义 MySQL 类型如何转换为相应的 ClickHouse 类型。由 decimal、datetime64、date2Date32 或 date2String 的任意组合组成的以逗号分隔的列表。

  • decimal：在精度允许的情况下，将 NUMERIC 和 DECIMAL 类型转换为 Decimal。
  • datetime64：当精度不为 0 时，将 DATETIME 和 TIMESTAMP 类型转换为 DateTime64 而非 DateTime。
  • date2Date32：将 DATE 转换为 Date32 而非 Date。优先级高于 date2String。
  • date2String：将 DATE 转换为 String 而非 Date。会被 datetime64 覆盖。

mysql_map_fixed_string_to_text_in_show_columns​

启用后，FixedString ClickHouse 数据类型在 SHOW COLUMNS 中将显示为 TEXT。

仅当通过 MySQL 有线协议建立连接时才有效。

  • 0 - 使用 BLOB。
  • 1 - 使用 TEXT。

mysql_map_string_to_text_in_show_columns​

启用后，String ClickHouse 数据类型在 SHOW COLUMNS 中将显示为 TEXT。

仅当通过 MySQL 有线协议建立连接时才有效。

  • 0 - 使用 BLOB。
  • 1 - 使用 TEXT。

mysql_max_rows_to_insert​

MySQL 存储引擎中 MySQL 批量插入的最大行数。

network_compression_method​

用于压缩客户端/服务器和服务器/服务器通信的编解码器。

可能的值

  • NONE — 不压缩。
  • LZ4 — 使用 LZ4 编解码器。
  • LZ4HC — 使用 LZ4HC 编解码器。
  • ZSTD — 使用 ZSTD 编解码器。

参见

network_zstd_compression_level​

调整 ZSTD 压缩级别。仅当 network_compression_method 设置为 ZSTD 时使用。

可能的值

  • 1 到 15 之间的正整数。

normalize_function_names​

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

number_of_mutations_to_delay​

如果发生变动的表包含至少这么多未完成的变动，则人为减慢该表的变动速度。0 - 禁用。

number_of_mutations_to_throw​

如果发生变动的表包含至少这么多未完成的变动，则抛出 'Too many mutations ...' 异常。0 - 禁用。

odbc_bridge_connection_pool_size​

ODBC 桥接器中每个连接设置字符串的连接池大小。

odbc_bridge_use_connection_pooling​

在 ODBC 桥接器中使用连接池。如果设置为 false，则每次都会创建一个新连接。

offset​

设置在开始从查询返回行之前要跳过的行数。它调整由 OFFSET 子句设置的偏移量，使这两个值相加。

可能的值

  • 0 — 不跳过任何行。
  • 正整数。

示例

输入表

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

查询

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

结果

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

opentelemetry_start_keeper_trace_probability​

为 ZooKeeper 请求启动跟踪的概率 - 无论是否存在父级跟踪。

可能的值

  • 'auto' - 等于 opentelemetry_start_trace_probability 设置
  • 0 — 禁用跟踪
  • 0 到 1 — 概率（例如，1.0 = 始终启用）

opentelemetry_start_trace_probability​

设置 ClickHouse 为执行的查询启动跟踪的概率（如果未提供父级 跟踪上下文/trace context）。

可能的值

  • 0 — 禁用所有执行查询的跟踪（如果未提供父级跟踪上下文）。
  • [0..1] 范围内的正浮点数。例如，如果设置值为 0.5，ClickHouse 平均可以为一半的查询启动跟踪。
  • 1 — 启用所有执行查询的跟踪。

opentelemetry_trace_cpu_scheduling​

为工作负载抢占式 CPU 调度收集 OpenTelemetry span。

opentelemetry_trace_processors​

为处理器收集 OpenTelemetry span。

optimize_aggregation_in_order​

在 SELECT 查询中为 MergeTree 表按相应顺序聚合数据启用 GROUP BY 优化。

可能的值

  • 0 — 禁用 GROUP BY 优化。
  • 1 — 启用 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_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 — 启用。

参见

注意

目前它需要 optimize_skip_unused_shards（其背后的原因是：它将来可能会默认启用，并且只有在数据通过 Distributed 表插入时它才能正确工作，即数据根据分片键分布）。

optimize_empty_string_comparisons​

仅当 col 为 String 或 FixedString 类型时，将 col = '' 或 '' = col 之类的表达式转换为 empty(col)，将 col != '' 或 '' != col 转换为 notEmpty(col)。

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​

通过将某些函数转换为读取子列来启用或禁用优化。这减少了读取的数据量。

可以转换这些函数：

可能的值

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

optimize_group_by_constant_keys​

当数据块中所有键都是常量时，优化 GROUP BY。

optimize_group_by_function_keys​

消除 GROUP BY 部分中其他键的函数。

optimize_if_chain_to_multiif​

将 if(cond1, then1, if(cond2, ...)) 链替换为 multiIf。目前这对数值类型没有益处。

optimize_if_transform_strings_to_enum​

将 If 和 Transform 中的字符串类型参数替换为枚举。默认禁用，因为它可能会在分布式查询中引起不一致的变化，从而导致失败。

optimize_injective_functions_in_group_by​

在 GROUP BY 部分将单射函数替换为它的参数。

optimize_injective_functions_inside_uniq​

删除 uniq*() 函数内部的单参数单射函数。

optimize_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 表。

可能的值

  • 0 — 禁用带有 FINAL 修饰符的 SELECT 查询中的自动 PREWHERE 优化。
  • 1 — 启用带有 FINAL 修饰符的 SELECT 查询中的自动 PREWHERE 优化。

参见

optimize_multiif_to_if​

将仅包含一个条件的 'multiIf' 替换为 'if'。

optimize_normalize_count_variants​

将语义上等同于 count() 的聚合函数重写为 count()。

optimize_on_insert​

启用或禁用在插入之前进行数据转换，就好像在这个数据块上已经执行了合并（根据表引擎）一样。

可能的值

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

示例

启用和禁用之间的区别。

查询

SET optimize_on_insert = 1;

CREATE TABLE test1 (`FirstTable` UInt32) ENGINE = ReplacingMergeTree ORDER BY FirstTable;

INSERT INTO test1 SELECT number % 2 FROM numbers(5);

SELECT * FROM test1;

SET optimize_on_insert = 0;

CREATE TABLE test2 (`SecondTable` UInt32) ENGINE = ReplacingMergeTree ORDER BY SecondTable;

INSERT INTO test2 SELECT number % 2 FROM numbers(5);

SELECT * FROM test2;

结果

┌─FirstTable─┐
│          0 │
│          1 │
└────────────┘

┌─SecondTable─┐
│           0 │
│           0 │
│           0 │
│           1 │
│           1 │
└─────────────┘

请注意，此设置会影响 物化视图 (Materialized view) 的行为。

optimize_or_like_chain​

将多个 OR LIKE 优化为 multiMatchAny。此优化不应默认启用，因为在某些情况下它会违背索引分析。

optimize_qbit_distance_function_reads​

将 QBit 数据类型上的距离函数替换为仅从存储中读取计算所需列的等效函数。

optimize_read_in_order​

在从 MergeTree 表读取数据的 SELECT 查询中启用 ORDER BY 优化。

可能的值

  • 0 — 禁用 ORDER BY 优化。
  • 1 — 启用 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 表达式作为参数的聚合函数。例如，avg(if(cond, col, null)) 可以重写为 avgOrNullIf(cond, col)。这可以提高性能。

注意

仅在启用分析器时支持 (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​

如果只有一个级别 > 0 的分区且该分区没有过期的 TTL，则启用或禁用 OPTIMIZE TABLE ... FINAL 查询的优化。

  • OPTIMIZE TABLE ... FINAL SETTINGS optimize_skip_merged_partitions=1

默认情况下，即使只有一个分区，OPTIMIZE TABLE ... FINAL 查询也会重写该分区。

可能的值

  • 1 - 启用优化。
  • 0 - 禁用优化。

optimize_skip_unused_shards​

对于在 WHERE/PREWHERE 中具有分片键条件的 SELECT 查询，启用或禁用跳过未使用的分片，并激活分布式查询的相关优化（例如按分片键聚合）。

注意

假设数据是按分片键分布的，否则查询会产生不正确的结果。

可能的值

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

optimize_skip_unused_shards_limit​

分片键值的数量限制，如果达到限制则关闭 optimize_skip_unused_shards。

过多的值可能需要大量的处理，而收益却值得怀疑，因为如果您在 IN (...) 中有大量值，那么查询很可能无论如何都会被发送到所有分片。

optimize_skip_unused_shards_nesting​

控制 optimize_skip_unused_shards（因此仍需要 optimize_skip_unused_shards）是否取决于分布式查询的嵌套级别（例如您有一个 Distributed 表指向另一个 Distributed 表）。

可能的值

  • 0 — 禁用，optimize_skip_unused_shards 始终有效。
  • 1 — 仅为第一层启用 optimize_skip_unused_shards。
  • 2 — 为最多第二层启用 optimize_skip_unused_shards。

optimize_skip_unused_shards_rewrite_in​

重写发往远程分片的查询中的 IN，以排除不属于该分片的值（需要 optimize_skip_unused_shards）。

可能的值

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

optimize_sorting_by_input_stream_properties​

根据输入流的排序属性优化排序。

optimize_substitute_columns​

使用 约束 进行列替换。默认为 false。

可能的值

  • true, false

optimize_syntax_fuse_functions​

启用融合具有相同参数的聚合函数。它将包含至少两个针对相同参数的 sum, count 或 avg 的查询重写为 sumCount。

可能的值

  • 0 — 具有相同参数的函数不被融合。
  • 1 — 具有相同参数的函数被融合。

示例

查询

CREATE TABLE fuse_tbl(a Int8, b Int8) Engine = Log;
SET optimize_syntax_fuse_functions = 1;
EXPLAIN SYNTAX 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 查询没有执行合并，启用或禁用抛出异常。

默认情况下，即使 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），在平凡计数（trivial count）优化中使用近似值。

可能的值

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

optimize_trivial_count_query​

启用或禁用对 SELECT count() FROM table 使用来自 MergeTree 元数据的平凡查询优化。如果您需要使用行级安全（row-level security），请禁用此设置。

可能的值

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

参见

optimize_trivial_insert_select​

优化简单的 'INSERT INTO table SELECT ... FROM TABLES' 查询。

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 查询时启用或禁用 投影 (projection) 优化。

可能的值

  • 0 — 禁用投影优化。
  • 1 — 启用投影优化。

optimize_using_constraints​

使用 约束 进行查询优化。默认为 false。

可能的值

  • true, false

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

在用户空间页面缓存（userspace page cache）中存储的文件块大小，以字节为单位。所有通过缓存进行的读取操作都将向上取整为此大小的倍数。

此设置可以在单个查询级别进行调整，但具有不同块大小的缓存条目无法重复使用。更改此设置将使缓存中现有的条目失效。

较高的值（如 1 MiB）适用于高吞吐量查询，而较低的值（如 64 KiB）适用于低延迟的点查询。

page_cache_inject_eviction​

用户空间页面缓存有时会随机使某些页面失效。旨在用于测试。

page_cache_lookahead_blocks​

当用户空间页面缓存未命中时，如果底层存储中连续的块也不在缓存中，则一次性从底层存储中读取最多此数量的连续块。每个块的大小为 page_cache_block_size 字节。

较高的值适用于高吞吐量查询，而低延迟点查询在没有预读的情况下效果更好。

parallel_distributed_insert_select​

启用并行分布式 INSERT ... SELECT 查询。

如果我们执行 INSERT INTO distributed_table_a SELECT ... FROM distributed_table_b 查询，且两张表使用相同的集群，并且两张表要么都是副本表，要么都不是副本表，那么该查询将在每个分片上本地处理。

可能的值

  • 0 — 禁用。
  • 1 — SELECT 将在每个分片的分布式引擎底层表上执行。
  • 2 — SELECT 和 INSERT 都将在每个分片的分布式引擎底层表上执行。

使用此设置时，需要将 enable_parallel_replicas = 1。

parallel_hash_join_threshold​

当应用基于哈希的连接（join）算法时，此阈值有助于在 hash 和 parallel_hash 之间做出决定（仅在右表大小估算可用时）。当我们知道右表大小低于阈值时，使用前者。

parallel_replica_offset​

Beta 功能。了解更多。

这是一个内部设置，不应直接使用，它代表了“并行副本”模式的实现细节。此设置将由发起者服务器针对分布式查询自动设置为参与并行副本查询处理的副本索引。

parallel_replicas_allow_in_with_subquery​

如果为 true，IN 操作的子查询将在每个跟随副本（follower replica）上执行。

parallel_replicas_allow_materialized_views​

允许在使用并行副本时使用物化视图。

parallel_replicas_connect_timeout_ms​

在使用并行副本执行查询期间，连接到远程副本的超时时间（以毫秒为单位）。如果超时，相应的副本将不用于查询执行。

parallel_replicas_count​

Beta 功能。了解更多。

这是一个内部设置，不应直接使用，它代表了“并行副本”模式的实现细节。此设置将由发起者服务器针对分布式查询自动设置为参与查询处理的并行副本数量。

parallel_replicas_custom_key​

Beta 功能。了解更多。

一个任意的整数表达式，可用于在特定表的副本之间拆分工作。该值可以是任何整数表达式。

首选使用主键的简单表达式。

如果该设置在由包含多个副本的单个分片组成的集群上使用，这些副本将被转换为虚拟分片。否则，它的行为与 SAMPLE 键相同，它将使用每个分片的多个副本。

parallel_replicas_custom_key_range_lower​

Beta 功能。了解更多。

允许过滤器类型 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​

Beta 功能。了解更多。

允许过滤器类型 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​

Beta 功能。了解更多。

允许将过滤器下推到并行副本选择执行的查询部分。

parallel_replicas_for_cluster_engines​

将表函数引擎替换为其对应的 -Cluster 变体。

parallel_replicas_for_non_replicated_merge_tree​

如果为 true，ClickHouse 也会对非副本 MergeTree 表使用并行副本算法。

parallel_replicas_index_analysis_only_on_coordinator​

索引分析仅在副本协调节点（replica-coordinator）上完成，并在其他副本上跳过。仅在启用 parallel_replicas_local_plan 时生效。

parallel_replicas_insert_select_local_pipeline​

在使用并行副本进行分布式 INSERT SELECT 期间使用本地管道。

parallel_replicas_local_plan​

为本地副本构建本地计划。

parallel_replicas_mark_segment_size​

Data Part 被虚拟地划分为段（segment），以便在副本之间分发进行并行读取。此设置控制这些段的大小。除非您完全确定自己在做什么，否则不建议更改。值应在 [128; 16384] 范围内。

parallel_replicas_min_number_of_rows_per_replica​

将查询中使用的副本数量限制为（估算的读取行数 / min_number_of_rows_per_replica）。最大值仍受 'max_parallel_replicas' 限制。

parallel_replicas_mode​

用于并行副本自定义键的过滤器类型。default - 对自定义键使用取模操作；range - 对自定义键使用范围过滤器，使用自定义键值类型的所有可能值。

parallel_replicas_only_with_analyzer​

必须启用分析器（analyzer）才能使用并行副本。如果分析器被禁用，查询执行将回退到本地执行，即使启用了副本并行读取。不支持在不启用分析器的情况下使用并行副本。

parallel_replicas_prefer_local_join​

如果为 true，且 JOIN 可以使用并行副本算法执行，且右连接部分的所有存储都是 *MergeTree，则将使用本地 JOIN 代替 GLOBAL JOIN。

parallel_replicas_support_projection​

投影（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 查询中部分合并连接算法右侧连接数据块的大小。

ClickHouse 服务端

  1. 将右侧连接数据拆分为最多包含指定行数的块。
  2. 使用其最小值和最大值为每个块建立索引。
  3. 如果可能，将准备好的块卸载到磁盘。

可能的值

  • 任何正整数。推荐值范围：[1000, 100000]。

partial_result_on_first_cancel​

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

parts_to_delay_insert​

如果目标表的单个分区中包含至少这么多活跃的 Data Part，则人为放慢向该表的插入速度。

parts_to_throw_insert​

如果目标表的单个分区中活跃 Data Part 数量超过此值，则抛出 'Too many parts ...' 异常。

per_part_index_stats​

记录每个 Data Part 的索引统计信息。

poll_interval​

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

postgresql_connection_attempt_timeout​

单次尝试连接 PostgreSQL 端点的连接超时时间（秒）。该值作为连接 URL 的 connect_timeout 参数传递。

postgresql_connection_pool_auto_close_connection​

在将连接返回到池之前关闭连接。

postgresql_connection_pool_retries​

PostgreSQL 表引擎和数据库引擎的连接池入队/出队重试次数。

postgresql_connection_pool_size​

PostgreSQL 表引擎和数据库引擎的连接池大小。

postgresql_connection_pool_wait_timeout​

PostgreSQL 表引擎和数据库引擎在连接池为空时的入队/出队等待超时时间。默认情况下，它将在空池上阻塞。

postgresql_fault_injection_probability​

内部（用于复制）PostgreSQL 查询失败的近似概率。有效值在 [0.0f, 1.0f] 区间内。

prefer_column_name_to_alias​

启用或禁用在查询表达式和子句中使用原始列名而非别名。当别名与列名相同时，这一点尤为重要，参见 表达式别名。启用此设置可使 ClickHouse 中的别名语法规则与大多数其他数据库引擎更兼容。

可能的值

  • 0 — 列名被别名替换。
  • 1 — 列名不被别名替换。

示例

启用和禁用之间的区别。

查询

SET prefer_column_name_to_alias = 0;
SELECT avg(number) AS number, max(number) FROM numbers(10);

结果

Received exception from server (version 21.5.1):
Code: 184. DB::Exception: Received from localhost:9000. DB::Exception: Aggregate function avg(number) is found inside another aggregate function in query: While processing avg(number) AS number.

查询

SET prefer_column_name_to_alias = 1;
SELECT avg(number) AS number, max(number) FROM numbers(10);

结果

┌─number─┬─max(number)─┐
│    4.5 │           9 │
└────────┴─────────────┘

prefer_external_sort_block_bytes​

首选外部排序的最大块字节数，以减少合并期间的内存使用。

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 的另一个用例是访问由外部引擎创建的表。此设置有助于在连接此类表时减少对外部源的调用次数：每次查询仅调用一次。

参见

  • 有关如何使用 GLOBAL IN/GLOBAL JOIN 的更多信息，请参阅 分布式子查询。

prefer_localhost_replica​

启用/禁用在处理分布式查询时优先使用本地主机副本。

可能的值

  • 1 — 如果存在本地主机副本，ClickHouse 始终向其发送查询。
  • 0 — ClickHouse 使用 load_balancing 设置指定的负载均衡策略。
注意

如果您在没有使用 parallel_replicas_custom_key 的情况下使用 max_parallel_replicas，请禁用此设置。如果设置了 parallel_replicas_custom_key，仅当在包含多个副本的多分片集群上使用时才禁用此设置。如果是在单分片多副本集群上使用，禁用此设置将产生负面影响。

prefer_warmed_unmerged_parts_seconds​

仅限 ClickHouse Cloud

仅在 ClickHouse Cloud 中有效。如果合并后的 Data Part 的生成时间少于此秒数且未进行预热（参见 cache_populated_by_fetch），但其所有源 Part 均可用且已预热，则 SELECT 查询将改为从这些源 Part 中读取。仅适用于 Replicated-/SharedMergeTree。请注意，这仅检查 CacheWarmer 是否处理了该 Part；如果该 Part 是由其他方式抓取到缓存中的，则在 CacheWarmer 处理它之前，它仍将被视为冷数据；如果它已被预热但随后从缓存中逐出，它仍将被视为热数据。

preferred_block_size_bytes​

此设置调整用于查询处理的数据块大小，代表了对粗略的 'max_block_size' 设置的进一步微调。如果列很大，并且在 'max_block_size' 行的情况下块大小可能大于指定的字节数，则会降低其大小以获得更好的 CPU 缓存局部性。

preferred_max_column_in_block_size_bytes​

读取时块中最大列大小的限制。有助于减少缓存未命中次数。应接近 L2 缓存大小。

preferred_optimize_projection_name​

如果将其设置为非空字符串，ClickHouse 将尝试在查询中应用指定的投影。

可能的值

  • 字符串：首选投影的名称

prefetch_buffer_size​

从文件系统读取的预取缓冲区的最大大小。

允许在 DESCRIBE 查询和 toTypeName() 函数中以带有缩进的漂亮方式打印深层嵌套的类型名称。

示例

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

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

priority​

查询的优先级。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_max_entries​

当前用户可以在 查询缓存 中存储的最大查询结果数量。0 表示无限制。

可能的值

  • 正整数 >= 0。

query_cache_max_size_in_bytes​

当前用户可以在 查询缓存 中分配的最大内存量（以字节为单位）。0 表示无限制。

可能的值

  • 正整数 >= 0。

query_cache_min_query_duration​

查询结果要存储在 查询缓存 中所需的最小查询运行持续时间（以毫秒为单位）。

可能的值

  • 正整数 >= 0。

query_cache_min_query_runs​

在 SELECT 查询结果存入 查询缓存 之前，该查询必须运行的最少次数。

可能的值

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

控制 查询缓存 如何处理针对系统表（即 system.* 和 information_schema.* 数据库中的表）的 SELECT 查询。

可能的值

  • 'throw' - 抛出异常且不缓存查询结果。
  • 'save' - 缓存查询结果。
  • 'ignore' - 不缓存查询结果，且不抛出异常。

query_cache_tag​

一个作为 查询缓存 条目标签的字符串。带有不同标签的相同查询会被查询缓存视为不同的查询。

可能的值

  • 任何字符串

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​

切换查询计划层级的顺序聚合（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​

在查询计划中确定连接的哪一侧应该是构建表（build table，也称为内表，即在哈希连接中插入哈希表的表）。此设置仅支持带有 JOIN ON 子句的 ALL 连接严格性。可能的值为：

  • 'auto'：让计划器决定使用哪张表作为构建表。
  • '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​

控制允许使用查询计划进行延迟物化（lazy materialization）优化的最大限制值。如果为零，则没有限制。

query_plan_max_limit_for_top_k_optimization​

控制允许通过使用 minmax 跳数索引和动态阈值过滤来评估 TopK 优化的查询计划最大限制值。如果为零，则没有限制。

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' - 基础贪婪算法 - 运行速度快，但可能不会产生最佳的连接顺序。
  • 'dpsize' - 实现 DPsize 算法，目前仅适用于内连接（Inner joins） - 考虑所有可能的连接顺序并找到最理想的一个，但对于包含多张表和连接谓词的查询可能会很慢。可以指定多个算法，例如 'dpsize,greedy'。

query_plan_optimize_join_order_limit​

优化同一子查询内的连接顺序。目前仅支持非常有限的情况。值为要优化的最大表数量。

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​

切换顺序读取（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_enable_optimizations 为 1 时生效。

注意

这是一个专家级设置，仅供开发人员调试使用。该设置未来可能会以不向后兼容的方式更改或被删除。

可能的值

  • 0 - 禁用
  • 1 - 启用

query_plan_use_new_logical_join_step​

别名：query_plan_use_logical_join_step

在查询计划中使用逻辑连接步骤。注意：设置 query_plan_use_new_logical_join_step 已弃用，请改用 query_plan_use_logical_join_step。

query_profiler_cpu_time_period_ns​

设置 查询分析器 (query profiler) 的 CPU 时钟定时器周期。此定时器仅计算 CPU 时间。

可能的值

  • 一个正整数，单位为纳秒。

    推荐值

    • 对于单个查询，为 10,000,000 纳秒（每秒 100 次）及以上。
    • 对于集群范围的分析，为 1,000,000,000 纳秒（每秒一次）。

  • 设置为 0 表示关闭定时器。

参见

query_profiler_real_time_period_ns​

设置 查询分析器 (query profiler) 的实时时钟定时器周期。实时时钟定时器计算挂钟时间（wall-clock time）。

可能的值

  • 一个正整数，单位为纳秒。

    推荐值

    • 对于单个查询，为 10,000,000 纳秒（每秒 100 次）及以下。
    • 对于集群范围的分析，为 1,000,000,000 纳秒（每秒一次）。

  • 设置为 0 表示关闭定时器。

参见

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

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

在按主键顺序进行多线程读取期间，运行初步合并步骤所需的最小读取 Data Part 数量。

read_in_order_use_buffering​

在按主键顺序读取时，在合并前使用缓冲。这增加了查询执行的并行度。

read_in_order_use_virtual_row​

在按主键顺序或其单调函数方式读取时使用虚拟行。这在搜索多个 Data Part 时很有用，因为仅会触及相关的部分。

read_overflow_mode​

超过限制时该怎么办。

read_overflow_mode_leaf​

设置当读取的数据量超过其中一个叶限制（leaf limits）时会发生什么。

可选选项

  • throw: 抛出异常（默认值）。
  • break：停止执行查询并返回部分结果。

read_priority​

从本地文件系统或远程文件系统读取数据的优先级。对于本地文件系统仅支持 'pread_threadpool' 方法，对于远程文件系统支持 threadpool 方法。

read_through_distributed_cache​

仅限 ClickHouse Cloud

仅在 ClickHouse Cloud 中有效。允许从分布式缓存中读取。

readonly​

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

receive_data_timeout_ms​

从副本接收第一个数据包或接收到具有正进度的包的连接超时时间。

receive_timeout​

从网络接收数据的超时时间（秒）。如果在该时间间隔内未收到任何字节，则抛出异常。如果在客户端设置此项，则服务器端相应连接端的套接字 'send_timeout' 也会被设置。

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​

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

可能的值

  • 正整数。

reject_expensive_hyperscan_regexps​

拒绝那些使用 hyperscan 评估时可能非常昂贵的模式（由于 NFA 状态爆炸）。

remerge_sort_lowered_memory_bytes_ratio​

如果重新合并（remerge）后的内存使用量没有按此比例减少，则将禁用重新合并。

remote_filesystem_read_method​

从远程文件系统读取数据的方法，可选值：read, threadpool。

remote_filesystem_read_prefetch​

从远程文件系统读取数据时是否应使用预取。

remote_fs_read_backoff_max_tries​

使用退避（backoff）机制读取的最大尝试次数。

remote_fs_read_max_backoff_ms​

尝试从远程磁盘读取数据时的最大等待时间。

remote_read_min_bytes_for_seek​

远程读取（url, s3）执行 seek 而不是带 ignore 的 read 所需的最小字节数。

rename_files_after_processing​

  • 类型：字符串

  • 默认值：空字符串

此设置允许为 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​

在还原（restore）时将外部字典源替换为 Null。适用于测试目的。

restore_replace_external_engines_to_null​

用于测试目的。将所有外部引擎替换为 Null，以免发起外部连接。

restore_replace_external_table_functions_to_null​

用于测试目的。将所有外部表函数替换为 Null，以免发起外部连接。

restore_replicated_merge_tree_to_shared_merge_tree​

在 RESTORE 期间将表引擎从 ReplicatedMergeTree 替换为 SharedMergeTree。

result_overflow_mode​

Cloud 默认值：throw

设置如果结果量超过其中一个限制时该怎么办。

可能的值

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

使用 'break' 类似于使用 LIMIT。Break 仅在数据块层级中断执行。这意味着返回的行数大于 max_result_rows，是 max_block_size 的倍数，且取决于 max_threads。

示例

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

SELECT *
FROM numbers_mt(100000)
FORMAT Null;

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。这可能有助于通过连接重排序来优化整个查询。

rows_before_aggregation​

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

s3_allow_multipart_copy​

允许在 S3 中进行分片复制（multipart copy）。

s3_allow_parallel_part_upload​

对 s3 分片上传使用多线程。这可能会导致内存使用量略有增加。

s3_check_objects_after_upload​

使用 head 请求检查每个上传到 s3 的对象，以确保上传成功。

s3_connect_timeout_ms​

s3 磁盘主机的连接超时时间。

s3_create_new_file_on_insert​

在 s3 引擎表中启用或禁用每次插入时创建新文件。如果启用，每次插入都会创建一个带有 key 的新 S3 对象，类似于此模式：

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

可能的值

  • 0 — INSERT 查询创建一个新文件，或者如果文件已存在且未设置 s3_truncate_on_insert 则失败。
  • 1 — 如果未设置 s3_truncate_on_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 请求的每秒速率限制。零表示无限制。

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

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​

可以从查询过滤器中提取的 _path 值的最大数量，用于文件迭代而不是通配符（glob）列表。0 表示禁用。

s3_request_timeout_ms​

向/从 S3 发送和接收数据的空闲超时时间。如果单个 TCP 读取或写入调用阻塞时间达到此值，则失败。

s3_skip_empty_files​

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

可能的值

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

s3_slow_all_threads_after_network_error​

当设置为 true 时，在任何单个 S3 请求遇到可重试的网络错误（如套接字超时）后，所有向同一备份端点执行 S3 请求的线程都会放慢速度。当设置为 false 时，每个线程独立于其他线程处理 S3 请求退避。

s3_strict_upload_part_size​

S3 分片上传期间上传分片的精确大小（某些实现不支持可变大小的分片）。

s3_throw_on_zero_files_match​

当 ListObjects 请求无法匹配任何文件时抛出错误。

s3_truncate_on_insert​

在 s3 引擎表中启用或禁用插入前的截断（truncate）。如果禁用，且 S3 对象已存在，则尝试插入时将抛出异常。

可能的值

  • 0 — INSERT 查询创建一个新文件，或者如果文件已存在且未设置 s3_create_new_file_on_insert 则失败。
  • 1 — INSERT 查询使用新数据替换文件的现有内容。

详见 此处。

s3_upload_part_size_multiply_factor​

每当单次写入 S3 上传了 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_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 使用缓存中的架构（适用于带有 Last-Modified 头的 URL）。

schema_inference_use_cache_for_azure​

使用 azure 表函数时，在架构推断中使用缓存。

schema_inference_use_cache_for_file​

使用 file 表函数时，在架构推断中使用缓存。

schema_inference_use_cache_for_hdfs​

在使用 hdfs 表函数进行模式推导时使用缓存

schema_inference_use_cache_for_s3​

在使用 s3 表函数进行模式推导时使用缓存

schema_inference_use_cache_for_url​

在使用 url 表函数进行模式推导时使用缓存

secondary_indices_enable_bulk_filtering​

为索引启用批量过滤算法。通常预期该算法表现更好，但我们保留此设置以用于兼容性和控制。

select_sequential_consistency​

注意

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

启用或禁用 SELECT 查询的顺序一致性。需要禁用 insert_quorum_parallel（默认启用）。

可能的值

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

用法

启用顺序一致性时，ClickHouse 仅允许客户端在那些包含所有先前使用 insert_quorum 执行的 INSERT 查询数据的副本上执行 SELECT 查询。如果客户端引用了部分副本，ClickHouse 将生成异常。SELECT 查询将不包含尚未写入法定副本数（quorum）的数据。

当启用 insert_quorum_parallel（默认值）时，select_sequential_consistency 不起作用。这是因为并行 INSERT 查询可能会写入不同的法定副本集，因此无法保证单个副本已接收所有写入。

参见

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 接口描述。

可能的值

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

send_timeout​

向网络发送数据的超时时间（以秒为单位）。如果客户端需要发送数据，但在该时间间隔内无法发送任何字节，则会抛出异常。如果您在客户端上设置此设置，套接字的 'receive_timeout' 也会在服务器相应的连接端进行设置。

serialize_query_plan​

为分布式处理序列化查询计划

serialize_string_in_memory_with_zero_byte​

在聚合期间序列化 String 值时，在末尾添加零字节。启用此项可在查询不兼容版本的集群时保持兼容性。

session_timezone​

Beta 功能。了解更多。

设置当前会话或查询的隐式时区。隐式时区是应用于没有明确指定时区的 DateTime/DateTime64 类型值的时区。该设置的优先级高于全局配置（服务器级）的隐式时区。值为 ''（空字符串）表示当前会话或查询的隐式时区等于 服务器时区。

您可以使用函数 timeZone() 和 serverTimeZone() 获取会话时区和服务器时区。

可能的值

  • 来自 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"

将没有明确指定时区的内部 DateTime 分配为会话时区 'America/Denver'

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

1999-12-13 07:23:23.123
注意

并非所有解析 DateTime/DateTime64 的函数都会遵循 session_timezone。这可能会导致微妙的错误。请参阅以下示例和解释。

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

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

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

由于解析管道不同，会发生这种情况

  • 在第一个 SELECT 查询中使用且没有明确给出时区的 toDateTime() 会遵循 session_timezone 设置和全局时区。
  • 在第二个查询中，DateTime 是从字符串中解析出来的，并继承了现有列 d 的类型和时区。因此，不遵循 session_timezone 设置和全局时区。

参见

set_overflow_mode​

设置当数据量超过限制之一时发生的情况。

可能的值

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

shared_merge_tree_sync_parts_on_partition_operations​

在 SMT 表中进行 MOVE|REPLACE|ATTACH 分区操作后自动同步数据部分集合。仅限云端使用。

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 查询输出中显示内部辅助进程。

内部进程包括字典重载、可刷新物化视图重载、在 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 优化期间将交叉的部分范围拆分为层

split_parts_ranges_into_intersecting_and_non_intersecting_final​

在 FINAL 优化期间将部分范围拆分为交叉和非交叉部分

splitby_max_substrings_includes_remaining_string​

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

可能的值

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

stop_refreshable_materialized_views_on_startup​

实验性功能。 了解更多。

在服务器启动时，阻止可刷新物化视图的调度，效果等同于使用 SYSTEM STOP VIEWS。之后您可以使用 SYSTEM START VIEWS 或 SYSTEM START VIEW <name> 手动启动它们。也适用于新创建的视图。对不可刷新的物化视图没有影响。

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 查询。如果存在附加的物化视图，即使启用此设置也不允许 SELECT 查询。如果没有附加的物化视图，启用此设置允许读取数据。请注意，通常读取的数据会从队列中删除。为了避免删除读取的数据，应正确配置相关的引擎设置。

stream_like_engine_insert_queue​

当类流式（stream-like）引擎从多个队列读取时，用户在写入时需要选择一个要插入的队列。由 Redis Streams 和 NATS 使用。

stream_poll_timeout_ms​

流式存储轮询数据的超时时间。

system_events_show_zero_values​

允许从 system.events 中选择值为零的事件。

某些监控系统要求为每个检查点传递所有指标值，即使指标值为零。

可能的值

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

table_engine_read_through_distributed_cache​

仅限 ClickHouse Cloud

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

临时文件写入器的缓冲区大小。较大的缓冲区意味着较少的系统调用，但更多的内存消耗。

temporary_files_codec​

设置在磁盘上进行排序和连接操作时使用的临时文件的压缩编解码器。

可能的值

  • LZ4 — 应用 LZ4 压缩。
  • NONE — 不应用压缩。

text_index_hint_max_selectivity​

使用倒排文本索引构建的提示时，过滤器的最大选择性。

text_index_use_bloom_filter​

用于测试目的，启用或禁用在文本索引中使用布隆过滤器。

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）时收集堆栈轨迹，以及配置文件事件的名称和增量值，并将它们发送到 trace_log。

可能的值

  • 1 — 启用配置文件事件追踪。
  • 0 — 禁用配置文件事件追踪。

trace_profile_events_list​

当启用 trace_profile_events 设置时，将追踪的事件限制为指定的逗号分隔名称列表。如果 trace_profile_events_list 为空字符串（默认值），则追踪所有配置文件事件。

示例值：'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 │
└──────┴───────┘

参见

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，在执行更新之前，数据部分集合将更新到最新版本。

use_async_executor_for_materialized_views​

对物化视图查询使用异步且可能是多线程的执行，可以加速 INSERT 期间的视图处理，但也会消耗更多内存。

use_cache_for_count_from_files​

在表函数 file/s3/url/hdfs/azureBlobStorage 中从文件计数时，启用行数缓存。

默认启用。

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 全局服务器设置）。如果禁用，即使服务器过载，也允许使用更多数量的线程（不建议正常使用，主要用于测试）。

use_hash_table_stats_for_join_reordering​

启用在 Join 重新排序期间使用收集的哈希表统计信息进行基数估算

use_hedged_requests​

为远程查询启用对冲请求（hedged requests）逻辑。它允许为查询与不同副本建立多个连接。如果在 hedged_connection_timeout 内未建立与副本的现有连接，或者在 receive_data_timeout 内未收到任何数据，则启用新连接。查询使用第一个发送非空进度数据包（如果 allow_changing_replica_until_first_data_packet，则为数据包）的连接；其他连接将被取消。支持 max_parallel_replicas > 1 的查询。

默认启用。

云端默认值：1

use_hive_partitioning​

启用后，ClickHouse 将在类文件表引擎 File/S3/URL/HDFS/AzureBlobStorage 的路径中检测 Hive 风格的分区（/name=value/），并允许在查询中将分区列用作虚拟列。这些虚拟列将与分区路径中的名称相同，但以 _ 开头。

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 运算符右侧集合的最大大小，以便使用表索引进行过滤。它允许避免由于为大型查询准备额外数据结构而导致的性能下降和更高的内存消耗。零表示没有限制。

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'。不会禁用 OS 页面缓存；为此可以使用 min_bytes_to_use_direct_io。仅影响常规表，不影响 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_primary_key​

在 MergeTree 表的查询执行期间使用主键裁剪颗粒（granules）。

可能的值

  • 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 修饰符执行查询时，由跳过索引返回的颗粒是否在较新的数据部分中展开，以返回正确的结果。

使用跳过索引可能会排除包含最新数据的行（颗粒），从而导致结果不正确。此设置可以通过扫描与跳过索引返回范围重叠的较新数据部分，确保返回正确的结果。只有在应用程序可以接受基于查看跳过索引得到的近似结果时，才应禁用此设置。

可能的值

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

use_skip_indexes_on_data_read​

启用在数据读取期间使用数据跳过索引。

启用后，跳过索引将在读取每个数据颗粒时动态求值，而不是在查询执行开始前预先分析。这可以减少查询启动延迟。

可能的值

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

use_statistics​

Beta 功能。了解更多。

/// 由于与 'use_primary_key' 和 'use_skip_indexes' 的一致性，优于 'allow_statistics_optimize'，允许使用统计信息优化查询

use_statistics_cache​

Beta 功能。了解更多。

在查询中使用统计信息缓存，以避免加载每个部分统计信息的开销

use_structure_from_insertion_table_in_table_functions​

使用插入表的结构，而不是从数据中进行模式推导。可能的值：0 - 禁用，1 - 启用，2 - 自动

use_text_index_dictionary_cache​

是否使用反序列化的文本索引字典块缓存。在处理大量文本索引查询时，使用文本索引字典块缓存可以显著降低延迟并提高吞吐量。

use_text_index_header_cache​

是否使用反序列化的文本索引头缓存。在处理大量文本索引查询时，使用文本索引头缓存可以显著降低延迟并提高吞吐量。

use_text_index_postings_cache​

是否使用反序列化的文本索引发布列表（posting lists）缓存。在处理大量文本索引查询时，使用文本索引发布列表缓存可以显著降低延迟并提高吞吐量。

use_top_k_dynamic_filtering​

在执行 ORDER BY <column> LIMIT n 查询时启用动态过滤优化。

启用后，查询执行器将尝试跳过不属于结果集中最终 top N 行的颗粒和行。这种优化在本质上是动态的，延迟改进取决于数据分布和查询中其他谓词的存在。

可能的值

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

use_uncompressed_cache​

是否使用未压缩数据块的缓存。接受 0 或 1。默认为 0（禁用）。在处理大量短查询时，使用未压缩缓存（仅适用于 MergeTree 系列表）可以显著降低延迟并提高吞吐量。为发送频繁短请求的用户启用此设置。同时请注意 uncompressed_cache_size 配置参数（仅在配置文件中设置）——未压缩缓存块的大小。默认情况下为 8 GiB。未压缩缓存根据需要填充，并自动删除最少使用的数据。

对于读取至少一定量数据（一百万行或更多）的查询，未压缩缓存会自动禁用，以为真正的短查询节省空间。这意味着您可以始终将 '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​

在接受变异（mutation）查询之前对其进行验证。变异在后台执行，运行无效查询会导致变异卡住，需要人工干预。

仅在遇到向后不兼容的错误时才更改此设置。

validate_polygons​

启用或禁用在 pointInPolygon 函数中抛出异常（如果多边形自相交或自切）。

可能的值

  • 0 — 禁用抛出异常。pointInPolygon 接受无效的多边形并可能返回错误的结果。
  • 1 — 启用抛出异常。

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）。如果不重新评分，矢量相似性索引将直接返回包含最佳匹配的行。通过重新评分，行被推断到颗粒级别，并再次检查颗粒中的所有行。在大多数情况下，重新评分对准确性的帮助微乎其微，但它会显著降低矢量搜索查询的性能。注意：在未启用重新评分且启用了并行副本的情况下运行的查询可能会回退到重新评分。

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

实验性功能。 了解更多。

窗口视图释放过期数据的清理间隔（秒）。

window_view_heartbeat_interval​

实验性功能。 了解更多。

指示观察查询存活的心跳间隔（秒）。

workload​

用于访问资源的负载名称

write_full_path_in_iceberg_metadata​

实验性功能。 了解更多。

在 iceberg 元数据文件中写入完整路径（包括 s3://）。

write_through_distributed_cache​

仅限 ClickHouse Cloud

仅在 ClickHouse Cloud 中生效。允许写入分布式缓存（向 s3 的写入也将由分布式缓存完成）

write_through_distributed_cache_buffer_size​

仅限 ClickHouse Cloud

仅在 ClickHouse Cloud 中生效。设置直写式分布式缓存的缓冲区大小。如果为 0，将使用在没有分布式缓存时本应使用的缓冲区大小。

zstd_window_log_max​

允许您选择 ZSTD 的最大窗口日志（它不会用于 MergeTree 系列表）

    © . This site is unofficial and not affiliated with ClickHouse, Inc.