feat(gfql): support cypher multihop relationships

lmeyerov · lmeyerov · commit 2dfdb57e18ea · 2026-03-14T16:32:42.000-07:00
diff --git a/graphistry/compute/chain.py b/graphistry/compute/chain.py
@@ -432,6 +432,41 @@ def apply_output_slice(op: ASTObject, op_label: ASTObject, df):
                         mapped_vals = out_df[id].map(hop_map)
                         out_df[hc] = out_df[hc].where(out_df[hc].notna(), mapped_vals)
 
+        if hop_cols:
+            hop_col = hop_cols[0]
+            for idx, (op, _g_step) in enumerate(steps):
+                if op._name is None or not isinstance(op, ASTNode) or op._name not in out_df.columns or idx == 0:
+                    continue
+                prev_op, _ = steps[idx - 1]
+                if not isinstance(prev_op, ASTEdge):
+                    continue
+                min_hop = (
+                    prev_op.output_min_hops
+                    if prev_op.output_min_hops is not None
+                    else (
+                        prev_op.min_hops
+                        if prev_op.min_hops is not None
+                        else (prev_op.hops if prev_op.hops is not None else 1)
+                    )
+                )
+                max_hop = (
+                    prev_op.output_max_hops
+                    if prev_op.output_max_hops is not None
+                    else (
+                        prev_op.max_hops
+                        if prev_op.max_hops is not None
+                        else prev_op.hops
+                    )
+                )
+                if prev_op.to_fixed_point:
+                    max_hop = None
+                label_mask = out_df[op._name].fillna(False).astype(bool)
+                if min_hop > 1:
+                    label_mask = label_mask & out_df[hop_col].notna() & (out_df[hop_col] >= min_hop)
+                if max_hop is not None:
+                    label_mask = label_mask & out_df[hop_col].notna() & (out_df[hop_col] <= max_hop)
+                out_df[op._name] = label_mask
+
     cols = list(out_df.columns)
     for c in cols:
         if c.endswith('_x'):
diff --git a/graphistry/compute/gfql/cypher/ast.py b/graphistry/compute/gfql/cypher/ast.py
@@ -64,6 +64,9 @@ class RelationshipPattern:
     types: Tuple[str, ...]
     properties: Tuple[PropertyEntry, ...]
     span: SourceSpan
+    min_hops: Optional[int] = None
+    max_hops: Optional[int] = None
+    to_fixed_point: bool = False
 
 
 PatternElement = Union[NodePattern, RelationshipPattern]
diff --git a/graphistry/compute/gfql/cypher/lowering.py b/graphistry/compute/gfql/cypher/lowering.py
@@ -2230,11 +2230,19 @@ def _lower_relationship(
         line=relationship.span.line,
         column=relationship.span.column,
     )
+    edge_kwargs = {
+        "edge_match": edge_match,
+        "hops": None if (relationship.min_hops is not None or relationship.max_hops is not None or relationship.to_fixed_point) else 1,
+        "min_hops": relationship.min_hops,
+        "max_hops": relationship.max_hops,
+        "to_fixed_point": relationship.to_fixed_point,
+        "name": relationship.variable,
+    }
     if relationship.direction == "forward":
-        return cast(ASTObject, e_forward(edge_match=edge_match, name=relationship.variable))
+        return cast(ASTObject, e_forward(**edge_kwargs))
     if relationship.direction == "reverse":
-        return cast(ASTObject, e_reverse(edge_match=edge_match, name=relationship.variable))
-    return cast(ASTObject, e_undirected(edge_match=edge_match, name=relationship.variable))
+        return cast(ASTObject, e_reverse(**edge_kwargs))
+    return cast(ASTObject, e_undirected(**edge_kwargs))
 
 
 def _pattern_line_column(pattern: Sequence[PatternElement], clause: MatchClause) -> Tuple[int, int]:
@@ -2257,6 +2265,9 @@ def _reverse_relationship_pattern(relationship: RelationshipPattern) -> Relation
         types=relationship.types,
         properties=relationship.properties,
         span=relationship.span,
+        min_hops=relationship.min_hops,
+        max_hops=relationship.max_hops,
+        to_fixed_point=relationship.to_fixed_point,
     )
 
 
diff --git a/graphistry/compute/gfql/cypher/parser.py b/graphistry/compute/gfql/cypher/parser.py
@@ -76,15 +76,18 @@
                     | rel_undirected_simple
                     | rel_bidirectional_simple
 
