Clearer error when vectorSearch() is used without a table alias

Running `SELECT ... FROM vectorSearch(...)` without an AS <alias>
previously produced an opaque parser error from the legacy SQL engine
fallback (`ERROR. token : TABLE, pos : 32`). Make the alias optional in
the grammar rule for `tableFunctionRelation` and reject the missing-alias
case in AstBuilder with a SemanticCheckException that tells the user to
add an alias, for example `FROM vectorSearch(...) AS v`.

SemanticCheckException (not SyntaxCheckException) is used on purpose so
the request does not fall back to the legacy engine, whose opaque error
would otherwise mask this message.

Signed-off-by: Eric Wei <mengwei.eric@gmail.com>

Author: mengweieric

integ-test/src/test/java/org/opensearch/sql/sql/VectorSearchIT.java

@@ -300,4 +300,25 @@ public void testExplainWithoutKnnPluginStillWorks() throws IOException {
 
     assertThat(explain, containsString("wrapper"));
   }
+
+  /**
+   * Users running FROM vectorSearch(...) without an AS alias previously received an opaque parser
+   * error from the legacy SQL engine fallback. The clearer SemanticCheckException from the v2
+   * engine must surface to the user instead.
+   */
+  @Test
+  public void testVectorSearchRequiresAlias() throws IOException {
+    ResponseException ex =
+        expectThrows(
+            ResponseException.class,
+            () ->
+                executeQuery(
+                    "SELECT * FROM vectorSearch("
+                        + "table='t', field='f', vector='[1.0]', option='k=5') "
+                        + "LIMIT 3"));
+
+    String body = ex.getMessage();
+    assertThat(body, containsString("requires a table alias"));
+    assertThat(body, containsString("vectorSearch"));
+  }
 }

sql/src/main/antlr/OpenSearchSQLParser.g4

@@ -109,9 +109,9 @@ fromClause
    ;
 
 relation
-   : tableName (AS? alias)?                                         # tableAsRelation
-   | LR_BRACKET subquery = querySpecification RR_BRACKET AS? alias  # subqueryAsRelation
-   | qualifiedName LR_BRACKET tableFunctionArgs RR_BRACKET AS? alias # tableFunctionRelation
+   : tableName (AS? alias)?                                            # tableAsRelation
+   | LR_BRACKET subquery = querySpecification RR_BRACKET AS? alias     # subqueryAsRelation
+   | qualifiedName LR_BRACKET tableFunctionArgs RR_BRACKET (AS? alias)? # tableFunctionRelation
    ;
 
 tableFunctionArgs

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

@@ -42,6 +42,7 @@
 import org.opensearch.sql.ast.tree.Values;
 import org.opensearch.sql.common.antlr.SyntaxCheckException;
 import org.opensearch.sql.common.utils.StringUtils;
+import org.opensearch.sql.exception.SemanticCheckException;
 import org.opensearch.sql.expression.function.BuiltinFunctionName;
 import org.opensearch.sql.sql.antlr.parser.OpenSearchSQLParser;
 import org.opensearch.sql.sql.antlr.parser.OpenSearchSQLParser.QuerySpecificationContext;
@@ -207,6 +208,19 @@ public UnresolvedPlan visitTableFunctionRelation(TableFunctionRelationContext ct
             });
     TableFunction tableFunction =
         new TableFunction(visitAstExpression(ctx.qualifiedName()), args.build());
+    if (ctx.alias() == null) {
+      String functionName = ctx.qualifiedName().getText();
+      // Use SemanticCheckException (not SyntaxCheckException) so the request does not fall back
+      // to the legacy SQL engine, whose opaque parser error would mask this message.
+      throw new SemanticCheckException(
+          String.format(
+              Locale.ROOT,
+              "Table function '%s' requires a table alias."
+                  + " Add an alias after the closing parenthesis, for example:"
+                  + " FROM %s(...) AS v",
+              functionName,
+              functionName));
+    }
     String alias = StringUtils.unquoteIdentifier(ctx.alias().getText());
     return new SubqueryAlias(alias, tableFunction);
   }

sql/src/test/java/org/opensearch/sql/sql/parser/AstBuilderTest.java

@@ -6,6 +6,8 @@
 package org.opensearch.sql.sql.parser;
 
 import static java.util.Collections.emptyList;
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.containsString;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.opensearch.sql.ast.dsl.AstDSL.agg;
@@ -44,6 +46,7 @@
 import org.opensearch.sql.ast.tree.SubqueryAlias;
 import org.opensearch.sql.ast.tree.TableFunction;
 import org.opensearch.sql.common.antlr.SyntaxCheckException;
+import org.opensearch.sql.exception.SemanticCheckException;
 
 class AstBuilderTest extends AstBuilderTestBase {
 
@@ -242,13 +245,16 @@ public void table_function_allows_alias_without_as_keyword() {
 
   @Test
   public void table_function_relation_requires_alias() {
-    assertThrows(
-        SyntaxCheckException.class,
-        () ->
-            buildAST(
-                "SELECT * FROM vectorSearch("
-                    + "table='products', field='embedding', "
-                    + "vector='[0.1,0.2]', option='k=10')"));
+    SemanticCheckException ex =
+        assertThrows(
+            SemanticCheckException.class,
+            () ->
+                buildAST(
+                    "SELECT * FROM vectorSearch("
+                        + "table='products', field='embedding', "
+                        + "vector='[0.1,0.2]', option='k=10')"));
+    assertThat(ex.getMessage(), containsString("requires a table alias"));
+    assertThat(ex.getMessage(), containsString("vectorSearch"));
   }
 
   @Test