Support DuckDB 2.0 APPROX NEAREST similarity joins

Adds JOIN t APPROX NEAREST n BY SIMILARITY expression, the vector
similarity join of DuckDB 2.0. APPROX no longer binds as a table alias
in that position. Also adds the lookahead the UNPIVOT statement's INTO
clause needed to keep the grammar free of choice conflicts.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EqinwHBKuAtPEmtXr3b5P2

Author: hayssams

src/main/java/net/sf/jsqlparser/statement/select/Join.java

@@ -37,6 +37,8 @@ public class Join extends ASTNodeAccessImpl {
     private boolean cross = false;
     private boolean semi = false;
     private boolean anti = false;
+    private Long approxNearest;
+    private Expression similarity;
     private boolean any = false;
     private boolean all = false;
     private boolean straight = false;
@@ -195,6 +197,36 @@ public Join withFetch(boolean b) {
      *
      * @return true if is a "SEMI" join
      */
+    /**
+     * DuckDB 2.0's similarity join:
+     * {@code JOIN products APPROX NEAREST 2 BY SIMILARITY array_cosine_similarity(...)}.
+     */
+    public Long getApproxNearest() {
+        return approxNearest;
+    }
+
+    public void setApproxNearest(Long approxNearest) {
+        this.approxNearest = approxNearest;
+    }
+
+    public Join withApproxNearest(Long approxNearest) {
+        setApproxNearest(approxNearest);
+        return this;
+    }
+
+    public Expression getSimilarity() {
+        return similarity;
+    }
+
+    public void setSimilarity(Expression similarity) {
+        this.similarity = similarity;
+    }
+
+    public Join withSimilarity(Expression similarity) {
+        setSimilarity(similarity);
+        return this;
+    }
+
     public boolean isAnti() {
         return anti;
     }
@@ -577,6 +609,11 @@ public String toString() {
             builder.append(fromItem).append((joinWindow != null) ? " WITHIN " + joinWindow : "");
         }
 
+        if (approxNearest != null) {
+            builder.append(" APPROX NEAREST ").append(approxNearest)
+                    .append(" BY SIMILARITY ").append(similarity);
+        }
+
         for (Expression onExpression : onExpressions) {
             builder.append(" ON ").append(onExpression);
         }

src/main/java/net/sf/jsqlparser/util/deparser/SelectDeParser.java

@@ -773,6 +773,12 @@ public void deparseJoin(Join join) {
             builder.append(" WITHIN ");
             builder.append(join.getJoinWindow().toString());
         }
+        if (join.getApproxNearest() != null) {
+            builder.append(" APPROX NEAREST ").append(join.getApproxNearest())
+                    .append(" BY SIMILARITY ");
+            join.getSimilarity().accept(expressionVisitor, null);
+        }
+
         for (Expression onExpression : join.getOnExpressions()) {
             builder.append(" ON ");
             onExpression.accept(expressionVisitor, null);

src/main/jjtree/net/sf/jsqlparser/parser/JSqlParserCC.jjt

@@ -1273,6 +1273,11 @@ public class CCJSqlParser extends AbstractJSqlParser<CCJSqlParser> {
                         || "POSITION".equalsIgnoreCase(getToken(2).image));
     }
 
+    /** DuckDB 2.0's APPROX NEAREST similarity join, never a table alias. */
+    private boolean isApproxNearestAhead() {
+        return getToken(1).kind == K_APPROX && getToken(2).kind == K_NEAREST;
+    }
+
     /** SEMI/ANTI stay contextual identifiers unless they prefix a JOIN. */
     private boolean isSemiAntiJoinAhead() {
         int kind = getToken(1).kind;
@@ -1311,7 +1316,7 @@ public class CCJSqlParser extends AbstractJSqlParser<CCJSqlParser> {
      * reserved keywords.
      */
     private boolean isAliasAhead() {
-        if (isAsOfJoinAhead() || isSemiAntiJoinAhead()) {
+        if (isAsOfJoinAhead() || isSemiAntiJoinAhead() || isApproxNearestAhead()) {
             return false;
         }
         Token t = getToken(1);
@@ -2008,6 +2013,7 @@ String NonReservedWord() :
       | tk=<K_ANTI:"ANTI">
       | tk=<K_APPEND_ONLY:"APPEND_ONLY">
       | tk=<K_APPLY:"APPLY">
+      | tk=<K_APPROX: "APPROX">
       | tk=<K_APPROXIMATE:"APPROXIMATE">
       | tk=<K_ARCHIVE: "ARCHIVE">
       | tk=<K_ARRAY_LITERAL: "ARRAY" >
@@ -2216,6 +2222,7 @@ String NonReservedWord() :
       | tk=<K_NAME:"NAME">
       | tk=<K_NEVER:"NEVER">
       | tk=<K_NEXT:"NEXT">
+      | tk=<K_NEAREST: "NEAREST">
       | tk=<K_NEXTVAL: (  (("NEXTVAL")((" ")+("FOR"))?)  |  ( ("NEXT")(" ")+("VALUE") (" ")+("FOR") )  )>
       | tk=<K_NO:"NO">
       | tk=<K_NOCACHE:"NOCACHE">
@@ -2321,6 +2328,7 @@ String NonReservedWord() :
       | tk=<K_SHARE : "SHARE">
       | tk=<K_SIBLINGS:"SIBLINGS">
       | tk=<K_SIMILAR:"SIMILAR">
+      | tk=<K_SIMILARITY: "SIMILARITY">
       | tk=<K_SIZE:"SIZE">
       | tk=<K_SKIP: "SKIP">
       | tk=<K_SLAVE: "SLAVE">
@@ -7745,7 +7753,9 @@ UnPivotQuery UnPivotQuery():
 {
     <K_UNPIVOT> fromItem=FromItem() { unPivotQuery.setFromItem(fromItem); }
     <K_ON> onExpressions=ExpressionList() { unPivotQuery.setOnExpressions(onExpressions); }
+    // greedy: INTO after the ON list belongs to this UNPIVOT
     [
+        LOOKAHEAD(2)
         <K_INTO> <K_NAME> nameColumn=RelObjectName() { unPivotQuery.setNameColumn(nameColumn); }
         <K_VALUE> valueColumns=ColumnList() { unPivotQuery.setValueColumns(valueColumns); }
     ]
@@ -8234,6 +8244,7 @@ Join JoinerExpression() #JoinerExpression:
     List<Column> columns = null;
     KSQLJoinWindow joinWindow = null;
     JoinHint joinHint = null;
+    Token tk = null;
 }
 {
     [ LOOKAHEAD({ isAsOfJoinAhead() }) <S_IDENTIFIER> { join.setAsOf(true); } ]
@@ -8289,6 +8300,12 @@ Join JoinerExpression() #JoinerExpression:
 
     right=FromItem()
 
+    // DuckDB 2.0: JOIN products APPROX NEAREST 2 BY SIMILARITY array_cosine_similarity(...)
+    [
+        LOOKAHEAD({ isApproxNearestAhead() })
+        <K_APPROX> <K_NEAREST> tk=<S_LONG> { join.setApproxNearest(Long.valueOf(tk.image)); }
+        <K_BY> <K_SIMILARITY> onExpression=Expression() { join.setSimilarity(onExpression); }
+    ]
     [
         LOOKAHEAD(2) (
                         [ <K_WITHIN> joinWindow = KSQLJoinWindowClause() {join.setJoinWindow(joinWindow);} ]

src/test/java/net/sf/jsqlparser/statement/select/DuckDBTest.java

@@ -638,4 +638,31 @@ void testUnPivotInFromClauseStillParses() throws JSQLParserException {
         String sqlStr = "SELECT * FROM monthly_sales UNPIVOT (sales FOR month IN (jan, feb))";
         TestUtils.assertSqlCanBeParsedAndDeparsed(sqlStr, true);
     }
+
+    @Test
+    void testApproxNearestJoin() throws JSQLParserException {
+        String sqlStr = "SELECT * FROM queries q INNER JOIN products t "
+                + "APPROX NEAREST 2 BY SIMILARITY array_cosine_similarity(q.vec, t.vec)";
+        PlainSelect select = (PlainSelect) TestUtils.assertSqlCanBeParsedAndDeparsed(sqlStr, true);
+        Join join = select.getJoins().get(0);
+
+        Assertions.assertEquals(2L, join.getApproxNearest());
+        Assertions.assertEquals("array_cosine_similarity(q.vec, t.vec)",
+                join.getSimilarity().toString());
+    }
+
+    @Test
+    void testApproxNearestJoinWithoutAlias() throws JSQLParserException {
+        String sqlStr = "SELECT * FROM queries JOIN products "
+                + "APPROX NEAREST 5 BY SIMILARITY array_distance(queries.vec, products.vec)";
+        PlainSelect select = (PlainSelect) TestUtils.assertSqlCanBeParsedAndDeparsed(sqlStr, true);
+
+        Assertions.assertNull(((Table) select.getJoins().get(0).getFromItem()).getAlias());
+    }
+
+    @Test
+    void testApproxRemainsUsableAsIdentifier() throws JSQLParserException {
+        String sqlStr = "SELECT approx, nearest, similarity FROM t";
+        TestUtils.assertSqlCanBeParsedAndDeparsed(sqlStr, true);
+    }
 }