pkg/planner: add order-aware logical join reorder rule

[AilinKid]

What problem does this PR solve?

Issue Number: ref #65208

Problem Summary:

The order-aware logic for the new CD-C join reorder path should live in a separate logical rule instead of being mixed into the generic join reorder solver.

What changed and how does it work?

This PR adds a new logical rule that inspects join groups with propagated TopN / ORDER BY columns, reuses the CD-C extractJoinGroup logic, and injects an internal LEADING preference when one ordered leaf can preserve the required ordering with compatible equality filters.

The change also adds dedicated planner rule tests for the new order-aware path.

Check List

Tests

• Unit test
• Integration test
• Manual test (add detailed scripts or steps below)
• No need to test

  • I checked and no code files have been changed.

Side effects

• Performance regression: Consumes more CPU
• Performance regression: Consumes more Memory
• Breaking backward compatibility

Documentation

• Affects user behaviors
• Contains syntax changes
• Contains variable changes
• Contains experimental features
• Changes MySQL compatibility

Release note

Please refer to Release Notes Language Style Guide to write a quality release note.

None

Summary by CodeRabbit

• New Features

  • Adds an order-aware join reordering optimizer that preserves ORDER BY semantics for order-sensitive queries and honors session controls to disable it.

• Behavior

  • Reduces spurious hint warnings by suppressing messages for internally generated join-order hints.
  • Enables order-aware reordering in additional query patterns (e.g., IN-subquery-to-join scenarios).

• Tests

  • Adds casetests and expected data validating plan and result equivalence for order-aware join reorders.

• Chores

  • Increased test shard count for the new casetests.

[ti-chi-bot]

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds an order-aware join-reorder optimization: new OrderAwareJoinReorder rule, join-order annotation (ordered-leading choice) and internal hint fields, new planner flag, build/test updates, and casetest suites validating ordering-preserving join reorders.

Changes

Cohort / File(s)	Summary
Build / Targets pkg/planner/core/BUILD.bazel, pkg/planner/core/casetest/rule/BUILD.bazel, pkg/planner/core/joinorder/BUILD.bazel	Added new source(s) to core and joinorder libraries, added //pkg/meta/model dep, and increased test shard count (25→27).
Optimizer integration pkg/planner/core/optimizer.go, pkg/planner/core/rule/logical_rules.go	Inserted OrderAwareJoinReorder into opt rule list and added FlagOrderAwareJoinReorder; cleared the flag when StraightJoinOrder is enabled.
Order-aware rule pkg/planner/core/rule_order_aware_join_reorder.go	New OrderAwareJoinReorder rule that propagates ordering columns through TopN/Sort/Projection/Limit/Selection/Join and invokes annotation/child traversal when appropriate.
Join-order annotation pkg/planner/core/joinorder/ordered_leading.go, pkg/planner/core/joinorder/...	Added exported OrderedLeadingChoice, FindOrderedLeadingChoice, TryAnnotateOrderedLeading and helpers to detect index/order satisfaction and synthesize internal LEADING hint.
Planner flagging points pkg/planner/core/expression_rewriter.go, pkg/planner/core/logical_plan_builder.go	Set FlagOrderAwareJoinReorder when rewriting IN-subqueries and when building joins (in addition to existing join-reorder flag).
Join-group / hint handling pkg/planner/core/joinorder/join_order.go, pkg/planner/core/operator/logicalop/logical_join.go	Track hasUserLeadingHint in join groups; add InternalHintInfo and InternalPreferJoinOrder fields on LogicalJoin and propagate internal hint state during semi-join rewrite; suppress user-warning emission for internal hints.
Tests — harness & cases pkg/planner/core/casetest/rule/main_test.go, pkg/planner/core/casetest/rule/rule_cdc_join_reorder_test.go	Registered order_aware_join_reorder_suite, added GetOrderAwareJoinReorderSuiteData() and tests TestOrderAwareCDCJoinReorder / TestOrderAwareJoinReorderPushSelection which prepare tables, run cases, and validate plans/results and hint warnings.
Testdata pkg/planner/core/casetest/rule/testdata/order_aware_join_reorder_suite_in.json, ..._out.json, ..._xut.json	Added three casetest JSON files specifying queries, expected plan trees, and expected results for order-aware join-reorder scenarios.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant Optimizer as Optimizer/RuleRunner
  participant Rule as OrderAwareJoinReorder
  participant JoinOrder as joinorder.AnnotateOrderedLeading
  participant PlannerNodes as LogicalPlan

  Client->>Optimizer: request plan build (root)
  Optimizer->>Rule: OrderAwareJoinReorder.Optimize(root)
  Rule->>PlannerNodes: traverse nodes (TopN/Sort/Proj/Limit/Selection/Join)
  alt ordering columns found
    Rule->>JoinOrder: FindOrderedLeadingChoice(root/group, orderingCols)
    JoinOrder-->>Rule: choice or nil
    alt choice found
      Rule->>PlannerNodes: annotate anchor join with internal leading hint
    end
  end
  Rule-->>Optimizer: return (plan, changed)
  Optimizer-->>Client: optimized plan

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• planner: enable cd-c algorithm by default for join reorder | tidb-test=pr/2676 #66349: Modifies planner join-reorder logic and introduces CDC/order-aware join-reorder paths — closely related.
• planner/core: disable new join reorder when DP is enabled #67079: Adjusts gating/conditions around advanced join-reorder invocation used by the new rule.
• planner/core: implement DP join reorder algorithm #67284: Changes joinorder package logic that may interact with the ordered-leading annotation.

