OPTIONAL MATCH support

graph-query-ir/src/main/java/oracle/pgql/lang/ir/OptionalGraphPattern.java

@@ -0,0 +1,30 @@
+/*
+ * Copyright (C) 2013 - 2024 Oracle and/or its affiliates. All rights reserved.
+ */
+package oracle.pgql.lang.ir;
+
+import java.util.LinkedHashSet;
+import java.util.Set;
+
+public class OptionalGraphPattern extends GraphPattern {
+
+  public OptionalGraphPattern(Set<QueryVertex> vertices, LinkedHashSet<VertexPairConnection> connections,
+      LinkedHashSet<QueryExpression> constraints) {
+    super(vertices, connections, constraints);
+  }
+
+  @Override
+  public TableExpressionType getTableExpressionType() {
+    return TableExpressionType.OPTIONAL_GRAPH_PATTERN;
+  }
+
+  @Override
+  public String toString() {
+    return "OPTIONAL " + super.toString();
+  }
+
+  @Override
+  public void accept(QueryExpressionVisitor v) {
+    v.visit(this);
+  }
+}

graph-query-ir/src/main/java/oracle/pgql/lang/ir/PgqlUtils.java

@@ -53,7 +53,7 @@ public class PgqlUtils {
 
   // make sure to keep in sync with list of reserved words in pgql-spoofax/syntax/Names.sdf3
   private final static Set<String> RESERVED_WORDS = new HashSet<>(
-      Arrays.asList("true", "false", "null", "not", "distinct"));
+      Arrays.asList("true", "false", "null", "not", "distinct", "optional"));
 
   static DecimalFormat DECIMAL_FORMAT = new DecimalFormat("#.#");
 
