feat(ppl): support bare-field join criteria join on <field> shorthand

Let `on`/`where` join criteria accept a bare field name (or `AND` of bare
fields) as shorthand for the qualified equality on that common field:

  source=t1 | inner join on a t2          == on t1.a = t2.a
  source=t1 | inner join on a AND b t2    == on t1.a = t2.a AND t1.b = t2.b
  source=t1 | join on a t2                == on t1.a = t2.a   (no prefix/alias)

The shorthand behaves exactly like the explicit `on l.f = r.f` criteria: it
KEEPS BOTH key columns (the right key renamed `<rightAlias>.f`, or
`<rightTable>.f` when no alias is given). This differs from the field-list
join (`join f t2`), which merges the duplicate key to a single column.

Implementation:
- Grammar: reorder the joinCommand alternatives so the criteria alternative
  is listed first. This lets the no-prefix form `join on a <right>` parse `on`
  as the criteria keyword instead of the field-list alternative greedily
  consuming `on`/`where` as a field name. ANTLR ALL(*) picks the first-listed
  alternative on genuine ambiguity.
- AstBuilder: a bare single-part field (or AND-chain of them) is left as the
  join condition verbatim -- the unresolved AST reflects what the user wrote.
- Planner (CalciteRelNodeVisitor.visitJoin): the criteria branch detects a
  bare-field condition and builds the equi-join from it, resolving each field
  by stack position (LEFT.f = RIGHT.f) via the existing
  buildJoinConditionByFieldName helper. No new planner code, and no AST
  mutation. Because resolution is positional rather than by qualifier, a
  self-join `join on f t` is a genuine cross-scan equi-join rather than the
  `f = f` tautology a name-based rewrite would collapse to.

Adds AstBuilder, Calcite plan, anonymizer, and integration tests; updates the
join command user manual.

Signed-off-by: Hanyu Wei <weihanyu@amazon.com>

Author: Hanyu Wei

core/src/main/java/org/opensearch/sql/calcite/CalciteRelNodeVisitor.java

