Parsing of GPML label patterns (#1139)

Now parsing the full assortment of node/edge label patterns: named label, disjunction, conjunction, negation, grouping, and wildcard.

CHANGELOG.md

@@ -29,18 +29,25 @@ Thank you to all who have contributed!
 ## [Unreleased]
 
 ### Added
-- Adds `org.partiql.value` (experimental) package for reading/writing PartiQL
-  values
+- Adds `org.partiql.value` (experimental) package for reading/writing PartiQL values.
 - Adds serialization and deserialization between IonValue and `org.partiql.value`.
 - Adds `org.partiql.ast` package and usage documentation
 - Adds `org.partiql.parser` package and usage documentation
 - Adds PartiQL's Timestamp Data Model. 
 - Adds support for Timestamp constructor call in Parser. 
-
+- Parsing of label patterns within node and edge graph patterns now supports 
+  disjunction `|`, conjunction `&`, negation `!`, and grouping.
 
 ### Changed
 
 - Upgrades ion-java to 1.10.2.
+- **Breaking** (within experimental graph features): As part of extending 
+  the language of graph label patterns: 
+  - Changed the type of the field `label` in AST nodes 
+    `org.partiql.lang.domains.PartiqlAst.GraphMatchPatternPart.{Node,Edge}`, 
+    from `SymbolPrimitive` to new `GraphLabelSpec`.
+  - Changed the names of subclasses of ` org.partiql.lang.graph.LabelSpec`, 
+    from `OneOf` to `Name`, and from `Whatever` to `Wildcard`.
 
 ### Deprecated
 

partiql-ast/src/main/kotlin/org/partiql/ast/helpers/ToLegacyAst.kt

@@ -831,7 +831,7 @@ private class AstTranslator(val metas: Map<String, MetaContainer>) : AstBaseVisi
         translate(node) { metas ->
             val prefilter = node.prefilter?.let { visitExpr(it, ctx) }
             val variable = node.variable
-            val label = node.label
+            val label = node.label?.let { visitGraphMatchLabel(it, ctx) }
             node(prefilter, variable, label, metas)
         }
 
@@ -849,7 +849,7 @@ private class AstTranslator(val metas: Map<String, MetaContainer>) : AstBaseVisi
             val quantifier = node.quantifier?.let { visitGraphMatchQuantifier(it, ctx) }
             val prefilter = node.prefilter?.let { visitExpr(it, ctx) }
             val variable = node.variable
-            val label = node.label
+            val label = node.label?.let { visitGraphMatchLabel(it, ctx) }
             edge(direction, quantifier, prefilter, variable, label, metas)
         }
 
@@ -902,6 +902,39 @@ private class AstTranslator(val metas: Map<String, MetaContainer>) : AstBaseVisi
         selectorShortestKGroup(k)
     }
 
+    override fun visitGraphMatchLabel(node: GraphMatch.Label, ctx: Ctx) =
+        super.visitGraphMatchLabel(node, ctx) as PartiqlAst.GraphLabelSpec
+
+    override fun visitGraphMatchLabelName(node: GraphMatch.Label.Name, ctx: Ctx) =
+        translate(node) { metas ->
+            graphLabelName(node.name, metas)
+        }
+
+    override fun visitGraphMatchLabelWildcard(node: GraphMatch.Label.Wildcard, ctx: Ctx) =
+        translate(node) { metas ->
+            graphLabelWildcard(metas)
+        }
+
+    override fun visitGraphMatchLabelNegation(node: GraphMatch.Label.Negation, ctx: Ctx) =
+        translate(node) { metas ->
+            val arg = visitGraphMatchLabel(node.arg, ctx)
+            graphLabelNegation(arg, metas)
+        }
+
+    override fun visitGraphMatchLabelConj(node: GraphMatch.Label.Conj, ctx: Ctx) =
+        translate(node) { metas ->
+            val lhs = visitGraphMatchLabel(node.lhs, ctx)
+            val rhs = visitGraphMatchLabel(node.rhs, ctx)
+            graphLabelConj(lhs, rhs, metas)
+        }
+
+    override fun visitGraphMatchLabelDisj(node: GraphMatch.Label.Disj, ctx: Ctx) =
+        translate(node) { metas ->
+            val lhs = visitGraphMatchLabel(node.lhs, ctx)
+            val rhs = visitGraphMatchLabel(node.rhs, ctx)
+            graphLabelDisj(lhs, rhs, metas)
+        }
+
     /**
      * DML
      */

