Package org.elasticsearch.xpack.esql.datasources.spi

Interface RowPositionStrategy

All Known Implementing Classes:
NullSpliceRowPositionStrategy, PassThroughRowPositionStrategy
public interface RowPositionStrategy
Per-reader strategy for populating the _rowPosition slot in emitted pages.

Every FormatReader declares its strategy via FormatReader.rowPositionStrategy(); the dispatcher applies the strategy polymorphically — there is no switch over reader types and no instanceof check on the reader. The strategy is a small, focused object that owns both the question "does the reader natively populate _rowPosition?" and the follow-up "if not, how should the slot be filled?".

Two concrete shapes today: PassThroughRowPositionStrategy for readers that fill the slot themselves in their native iterator (parquet-mr, ORC, CSV, NDJSON), and NullSpliceRowPositionStrategy for readers that have no row-position channel and must surface NULL (parquet-rs). A future ByteOffsetRowPositionStrategy can lift the per-batch byte-offset injection out of the CSV / NDJSON hot path without touching the dispatcher.

Adding a new strategy is the only change required to support a new reader family — every dispatch site already calls strategy.apply(inner, ctx) polymorphically.

  • Method Summary

    Modifier and Type
    Method
    Description
    CloseableIterator<Page>
    apply(CloseableIterator<Page> inner, int rowPositionSlot)
    Wrap (or pass through) the reader's inner page iterator so each page has the _rowPosition slot populated.
    default String
    reason()
    Human-readable reason why this strategy emits the shape it does, available to wrapping iterators for their describe() output (the null-splice iterator embeds it) so _id composition against a null-splice reader is attributable rather than silently null.

  • Method Details

    • apply

      CloseableIterator<Page> apply(CloseableIterator<Page> inner, int rowPositionSlot)
      Wrap (or pass through) the reader's inner page iterator so each page has the _rowPosition slot populated. Validates any preconditions this strategy requires; throws IllegalStateException when a precondition is unmet (e.g. byte-offset strategy called with no decompressed anchor).
      Parameters:
      rowPositionSlot - the index in the projected output where _rowPosition sits, or -1 when _rowPosition is not in the projection. The dispatcher pre-computes this once per reader.read() so strategies inspect a primitive instead of walking a list per call.

    • reason

      default String reason()
      Human-readable reason why this strategy emits the shape it does, available to wrapping iterators for their describe() output (the null-splice iterator embeds it) so _id composition against a null-splice reader is attributable rather than silently null. The default returns the simple class name; the null-splice strategy overrides to expose its constructor reason.