@@ -306,7 +306,8 @@ private static String printPgqlString(GraphPattern graphPattern, SchemaQualified
     Set<QueryVertex> uncoveredVertices = new LinkedHashSet<>(graphPattern.getVertices());
     List<String> graphPatternMatches = new ArrayList<String>();
 
-    boolean parenthesizeMatch = !graphPattern.getConstraints().isEmpty() && !isLastTableExpression;
+    boolean parenthesizeMatch = !graphPattern.getConstraints().isEmpty()
+        && !isLastTableExpression || graphPattern instanceof OptionalGraphPattern;
 
     Iterator<VertexPairConnection> connectionIt = graphPattern.getConnections().iterator();
     while (connectionIt.hasNext()) {

graph-query-ir/src/main/java/oracle/pgql/lang/ir/QueryExpressionVisitor.java

@@ -175,6 +175,8 @@ public interface QueryExpressionVisitor {
 
   public void visit(GraphPattern graphPattern);
 
+  public void visit(OptionalGraphPattern optionalGraphPattern);
+
   public void visit(Projection projection);
 
   public void visit(ExpAsVar expAsVar);

graph-query-ir/src/main/java/oracle/pgql/lang/ir/TableExpressionType.java

@@ -4,8 +4,10 @@
 package oracle.pgql.lang.ir;
 
 public enum TableExpressionType {
- 
+
   GRAPH_PATTERN,
-
+
+  OPTIONAL_GRAPH_PATTERN,
+
   DERIVED_TABLE
 }

graph-query-ir/src/main/java/oracle/pgql/lang/util/AbstractQueryExpressionVisitor.java

@@ -8,6 +8,7 @@
 import oracle.pgql.lang.ir.GraphPattern;
 import oracle.pgql.lang.ir.GraphQuery;
 import oracle.pgql.lang.ir.GroupBy;
+import oracle.pgql.lang.ir.OptionalGraphPattern;
 import oracle.pgql.lang.ir.OrderBy;
 import oracle.pgql.lang.ir.OrderByElem;
 import oracle.pgql.lang.ir.Projection;
@@ -391,6 +392,11 @@ public void visit(GraphPattern graphPattern) {
     graphPattern.getConstraints().stream().forEach(e -> e.accept(this));
   }
 
+  @Override
+  public void visit(OptionalGraphPattern optionalGraphPattern) {
+    visit((GraphPattern) optionalGraphPattern);
+  }
+
   @Override
   public void visit(Projection projection) {
     projection.getElements().stream().forEach(e -> e.accept(this));

graph-query-ir/src/main/java/oracle/pgql/lang/util/ReplaceExpressions.java

@@ -12,6 +12,7 @@
 import oracle.pgql.lang.ir.GraphPattern;
 import oracle.pgql.lang.ir.GraphQuery;
 import oracle.pgql.lang.ir.GroupBy;
+import oracle.pgql.lang.ir.OptionalGraphPattern;
 import oracle.pgql.lang.ir.OrderBy;
 import oracle.pgql.lang.ir.OrderByElem;
 import oracle.pgql.lang.ir.Projection;
@@ -404,6 +405,11 @@ public void visit(GraphPattern graphPattern) {
     graphPattern.setConstraints(replaceInSet(graphPattern.getConstraints()));
   }
 
+  @Override
+  public void visit(OptionalGraphPattern optionalGraphPattern) {
+    optionalGraphPattern.setConstraints(replaceInSet(optionalGraphPattern.getConstraints()));
+  }
+
   @Override
   public void visit(ExpAsVar expAsVar) {
     expAsVar.setExp(replaceMatching(expAsVar.getExp()));

pgql-lang/src/main/java/oracle/pgql/lang/SpoofaxAstToGraphQuery.java

@@ -26,6 +26,7 @@
 import oracle.pgql.lang.ir.GraphPattern;
 import oracle.pgql.lang.ir.GraphQuery;
 import oracle.pgql.lang.ir.GroupBy;
+import oracle.pgql.lang.ir.OptionalGraphPattern;
 import oracle.pgql.lang.ir.OrderBy;
 import oracle.pgql.lang.ir.PathFindingGoal;
 import oracle.pgql.lang.ir.PathMode;
@@ -137,6 +138,7 @@ public class SpoofaxAstToGraphQuery {
   private static final int POS_VERTICES = 0;
   private static final int POS_CONNECTIONS = 1;
   private static final int POS_CONSTRAINTS = 2;
+  private static final int POS_OPTIONAL_MATCH_KEYWORD = 3;
 
   private static final int POS_VERTEX_NAME = 0;
   private static final int POS_VERTEX_ORIGIN_OFFSET = 1;
@@ -330,8 +332,12 @@ private static GraphPattern translateGraphPattern(TranslationContext ctx, IStrat
     IStrategoTerm constraintsT = getList(graphPatternT.getSubterm(POS_CONSTRAINTS));
     LinkedHashSet<QueryExpression> constraints = getQueryExpressions(constraintsT, ctx);
 
+    // OPTIONAL match keyword
+    boolean optionalMatch = isSome(graphPatternT.getSubterm(POS_OPTIONAL_MATCH_KEYWORD));
+
     // graph pattern
-    graphPattern = new GraphPattern(vertices, connections, constraints);
+    graphPattern = optionalMatch ? new OptionalGraphPattern(vertices, connections, constraints)
+        : new GraphPattern(vertices, connections, constraints);
     return graphPattern;
   }
 

pgql-lang/src/test/java/oracle/pgql/lang/BugFixTest.java

@@ -8,6 +8,7 @@
 import static org.junit.Assert.assertNotNull;
 import static org.junit.Assert.assertTrue;
 
+import java.util.Iterator;
 import java.util.List;
 
 import org.junit.Ignore;
@@ -16,11 +17,14 @@
 import oracle.pgql.lang.ddl.propertygraph.CreateSuperPropertyGraph;
 import oracle.pgql.lang.ir.ExpAsVar;
 import oracle.pgql.lang.ir.GraphQuery;
+import oracle.pgql.lang.ir.PathFindingGoal;
 import oracle.pgql.lang.ir.QueryExpression.AllProperties;
 import oracle.pgql.lang.ir.QueryExpression.FunctionCall;
 import oracle.pgql.lang.ir.QueryExpression.PropertyAccess;
+import oracle.pgql.lang.ir.QueryPath;
 import oracle.pgql.lang.ir.QueryExpression.Aggregation.AggrJsonArrayagg;
 import oracle.pgql.lang.ir.SelectQuery;
+import oracle.pgql.lang.ir.VertexPairConnection;
 
 public class BugFixTest extends AbstractPgqlTest {
 
@@ -474,8 +478,63 @@ public void formatJson() throws Exception {
     assertTrue(agg.isFormatJson());
 
     result = pgql.parse("SELECT JSON_ARRAYAGG(v.prop) FROM MATCH (v)");
-    agg = (AggrJsonArrayagg) ((SelectQuery) result.getGraphQuery()).getProjection().getElements()
-        .get(0).getExp();
+    agg = (AggrJsonArrayagg) ((SelectQuery) result.getGraphQuery()).getProjection().getElements().get(0).getExp();
     assertFalse(agg.isFormatJson());
   }
+
+  @Test
+  public void ambiguityForOptionalMatch() throws Exception {
+    /*
+     * Previously, the below query was a valid PGQL 1.1/1.2 query in which "OPTIONAL" is the name of the graph. This
+     * caused an ambiguity because the query is now also seen as a PGQL 2.0 query with OPTIONAL MATCH pattern. The fix
+     * was to disallow "OPTIONAL" as graph name in PGQL 1.1/1.2.
+     */
+    PgqlResult result = pgql
+        .parse("SELECT n FROM OPTIONAL MATCH (n IS Person) -[e IS likes]-> (m IS Person) WHERE n.name = 'Dave'");
+    assertTrue(result.isQueryValid());
+
+    /*
+     * You can still use OPTIONAL as graph name in PGQL 1.2, but it requires double quoting. Also, you can still use
+     * OPTIONAL as property name or variable name.
+     */
+    result = pgql.parse(
+        "SELECT n FROM \"OPTIONAL\" MATCH (n IS Person) -[e IS likes]-> (optional IS Person) WHERE optional.optional = true");
+    assertTrue(result.isQueryValid());
+
+    /*
+     * And you can also use OPTIONAL as graph name in newer PGQL versions, without requiring double quoting.
+     */
+    result = pgql
+        .parse("SELECT n FROM MATCH (n IS Person) -[e IS likes]-> (m IS Person) ON optional WHERE n.name = 'Dave'");
+    assertTrue(result.isQueryValid());
+  }
+
+  @Test
+  public void explicitOneRowPerMatch() throws Exception {
+    PgqlResult result = pgql.parse(
+        "SELECT sum FROM LATERAL (SELECT sum(v2.integerprop) as sum FROM MATCH ANY SHORTEST (v)  ->* (v2) ONE ROW PER MATCH)");
+    assertTrue(result.isQueryValid());
+  }
+
+  @Test
+  public void parsePathSelectorInParenthesizedMatch() throws Exception {
+    String query = "SELECT SUM(e.amount) as sum " //
+        + "FROM MATCH ( ANY CHEAPEST (y)(-[e:transaction]-> COST e.amount)* (x)) ";
+    PgqlResult result = pgql.parse(query);
+    assertTrue(result.isQueryValid());
+    Iterator<VertexPairConnection> it = result.getGraphQuery().getGraphPattern().getConnections().iterator();
+    QueryPath path = (QueryPath) it.next();
+    assertEquals(PathFindingGoal.CHEAPEST, path.getPathFindingGoal());
+
+    query = "SELECT SUM(e.amount) as sum " //
+        + "FROM MATCH ( ANY CHEAPEST (y)(-[e:transaction]-> COST e.amount)* (x), " //
+        + "ANY CHEAPEST (y)(-[e2:transaction]-> COST e.amount)* (x) WHERE sum < 2000) ";
+    result = pgql.parse(query);
+    assertTrue(result.isQueryValid());
+    it = result.getGraphQuery().getGraphPattern().getConnections().iterator();
+    path = (QueryPath) it.next();
+    assertEquals(PathFindingGoal.CHEAPEST, path.getPathFindingGoal());
+    path = (QueryPath) it.next();
+    assertEquals(PathFindingGoal.CHEAPEST, path.getPathFindingGoal());
+  }
 }

pgql-lang/src/test/java/oracle/pgql/lang/PrettyPrintingTest.java

@@ -801,4 +801,37 @@ public void testMatchWithWhereFollowedByLateral() throws Exception {
         "WHERE n.number = 1001 AND p.number > 8020";
     checkRoundTrip(query);
   }
+
+  @Test
+  public void testOptionalMatch() throws Exception {
+    String query = "SELECT n.name AS n_name, m.name AS m_name " + //
+        "FROM MATCH (n IS Person), " + //
+        "     OPTIONAL MATCH (n) -[e IS likes]-> (m IS Person) " + //
+        "WHERE n.name = 'Dave'";
+    checkRoundTrip(query);
+
+    query = "SELECT n.name AS n_name, m.name AS m_name " + //
+        "FROM MATCH (n IS Person), " + //
+        "     OPTIONAL MATCH ( (n) -[e IS likes]-> (m IS Person) WHERE n.dob > m.dob ) " + //
+        "WHERE n.name = 'Dave'";
+    checkRoundTrip(query);
+
+    query = "SELECT n.name AS n_name, m.name AS m_name " + //
+        "FROM MATCH (n IS Person), " + //
+        "    OPTIONAL MATCH ( (n) -[e1 IS likes]-> (m IS Person), " + //
+        "                     (n) <-[e2 IS likes]- (m) " + //
+        "                     WHERE n.dob > m.dob ) " + //
+        "WHERE n.name = 'Dave'";
+    checkRoundTrip(query);
+
+    query = "SELECT id(y), x, id(z) " + //
+        "FROM OPTIONAL MATCH ((y) -> (z) WHERE y.number = 1001), " + //
+        "     OPTIONAL MATCH ((y)->(x)<-(z))";
+    checkRoundTrip(query);
+
+    query = "SELECT SUM(e.amount) as sum, id(x), id(z) " + //
+        "FROM MATCH ANY CHEAPEST ((y)(-[e:transaction]-> COST e.amount)* (x) WHERE sum < 2000) " + //
+        "   , OPTIONAL MATCH ((x)->(z) WHERE id(z)='Person(1)')";
+    checkRoundTrip(query);
+  }
 }

pgql-lang/src/test/java/oracle/pgql/lang/StaticOptimizationsTest.java

@@ -289,6 +289,26 @@ public void testPredicatePushDownLateralWithLimitOffset2() throws Exception {
     assertEquals(1L, graphPattern2.getConstraints().size());
   }
 
+  @Test
+  public void testPredicatePushDownIntoMatchBeforeOptionalMAtch() throws Exception {
+    String query = "SELECT 1 FROM MATCH (x), OPTIONAL MATCH (x) -> (y)" + //
+        "WHERE x.prop < 20 AND y.prop IS NULL";
+
+    // outer query has predicate y.prop IS NULL
+    SelectQuery outerQuery = (SelectQuery) pgql.parse(query).getGraphQuery();
+    assertEquals(1L, outerQuery.getConstraints().size());
+    assertEquals(ExpressionType.IS_NULL, outerQuery.getConstraints().iterator().next().getExpType());
+
+    // MATCH (x) has predicate x.prop < 20
+    GraphPattern graphPattern1 = (GraphPattern) outerQuery.getTableExpressions().get(0);
+    assertEquals(1L, graphPattern1.getConstraints().size());
+    assertEquals(ExpressionType.LESS, graphPattern1.getConstraints().iterator().next().getExpType());
+
+    // OPTIONAL MATCH (x) -> (y) has no constraints
+    GraphPattern graphPattern2 = (GraphPattern) outerQuery.getTableExpressions().get(1);
+    assertEquals(0L, graphPattern2.getConstraints().size());
+  }
+
   @Test
   public void testSelectStarWithLateral() throws Exception {
     String query = "SELECT * " + //

pgql-spoofax/syntax/Legacy.sdf3

@@ -27,10 +27,21 @@ context-free syntax // PGQL 1.1/1.2
       <LimitOffsetClauses?>
     >
 
-  Pgql11FromClause.Pgql11FromClause = <FROM <GraphName>> {case-insensitive}
+  Pgql11FromClause.Pgql11FromClause = <FROM <Pgql11GraphName>> {case-insensitive}
+
+  Pgql11GraphName.Name = <<SchemaNameDot?><Pgql11GraphNameIdentifier>>
+
+  /* PGQL 1.1 graph name has the additional restriciton that the OPTIONAL keyword is reserved */
+  Pgql11GraphNameIdentifier.RegularIdentifier = PGQL11-GRAPH-NAME-REGULAR-IDENTIFIER
+  Pgql11GraphNameIdentifier.DelimitedIdentifier = DELIMITED-IDENTIFIER
 
   MatchWhereClauses.MatchWhereClauses = <MATCH <{PathPattern ","}+> <WhereClause?>> {case-insensitive}
 
+lexical syntax
+
+  PGQL11-GRAPH-NAME-REGULAR-IDENTIFIER = REGULAR-IDENTIFIER
+  PGQL11-GRAPH-NAME-REGULAR-IDENTIFIER = 'optional' {reject}
+
 context-free syntax // pgql-lang.sdf3 for PGQL 1.0
 
   Legacy10Query.Pgql10Query =

pgql-spoofax/syntax/pgql-lang.sdf3

@@ -49,10 +49,11 @@ context-free syntax
 
   TableExpression = GraphTableDerivedTable
 
-  GraphMatch.GraphMatch = MatchKeyword? PathPattern OptionalGraphMatchParts?
+  GraphMatch.GraphMatch = OptionalMatchKeyword? MatchKeyword? PathPattern OptionalGraphMatchParts?
 
-  GraphMatch.ParenthesizedGraphMatch = <MATCH ( <PathPattern>, <{PathPattern ","}+> <WhereClause?> ) <OptionalGraphMatchParts?>> {case-insensitive}
+  GraphMatch.ParenthesizedGraphMatch = <<OptionalMatchKeyword?> MATCH ( <PathPattern>, <{PathPattern ","}+> <WhereClause?> ) <OptionalGraphMatchParts?>> {case-insensitive}
 
+  OptionalMatchKeyword.OptionalMatchKeyword = <OPTIONAL> {case-insensitive}
   MatchKeyword.MatchKeyword = <MATCH> {case-insensitive}
 
   OptionalGraphMatchParts.OptionalGraphMatchParts1 = GraphTableRowsClause OnClause? // deprecated