partiql-ast/src/main/pig/partiql.ion

@@ -271,21 +271,31 @@ may then be further optimized by selecting better implementations of each operat
              (edge_left_or_right)
              (edge_left_or_undirected_or_right))
 
+        // A label spec in a node pattern like `MATCH (x : <lab>)` or in an edge pattern like `MATCH −[t : <lab>]−>`
+        (sum graph_label_spec
+            (graph_label_name name::symbol)                   // as in `MATCH (x:Account)` or `MATCH -[x:Transfer]->`
+            (graph_label_wildcard)                            // as in `MATCH (x: %)`
+            (graph_label_negation arg::graph_label_spec)      // as in `MATCH (x: !Account)`
+            (graph_label_conj lhs::graph_label_spec rhs::graph_label_spec)   // as in `MATCH (x: City&Country)` - Monaco can do
+            (graph_label_disj lhs::graph_label_spec rhs::graph_label_spec)   // as in `MATCH (x: City|Country)` - either Paris or Germany will do
+        )
+
         // A part of a graph pattern
         (sum graph_match_pattern_part
              // A single node in a graph pattern.
              (node
                  prefilter::(? expr)   // an optional node pre-filter, e.g.: `WHERE c.name='Alarm'` in `MATCH (c WHERE c.name='Alarm')`
                  variable::(? symbol)  // the optional element variable of the node match, e.g.: `x` in `MATCH (x)`
-                 label::(* symbol 0))  // the optional label(s) to match for the node, e.g.: `Entity` in `MATCH (x:Entity)`
+                 label::(? graph_label_spec))  // the optional label spec to match for the node, e.g.: `Entity` in `MATCH (x:Entity)`
 
              // A single edge in a graph pattern.
              (edge
                  direction::graph_match_direction       // edge direction
                  quantifier::(? graph_match_quantifier) // an optional quantifier for the entire pattern match, e.g. `{2,5}` in `MATCH (a:Account)−[:Transfer]−>{2,5}(b:Account)`
                  prefilter::(? expr)   // an optional edge pre-filter, e.g.: `WHERE t.capacity>100` in `MATCH −[t:hasSupply WHERE t.capacity>100]−>`
                  variable::(? symbol)  // the optional element variable of the edge match, e.g.: `t` in `MATCH −[t]−>`
-                 label::(* symbol 0))  // the optional label(s) to match for the edge. e.g.: `Target` in `MATCH −[t:Target]−>`
+                 label::(? graph_label_spec))  // the optional label spec to match for the edge. e.g.: `Target` in `MATCH −[t:Target]−>`
+
              // A sub-pattern.
              (pattern pattern::graph_match_pattern))
 

partiql-ast/src/main/resources/partiql_ast.ion

@@ -651,15 +651,15 @@ graph_match::{
           node::{
             prefilter:  optional::expr,    // An optional node pre-filter, e.g.: `WHERE c.name='Alarm'` in `MATCH (c WHERE c.name='Alarm')`
             variable:   optional::string,  // The optional element variable of the node match, e.g.: `x` in `MATCH (x)`
-            label:      list::[string],    // The optional label(s) to match for the node, e.g.: `Entity` in `MATCH (x:Entity)`
+            label:      optional::label,    // The optional label(s) to match for the node, e.g.: `Entity` in `MATCH (x:Entity)`
           },
           // A single edge in a graph pattern
           edge::{
             direction:  direction,            // Edge Direction
             quantifier: optional::quantifier, // An optional quantifier for the entire pattern match, e.g. `{2,5}` in `MATCH (a:Account)−[:Transfer]−>{2,5}(b:Account)`
             prefilter:  optional::expr,       // An optional edge pre-filter, e.g.: `WHERE t.capacity>100` in `MATCH −[t:hasSupply WHERE t.capacity>100]−>`
             variable:   optional::string,     // The optional element variable of the edge match, e.g.: `t` in `MATCH −[t]−>`
-            label:      list::[string],       // The optional label(s) to match for the edge. e.g.: `Target` in `MATCH −[t:Target]−>`
+            label:      optional::label,      // The optional label spec to match for the edge. e.g.: `Target` in `MATCH −[t:Target]−>`
           },
           // A sub-pattern
           pattern::{
@@ -702,6 +702,15 @@ graph_match::{
       shortest_k::{ k: long },        // SHORTEST k
       shortest_k_group::{ k: long },  // SHORTEST k GROUP
     ],                                // Fig. 8 — https://arxiv.org/abs/2112.06217
+
+    // A label spec in a node pattern like `MATCH (x : <lab>)` or in an edge pattern like `MATCH −[t : <lab>]−>`
+    label::[
+      name::{ name: string },          // as in `MATCH (x:Account)` or `MATCH -[x:Transfer]->`
+      wildcard::{},                    // as in `MATCH (x: %)`
+      negation::{arg: label},          // as in `MATCH (x: !Account)`
+      conj::{lhs: label, rhs: label},  // as in `MATCH (x: City&Country)` - Monaco can do
+      disj::{lhs: label, rhs: label},  // as in `MATCH (x: City|Country)` - either Paris or Germany will do
+    ],
   ],
 }
 

