Skip to content

fix(scheduler): give unsplittable UNION ALL branches a stage of their own under the adaptive planner - #2914

Draft
NoahKusaba wants to merge 1 commit into
apache:mainfrom
NoahKusaba:aqe-union-branch-stage
Draft

NoahKusaba wants to merge 1 commit into
apache:mainfrom
NoahKusaba:aqe-union-branch-stage

Conversation

@NoahKusaba

Copy link
Copy Markdown
Contributor

Which issue does this PR close?

Closes #2854.

Rationale for this change

When a union's stage is split between tasks, each task restricts the UnionExec branches other tasks own to no partitions. A branch that merges its input into one partition (a SortExec from an ORDER BY, a global aggregate, a LIMIT) keeps its one partition however its inputs are restricted, so every task would run it. #2852 stopped the wrong rows by running such a stage as one task, which costs parallelism. The static planner has always avoided the problem by giving such a branch a stage of its own (can_stay_inline, #2184). The adaptive planner had no equivalent.

Restriction can't fix this per task. Emptying the whole branch changes the task plan's node count, and emptying only its leaves still leaves a global aggregate's count = 0 row. So the boundary has to be placed when the plan is made.

What changes are included in this PR?

  • DistributedExchangeRule stages unsplittable union branches. Each UnionExec branch is put to branch_splits, the same test the static planner uses, as the stage's tasks would see it: its exchanges replaced by their readers (BallistaAdapter::with_readers). A branch that fails gets an ExchangeExec. A branch over an exchange that hasn't run is judged in a later pass, once its reader can be built. The union's stage can't start before then, and a replan follows every finished stage. The rule's other arms already wait the same way.
  • A union of stage boundaries counts as a boundary. Without this, ORDER BY over a union whose branches were all cut got a union stage that only copied its readers into another shuffle for the merge. is_stage_boundary now counts a UnionExec whose branches are all boundaries, and the coalesce and null-aware probe arms use it as well, in place of their bare ExchangeExec checks. No existing plan changes.
  • Remove fix(scheduler): fix split UNION ALL stages over custom sources or with merging branches #2852's one-task fallback. With both planners staging such branches, nothing needs it: the union check in binding, its packing and vcore rule in bind_one, the cache on RunningStage, the resolver carried on JobInfoCache, and the #[non_exhaustive] markers those fields needed. cluster/mod.rs is back to its state before fix(scheduler): fix split UNION ALL stages over custom sources or with merging branches #2852. ensure_branch_restricted stays as a backstop: should a planner leave such a branch in the union's stage, the task is refused rather than return rows twice. branch_splits loses its resolver parameter, since both callers pass none.

Tests:

  • A rule test covering four branch shapes: a scan stays, a sort is staged, a sort over an exchange that hasn't run waits, and an exchange that has run stays as a reader. A second rule test covers a coalesce reading a union of staged branches directly.
  • Planner tests that snapshot every stage of a UNION ALL of global aggregates, and of ORDER BY over a UNION ALL of one-partition branches (3 stages, the merge reading both sorted branches).
  • split_union.rs already runs the merging-branch queries adaptively at 1 and 2 partitions per task. Before this PR, 7 of its union stages were run as one task. With it there are none, and none hit the backstop error.

Are there any user-facing changes?

Under the adaptive planner, a UNION ALL branch that merges its input now gets a stage of its own. The union's stage splits between tasks again, instead of running as one task that ignores ballista.scheduler.max_partitions_per_task. Each such branch adds a stage, which runs in parallel with the others. The 56.0.0 upgrade note and the resolver docs in extending-components.md are updated accordingly.

Some cases behave differently from #2852:

  • A union branch over a custom leaf of more than one partition, with no resolver, now gets its own stage. Like any stage over such a leaf, that stage needs a resolver when it's split. Before, it worked only because the whole union stage ran as one task. Iceberg scans report one partition and stay inline.
  • An embedder's replan_rules run after DistributedExchangeRule. A rule that puts a node that keeps its own partition count into a union branch now hits the backstop error when the stage is split, instead of the stage running as one task.

No public API changes compared with 55.0.0. JobInfoCache and RunningStage are as they were before #2852, which was going to change them in 56.0.0.

… own under the adaptive planner

When a union's stage is split between tasks, each task restricts the
branches other tasks own to no partitions. A branch that merges its input
into one partition, such as a sort, a global aggregate or a LIMIT, keeps
its partition however its inputs are restricted, so every task would run
it. apache#2852 made the scheduler run such a stage as one task; the static
planner has always given such a branch a stage of its own.

DistributedExchangeRule now does the same, asking the same question as the
static planner (branch_splits) of each branch as its stage's tasks would see
it, with its exchanges replaced by their readers. A branch over an exchange
that hasn't run is judged in a later pass, before the union's stage can
start.

A union whose branches are all stage boundaries now counts as a boundary
itself, so a merge or coalesce above it reads the branches directly instead
of through a stage that would only copy them.

With the planners covering every such branch, remove the one-task fallback:
the union check and its packing in bind_one, the cache on RunningStage, the
resolver carried on JobInfoCache, and the #[non_exhaustive] markers those
fields needed. Restriction still refuses a task whose union branch keeps
partitions, as a backstop.
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Nov 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Adaptive planner: a UNION ALL branch that collapses its input returns duplicate rows when its stage is split

1 participant