Suggested reviewers

• guo-shaoge
• qw4990

Poem

🐇 I hop through plans with nimble feet,
Nudging joins so ORDER stays neat.
Indices aligned, hints tucked inside,
The optimizer sings — reorders with pride.
Hooray — a rabbit's tidy treat!

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 18.75% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title clearly and concisely summarizes the main change: adding a new order-aware logical join reorder rule to the planner package.
Description check	✅ Passed	The PR description includes the required issue reference and explains the problem, changes, and test coverage, though it partially follows the template structure.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[tiprow]

Hi @AilinKid. Thanks for your PR.

PRs from untrusted users cannot be marked as trusted with /ok-to-test in this repo meaning untrusted PR authors can never trigger tests themselves. Collaborators can still trigger tests on the PR using /test all.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[hawkingrei]

/ok-to-test

[pantheon-ai]

Review failed due to infrastructure/execution failure after retries. Please re-trigger review.

_{ℹ️ Learn more details on Pantheon AI.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

pkg/planner/core/joinorder/ordered_leading.go (1)

77-99: Consider handling GenerateQBName error more explicitly.

The error from GenerateQBName is silently swallowed, leaving qbName as an empty CIStr. While this may work (the hint can still match without a QBName), consider logging or documenting this fallback behavior.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@pkg/planner/core/joinorder/ordered_leading.go` around lines 77 - 99, The
function buildSingleTableLeadingHint currently swallows errors from
hint.GenerateQBName leaving qbName empty; update buildSingleTableLeadingHint to
handle the error explicitly by checking the returned err and logging or
recording it (e.g., using the package logger or standard log) when err != nil,
so callers can see why a QBName wasn't generated; keep the fallback behavior of
using an empty ast.CIStr but add a clear log message referencing GenerateQBName,
qbName and buildSingleTableLeadingHint so the failure is discoverable during
debugging.

plans/order-aware-cdc-join-reorder-rule.md (1)

9-9: Minor: Hyphenate compound adjective.

Static analysis flagged "CD-C based" should be "CD-C-based" when used as a compound adjective.

📝 Suggested fix

-and feed that preference into the new CD-C based join reorder implementation as a separate logical rule.
+and feed that preference into the new CD-C-based join reorder implementation as a separate logical rule.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@plans/order-aware-cdc-join-reorder-rule.md` at line 9, The phrase "CD-C
based" is a compound adjective and should be hyphenated as "CD-C-based"; update
the text where it appears (context: the sentence mentioning "CD-C based join
reorder implementation" and references to JoinReOrderSolver and join group) to
use "CD-C-based" so the compound modifier is correct and consistent with
surrounding wording.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@pkg/planner/core/rule_order_aware_join_reorder.go`:
- Around line 92-95: The tests enable the failpoint "enableCDCJoinReorder" but
production lacks a failpoint hook, so update shouldUseCDCBasedJoinReorder (or an
appropriate initializer in the joinorder module) to honor that failpoint: add a
failpoint.Inject("enableCDCJoinReorder", ...) branch that forces a true/false
return or toggles the session var checks so the function returns the intended
value during tests; ensure the injected branch short-circuits or sets
vars.TiDBOptEnableAdvancedJoinReorder / vars.TiDBOptJoinReorderThreshold
equivalently so existing callers of shouldUseCDCBasedJoinReorder behave as tests
expect.

---

Nitpick comments:
In `@pkg/planner/core/joinorder/ordered_leading.go`:
- Around line 77-99: The function buildSingleTableLeadingHint currently swallows
errors from hint.GenerateQBName leaving qbName empty; update
buildSingleTableLeadingHint to handle the error explicitly by checking the
returned err and logging or recording it (e.g., using the package logger or
standard log) when err != nil, so callers can see why a QBName wasn't generated;
keep the fallback behavior of using an empty ast.CIStr but add a clear log
message referencing GenerateQBName, qbName and buildSingleTableLeadingHint so
the failure is discoverable during debugging.

In `@plans/order-aware-cdc-join-reorder-rule.md`:
- Line 9: The phrase "CD-C based" is a compound adjective and should be
hyphenated as "CD-C-based"; update the text where it appears (context: the
sentence mentioning "CD-C based join reorder implementation" and references to
JoinReOrderSolver and join group) to use "CD-C-based" so the compound modifier
is correct and consistent with surrounding wording.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 09990315-15d5-452d-bd22-f499c87a18b2

📥 Commits

Reviewing files that changed from the base of the PR and between c5b7db3 and 9157837.

📒 Files selected for processing (13)

• pkg/planner/core/BUILD.bazel
• pkg/planner/core/casetest/rule/BUILD.bazel
• pkg/planner/core/casetest/rule/main_test.go
• pkg/planner/core/casetest/rule/rule_cdc_join_reorder_test.go
• pkg/planner/core/casetest/rule/testdata/order_aware_join_reorder_suite_in.json
• pkg/planner/core/casetest/rule/testdata/order_aware_join_reorder_suite_out.json
• pkg/planner/core/casetest/rule/testdata/order_aware_join_reorder_suite_xut.json
• pkg/planner/core/joinorder/BUILD.bazel
• pkg/planner/core/joinorder/ordered_leading.go
• pkg/planner/core/operator/logicalop/logical_join.go
• pkg/planner/core/optimizer.go
• pkg/planner/core/rule_order_aware_join_reorder.go
• plans/order-aware-cdc-join-reorder-rule.md

[hawkingrei]

/retest

[ti-chi-bot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: hawkingrei, qw4990

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [hawkingrei,qw4990]
• pkg/planner/OWNERS [hawkingrei,qw4990]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[ti-chi-bot]

[LGTM Timeline notifier]

Timeline:

• 2026-04-01 10:32:51.603506568 +0000 UTC m=+347576.808866615: ☑️ agreed by qw4990.
• 2026-04-02 09:44:57.982352667 +0000 UTC m=+431103.187712724: ☑️ agreed by hawkingrei.

[hawkingrei]

/retest

[hawkingrei]

/retest

[hawkingrei]

/retest

[hawkingrei]

/retest

[hawkingrei]

/retest

[AilinKid]

/retest-required

[AilinKid]

/retest-required

[AilinKid]

/retest-required

[AilinKid]

/retest-required

[AilinKid]

/retest-required

[AilinKid]

/retest-required