@@ -1889,10 +1889,22 @@ public RelNode visitJoin(Join node, CalcitePlanContext context) {
       }
     } else {
       // The join-with-criteria grammar doesn't allow empty join condition
-      RexNode joinCondition =
-          node.getJoinCondition()
-              .map(c -> rexVisitor.analyzeJoinCondition(c, context))
-              .orElse(context.relBuilder.literal(true));
+      RexNode joinCondition;
+      List<String> bareFields = new ArrayList<>();
+      if (JoinAndLookupUtils.collectBareFields(node.getJoinCondition().get(), bareFields)) {
+        // Bare-field shorthand `on a [AND b ...]`. Resolving by stack position rather than by
+        // qualifier keeps a self-join `join on f t` a real cross-scan equi-join, not f = f.
+        joinCondition =
+            bareFields.stream()
+                .map(f -> buildJoinConditionByFieldName(context, f))
+                .reduce(context.rexBuilder::and)
+                .orElse(context.relBuilder.literal(true));
+      } else {
+        joinCondition =
+            node.getJoinCondition()
+                .map(c -> rexVisitor.analyzeJoinCondition(c, context))
+                .orElse(context.relBuilder.literal(true));
+      }
       if (node.getJoinType() == SEMI || node.getJoinType() == ANTI) {
         // semi and anti join only return left table outputs
         context.relBuilder.join(

core/src/main/java/org/opensearch/sql/calcite/utils/JoinAndLookupUtils.java

@@ -13,6 +13,10 @@
 import org.apache.calcite.rel.core.JoinRelType;
 import org.apache.calcite.rex.RexNode;
 import org.apache.calcite.util.Pair;
+import org.opensearch.sql.ast.expression.And;
+import org.opensearch.sql.ast.expression.Field;
+import org.opensearch.sql.ast.expression.QualifiedName;
+import org.opensearch.sql.ast.expression.UnresolvedExpression;
 import org.opensearch.sql.ast.tree.Join;
 import org.opensearch.sql.ast.tree.Lookup;
 import org.opensearch.sql.calcite.CalcitePlanContext;
@@ -37,6 +41,24 @@ static JoinRelType translateJoinType(Join.JoinType joinType) {
     }
   }
 
+  /**
+   * Collects the names of bare single-part-field join criteria (e.g. `on a AND b` -> [a, b]).
+   * Returns false for anything else (qualified field, comparison, OR); {@code out} is only valid
+   * when this returns true, so callers must check the return before reading it.
+   */
+  static boolean collectBareFields(UnresolvedExpression expr, List<String> out) {
+    if (expr instanceof And and) {
+      return collectBareFields(and.getLeft(), out) && collectBareFields(and.getRight(), out);
+    }
+    if (expr instanceof Field field
+        && field.getField() instanceof QualifiedName qn
+        && qn.getParts().size() == 1) {
+      out.add(qn.getParts().get(0));
+      return true;
+    }
+    return false;
+  }
+
   /* ------For Lookup------ */
 
   /**

docs/user/ppl/cmd/join.md

@@ -29,6 +29,9 @@ source = table1 | left anti join left = l right = r on l.a = r.a table2
 source = table1 | join left = l right = r [ source = table2 | where d > 10 | head 5 ]
 source = table1 | inner join on table1.a = table2.a table2 | fields table1.a, table2.a, table1.b, table1.c
 source = table1 | inner join on a = c table2 | fields a, b, c, d
+source = table1 | inner join on a table2 | fields a, table2.a, b, c
+source = table1 | inner join on a AND b table2 | fields a, table2.a, b, table2.b
+source = table1 | join on a table2 | fields a, table2.a, b, c
 source = table1 as t1 | join left = l right = r on l.a = r.a table2 as t2 | fields l.a, r.a
 source = table1 as t1 | join left = l right = r on l.a = r.a table2 as t2 | fields t1.a, t2.a
 source = table1 | join left = l right = r on l.a = r.a [ source = table2 ] as s | fields l.a, s.a
@@ -40,7 +43,7 @@ The basic `join` syntax supports the following parameters.
 
 | Parameter | Required/Optional | Description |
 | --- | --- | --- |
-| `<joinCriteria>` | Required | A comparison expression specifying how to join the datasets. Must be placed after the `on` or `where` keyword in the query. |
+| `<joinCriteria>` | Required | A comparison expression specifying how to join the datasets. Must be placed after the `on` or `where` keyword in the query. A bare field name `f` (or `f AND g ...`) is shorthand for an equi-join on the common field(s) and keeps both key columns. |
 | `<right-dataset>` | Required | The right dataset, which can be an index or a subsearch, with or without an alias. |
 | `joinType` | Optional | The type of join to perform. Valid values are `left`, `semi`, `anti`, and performance-sensitive types (`right`, `full`, and `cross`). Default is `inner`. |
 | `left` | Optional | An alias for the left dataset (typically a subsearch) used to avoid ambiguous field names. Specify as `left = <leftAlias>`. |
@@ -71,7 +74,7 @@ The extended `join` syntax supports the following parameters.
 
 | Parameter | Required/Optional | Description |
 | --- | --- | --- |
-| `<joinCriteria>` | Required | A comparison expression specifying how to join the datasets. Must be placed after the `on` or `where` keyword in the query. |
+| `<joinCriteria>` | Required | A comparison expression specifying how to join the datasets. Must be placed after the `on` or `where` keyword in the query. A bare field name `f` (or `f AND g ...`) is shorthand for an equi-join on the common field(s); it keeps both key columns and differs from `<join-field-list>`, which merges duplicates. |
 | `<right-dataset>` | Required | The right dataset, which can be an index or a subsearch, with or without an alias. |  
 | `type` | Optional | The join type when using extended syntax. Valid values are `left`, `outer` (same as `left`), `semi`, `anti`, and performance-sensitive types (`right`, `full`, and `cross`). Default is `inner`. |
 | `<join-field-list>` | Optional | A list of fields used to build the join criteria. These fields must exist in both datasets. If not specified, all fields common to both datasets are used as join keys. |

integ-test/src/test/java/org/opensearch/sql/calcite/remote/CalcitePPLJoinIT.java

@@ -928,6 +928,106 @@ public void testJoinWhenLegacyNotPreferred() throws IOException {
         });
   }
 
+  @Test
+  public void testJoinWithImplicitField() throws IOException {
+    // Keep-both, so co-named columns (other than the key) resolve to the left side.
+    JSONObject actual =
+        executeQuery(
+            String.format(
+                "source=%s | inner join on name %s | fields name, age, state, country, occupation,"
+                    + " salary",
+                TEST_INDEX_STATE_COUNTRY, TEST_INDEX_OCCUPATION));
+    verifySchema(
+        actual,
+        schema("name", "string"),
+        schema("age", "int"),
+        schema("state", "string"),
+        schema("country", "string"),
+        schema("occupation", "string"),
+        schema("salary", "int"));
+    verifyDataRows(
+        actual,
+        rows("Jake", 70, "California", "USA", "Engineer", 100000),
+        rows("Hello", 30, "New York", "USA", "Artist", 70000),
+        rows("John", 25, "Ontario", "Canada", "Doctor", 120000),
+        rows("Jane", 20, "Quebec", "Canada", "Scientist", 90000),
+        rows("David", 40, "Washington", "USA", "Doctor", 120000),
+        rows("David", 40, "Washington", "USA", "Unemployed", 0));
+
+    // The shorthand and the explicit qualified-equality form are output-identical.
+    JSONObject explicitForm =
+        executeQuery(
+            String.format(
+                "source=%s | inner join on %s.name = %s.name %s | fields name, age, state, country,"
+                    + " occupation, salary",
+                TEST_INDEX_STATE_COUNTRY,
+                TEST_INDEX_STATE_COUNTRY,
+                TEST_INDEX_OCCUPATION,
+                TEST_INDEX_OCCUPATION));
+    assertJsonEquals(explicitForm.toString(), actual.toString());
+  }
+
+  @Test
+  public void testJoinNoPrefixImplicitField() throws IOException {
+    // No-prefix `join on name` matches the explicit qualified form, not the field-list `join name`.
+    JSONObject actual =
+        executeQuery(
+            String.format(
+                "source=%s | join on name %s | fields name, age, state, occupation, salary",
+                TEST_INDEX_STATE_COUNTRY, TEST_INDEX_OCCUPATION));
+    JSONObject explicitForm =
+        executeQuery(
+            String.format(
+                "source=%s | join on %s.name = %s.name %s | fields name, age, state, occupation,"
+                    + " salary",
+                TEST_INDEX_STATE_COUNTRY,
+                TEST_INDEX_STATE_COUNTRY,
+                TEST_INDEX_OCCUPATION,
+                TEST_INDEX_OCCUPATION));
+    assertJsonEquals(explicitForm.toString(), actual.toString());
+  }
+
+  @Test
+  public void testLeftJoinWithImplicitField() throws IOException {
+    // Keep-both does not coalesce, so unmatched-left rows keep the non-null left key, not a NULL.
+    JSONObject actual =
+        executeQuery(
+            String.format(
+                "source=%s | left join on name %s | fields name, age, state, occupation, salary",
+                TEST_INDEX_STATE_COUNTRY, TEST_INDEX_OCCUPATION));
+    verifySchema(
+        actual,
+        schema("name", "string"),
+        schema("age", "int"),
+        schema("state", "string"),
+        schema("occupation", "string"),
+        schema("salary", "int"));
+    verifyDataRows(
+        actual,
+        rows("Jake", 70, "California", "Engineer", 100000),
+        rows("Hello", 30, "New York", "Artist", 70000),
+        rows("John", 25, "Ontario", "Doctor", 120000),
+        rows("Jane", 20, "Quebec", "Scientist", 90000),
+        rows("David", 40, "Washington", "Doctor", 120000),
+        rows("David", 40, "Washington", "Unemployed", 0),
+        rows("Jim", 27, "B.C", null, null),
+        rows("Peter", 57, "B.C", null, null),
+        rows("Rick", 70, "B.C", null, null));
+  }
+
+  @Test
+  public void testAliasedSelfJoinWithImplicitField() throws IOException {
+    // Self-join on the unique `name`: a real equi-join matches each of the 8 rows to itself (8
+    // rows), not the 64-row cross product a tautology would give.
+    JSONObject actual =
+        executeQuery(
+            String.format(
+                "source=%s | inner join left=l right=r on name %s | fields name, r.name",
+                TEST_INDEX_STATE_COUNTRY, TEST_INDEX_STATE_COUNTRY));
+    verifyNumOfRows(actual, 8);
+    verifySchema(actual, schema("name", "string"), schema("r.name", "string"));
+  }
+
   @Test
   public void testJoinComparing() throws IOException {
     JSONObject actual =

ppl/src/main/antlr/OpenSearchPPLParser.g4

@@ -729,8 +729,9 @@ sourceFilterArg
 
 // join
 joinCommand
-   : JOIN (joinOption)* (fieldList)? right = tableOrSubqueryClause
-   | sqlLikeJoinType? JOIN (joinOption)* sideAlias joinHintList? joinCriteria right = tableOrSubqueryClause
+   // Criteria alt listed first - so `join on a` reads `on` as the criteria keyword, not a field.
+   : sqlLikeJoinType? JOIN (joinOption)* sideAlias joinHintList? joinCriteria right = tableOrSubqueryClause
+   | JOIN (joinOption)* (fieldList)? right = tableOrSubqueryClause
    ;
 
 sqlLikeJoinType

ppl/src/main/java/org/opensearch/sql/ppl/parser/AstBuilder.java

@@ -326,6 +326,8 @@ public UnresolvedPlan visitJoinCommand(OpenSearchPPLParser.JoinCommandContext ct
     if (ctx.fieldList() != null) {
       joinFields = Optional.of(getFieldList(ctx.fieldList()));
     }
+    // Keep a bare `on <field>` criteria verbatim; the planner expands it to an equi-join. Folding
+    // it into joinFields here would instead merge the key into one column.
     return new Join(
         projectExceptMeta(right),
         leftAlias,