feat(core): add TopNRel physical operator

[nielspardon]

What

Adds core support for the TopNRel physical relational operator, introduced to the
Substrait spec in substrait#1009
and released in v0.88.0 (the spec version this repo's submodule pins). TopNRel
is a combined sort + fetch operator (top_n = 23 in the Rel oneof) — a genuinely new
relation rather than sugar over the existing Sort + Fetch, since it uses
Expression-based offset/count and adds WITH TIES semantics.

Changes

• New POJO io.substrait.relation.physical.TopN (a SingleInputRel): >= 1 sort
  fields, Optional<Expression> offset (null → 0) and count (absent → ALL), and a nested
  Mode enum (ROWS_ONLY / WITH_TIES, default ROWS_ONLY) that maps to/from the proto
  FetchMode via toProto() / fromProto().
• Relation visitor wiring: RelVisitor.visit(TopN), an AbstractRelVisitor fallback
  default, and RelCopyOnWriteVisitor.visit(TopN).
• Both proto converters: RelProtoConverter (POJO → proto) and ProtoRelConverter
  (proto → POJO, including the TOP_N dispatch case).
• DSL helper SubstraitBuilder.topN(...) for ergonomics.
• Proto round-trip test TopNRelRoundtripTest covering rows-only, offset+count,
  count-absent (ALL), WITH_TIES, default mode, multiple sort fields, and nesting.

Mode normalization

The POJO Mode enum models only the two modes a producer may set (ROWS_ONLY, WITH_TIES). On
proto → POJO conversion, an unset/FETCH_MODE_UNSPECIFIED mode is normalized to ROWS_ONLY,
which the spec defines as its default — so downstream code never encounters an unspecified mode.
The consequence is that a proto → POJO → proto pass over a plan with an unset mode is not
byte-identical (mode 0 → 1) but is semantically equivalent — the kind of spec-irrelevant
difference tracked by #994 (semantics-aware plan comparison).

Scope

Engine mappings for isthmus (Calcite) and Spark are intentionally out of scope:
those integrations map only logical operators today, and neither engine has a native
single top-N node or WITH TIES semantics, so how to map this physical operator there is a
separate decision left for a follow-up. To keep the two direct RelVisitor implementors
outside :core compiling, SqlKindFromRel returns SELECT for TopN and the example
SubstraitStringify gains a stringify branch — no behavioral engine mapping is added.

Testing

./gradlew clean build passes: :core (PMD, javadoc, spotless, tests incl. the new
round-trip test), :isthmus, :examples:substrait-spark, and all three Spark variants
(spark-3.4_2.12, spark-3.5_2.12, spark-4.0_2.13).

Closes #806

🤖 Generated with AI