query_plan_aggregation_bucket_top_k
切换一项查询计划级别的优化:当最终聚合的输出经由带有LIMIT n 的 ORDER BY 排序,且计划能够证明每个桶的选择结果准确时,该优化会在聚合的最终合并或转换过程中,仅保留每个两级桶中排名前 n 的组。结果准确无误:未进入所在桶前 n 名的组,在全局范围内至少有 n 个组排在它之前,因此不可能进入全局前 n 名。
对于按 count 排序的情况,该优化可以在最终转换过程中选出排名靠前的组。对于可根据部分状态确定合并后取值边界的聚合函数,该优化则可以改用阈值合并 (Fagin 阈值算法) ,跳过合并那些不可能进入前 n 名的组。降序排列时,此方式支持 count、结果为 UInt64 的无符号整数 sum (参数为 UInt8 至 UInt64;不包括 UInt128 等宽无符号整数) 以及 uniqExact;对于整数、日期、日期时间、小数和枚举类型,还支持降序排列的 max 和升序排列的 min (不包括浮点、UUID、IPv4、IPv6、String、FixedString 及其他类型) 。使用 If 和 Null 组合器时,仅 count、无符号 sum 和 uniqExact 保留阈值合并,且仅限结果不可为空的情况 (例如 countIf、参数非 Nullable 的 sumIf,或参数为 Nullable 的 uniqExact) ;参数为 Nullable 的 sum 和 sumIf (其结果为 Nullable) 、maxIf、minIf,以及参数为 Nullable 的 max 或 min 则使用普通合并。具体采用哪种算法,会根据聚合函数、查询形态以及部分状态的分布自动选择。
未进入所在桶前 n 名的组既不会被合并,也不会被标记为已完成,因此这不仅仅是一个性能开关:对于不可能进入前 n 名的组,查询中的其他聚合函数也不会再对其进行合并并将其标记为已完成。原本在此类组上合并或最终计算某个聚合函数时会抛出异常的查询,现在可能转而返回结果行。将此设置设为 0 可保留之前的行为。
仅当设置 query_plan_enable_optimizations 为 1 时生效。
可选值:
- 0 - 禁用
- 1 - 启用
query_plan_aggregation_having_prefilter
控制是否启用一项查询计划级别的优化,适用于带有GROUP BY 的 HAVING count() <comparison> <constant> 查询。在将聚合结果的两级桶转换为块时,如果某个分组的计数无法满足边界条件,则在物化其键列之前跳过该分组,而不是先物化,再由上层过滤器丢弃。此优化可加速高基数 GROUP BY 上的“分组计数超过阈值”查询:这类查询会丢弃大多数分组,而转换工作大多花在这些被丢弃分组的键上。
被跳过的分组既不经过过滤,也不进行最终处理,因此此设置不仅影响性能:对于边界条件排除的分组,不再对写在该边界条件之前的 HAVING 合取条件求值,也不再执行同级聚合的最终处理。此前因这些操作之一引发异常的查询可能改为返回行,例如在使用 count() AS cnt 的查询中指定 HAVING throwIf(cnt = 3) = 0 AND count() > 3。将此设置设为 0,或将 compatibility 设为低于 26.10 的版本,可保留先前的行为。
仅当设置 query_plan_enable_optimizations 为 1 时生效。
可选值:
- 0 - 禁用
- 1 - 启用
query_plan_convert_any_join_to_semi_or_anti_join
如果 JOIN 之后的过滤器对未匹配行或已匹配行的求值结果始终为 false,则允许将 ANY JOIN 转换为 SEMI 或 ANTI JOINquery_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_convert_outer_join_to_inner_join_transitively
扩展query_plan_convert_outer_join_to_inner_join 的作用范围,使其同时考虑查询计划中更上层的过滤器以及外层 JOIN 的条件。仅在启用 query_plan_convert_outer_join_to_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_filter_push_down_below_limit_by
控制是否将作用于LIMIT BY 键列的过滤器下推到 LIMIT BY 步骤之下。
仅当设置 query_plan_enable_optimizations 为 1 时生效。
该设置独立于 query_plan_filter_push_down 读取:一旦添加了 JOIN 运行时过滤器,即使后者处于关闭状态,下推优化过程仍会执行。
这是一个专家级设置,仅应由开发人员用于调试。该设置将来可能会以不向后兼容的方式更改或被移除。
- 0 - 禁用
- 1 - 启用
query_plan_fuse_filter_into_array_join
启用或禁用一项查询计划级别的优化:将针对ARRAY JOIN 后元素列的过滤器融合到 ARRAY JOIN 步骤中,在展开前按元素筛选数组,确保被过滤掉的元素不会被展开或复制。
仅当设置 query_plan_enable_optimizations 为 1 时生效。
这是一项专家级设置,仅供开发人员调试时使用。该设置未来可能会以不向后兼容的方式变更或被移除。
query_plan_join_shard_by_pk_ranges
当连接键包含两个表主键的前缀时,将两个 MergeTree 表的 JOIN 按主键范围拆分为多个相互独立的连接来执行。两个表会按该前缀的值拆分为相同的范围 (方式与FINAL 将数据部分拆分为互不相交的层相同) ,因此相等的键必然落入同一范围,每个范围在各自的线程上完成连接。
对于 full_sorting_merge 和 parallel_full_sorting_merge,该设置会将覆盖两个表的单个单线程归并连接,替换为每个范围各自一个并行运行的流式归并连接,通常可将速度提升数倍,同时将内存占用降低数倍。
对于 hash 和 parallel_hash,每个范围使用各自独立的哈希表。仅当 JOIN 运行时过滤器 (enable_join_runtime_filters) 和落盘 (max_bytes_ratio_before_external_join、max_bytes_before_external_join) 均未生效时,此优化才会应用,因为二者都会使该连接对此优化不透明;在这种情况下,它通常不会提升查询速度,但可能降低内存消耗。范围以静态方式分配给线程,因此如果某个过滤器仅在主键范围的部分区间内具有较高选择性,就会导致部分线程空闲。
此优化不适用于 FINAL、ASOF、ON 中包含多个析取项的连接,也不适用于使用并行副本读取的情况。
query_plan_join_swap_table
确定在查询计划中,JOIN 的哪一侧应作为 build 表 (也称 inner,即在 hash join 中插入哈希表的一侧) 。此设置仅支持带有JOIN ON 子句的 ALL join strictness。可能的值包括:
- ‘auto’:由 planner 决定使用哪个表作为 build 表。
- ‘false’:从不交换表 (右表为 build 表) 。
- ‘true’:始终交换表 (左表为 build 表) 。
query_plan_lazy_materialization_for_join
对包含连接的LIMIT n 查询 (无论是否带有 ORDER BY) 使用延迟物化:
MergeTree 表的列,以及在启用
query_plan_optimize_lazy_materialization_for_object_storage 时对象存储表的列,只会针对经过 LIMIT 后保留下来的 n 行进行读取,
而不是针对连接产生的每一行都进行读取。该决策基于 LIMIT 下方整个子树对应的单个已合并
ActionsDAG 做出。因此,对于过滤器需要、结果中也需要的值,会在 LIMIT 上方以较低开销再计算一次,
而不是作为一列在中间的每个连接中逐层传递。仅当启用 query_plan_optimize_lazy_materialization 时,此设置才会生效。
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_lower_array_join_function
启用或禁用一项查询计划级别的优化:将表达式中的arrayJoin 函数降为真正的 ARRAY JOIN 步骤,使其采用与 ARRAY JOIN 子句相同的执行机制 (惰性复制和过滤器融合) 。
仅当设置 query_plan_enable_optimizations 为 1 时生效。
这是一项专家级设置,仅应由开发人员用于调试。该设置未来可能会以不向后兼容的方式更改或被移除。
query_plan_max_limit_for_join_lazy_indexing
控制可在 JOIN 中使用查询计划进行惰性索引优化时允许的最大 LIMIT 值。若为 0,则不受限制。query_plan_max_limit_for_lazy_materialization
控制可对惰性物化优化使用查询计划的最大 LIMIT 值。若为 0,则不受限制。query_plan_max_limit_for_top_k_optimization
控制允许使用 minmax 跳过索引和动态阈值筛选来评估 TopK 优化查询计划的最大 LIMIT 值。如果为 0,则不设限制。 此设置还控制 enable_group_by_top_k_optimization 的行为。query_plan_max_optimizations_to_apply
限制应用到查询计划上的优化总次数,参见设置 query_plan_enable_optimizations。 可用于避免复杂查询的优化耗时过长。 在 EXPLAIN PLAN 查询中,达到此限制后将停止继续应用优化,并按原样返回查询计划。 对于常规查询执行,如果实际优化次数超过此设置,则会抛出异常。这是一个专家级设置,仅应供开发人员用于调试。该设置未来可能会以不向后兼容的方式更改,或者被移除。
query_plan_max_set_size_for_projection_match
在判断两个IN 子句集合是否相等时,投影匹配器会计算并比较其内容哈希;此设置定义了可执行该操作的最大行数。超过此值的集合会被视为不匹配,并跳过该投影。值为 0 时将完全禁用内容哈希比较:对于包含 IN 子句集合的节点,投影匹配将永远不会成功。
该设置由聚合投影匹配器使用 (以及未来任何需要比较 IN 子句集合的投影匹配器) 。计算内容哈希的复杂度相对于集合中元素数量为 O(N log N);当查询或投影中出现大量 IN 子句时,此设置可限制规划阶段的开销。
query_plan_max_step_description_length
EXPLAIN PLAN 中步骤描述的最大长度。query_plan_merge_expression_into_join
允许在 JOIN 重排序优化过程中将表达式合并到 JOIN 步骤中。query_plan_merge_expressions
用于启用或禁用一项会合并连续过滤器的查询计划级别的优化。 仅在设置 query_plan_enable_optimizations 为 1 时生效。这是一个专家级设置,仅供开发人员用于调试。该设置未来可能会以向后不兼容的方式发生变化,或者被移除。
- 0 - 禁用
- 1 - 启用
query_plan_merge_filter_into_join_condition
允许将过滤条件合并到JOIN 条件中,并将 CROSS JOIN 转换为 INNER JOIN。
query_plan_merge_filters
允许在查询计划中合并过滤器。query_plan_min_columns_for_join_lazy_indexing
控制启用 JOIN 中惰性索引优化时左侧所需的最小载荷列数。0 表示禁用此优化。query_plan_optimize_count_from_text_index
允许直接利用文本索引倒排列表的基数执行SELECT count() ... WHERE <text search predicate>,无需具体化匹配的行。
仅在启用 query_plan_direct_read_from_text_index 时生效。
query_plan_optimize_join_order_algorithm
指定在优化查询计划时要尝试哪些 JOIN 顺序算法。可用算法如下:- ‘greedy’ - 基础贪心算法 - 速度快,但不一定能生成最佳 JOIN 顺序
- ‘dpsize’ - 实现 DPsize 算法,目前仅支持 INNER JOIN - 会考虑所有可能的 JOIN 顺序并找出最优方案,但对于包含大量表和 JOIN 谓词的查询可能较慢。
- ‘dpsub’ - 实现 DPsub 算法,同时支持 INNER JOIN 和非 INNER JOIN - 会考虑所有可能的 JOIN 顺序并找出最优方案。该算法仅适用于最多包含 12 个 relation 的查询;超出该数量时,将交由列表中的下一个算法处理。
- ‘dphyp’ - 实现 DPhyp (通过超图分区进行动态规划) 算法,目前仅支持 INNER JOIN - 探索与
dpsize相同的搜索空间,但只枚举连通子图对,因此在稀疏 JOIN 图上生成的中间 JOIN 更少,代价是不考虑笛卡尔积 可以将多个算法指定为逗号分隔的列表,例如dphyp,greedy。系统会按顺序尝试这些算法;如果某个算法无法处理该查询 (例如由于 relation 过多或存在不连通分量) ,则会回退到下一个算法。
query_plan_optimize_join_order_conflict_detector
仅对dpsub JOIN 顺序算法生效。用于选择 DPsub 判定哪些 JOIN 重排序 有效时所使用的
conflict detector。可选取值如下:
''—— 不使用 conflict detector,DPsub 采用按 relation 划分的ONclause 限制'a'—— CD-A conflict detector,正确但不完备'c'(默认) —— CD-C conflict detector,正确且完备
query_plan_optimize_join_order_limit
优化同一子查询中 JOIN 的顺序。目前仅支持极少数情况。 值表示可优化的最大表数量。query_plan_optimize_join_order_max_searched_plans
JOIN 顺序优化器在放弃当前算法并回退到query_plan_optimize_join_order_algorithm 中的下一个算法之前,可枚举的部分计划最大数量。
该设置会以确定性的方式限制优化时间 (与实际时钟时间无关) ,适用于团状或星状等稠密 JOIN 图,因为这类场景中的搜索空间会呈指数级增长。
设置为 0 可禁用此限制。对默认的 query_plan_optimize_join_order_limit 没有影响,因为在默认情况下,搜索规模始终远低于此上限。
query_plan_optimize_join_order_randomize
当该值非 0 时,JOIN 顺序优化器会使用随机生成的基数和 NDV,而不是真实的统计信息。 当设置为 1 时,会生成一个随机种子;当设置为大于 1 的值时,则直接使用该值作为种子。 此设置用于测试,以发现由不同 JOIN 顺序引起的错误。query_plan_optimize_lazy_final
通过构建主键集合并将其用于索引分析,优化从 ReplacingMergeTree 使用 FINAL 读取时的性能。query_plan_optimize_lazy_materialization
使用查询计划进行惰性物化优化。query_plan_optimize_lazy_materialization_for_file
对通过file 表函数和 File 表引擎读取本地 Parquet 文件启用惰性物化优化:对于 ORDER BY ... LIMIT n 查询,仅针对通过 LIMIT 保留下来的 n 行读取排序和筛选所不需要的列。仅当 query_plan_optimize_lazy_materialization 已启用时生效。
query_plan_optimize_lazy_materialization_for_object_storage
对从对象存储 (包括 Iceberg 表) 读取 Parquet 文件时使用惰性物化优化:对于ORDER BY ... LIMIT n 查询,仅对经 LIMIT 保留的 n 行读取排序和筛选不需要的列。仅当启用 query_plan_optimize_lazy_materialization 时生效。
query_plan_propagate_predicate_across_join
启用或禁用一项查询计划级别的优化:该优化会通过等值键替换,将过滤合取项从等值连接的一侧复制到另一侧, 使另一侧的主键/索引裁剪也能利用这些合取项。 当过滤器与MergeTree 读取之间仅隔有表达式和过滤步骤时,以及复制的合取项将主键列与常量进行比较时
(包括使用常量集合的 IN) ,此优化才会生效。位于嵌套连接或 DISTINCT 下方的谓词,以及两个键列之间的
比较,不会被复制:它们无法驱动另一侧的主键裁剪,复制只会增加额外工作。
仅当 query_plan_enable_optimizations 为 1 时生效。
query_plan_push_down_limit
控制是否启用一项查询计划级别的优化:将 LIMIT 下推到执行计划的更低层级。 仅在设置 query_plan_enable_optimizations 为 1 时生效。这是一项专家级设置,仅供开发人员在调试时使用。该设置未来可能会以不向后兼容的方式更改,或被移除。
- 0 - 禁用
- 1 - 启用
query_plan_push_down_volume_reducing_functions
启用或禁用一项查询计划级别的优化:在执行计划中,将减少数据量的函数 (length、lengthUTF8、empty、notEmpty)
下推到 Sorting 和 Filter 步骤之后。固定大小的结果会替换宽 String / FixedString
参数,因此该参数无需再经过这些步骤传递。
仅当参数列在被下推步骤之前不再需要时,才会应用此重写。
仅当设置 query_plan_enable_optimizations 为 1 时,此设置才生效。
可能的值:
- 0 - 禁用
- 1 - 启用
query_plan_push_limit_by_into_sort
控制ORDER BY ... LIMIT BY 查询的一项查询计划级别的优化。当 LIMIT BY 的列是 ORDER BY 子句的前缀时,每个并行排序流都会在合并成一个流之前先执行 LIMIT BY,从而减少最终合并以及后续管道阶段需要处理的行数。对于 LIMIT BY 会丢弃大量行的查询,这项优化可提升速度。
仅当设置 query_plan_enable_optimizations 为 1 时,此设置才会生效。
可能的值:
- 0 - 禁用
- 1 - 启用
query_plan_read_in_order_through_join
在 JOIN 操作中保持对左表的按序读取,以便后续步骤加以利用。 对于LEFT 以外的连接,只有当左表的每个 part 都声明了虚拟行时,读取才会保持有序 (参见 read_in_order_use_virtual_row) 。如果没有虚拟行,连接之后的合并阶段实际读取的数据量可能远超 limit 所需。取值为 force 时,则无论何种情况都会保持按序读取。
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_replace_always_true_filter
当过滤条件始终为 true 且查询未使用过滤器列时,将过滤器步骤替换为表达式步骤。此类过滤器步骤虽然不会过滤掉任何行,但会阻碍 JOIN 重排序。query_plan_reuse_storage_ordering_for_window_functions
别名:optimize_read_in_window_order
切换一项查询计划级别的优化,在对窗口函数进行排序时复用存储排序。
仅在设置 query_plan_enable_optimizations 为 1 时生效。
这是一个专家级设置,仅应供开发人员用于调试。该设置未来可能会发生不向后兼容的变更,或被移除。
- 0 - 禁用
- 1 - 启用
query_plan_short_circuit_constant_false_join
对于ON 条件可折叠为常量 false 的 JOIN,将无法产生行的每个输入侧替换为空源 (INNER/CROSS/SEMI 为两侧,LEFT/RIGHT 为非保留侧) ,从而避免读取无法产生结果的一侧。适用于非分布式查询计划。
query_plan_split_filter
这是一个专家级设置,仅供开发人员调试时使用。该设置未来可能会发生向后不兼容的变更,或被移除。
- 0 - 禁用
- 1 - 启用
query_plan_text_index_add_hint
允许为查询计划中基于倒排文本索引构建的过滤器添加 hint (附加谓词) 。query_plan_top_k_through_join
用于切换一种查询计划级别的优化:当排序键仅引用连接保留侧 (LEFT/RIGHT) 的列时,将ORDER BY ... LIMIT n 下推到连接之前。该优化会限制保留侧输入在连接前需要生成的行数。
仅在设置 query_plan_enable_optimizations 为 1 时生效。
可能的值:
- 0 - 禁用
- 1 - 启用
query_plan_try_use_vector_search
控制是否启用一项会尝试使用向量相似度索引的查询计划级别的优化。 仅在设置query_plan_enable_optimizations 为 1 时生效。
这是一个专家级设置,仅供开发者调试使用。该设置未来可能会以不向后兼容的方式变更,或被移除。
- 0 - 禁用
- 1 - 启用