Add experimental draft support for GPML-style graph query

jpschorr · jpschorr · commit 5906a9361bb6 · 2022-08-10T10:54:20.000-07:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+- An experimental (pending [#15](https://github.com/partiql/partiql-docs/issues/15)) embedding of a subset of
+  the [GPML (Graph Pattern Matching Language)](https://arxiv.org/abs/2112.06217) graph query into the `FROM` clause,
+  supporting. The use within the grammar is based on the assumption of a new graph data type being added to the
+  specification of data types within PartiQL, and should be considered experimental until the semantics of the graph
+  data type are specified.
+  - basic and abbreviated node and edge patterns (section 4.1 of the GPML paper)
+  - concatenated path patterns  (section 4.2 of the GPML paper)
+  - path variables  (section 4.2 of the GPML paper)
+  - graph patterns (i.e., comma separated path patterns)  (section 4.3 of the GPML paper)
+  - parenthesized patterns (section 4.4 of the GPML paper)
+  - path quantifiers  (section 4.4 of the GPML paper)
+  - restrictors and selector  (section 5.1 of the GPML paper)
+  - pre-filters and post-filters (section 5.2 of the GPML paper)
 
 ## [0.1.0] - 2022-08-05
 ### Added
@@ -18,5 +31,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - PartiQL Playground proof of concept (POC)
 - PartiQL CLI with REPL and query visualization features
 
+
 [Unreleased]: https://github.com/partiql/partiql-lang-rust/compare/v0.1.0...HEAD
 [0.1.0]: https://github.com/partiql/partiql-lang-rust/compare/v0.1.0
diff --git a/partiql-ast/src/ast.rs b/partiql-ast/src/ast.rs
@@ -12,6 +12,7 @@ use rust_decimal::Decimal as RustDecimal;
 
 use std::fmt;
 use std::fmt::Display;
+use std::num::NonZeroU32;
 use std::ops::Range;
 
 #[cfg(feature = "serde")]
@@ -258,6 +259,13 @@ pub type CallAst = AstBytePos<Call>;
 pub type CaseAst = AstBytePos<Case>;
 pub type FromClauseAst = AstBytePos<FromClause>;
 pub type FromLetAst = AstBytePos<FromLet>;
+pub type GraphMatchAst = AstBytePos<GraphMatch>;
+pub type GraphMatchExprAst = AstBytePos<GraphMatchExpr>;
+pub type GraphMatchEdgeAst = AstBytePos<GraphMatchEdge>;
+pub type GraphMatchNodeAst = AstBytePos<GraphMatchNode>;
+pub type GraphMatchPatternAst = AstBytePos<GraphMatchPattern>;
+pub type GraphMatchPatternPartAst = AstBytePos<GraphMatchPatternPart>;
+pub type GraphMatchQuantifierAst = AstBytePos<GraphMatchQuantifier>;
 pub type GroupByExprAst = AstBytePos<GroupByExpr>;
 pub type GroupKeyAst = AstBytePos<GroupKey>;
 pub type InAst = AstBytePos<In>;
@@ -675,6 +683,9 @@ pub enum FromClause {
     FromLet(FromLetAst),
     /// <from_source> JOIN \[INNER | LEFT | RIGHT | FULL\] <from_source> ON <expr>
     Join(JoinAst),
+
+    /// <expr> MATCH <graph_pattern>
+    GraphMatch(GraphMatchAst),
 }
 
 #[derive(Clone, Debug, PartialEq)]
@@ -724,6 +735,152 @@ pub enum JoinKind {
     Cross,
 }
 
+#[derive(Clone, Debug, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub struct GraphMatch {
+    pub expr: Box<Expr>,
+    pub graph_expr: Box<GraphMatchExprAst>,
+}
+
+/// The direction of an edge
+/// | Orientation               | Edge pattern | Abbreviation |
+/// |---------------------------+--------------+--------------|
+/// | Pointing left             | <−[ spec ]−  | <−           |
+/// | Undirected                | ~[ spec ]~   | ~            |
+/// | Pointing right            | −[ spec ]−>  | −>           |
+/// | Left or undirected        | <~[ spec ]~  | <~           |
+/// | Undirected or right       | ~[ spec ]~>  | ~>           |
+/// | Left or right             | <−[ spec ]−> | <−>          |
+/// | Left, undirected or right | −[ spec ]−   | −            |
+///
+/// Fig. 5. Table of edge patterns:
+/// https://arxiv.org/abs/2112.06217
+#[derive(Clone, Debug, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub enum GraphMatchDirection {
+    Left,
+    Undirected,
+    Right,
+    LeftOrUndirected,
+    UndirectedOrRight,
+    LeftOrRight,
+    LeftOrUndirectedOrRight,
+}
+
+/// A part of a graph pattern
+#[derive(Clone, Debug, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub enum GraphMatchPatternPart {
+    /// A single node in a graph pattern.
+    Node(GraphMatchNodeAst),
+
+    /// A single edge in a graph pattern.
+    Edge(GraphMatchEdgeAst),
+
+    /// A sub-pattern.
+    Pattern(GraphMatchPatternAst),
+}
+
+/// A quantifier for graph edges or patterns. (e.g., the `{2,5}` in `MATCH (x)->{2,5}(y)`)
+#[derive(Clone, Debug, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub struct GraphMatchQuantifier {
+    pub lower: u32,
+    pub upper: Option<NonZeroU32>,
+}
+
+/// A path restrictor
+/// | Keyword        | Description
+/// |----------------+--------------
+/// | TRAIL          | No repeated edges.
+/// | ACYCLIC        | No repeated nodes.
+/// | SIMPLE         | No repeated nodes, except that the ﬁrst and last nodes may be the same.
+///
+/// Fig. 7. Table of restrictors:
+/// https://arxiv.org/abs/2112.06217
+#[derive(Clone, Debug, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub enum GraphMatchRestrictor {
+    Trail,
+    Acyclic,
+    Simple,
+}
+
+/// A single node in a graph pattern.
+#[derive(Clone, Debug, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub struct GraphMatchNode {
+    /// an optional node pre-filter, e.g.: `WHERE c.name='Alarm'` in `MATCH (c WHERE c.name='Alarm')`
+    pub prefilter: Option<Box<Expr>>,
+    /// the optional element variable of the node match, e.g.: `x` in `MATCH (x)`
+    pub variable: Option<SymbolPrimitive>,
+    /// the optional label(s) to match for the node, e.g.: `Entity` in `MATCH (x:Entity)`
+    pub label: Option<Vec<SymbolPrimitive>>,
+}
+
+/// A single edge in a graph pattern.
+#[derive(Clone, Debug, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub struct GraphMatchEdge {
+    /// edge direction
+    pub direction: GraphMatchDirection,
+    /// an optional quantifier for the edge match
+    pub quantifier: Option<GraphMatchQuantifierAst>,
+    /// an optional edge pre-filter, e.g.: `WHERE t.capacity>100` in `MATCH −[t:hasSupply WHERE t.capacity>100]−>`
+    pub prefilter: Option<Box<Expr>>,
+    /// the optional element variable of the edge match, e.g.: `t` in `MATCH −[t]−>`
+    pub variable: Option<SymbolPrimitive>,
+    /// the optional label(s) to match for the edge. e.g.: `Target` in `MATCH −[t:Target]−>`
+    pub label: Option<Vec<SymbolPrimitive>>,
+}
+
+/// A single graph match pattern.
+#[derive(Clone, Debug, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub struct GraphMatchPattern {
+    pub restrictor: Option<GraphMatchRestrictor>,
+    /// an optional quantifier for the entire pattern match
+    pub quantifier: Option<GraphMatchQuantifierAst>,
+    /// an optional pattern pre-filter, e.g.: `WHERE a.name=b.name` in `MATCH [(a)->(b) WHERE a.name=b.name]`
+    pub prefilter: Option<Box<Expr>>,
+    /// the optional element variable of the pattern, e.g.: `p` in `MATCH p = (a) −[t]−> (b)`
+    pub variable: Option<SymbolPrimitive>,
+    /// the ordered pattern parts
+    pub parts: Vec<GraphMatchPatternPart>,
+}
+
+/// A path selector
+/// | Keyword
+/// |------------------
+/// | ANY SHORTEST
+/// | ALL SHORTEST
+/// | ANY
+/// | ANY k
+/// | SHORTEST k
+/// | SHORTEST k GROUP
+///
+/// Fig. 8. Table of restrictors:
+/// https://arxiv.org/abs/2112.06217
+#[derive(Clone, Debug, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub enum GraphMatchSelector {
+    AnyShortest,
+    AllShortest,
+    Any,
+    AnyK(NonZeroU32),
+    ShortestK(NonZeroU32),
+    ShortestKGroup(NonZeroU32),
+}
+
+/// A graph match clause as defined in GPML
+/// See https://arxiv.org/abs/2112.06217
+#[derive(Clone, Debug, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub struct GraphMatchExpr {
+    pub selector: Option<GraphMatchSelector>,
+    pub patterns: Vec<GraphMatchPatternAst>,
+}
+
 /// A generic pair of expressions. Used in the `pub struct`, `searched_case`
 /// and `simple_case` expr variants above.
 #[derive(Clone, Debug, PartialEq)]
