Module org.elasticsearch.compute
Package org.elasticsearch.compute.operator.topn

Class NumericTopNOperator

java.lang.Object
org.elasticsearch.compute.operator.topn.NumericTopNOperator
All Implemented Interfaces:
Closeable, AutoCloseable, Operator, Releasable
public final class NumericTopNOperator extends Object implements Operator
Specialised, allocation-free Top-K operator for a single fixed-width numeric sort key sitting directly above an ExternalSourceExec that has been narrowed to [sortKey, _rowPosition] by the InsertExternalFieldExtraction rule.

The operator replaces TopNOperator for this specific plan shape: instead of encoding each sort key into a BytesRef and ranking TopNRow objects in a Lucene PriorityQueue, it ranks primitive long encodings directly using PrimitiveTernaryHeap. The encoding maps the raw sort value to a long such that "more competitive" corresponds to "larger encoded" — a min-heap of size K then exactly holds the top-K most competitive rows, with the root being the rejection threshold for the next incoming row.

Scope (PR 1, Tier 1):

  • Exactly one sort key.
  • Sort key ElementType is ElementType.LONG, ElementType.INT, ElementType.DOUBLE, or ElementType.BOOLEAN. ESQL DATETIME and DATE_NANOS map to LONG at planning time, so they go through the LONG path. ESQL FLOAT, HALF_FLOAT and SCALED_FLOAT widen to DOUBLE on load so they reach this operator as DoubleBlock.
  • Input page has exactly 2 channels in this fixed order: [sortKey, _rowPosition]. Enforced by LocalExecutionPlanner.tryBuildNumericTopN(), asserted at runtime.
  • Sort key may contain nulls and may be multi-valued. Multi-values are reduced to the most-favourable single value for the configured direction (MV-min for ASC, MV-max for DESC) — exactly the semantics the generic TopNOperator applies via its KeyExtractorForX family. An empty MV slot is treated as a null. See NumericSortKeyExtractor for the per-type breakdown.

Out of scope (deferred PRs): multi-key sorts, byte-keyed sorts, UNSIGNED_LONG sort keys.

  • Field Details

    • SORT_KEY_CHANNEL

      public static final int SORT_KEY_CHANNEL
      Channel of the primary sort key in every input page.
      See Also:

    • ROW_POSITION_CHANNEL

      public static final int ROW_POSITION_CHANNEL
      Channel of the synthetic _rowPosition column in every input page.
      See Also:

  • Method Details

    • needsInput

      public boolean needsInput()
      Description copied from interface: Operator
      whether the given operator can accept more input pages
      Specified by:
      needsInput in interface Operator

    • addInput

      public void addInput(Page page)
      Description copied from interface: Operator
      adds an input page to the operator. only called when needsInput() == true and isFinished() == false
      Specified by:
      addInput in interface Operator

    • finish

      public void finish()
      Description copied from interface: Operator
      notifies the operator that it won't receive any more input pages
      Specified by:
      finish in interface Operator

    • isFinished

      public boolean isFinished()
      Description copied from interface: Operator
      whether the operator has finished processing all input pages and made the corresponding output pages available
      Specified by:
      isFinished in interface Operator

    • canProduceMoreDataWithoutExtraInput

      public boolean canProduceMoreDataWithoutExtraInput()
      Description copied from interface: Operator
      Returns true if the operator can produce more output pages without requiring additional input pages. This is useful for operators that buffer data or have internal state that can produce multiple output pages.

      Operators that do not buffer data should return false - they cannot produce pages out of thin air. Examples of operators that may return true:

      • Operators with internal buffers (e.g., AsyncOperator with pending results)
      • Operators processing a single input page into multiple output pages
      • Aggregation operators that buffer partial results
      Specified by:
      canProduceMoreDataWithoutExtraInput in interface Operator
      Returns:
      true if the operator has buffered data that can produce output, false otherwise

    • getOutput

      public Page getOutput()
      Description copied from interface: Operator
      returns non-null if output page available. Only called when isFinished() == false
      Specified by:
      getOutput in interface Operator

    • close

      public void close()
      Description copied from interface: Operator
      notifies the operator that it won't be used anymore (i.e. none of the other methods called), and its resources can be cleaned up
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Specified by:
      close in interface Operator
      Specified by:
      close in interface Releasable

    • status

      public Operator.Status status()
      Description copied from interface: Operator
      The status of the operator.
      Specified by:
      status in interface Operator

    • toString

      public String toString()
      Overrides:
      toString in class Object