feat(core): add SubstraitBuilder.fieldReference(s) methods for joins

Signed-off-by: Niels Pardon <par@zurich.ibm.com>

Author: nielspardon

core/src/main/java/io/substrait/dsl/SubstraitBuilder.java

@@ -508,10 +508,40 @@ public List<FieldReference> fieldReferences(Rel input, int... indexes) {
         .collect(java.util.stream.Collectors.toList());
   }
 
+  /**
+   * Creates a field reference for a join operation by index across both left and right relations.
+   * The index spans across the combined schema of both join inputs, where fields from the left
+   * relation come first, followed by fields from the right relation.
+   *
+   * @param inputs the join inputs containing both left and right relations
+   * @param index the zero-based field index across the combined schema of both relations
+   * @return a {@link FieldReference} pointing to the specified field in the join context
+   */
+  public FieldReference fieldReference(JoinInput inputs, int index) {
+    return FieldReference.newInputRelReference(index, List.of(inputs.left, inputs.right));
+  }
+
   public FieldReference fieldReference(List<Rel> inputs, int index) {
     return FieldReference.newInputRelReference(index, inputs);
   }
 
+  /**
+   * Creates multiple field references for a join operation by indexes across both left and right
+   * relations. Each index spans across the combined schema of both join inputs, where fields from
+   * the left relation come first, followed by fields from the right relation.
+   *
+   * @param inputs the join inputs containing both left and right relations
+   * @param indexes the zero-based field indexes across the combined schema of both relations
+   * @return a list of {@link FieldReference} objects pointing to the specified fields in the join
+   *     context
+   */
+  public List<FieldReference> fieldReferences(JoinInput inputs, int... indexes) {
+    final List<Rel> inputsList = List.of(inputs.left, inputs.right);
+    return Arrays.stream(indexes)
+        .mapToObj(index -> fieldReference(inputsList, index))
+        .collect(java.util.stream.Collectors.toList());
+  }
+
   public List<FieldReference> fieldReferences(List<Rel> inputs, int... indexes) {
     return Arrays.stream(indexes)
         .mapToObj(index -> fieldReference(inputs, index))

core/src/test/java/io/substrait/type/proto/JoinRoundtripTest.java

@@ -48,12 +48,11 @@ void mergeJoin() {
 
   @Test
   void nestedLoopJoin() {
-    List<Rel> inputRels = Arrays.asList(leftTable, rightTable);
     Rel rel =
         NestedLoopJoin.builder()
             .from(
                 sb.nestedLoopJoin(
-                    __ ->
+                    inputRels ->
                         sb.equal(sb.fieldReference(inputRels, 0), sb.fieldReference(inputRels, 5)),
                     NestedLoopJoin.JoinType.INNER,
                     leftTable,