diff --git a/partiql-parser/benches/bench_parse.rs b/partiql-parser/benches/bench_parse.rs
@@ -34,6 +34,20 @@ const Q_COMPLEX_FEXPR: &str = r#"
             AS deltas FROM SOURCE_VIEW_DELTA_FULL_TRANSACTIONS delta_full_transactions
             "#;
 
+const Q_COMPLEX_MATCH: &str = r#"
+            SELECT (
+                SELECT numRec, data
+                FROM
+                (deltaGraph MATCH (t) -[:hasChange]-> (dt), (dt) -[:checkPointedBy]-> (t1)), 
+                (
+                    SELECT foo(u.id), bar(review), rindex
+                    FROM delta.data as u CROSS JOIN UNPIVOT u.reviews as review AT rindex
+                ) as data,
+                delta.numRec as numRec
+            )
+            AS deltas FROM SOURCE_VIEW_DELTA_FULL_TRANSACTIONS delta_full_transactions
+            "#;
+
 fn parse_bench(c: &mut Criterion) {
     fn parse(text: &str) -> ParserResult {
         Parser::default().parse(text)
@@ -45,6 +59,9 @@ fn parse_bench(c: &mut Criterion) {
     c.bench_function("parse-complex-fexpr", |b| {
         b.iter(|| parse(black_box(Q_COMPLEX_FEXPR)))
     });
+    c.bench_function("parse-complex-match", |b| {
+        b.iter(|| parse(black_box(Q_COMPLEX_MATCH)))
+    });
 }
 
 criterion_group! {
diff --git a/partiql-parser/src/lexer.rs b/partiql-parser/src/lexer.rs
@@ -467,6 +467,8 @@ pub enum Token<'input> {
     Caret,
     #[token(".")]
     Period,
+    #[token("~")]
+    Tilde,
     #[token("||")]
     DblPipe,
 
@@ -512,10 +514,14 @@ pub enum Token<'input> {
     // Keywords
     #[regex("(?i:All)")]
     All,
+    #[regex("(?i:Acyclic)")]
+    Acyclic,
     #[regex("(?i:Asc)")]
     Asc,
     #[regex("(?i:And)")]
     And,
+    #[regex("(?i:Any)")]
+    Any,
     #[regex("(?i:As)")]
     As,
     #[regex("(?i:At)")]
@@ -576,6 +582,8 @@ pub enum Token<'input> {
     Like,
     #[regex("(?i:Limit)")]
     Limit,
+    #[regex("(?i:Match)")]
+    Match,
     #[regex("(?i:Missing)")]
     Missing,
     #[regex("(?i:Natural)")]
@@ -612,8 +620,14 @@ pub enum Token<'input> {
     Time,
     #[regex("(?i:Timestamp)")]
     Timestamp,
+    #[regex("(?i:Simple)")]
+    Simple,
+    #[regex("(?i:Shortest)")]
+    Shortest,
     #[regex("(?i:Then)")]
     Then,
+    #[regex("(?i:Trail)")]
+    Trail,
     #[regex("(?i:True)")]
     True,
     #[regex("(?i:Union)")]
@@ -642,9 +656,11 @@ impl<'input> Token<'input> {
     pub fn is_keyword(&self) -> bool {
         matches!(
             self,
-            Token::All
+            Token::Acyclic
+                | Token::All
                 | Token::Asc
                 | Token::And
+                | Token::Any
                 | Token::As
                 | Token::At
                 | Token::Between
@@ -671,6 +687,7 @@ impl<'input> Token<'input> {
                 | Token::Left
                 | Token::Like
                 | Token::Limit
+                | Token::Match
                 | Token::Missing
                 | Token::Natural
                 | Token::Not
@@ -689,7 +706,10 @@ impl<'input> Token<'input> {
                 | Token::Table
                 | Token::Time
                 | Token::Timestamp
+                | Token::Simple
+                | Token::Shortest
                 | Token::Then
+                | Token::Trail
                 | Token::Union
                 | Token::Unpivot
                 | Token::Using
@@ -736,6 +756,7 @@ impl<'input> fmt::Display for Token<'input> {
             Token::Slash => write!(f, "/"),
             Token::Caret => write!(f, "^"),
             Token::Period => write!(f, "."),
+            Token::Tilde => write!(f, "~"),
             Token::DblPipe => write!(f, "||"),
             Token::UnquotedIdent(id) => write!(f, "<{}:UNQUOTED_IDENT>", id),
             Token::QuotedIdent(id) => write!(f, "<{}:QUOTED_IDENT>", id),
@@ -748,9 +769,11 @@ impl<'input> fmt::Display for Token<'input> {
             Token::EmbeddedIonQuote => write!(f, "<ION>"),
             Token::Ion(txt) => write!(f, "<{}:ION>", txt),
 
-            Token::All
+            Token::Acyclic
+            | Token::All
             | Token::Asc
             | Token::And
+            | Token::Any
             | Token::As
             | Token::At
             | Token::Between
@@ -781,6 +804,7 @@ impl<'input> fmt::Display for Token<'input> {
             | Token::Left
             | Token::Like
             | Token::Limit
+            | Token::Match
             | Token::Missing
             | Token::Natural
             | Token::Not
@@ -799,7 +823,10 @@ impl<'input> fmt::Display for Token<'input> {
             | Token::Table
             | Token::Time
             | Token::Timestamp
+            | Token::Simple
+            | Token::Shortest
             | Token::Then
+            | Token::Trail
             | Token::True
             | Token::Union
             | Token::Unpivot
@@ -836,7 +863,8 @@ mod tests {
             "WiTH Where Value uSiNg Unpivot UNION True Select right Preserve pivoT Outer Order Or \
              On Offset Nulls Null Not Natural Missing Limit Like Left Lateral Last Join \
              Intersect Is Inner In Having Group From For Full First False Except Escape Desc \
-             Cross Table Time Timestamp Date By Between At As And Asc All Values Case When Then Else End";
+             Cross Table Time Timestamp Date By Between At As And Asc All Values Case When Then Else End \
+             Match Any Shortest Trail Acyclic Simple";
         let symbols = symbols.split(' ').chain(primitives.split(' '));
         let keywords = keywords.split(' ');
 
@@ -858,7 +886,7 @@ mod tests {
             "<unquoted_atident:UNQUOTED_ATIDENT>", "GROUP", "<quoted_atident:QUOTED_ATIDENT>",
             "FROM", "FOR", "FULL", "FIRST", "FALSE", "EXCEPT", "ESCAPE", "DESC", "CROSS", "TABLE",
             "TIME", "TIMESTAMP", "DATE", "BY", "BETWEEN", "AT", "AS", "AND", "ASC", "ALL", "VALUES",
-            "CASE", "WHEN", "THEN", "ELSE", "END"
+            "CASE", "WHEN", "THEN", "ELSE", "END", "MATCH", "ANY", "SHORTEST", "TRAIL", "ACYCLIC", "SIMPLE"
         ];
         let displayed = toks
             .into_iter()
diff --git a/partiql-parser/src/parse/mod.rs b/partiql-parser/src/parse/mod.rs
diff --git a/partiql-parser/src/parse/partiql.lalrpop b/partiql-parser/src/parse/partiql.lalrpop
