From 73b79b8692592ca93a3a421512b6d467976ba503 Mon Sep 17 00:00:00 2001 From: Weizhen Wang Date: Tue, 10 Mar 2026 18:30:42 +0800 Subject: [PATCH 1/4] doc: sync blocklist rule names with planner --- blocklist-control-plan.md | 43 ++++++++++++++++++++++++++++----------- 1 file changed, 31 insertions(+), 12 deletions(-) diff --git a/blocklist-control-plan.md b/blocklist-control-plan.md index e2c39aac442e0..3a34a60dd537a 100644 --- a/blocklist-control-plan.md +++ b/blocklist-control-plan.md @@ -11,22 +11,41 @@ This document introduces how to use the blocklist of optimization rules and the The blocklist of optimization rules is one way to tune optimization rules, mainly used to manually disable some optimization rules. -### Important optimization rules +### Optimization rules and rule names + +The available rule names are defined by each rule's `Name()` method in `pkg/planner/core`. The following table follows the logical optimizer pipeline in `optRuleList`. + +Not every rule applies to every query. Some entries are internal optimizer stages, and some are enabled only for specific query patterns, hints, or session variables. |**Optimization Rule**|**Rule Name**|**Description**| | :--- | :--- | :--- | -| Column pruning | column_prune | One operator will prune the column if it is not needed by the upper executor. | -| Decorrelate subquery | decorrelate | Tries to rewrite the correlated subquery to non-correlated join or aggregation. | -| Aggregation elimination | aggregation_eliminate | Tries to remove unnecessary aggregation operators from the execution plan. | +| Generated column substitution | generate_column_substitute | Replaces eligible expressions with equivalent indexed virtual generated columns so that expression indexes can be used. | +| Column pruning | column_prune | Removes columns that are not needed by upper operators. This rule is executed twice in the logical optimizer pipeline. | +| Result reorder | result_reorder | Adds or completes ordering keys to make result ordering deterministic in special scenarios. | +| Build key information | build_keys | Derives unique key information for logical operators. | +| Decorrelate subquery | decorrelate | Rewrites correlated subqueries to non-correlated joins or aggregations when possible. | +| Semi join rewrite | semi_join_rewrite | Rewrites eligible `EXISTS` semi joins to inner joins with aggregation when the related hint or session variable is enabled. | +| Aggregation elimination | aggregation_eliminate | Removes unnecessary aggregation operators from the execution plan. | +| Skew distinct aggregation rewrite | skew_distinct_agg_rewrite | Rewrites eligible skewed distinct aggregations into two-level aggregations when the rule is enabled. | | Projection elimination | projection_eliminate | Removes unnecessary projection operators from the execution plan. | -| Max/Min elimination | max_min_eliminate | Rewrites some max/min functions in aggregation to the `order by` + `limit 1` form. | -| Predicate pushdown | predicate_push_down | Tries to push predicates down to the operator that is closer to the data source. | -| Outer join elimination | outer_join_eliminate | Tries to remove the unnecessary left join or right join from the execution plan. | -| Partition pruning | partition_processor | Prunes partitions which are rejected by the predicates and rewrite partitioned table query to the `UnionAll + Partition Datasource` form. | -| Aggregation pushdown | aggregation_push_down | Tries to push aggregations down to their children. | -| TopN pushdown | topn_push_down | Tries to push the TopN operator to the place closer to the data source. | +| Max/Min elimination | max_min_eliminate | Rewrites some `MAX()` or `MIN()` aggregations to the `ORDER BY` + `LIMIT 1` form. | +| Constant propagation | constant_propagation | Propagates constant predicates across query blocks and join boundaries. | +| Convert outer joins to inner joins | convert_outer_to_inner_joins | Converts outer joins to inner joins when predicates filter out unmatched rows. | +| Predicate pushdown | predicate_push_down | Pushes predicates down to the operators that are closer to the data source. | +| Outer join elimination | outer_join_eliminate | Removes unnecessary left joins or right joins from the execution plan. | +| Partition pruning | partition_processor | Prunes partitions rejected by predicates and rewrites partitioned table queries to the `UnionAll + Partition DataSource` form. | +| Collect predicate columns point | collect_predicate_columns_point | Collects predicate columns and prunes access paths for later statistics loading. | +| Aggregation pushdown | aggregation_push_down | Pushes aggregations down to their children. | +| Derive TopN or Limit from window functions | derive_topn_from_window | Derives `TopN` or `Limit` operators from window functions. | +| Predicate simplification | predicate_simplification | Simplifies predicates by consolidating ranges and removing impossible branches. | +| TopN pushdown | topn_push_down | Pushes the `TopN` operator closer to the data source. | +| Sync wait stats load point | sync_wait_stats_load_point | Waits for synchronous statistics loading before later cost-sensitive optimization stages continue. | | Join reorder | join_reorder | Decides the order of multi-table joins. | -| Derive TopN or Limit from window functions | derive_topn_from_window | Derives the TopN or Limit operator from window functions. | +| Outer join to semi join rewrite | outer_join_to_semi_join | Rewrites eligible outer join plus `IS NULL` patterns to anti semi joins. | +| Push down sequence | push_down_sequence | Pushes `LogicalSequence` nodes down the logical plan when possible. | +| Eliminate empty `UnionAll` branches | union_all_eliminate_dual_item | Removes empty `TableDual` branches from `UnionAll` plans. | +| Eliminate empty selection | eliminate_empty_selection | Removes `Selection` operators that have no remaining predicates. | +| Resolve expand | resolve_expand | Finalizes `Expand` projections for grouping sets and `ROLLUP` after earlier logical optimization finishes. | ### Disable optimization rules @@ -36,7 +55,7 @@ You can use the blocklist of optimization rules to disable some of them if some > **Note:** > -> All the following operations need the `super privilege` privilege of the database. Each optimization rule has a name. For example, the name of column pruning is `column_prune`. The names of all optimization rules can be found in the second column of the table [Important Optimization Rules](#important-optimization-rules). +> All the following operations need the `super privilege` privilege of the database. Each optimization rule has a name. For example, the name of column pruning is `column_prune`. The names of all optimization rules can be found in the second column of the table [Optimization rules and rule names](#optimization-rules-and-rule-names). - If you want to disable some rules, write its name to the `mysql.opt_rule_blacklist` table. For example: From f80079f7253d5ad9fb45233264d694e4dc12c03e Mon Sep 17 00:00:00 2001 From: Weizhen Wang Date: Tue, 10 Mar 2026 21:45:03 +0800 Subject: [PATCH 2/4] doc: make blocklist rule section user-facing --- blocklist-control-plan.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/blocklist-control-plan.md b/blocklist-control-plan.md index 3a34a60dd537a..fc8820bfab468 100644 --- a/blocklist-control-plan.md +++ b/blocklist-control-plan.md @@ -11,16 +11,16 @@ This document introduces how to use the blocklist of optimization rules and the The blocklist of optimization rules is one way to tune optimization rules, mainly used to manually disable some optimization rules. -### Optimization rules and rule names +### Important optimization rules -The available rule names are defined by each rule's `Name()` method in `pkg/planner/core`. The following table follows the logical optimizer pipeline in `optRuleList`. +The following table lists the optimization rules that can be controlled by the blocklist and their corresponding rule names. -Not every rule applies to every query. Some entries are internal optimizer stages, and some are enabled only for specific query patterns, hints, or session variables. +Not every rule applies to every query. Some rules are effective only for specific query patterns, SQL features, hints, or session variables. |**Optimization Rule**|**Rule Name**|**Description**| | :--- | :--- | :--- | | Generated column substitution | generate_column_substitute | Replaces eligible expressions with equivalent indexed virtual generated columns so that expression indexes can be used. | -| Column pruning | column_prune | Removes columns that are not needed by upper operators. This rule is executed twice in the logical optimizer pipeline. | +| Column pruning | column_prune | Removes columns that are not needed by upper operators. This rule is executed twice during logical optimization. | | Result reorder | result_reorder | Adds or completes ordering keys to make result ordering deterministic in special scenarios. | | Build key information | build_keys | Derives unique key information for logical operators. | | Decorrelate subquery | decorrelate | Rewrites correlated subqueries to non-correlated joins or aggregations when possible. | @@ -55,7 +55,7 @@ You can use the blocklist of optimization rules to disable some of them if some > **Note:** > -> All the following operations need the `super privilege` privilege of the database. Each optimization rule has a name. For example, the name of column pruning is `column_prune`. The names of all optimization rules can be found in the second column of the table [Optimization rules and rule names](#optimization-rules-and-rule-names). +> All the following operations need the `super privilege` privilege of the database. Each optimization rule has a name. For example, the name of column pruning is `column_prune`. The names of all optimization rules can be found in the second column of the table [Important optimization rules](#important-optimization-rules). - If you want to disable some rules, write its name to the `mysql.opt_rule_blacklist` table. For example: From 4779f3204e2fcce0770b472a9cb3ab95574ba2b7 Mon Sep 17 00:00:00 2001 From: Weizhen Wang Date: Wed, 11 Mar 2026 14:18:13 +0800 Subject: [PATCH 3/4] doc: trim internal optimizer rules from blocklist table --- blocklist-control-plan.md | 16 ++++------------ 1 file changed, 4 insertions(+), 12 deletions(-) diff --git a/blocklist-control-plan.md b/blocklist-control-plan.md index fc8820bfab468..ad28d01e482f6 100644 --- a/blocklist-control-plan.md +++ b/blocklist-control-plan.md @@ -13,16 +13,14 @@ The blocklist of optimization rules is one way to tune optimization rules, mainl ### Important optimization rules -The following table lists the optimization rules that can be controlled by the blocklist and their corresponding rule names. +The following table lists common optimization rules that can be controlled by the blocklist and their corresponding rule names. Not every rule applies to every query. Some rules are effective only for specific query patterns, SQL features, hints, or session variables. |**Optimization Rule**|**Rule Name**|**Description**| | :--- | :--- | :--- | | Generated column substitution | generate_column_substitute | Replaces eligible expressions with equivalent indexed virtual generated columns so that expression indexes can be used. | -| Column pruning | column_prune | Removes columns that are not needed by upper operators. This rule is executed twice during logical optimization. | -| Result reorder | result_reorder | Adds or completes ordering keys to make result ordering deterministic in special scenarios. | -| Build key information | build_keys | Derives unique key information for logical operators. | +| Column pruning | column_prune | Removes columns that are not needed by upper operators. | | Decorrelate subquery | decorrelate | Rewrites correlated subqueries to non-correlated joins or aggregations when possible. | | Semi join rewrite | semi_join_rewrite | Rewrites eligible `EXISTS` semi joins to inner joins with aggregation when the related hint or session variable is enabled. | | Aggregation elimination | aggregation_eliminate | Removes unnecessary aggregation operators from the execution plan. | @@ -33,19 +31,13 @@ Not every rule applies to every query. Some rules are effective only for specifi | Convert outer joins to inner joins | convert_outer_to_inner_joins | Converts outer joins to inner joins when predicates filter out unmatched rows. | | Predicate pushdown | predicate_push_down | Pushes predicates down to the operators that are closer to the data source. | | Outer join elimination | outer_join_eliminate | Removes unnecessary left joins or right joins from the execution plan. | -| Partition pruning | partition_processor | Prunes partitions rejected by predicates and rewrites partitioned table queries to the `UnionAll + Partition DataSource` form. | -| Collect predicate columns point | collect_predicate_columns_point | Collects predicate columns and prunes access paths for later statistics loading. | +| Partition pruning | partition_processor | Prunes partitions rejected by predicates. | | Aggregation pushdown | aggregation_push_down | Pushes aggregations down to their children. | | Derive TopN or Limit from window functions | derive_topn_from_window | Derives `TopN` or `Limit` operators from window functions. | | Predicate simplification | predicate_simplification | Simplifies predicates by consolidating ranges and removing impossible branches. | | TopN pushdown | topn_push_down | Pushes the `TopN` operator closer to the data source. | -| Sync wait stats load point | sync_wait_stats_load_point | Waits for synchronous statistics loading before later cost-sensitive optimization stages continue. | | Join reorder | join_reorder | Decides the order of multi-table joins. | | Outer join to semi join rewrite | outer_join_to_semi_join | Rewrites eligible outer join plus `IS NULL` patterns to anti semi joins. | -| Push down sequence | push_down_sequence | Pushes `LogicalSequence` nodes down the logical plan when possible. | -| Eliminate empty `UnionAll` branches | union_all_eliminate_dual_item | Removes empty `TableDual` branches from `UnionAll` plans. | -| Eliminate empty selection | eliminate_empty_selection | Removes `Selection` operators that have no remaining predicates. | -| Resolve expand | resolve_expand | Finalizes `Expand` projections for grouping sets and `ROLLUP` after earlier logical optimization finishes. | ### Disable optimization rules @@ -55,7 +47,7 @@ You can use the blocklist of optimization rules to disable some of them if some > **Note:** > -> All the following operations need the `super privilege` privilege of the database. Each optimization rule has a name. For example, the name of column pruning is `column_prune`. The names of all optimization rules can be found in the second column of the table [Important optimization rules](#important-optimization-rules). +> All the following operations need the `super privilege` privilege of the database. Each optimization rule has a name. For example, the name of column pruning is `column_prune`. The rule names listed in [Important optimization rules](#important-optimization-rules) are shown in the second column. - If you want to disable some rules, write its name to the `mysql.opt_rule_blacklist` table. For example: From cb7d8e01c2d6db007767897d65905627d6704482 Mon Sep 17 00:00:00 2001 From: Weizhen Wang Date: Wed, 11 Mar 2026 23:43:33 +0800 Subject: [PATCH 4/4] doc: drop partition pruning from blocklist table --- blocklist-control-plan.md | 1 - 1 file changed, 1 deletion(-) diff --git a/blocklist-control-plan.md b/blocklist-control-plan.md index ad28d01e482f6..377908e8dbe48 100644 --- a/blocklist-control-plan.md +++ b/blocklist-control-plan.md @@ -31,7 +31,6 @@ Not every rule applies to every query. Some rules are effective only for specifi | Convert outer joins to inner joins | convert_outer_to_inner_joins | Converts outer joins to inner joins when predicates filter out unmatched rows. | | Predicate pushdown | predicate_push_down | Pushes predicates down to the operators that are closer to the data source. | | Outer join elimination | outer_join_eliminate | Removes unnecessary left joins or right joins from the execution plan. | -| Partition pruning | partition_processor | Prunes partitions rejected by predicates. | | Aggregation pushdown | aggregation_push_down | Pushes aggregations down to their children. | | Derive TopN or Limit from window functions | derive_topn_from_window | Derives `TopN` or `Limit` operators from window functions. | | Predicate simplification | predicate_simplification | Simplifies predicates by consolidating ranges and removing impossible branches. |