partiql-lang/src/main/kotlin/org/partiql/lang/graph/GpmlTranslator.kt

@@ -2,7 +2,6 @@ package org.partiql.lang.graph
 
 import org.partiql.lang.domains.PartiqlAst
 import org.partiql.lang.graph.GpmlTranslator.normalizeElemList
-import org.partiql.pig.runtime.SymbolPrimitive
 
 /** Translate an AST graph pattern into a "plan spec" to be executed by the graph engine.
  *  Currently, the only non-trivial aspect is making sure (in [normalizeElemList]) that node and edge elements alternate.
@@ -52,11 +51,12 @@ object GpmlTranslator {
         )
     }
 
-    fun translateLabels(labels: List<SymbolPrimitive>): LabelSpec {
-        return when (labels.size) {
-            0 -> LabelSpec.Whatever
-            1 -> LabelSpec.OneOf(labels[0].text)
-            else -> TODO("Not yet supported in evaluating a GPML graph element pattern: multiple/alternating labels")
+    fun translateLabels(labelSpec: PartiqlAst.GraphLabelSpec?): LabelSpec {
+        return when (labelSpec) {
+            null -> LabelSpec.Wildcard
+            is PartiqlAst.GraphLabelSpec.GraphLabelName -> LabelSpec.Name(labelSpec.name.text)
+            is PartiqlAst.GraphLabelSpec.GraphLabelWildcard -> LabelSpec.Wildcard
+            else -> TODO("Not yet supported graph label pattern: $labelSpec")
         }
     }
 
@@ -76,7 +76,7 @@ object GpmlTranslator {
      *  TODO: Deal with adjacent [NodeSpec]s -- by "unification" or prohibit.
      */
     fun normalizeElemList(elems: List<ElemSpec>): List<ElemSpec> {
-        val fillerNode = NodeSpec(null, LabelSpec.Whatever)
+        val fillerNode = NodeSpec(null, LabelSpec.Wildcard)
         val normalized = mutableListOf<ElemSpec>()
         var expectNode = true
         for (x in elems) {

partiql-lang/src/main/kotlin/org/partiql/lang/graph/Graph.kt

@@ -66,11 +66,11 @@ interface Graph {
  *  based on labels at them.
  */
 sealed class LabelSpec {
-    /** A graph element matches when one of its labels is [name].*/
-    data class OneOf(val name: String) : LabelSpec()
+    /** A graph element (node or edge) matches when its label set contains [name]. */
+    data class Name(val name: String) : LabelSpec()
 
-    /** A graph element always matches (even when it is not labeled at all).*/
-    object Whatever : LabelSpec()
+    /** A graph element matches as long as it has a label. */
+    object Wildcard : LabelSpec()
 
     // TODO: more LabelSpec features: alternation, negation, string patterns, ...
 }

partiql-lang/src/main/kotlin/org/partiql/lang/graph/SimpleGraph.kt

@@ -35,8 +35,8 @@ class SimpleGraph(
 
     private fun labelsMatchSpec(labels: Set<String>, spec: LabelSpec): Boolean =
         when (spec) {
-            LabelSpec.Whatever -> true
-            is LabelSpec.OneOf -> labels.contains(spec.name)
+            LabelSpec.Wildcard -> true
+            is LabelSpec.Name -> labels.contains(spec.name)
         }
 
     private fun Graph.Elem.matches(labelSpec: LabelSpec): Boolean =

partiql-lang/src/main/kotlin/org/partiql/lang/syntax/impl/PartiQLPigVisitor.kt

@@ -781,8 +781,36 @@ internal class PartiQLPigVisitor(
         }
     }
 
-    override fun visitPatternPartLabel(ctx: PartiQLParser.PatternPartLabelContext) =
-        visitSymbolPrimitive(ctx.symbolPrimitive())
+    override fun visitLabelSpecOr(ctx: PartiQLParser.LabelSpecOrContext): PartiqlAst.GraphLabelSpec =
+        PartiqlAst.build {
+            val lhs = visit(ctx.labelSpec()) as PartiqlAst.GraphLabelSpec
+            val rhs = visit(ctx.labelTerm()) as PartiqlAst.GraphLabelSpec
+            graphLabelDisj(lhs, rhs, ctx.VERTBAR().getSourceMetaContainer())
+        }
+
+    override fun visitLabelTermAnd(ctx: PartiQLParser.LabelTermAndContext): PartiqlAst.GraphLabelSpec =
+        PartiqlAst.build {
+            val lhs = visit(ctx.labelTerm()) as PartiqlAst.GraphLabelSpec
+            val rhs = visit(ctx.labelFactor()) as PartiqlAst.GraphLabelSpec
+            graphLabelConj(lhs, rhs, ctx.AMPERSAND().getSourceMetaContainer())
+        }
+
+    override fun visitLabelFactorNot(ctx: PartiQLParser.LabelFactorNotContext) = PartiqlAst.build {
+        val arg = visit(ctx.labelPrimary()) as PartiqlAst.GraphLabelSpec
+        graphLabelNegation(arg, ctx.BANG().getSourceMetaContainer())
+    }
+
+    override fun visitLabelPrimaryName(ctx: PartiQLParser.LabelPrimaryNameContext) = PartiqlAst.build {
+        val x = visitSymbolPrimitive(ctx.symbolPrimitive())
+        graphLabelName_(x.name, x.metas)
+    }
+
+    override fun visitLabelPrimaryWild(ctx: PartiQLParser.LabelPrimaryWildContext) = PartiqlAst.build {
+        graphLabelWildcard(ctx.PERCENT().getSourceMetaContainer())
+    }
+
+    override fun visitLabelPrimaryParen(ctx: PartiQLParser.LabelPrimaryParenContext) =
+        visit(ctx.labelSpec()) as PartiqlAst.GraphLabelSpec
 
     override fun visitPattern(ctx: PartiQLParser.PatternContext) = PartiqlAst.build {
         val restrictor = ctx.restrictor?.let { visitPatternRestrictor(it) }
@@ -817,13 +845,8 @@ internal class PartiQLPigVisitor(
         val placeholderDirection = edgeRight()
         val variable = ctx.symbolPrimitive()?.let { visitSymbolPrimitive(it).name }
         val prefilter = ctx.whereClause()?.let { visitWhereClause(it) }
-        val label = ctx.patternPartLabel()?.let { visitPatternPartLabel(it).name }
-        edge_(
-            direction = placeholderDirection,
-            variable = variable,
-            prefilter = prefilter,
-            label = listOfNotNull(label)
-        )
+        val label = ctx.labelSpec()?.let { visit(it) as PartiqlAst.GraphLabelSpec }
+        edge_(direction = placeholderDirection, variable = variable, prefilter = prefilter, label = label)
     }
 
     override fun visitEdgeSpecLeft(ctx: PartiQLParser.EdgeSpecLeftContext) = PartiqlAst.build {
@@ -887,8 +910,8 @@ internal class PartiQLPigVisitor(
     override fun visitNode(ctx: PartiQLParser.NodeContext) = PartiqlAst.build {
         val variable = ctx.symbolPrimitive()?.let { visitSymbolPrimitive(it).name }
         val prefilter = ctx.whereClause()?.let { visitWhereClause(it) }
-        val label = ctx.patternPartLabel()?.let { visitPatternPartLabel(it).name }
-        node_(variable = variable, prefilter = prefilter, label = listOfNotNull(label))
+        val label = ctx.labelSpec()?.let { visit(it) as PartiqlAst.GraphLabelSpec }
+        node_(variable = variable, prefilter = prefilter, label = label)
     }
 
     override fun visitPatternRestrictor(ctx: PartiQLParser.PatternRestrictorContext) = PartiqlAst.build {