Package org.elasticsearch.xpack.esql.optimizer.rules.physical.local

Class PushTopNIntoExternalSource

java.lang.Object
org.elasticsearch.xpack.esql.rule.Rule<TopNExec,PhysicalPlan>
org.elasticsearch.xpack.esql.rule.ParameterizedRule<TopNExec,PhysicalPlan,LocalPhysicalOptimizerContext>
org.elasticsearch.xpack.esql.optimizer.PhysicalOptimizerRules.ParameterizedOptimizerRule<TopNExec,LocalPhysicalOptimizerContext>
org.elasticsearch.xpack.esql.optimizer.rules.physical.local.PushTopNIntoExternalSource
public class PushTopNIntoExternalSource extends PhysicalOptimizerRules.ParameterizedOptimizerRule<TopNExec,LocalPhysicalOptimizerContext>
Annotates an ExternalSourceExec with a Top-N grouping hint when the local plan tree has the shape TopNExec → AggregateExec → ... → ExternalSourceExec and every sort key maps to one of the aggregate's grouping attributes. The hint flows through the planner into the BlockHash, which prunes non-competitive groups during aggregation, eliminating the need to materialize the full hash table.

Conditions for the rule to fire:

  • Every Order in the sort references one of the aggregate's grouping attributes (not an aggregation output such as COUNT(*)).
  • The primary (first) sort key's element type is supported by a Top-N BlockHash implementation (currently ElementType.LONG and ElementType.BYTES_REF).
  • The limit is a non-negative integer literal.
  • The aggregate's child subtree contains an ExternalSourceExec.

The TopNExec and AggregateExec nodes are not removed: they remain as the correctness safety net (necessary for distributed execution where each node prunes independently and the coordinator merges partial results). Only the ExternalSourceExec.pushedTopN() field is set.