-rel_forward: "-" "[" variable? rel_types? properties? "]" "->"
-rel_reverse: "<-" "[" variable? rel_types? properties? "]" "-"
-rel_undirected: "-" "[" variable? rel_types? properties? "]" "-"
+rel_forward: "-" "[" variable? rel_types? rel_range? properties? "]" "->"
+rel_reverse: "<-" "[" variable? rel_types? rel_range? properties? "]" "-"
+rel_undirected: "-" "[" variable? rel_types? rel_range? properties? "]" "-"
 rel_forward_simple: REL_FWD_SIMPLE
 rel_reverse_simple: REL_REV_SIMPLE
 rel_undirected_simple: REL_UNDIR_SIMPLE
 rel_bidirectional_simple: REL_BIDIR_SIMPLE
 
 rel_types: ":" LABEL_NAME ("|" ":"? LABEL_NAME)*
+rel_range: "*" INT ".." INT      -> rel_range_bounded
+         | "*" INT               -> rel_range_exact
+         | "*"                   -> rel_range_fixed
 
 variable: NAME
 
@@ -389,46 +392,13 @@ def _to_unsupported(message: str, *, line: Optional[int] = None, column: Optiona
     )
 
 
-_VARIABLE_REL_PATTERN_RE = re.compile(
-    r"(?:<-\s*\[[^\]\n]*\*[^\]\n]*\]\s*-)|(?:-\s*\[[^\]\n]*\*[^\]\n]*\]\s*->)|(?:-\s*\[[^\]\n]*\*[^\]\n]*\]\s*-)"
-)
-
-
 def _line_and_column_from_offset(source: str, offset: int) -> Tuple[int, int]:
     line = source.count("\n", 0, offset) + 1
     last_newline = source.rfind("\n", 0, offset)
     column = offset + 1 if last_newline < 0 else offset - last_newline
     return line, column
 
 
