Rework CIP

Author: boggle

cip/1.accepted/CIP2017-01-18-configurable-pattern-matching-semantics.adoc

@@ -0,0 +1,231 @@
+= CIP2017-01-18 - Configurable Pattern Matching Semantics
+:numbered:
+:toc:
+:toc-placement: macro
+:source-highlighter: codemirror
+
+*Author:* Stefan Plantikow <stefan.plantikow@neotechnology.com>
+
+This proposal is a response to CIR-2017-174.
+
+== Motivation
+
+Currently Cypher uses pattern matching semantics that treats all patterns that occur in a `MATCH` clause as a unit (called a *uniqueness scope*) and only considers pattern instances that bind different relationships to each fixed length relationship pattern variable and to each element of a variable length relationship pattern variable.
+This has come to be called *cypermorphism* informally and is a variation of edge isomorphism.
+
+Cyphermorphism lies at the intersection of returning as many results as possible while still ruling out returning an infinite number of paths when matching graphs that contain cycles.
+
+However, the notion of *uniqueness scope* has proven to be non-standard and is occasionally confusing for users and cyphermorphic matching is not tractable in terms of computational complexity for some graphs.
+
+The CIP aims to address these issues.
+
+== Background
+
+This CIP relies on the terminology introduced by the openCypher grammar.
+
+Most notably, a pattern in Cypher consists of a comma separated list of *pattern parts*.
+Pattern parts may be bound to a path variable and consist of a linear chain of connected node and relationship patterns.
+
+While Cypher allows omitting path, node, and relationship variables in a pattern this is just syntactic sugar, i.e. all parts of a pattern should be considered to be bound to a variable name from the viewpoint of pattern matching semantics (names are either provided in the query or automatically generated by a conforming implementation).
+
+== Proposal
+
+This CIP proposes to replace the notion of *uniqueness scope* and *cyphermorphism* and all associated rules by providing new, configurable pattern matching semantics for Cypher as outlined in this section.
+
+This CIP has been submitted in the belief that *CIP2017-02-06 Path Pattern Queries* will be accepted and is aligned with it.
+
+=== Walks
+
+This CIP introduces the following kinds of walks:
+
+* `WALK`: A walk is an arbitrary, non-empty sequence of alternating nodes and relationships that starts with a node and ends with a node.
+* `TRAIL`: A trail is a walk that does not contain the same relationship twice.
+* `PATH`: A simple path is a trail that does not contain the same node twice unless that node is both the start node and the end node of the path.
+
+Note that every `PATH` is a `TRAIL` and that every `TRAIL` is a `WALK`.
+
+This CIP proposes to rename the cypher type `PATH` to `WALK`.
+
+=== Pattern binders
+
+This CIP proposes to name the path variable that occurs before a pattern element of a pattern part to *pattern binder* in the grammar.
+Note that such variables are always bound to a linear sequence of node, relationship, and path query patterns of its pattern element.
+
+This CIP proposes introducing the notion of a *pattern binder class* that may be writtern before a pattern binder in a read-only pattern (i.e. a pattern that is not used as an argument to an updating clause) and restricts the set of valid pattern matches for the following pattern element.
+The proposed pattern binder classes are:
+
+* `WALK` This pattern binder should only be bound to a `WALK` that matches all node, relationship, and path query patterns given in the following pattern element
+* `TRAIL` This pattern binder should only be bound to a `TRAIL` that matches all node, relationship, and path query patterns given in the following pattern element
+* `PATH` This pattern binder should only be bound to a simple `PATH` that matches all node, relationship, and path query patterns given in the following pattern element
+
+The pattern binder class may be futher qualified with one of the following prefixes:
+
+* `OPEN WALK|TRAIL|PATH` This pattern binder should only be bound to walks (or trails, or paths respectively) whose start and end nodes are _not the same node_
+* `CLOSED WALK|TRAIL|PATH` This pattern binder should only be bound to walks (or trails, or paths respectively) whose start and end nodes are _the same node_
+
+The following additional pattern binder classes are proposed to accomodate existing terminology that is commonly used in graph theory:
+
+* `CIRCUIT` is a synonym for `CLOSED TRAIL`
+* `CYCLE` is a synonym for `CLOSED PATH`
+
+Implementations are advised to signal a warning for every use of an `OPEN` pattern binder class if the two endpoints of the pattern element are both unbound and both use the same variable name.
+
+Implementations are advised to signal a warning for every use of an `CLOSED` pattern binder class if the two endpoints of the pattern element are both unbound and both use a different variable name.
+
+=== Pattern match modes
+
+This CIP proposes introducing the notion of a *pattern match mode* that may be writtern before a pattern binder in a read-only pattern (i.e. a pattern that is not used as an argument to an updating clause) and restricts the set of valid pattern matches for the following pattern element.
+
+A pattern match mode is always written before any pattern binder class that has been explicitly given for the same pattern binder.
+
+==== MATCH EVERY mode
+
+This CIP proposes the new `MATCH EVERY` pattern match mode that matches every walk (or trail, or path respectively) as described by all node, relationship, and path query patterns given in the following pattern elements.
+This may return an infinite or at least a very large result for some graphs.
+
+Implementations are advised to signal a warning for every use of `MATCH EVERY (OPEN|CLOSED) WALK` that may lead to the generation of an infinite result set.
+
+==== MATCH SHORTEST mode
+
+This CIP proposes the new `MATCH SHORTEST` pattern match mode that matches every _shortest_ walk (or trail, or path respectively) as described by all node, relationship, and path query patterns in the following pattern elements.
+
+This CIP proposes to deprecate the existing syntax for both `shortestPath` and `allShortestPaths` matching of Cypher.
+
+==== Weight declarations
+
+This CIP proposes that pattern elements may optionally be followed by weight declarations of one of the following forms:
+
+* `WEIGHT <numerical-aggregation> OVER <rel> AS <weight>` Calculates a weight `<weight>` by evaluating the given `<numerical-aggregation>` for each relationship `<rel>` in the associated match
+* `WEIGHT |<expr>| AS <weight>` Calculates a weight `<weight>` by summing the results of evaluating `abs(<expr>)` for each relationship `r` in the associated match in a special scope that only contains all properties of `r` as variables
+
+Multiple weight declarations may be given as long as they do not define the same `<weight>` variable.
+
+==== MATCH CHEAPEST mode
+
+This CIP proposes the new `MATCH CHEAPEST` pattern match mode that matches every cheapest walk (or trail, or path respectively) as described by all node, relationship, and path query patterns given in the following pattern element and according to the pattern element's concluding first _mandatory_ weight declaration.
+
+==== Mandatory weight declarations
+
+A mandatory weight declaration is prefixed with `BY`, may omit specifying a variable name for the computed weight, and it's aggregation must be monotone (i.e. the sequence of intermediary results obtained by computing the aggregation incrementally over all input values in any order is always monotonically increasing).
+
+A conforming implementation is expected to raise a runtime error when the monotonicity of a mandatory weight declaration is violated at runtime.
+
+A conforming implementation may raise a compile time error when it can statically prove that the monotonicity of a mandatory weight declaration may be violated at runtime.
+
+Additional weight declarations may be given after a mandatory weight declaration as long as no two weight declarations define conflicting aliases.
+
+==== Singular matches
+
+This CIP proposes optionally prefixing pattern match modes and pattern binder classes with the `ONE [OF]` marker to support returning at most one match.
+
+=== Multiple pattern parts
+
+If a pattern consists of multiple pattern parts, they are first solved independently before returning their cross product as the final result of the pattern.
+
+=== Default pattern matching semantics
+
+This CIP defines three classes of pattern parts:
+
+* *Fixed length pattern parts* are top-level pattern parts that may consist of node patterns or single length relationship patterns only.
+* *Variable length pattern parts* are top-level pattern parts that may consist of node patterns, single length relationship patterns, or path query patterns only.
+* *Legacy variable length pattern parts* are top-level pattern parts that may consist of node patterns, single length relationship patterns, or path query patterns and contain at least one legacy variable length pattern (including chains of single length patterns expressed as bounded variable length patterns).
+
+Current Cypher pattern matching semantics correspond to using `MATCH EVERY TRAIL` by default for all top-level pattern parts (i.e. `MATCH` behaves like `MATCH EVERY TRAIL`)
+
+This CIP proposes to adopt the following new default pattern match modes and default pattern binder classes:
+
+* `EVERY WALK` for fixed length pattern parts,
+* `SHORTEST WALK` for variable length pattern parts, and
+* `EVERY TRAIL` for legacy variable length pattern parts only.
+
+This CIP aligns with the introduction of path query patterns by proposing that existing bounded and unbounded variable length patterns are to be deprecated in favor of path query patterns.
+
+This changes Cypher to use homomorphic matching for all non-deprecated pattern parts.
+
+=== Predicates and functions for working with walks
+
+This CIP proposes to introduce additional predicates and functions for working with walks
+
+* `open(p)`: true if the start node and the end node of `p` are not the same node
+* `closed(p)`: true if the start node and the end node of `p` are the same node
+* `trail(p)`: `p` if `p` contains no duplicate relationships, `NULL` otherwise
+* `path(p)`: `p` if `p` contains no duplicate relationships and either no duplicate nodes at all or the start node and the end node are the same node, `NULL` otherwise
+* `circuit(p)`:  `trail(p)`, if `closed(p)` is true, `NULL` otherwise
+* `cycle(p)`: `path(p)`, if `closed(p)` is true, `NULL` otherwise
+* `disjoint(list1, list2, ..., list_n)` is true if the lists do not share any elements
+
+To support a common family of weight calculations, this CIP proposes the introduction of a new aggregate function `product` for computing the product of a set of numbers.
+
+Evaluating `product` for an empty set returns `1`.
+
+== Examples
+
+The following examples demonstrates various ways in which the newly proposed constructs may be used if this CIP is adopted.
+
+=== Matching shortest paths
+
+[source=cypher]
+----
+// shortestPath(...) today becomes:
+MATCH ONE SHORTEST [TRAIL] p=(a)-[r*]->(b)
+RETURN *
+
+// allShortestPaths(...) today becomes:
+MATCH SHORTEST [TRAIL] p=(a)-[r*]->(b)
+RETURN p
+----
+
+=== Matching cheapest paths
+
+[source=cypher]
+----
+MATCH CHEAPEST PATH p=(a)-/(:LOVES|:LIKES)*/->(b) BY WEIGHT |strength| AS w
+RETURN p AS path, w AS weight
+----
+
+=== Matching one path and computing its weight
+
+[source=cypher]
+----
+MATCH ONE PATH p=(a)-[*]->(b) WEIGHT product(r.score+r.handicap) OVER r AS w
+RETURN p, w
+----
+
+=== Matching with existing semantics
+
+`overlap` may be used to precisely express Cypher's current pattern matching semantics.
+
+[source=cypher]
+----
+// Today (using same uniqueness scope for pat1, pat2, and pat)
+MATCH pat1=..., pat2=..., pat3=...
+
+// This CIP
+MATCH EVERY TRAIL pat1=...
+MATCH EVERY TRAIL pat2=...
+MATCH EVERY TRAIL pat3=...
+WHERE disjoint(rels(pat1), rels(pat2), rels(pat3))
+----
+
+== Per-parser options
+
+It is suggested that a conforming implementation should provide pre-parser options for defining the default pattern binder class for each pattern match mode as well as the default pattern match mode for each class of pattern parts:
+
+* `match-every=walk|trail|path` for configuring the default pattern binder class for each use of the `MATCH EVERY` pattern match mode
+* `match-shortest=walk|trail|path` for configuring the default pattern binder class for each use of the `MATCH SHORTEST` pattern match mode
+* `match-cheapest=walk|trail|path` for configuring the default pattern binder class for each use of the `MATCH CHEAPEST` pattern match mode
+* `fixlen-mode=every|shortest` for configuring the default pattern match mode of fixed length pattern parts
+* `varlen-mode=every|shortest` for configuring the default pattern match mode of variable length pattern parts
+
+== Benefits to this proposal
+
+This proposal adds a generic facility to Cypher for expressing desired pattern matching semantics.
+
+== Caveats to this proposal
+
+A moderate increase in language complexity.
+
+A substantial departure from current pattern matching semantics.
+However, care has been taken to retain access to current semantics.
+
+`MATCH EVERY [OPEN|CLOSED] WALK` allows for non-terminating queries.