-def _find_variable_length_relationship_pattern(source: str) -> Optional[Tuple[str, int, int]]:
-    in_single_quote = False
-    escape = False
-    segment_start = 0
-    for idx, ch in enumerate(source):
-        if in_single_quote:
-            if escape:
-                escape = False
-            elif ch == "\\":
-                escape = True
-            elif ch == "'":
-                in_single_quote = False
-                segment_start = idx + 1
-            continue
-        if ch == "'":
-            match = _VARIABLE_REL_PATTERN_RE.search(source, segment_start, idx)
-            if match is not None:
-                line, column = _line_and_column_from_offset(source, match.start())
-                return match.group(0), line, column
-            in_single_quote = True
-            continue
-    match = _VARIABLE_REL_PATTERN_RE.search(source, segment_start)
-    if match is None:
-        return None
-    line, column = _line_and_column_from_offset(source, match.start())
-    return match.group(0), line, column
-
-
 def _build_transformer(source: str) -> _TransformerLike:
     _, Transformer, _, v_args = _lark_imports()
     op_map = {
@@ -523,9 +493,16 @@ def _relationship(
             variable: Optional[str] = None
             rel_types: Tuple[str, ...] = ()
             properties: Tuple[PropertyEntry, ...] = ()
+            min_hops: Optional[int] = None
+            max_hops: Optional[int] = None
+            to_fixed_point = False
             for item in items:
                 if isinstance(item, str):
                     variable = item
+                elif isinstance(item, dict):
+                    min_hops = cast(Optional[int], item.get("min_hops"))
+                    max_hops = cast(Optional[int], item.get("max_hops"))
+                    to_fixed_point = bool(item.get("to_fixed_point", False))
                 elif isinstance(item, tuple) and all(isinstance(v, str) for v in item):
                     rel_types = cast(Tuple[str, ...], item)
                 elif isinstance(item, tuple):
@@ -536,8 +513,50 @@ def _relationship(
                 types=rel_types,
                 properties=properties,
                 span=_span_from_meta(meta),
+                min_hops=min_hops,
+                max_hops=max_hops,
+                to_fixed_point=to_fixed_point,
             )
 
+        def _rel_hops(self, meta: Any, token: Any) -> int:
+            try:
+                value = int(str(token))
+            except Exception as exc:
+                raise _to_syntax_error("Invalid relationship range bound", line=meta.line, column=meta.column) from exc
+            if value <= 0:
+                raise _to_unsupported(
+                    "Cypher zero-hop relationship ranges are not yet supported in the current GFQL Cypher compiler",
+                    line=meta.line,
+                    column=meta.column,
+                    field="match",
+                    value=self._slice(_span_from_meta(meta)),
+                )
+            return value
+
+        def rel_range_exact(self, meta: Any, items: Sequence[Any]) -> dict[str, Any]:
+            if len(items) != 1:
+                raise _to_syntax_error("Invalid relationship range", line=meta.line, column=meta.column)
+            hops = self._rel_hops(meta, items[0])
+            return {"min_hops": hops, "max_hops": hops, "to_fixed_point": False}
+
+        def rel_range_bounded(self, meta: Any, items: Sequence[Any]) -> dict[str, Any]:
+            if len(items) != 2:
+                raise _to_syntax_error("Invalid relationship range", line=meta.line, column=meta.column)
+            min_hops = self._rel_hops(meta, items[0])
+            max_hops = self._rel_hops(meta, items[1])
+            if min_hops > max_hops:
+                raise _to_unsupported(
+                    "Cypher relationship ranges require lower bound <= upper bound",
+                    line=meta.line,
+                    column=meta.column,
+                    field="match",
+                    value=self._slice(_span_from_meta(meta)),
+                )
+            return {"min_hops": min_hops, "max_hops": max_hops, "to_fixed_point": False}
+
+        def rel_range_fixed(self, meta: Any, _items: Sequence[Any]) -> dict[str, Any]:
+            return {"min_hops": None, "max_hops": None, "to_fixed_point": True}
+
         def rel_forward(self, meta: Any, items: Sequence[Any]) -> RelationshipPattern:
             return self._relationship(meta, items, direction="forward")
 
@@ -1261,16 +1280,6 @@ def parse_cypher(query: str) -> Union[CypherQuery, CypherUnionQuery]:
     """
     if not isinstance(query, str) or query.strip() == "":
         raise _to_syntax_error("Cypher query must be a non-empty string")
-    variable_length_pattern = _find_variable_length_relationship_pattern(query)
-    if variable_length_pattern is not None:
-        pattern_text, line, column = variable_length_pattern
-        raise _to_unsupported(
-            "Cypher variable-length relationship patterns are not yet supported in the current GFQL Cypher compiler",
-            line=line,
-            column=column,
-            field="match",
-            value=pattern_text,
-        )
 
     parser = _parser()
     transformer = _build_transformer(query)
diff --git a/graphistry/tests/compute/gfql/cypher/test_lowering.py b/graphistry/tests/compute/gfql/cypher/test_lowering.py
@@ -114,6 +114,36 @@ def test_lower_match_clause_relationship_direction(query: str, edge_type: type)
     assert isinstance(ops[1], edge_type)
 
 
+@pytest.mark.parametrize(
+    "query,edge_type,min_hops,max_hops,to_fixed_point,edge_match",
+    [
+        ("MATCH (a)-[*2]->(b) RETURN b", ASTEdgeForward, 2, 2, False, None),
+        ("MATCH (a)<-[*3]-(b) RETURN b", ASTEdgeReverse, 3, 3, False, None),
+        ("MATCH (a)-[:R*1..4]-(b) RETURN b", ASTEdgeUndirected, 1, 4, False, {"type": "R"}),
+        ("MATCH (a)-[*]->(b) RETURN b", ASTEdgeForward, None, None, True, None),
+    ],
+)
+def test_lower_match_clause_variable_length_relationships(
+    query: str,
+    edge_type: type,
+    min_hops: int | None,
+    max_hops: int | None,
+    to_fixed_point: bool,
+    edge_match: dict[str, object] | None,
+) -> None:
+    parsed = _parse_query(query)
+    assert parsed.match is not None
+
+    ops = lower_match_clause(parsed.match)
+
+    assert isinstance(ops[1], edge_type)
+    edge = ops[1]
+    assert edge.min_hops == min_hops
+    assert edge.max_hops == max_hops
+    assert edge.to_fixed_point is to_fixed_point
+    assert edge.edge_match == edge_match
+
+
 def test_lower_match_clause_relationship_type_alternation_uses_is_in_predicate() -> None:
     parsed = _parse_query("MATCH (n)-[r:KNOWS|HATES]->(x) RETURN r")
     assert parsed.match is not None
@@ -2331,23 +2361,89 @@ def test_string_cypher_failfast_rejects_graph_backed_unwind_after_with_as_valida
     assert "UNWIND after WITH/RETURN" in exc_info.value.message
 
 
-def test_string_cypher_failfast_rejects_variable_length_relationship_patterns_as_validation_error() -> None:
+def test_string_cypher_executes_exact_multihop_relationship_pattern() -> None:
     graph = _mk_graph(
         pd.DataFrame({"id": ["a", "b", "c", "d", "e", "f"]}),
         pd.DataFrame(
             {
-                "s": ["a", "c", "d", "e"],
-                "d": ["b", "d", "e", "f"],
-                "type": ["R", "R", "R", "R"],
+                "s": ["a", "b", "c", "d", "e"],
+                "d": ["b", "c", "d", "e", "f"],
+                "type": ["R", "R", "R", "R", "R"],
             }
         ),
     )
 
-    with pytest.raises(GFQLValidationError) as exc_info:
-        graph.gfql("MATCH p = (a)-[*]->(b) RETURN collect(nodes(p)) AS paths, length(p) AS l ORDER BY l")
+    result = graph.gfql("MATCH (a {id: 'a'})-[*2]->(b) RETURN b.id AS id ORDER BY id")
 
-    assert exc_info.value.code == ErrorCode.E108
-    assert "variable-length relationship patterns" in exc_info.value.message
+    assert result._nodes.to_dict(orient="records") == [{"id": "c"}]
+
+
+def test_string_cypher_executes_bounded_multihop_relationship_pattern() -> None:
+    graph = _mk_graph(
+        pd.DataFrame({"id": ["a", "b", "c", "d", "e"]}),
+        pd.DataFrame(
+            {
+                "s": ["a", "b", "c", "a"],
+                "d": ["b", "c", "d", "e"],
+                "type": ["R", "R", "R", "S"],
+            }
+        ),
+    )
+
+    result = graph.gfql("MATCH (a {id: 'a'})-[:R*1..3]->(b) RETURN b.id AS id ORDER BY id")
+
+    assert result._nodes.to_dict(orient="records") == [{"id": "b"}, {"id": "c"}, {"id": "d"}]
+
+
+def test_string_cypher_executes_fixed_point_relationship_pattern() -> None:
+    graph = _mk_graph(
+        pd.DataFrame({"id": ["a", "b", "c", "d", "e"]}),
+        pd.DataFrame(
+            {
+                "s": ["a", "b", "c", "a"],
+                "d": ["b", "c", "d", "e"],
+                "type": ["R", "R", "R", "S"],
+            }
+        ),
+    )
+
+    result = graph.gfql("MATCH (a {id: 'a'})-[*]->(b) RETURN b.id AS id ORDER BY id")
+
+    assert result._nodes.to_dict(orient="records") == [{"id": "b"}, {"id": "c"}, {"id": "d"}, {"id": "e"}]
+
+
+def test_string_cypher_executes_reverse_multihop_relationship_pattern() -> None:
+    graph = _mk_graph(
+        pd.DataFrame({"id": ["a", "b", "c", "d"]}),
+        pd.DataFrame(
+            {
+                "s": ["a", "b", "c"],
+                "d": ["b", "c", "d"],
+                "type": ["R", "R", "R"],
+            }
+        ),
+    )
+
+    result = graph.gfql("MATCH (a {id: 'c'})<-[*2]-(b) RETURN b.id AS id ORDER BY id")
+
+    assert result._nodes.to_dict(orient="records") == [{"id": "a"}]
+
+
+def test_string_cypher_executes_undirected_multihop_relationship_pattern() -> None:
+    graph = _mk_graph(
+        pd.DataFrame({"id": ["a", "b", "c", "d"]}),
+        pd.DataFrame(
+            {
+                "s": ["a", "b", "c"],
+                "d": ["b", "c", "d"],
+                "type": ["R", "R", "R"],
+            }
+        ),
+    )
+
+    result = graph.gfql("MATCH (a {id: 'a'})-[:R*1..2]-(b) RETURN b.id AS id ORDER BY id")
+
+    assert result._nodes.to_dict(orient="records") == [{"id": "b"}, {"id": "c"}]
 
 
 @pytest.mark.parametrize(
diff --git a/graphistry/tests/compute/gfql/cypher/test_parser.py b/graphistry/tests/compute/gfql/cypher/test_parser.py
diff --git a/graphistry/tests/compute/test_chain.py b/graphistry/tests/compute/test_chain.py
