feat(cypher): support OR/XOR-around-pattern WHERE lowering (#1236)

Author: lmeyerov

graphistry/compute/ast.py

@@ -1764,6 +1764,28 @@ def anti_semi_apply(
     )
 
 
+def semi_apply_mark(
+    *,
+    binding_ops: List[Dict[str, Any]],
+    join_aliases: Sequence[str],
+    out_col: str,
+) -> ASTCall:
+    """Annotate active rows with a correlated pattern-existence boolean.
+
+    ``binding_ops`` encodes the pattern to evaluate as bindings rows.
+    ``join_aliases`` names shared aliases used as join keys.
+    ``out_col`` receives a bool marker where True means the pattern matched.
+    """
+    return ASTCall(
+        "semi_apply_mark",
+        {
+            "binding_ops": binding_ops,
+            "join_aliases": list(join_aliases),
+            "out_col": out_col,
+        },
+    )
+
+
 def order_by(keys: Iterable[Tuple[Any, str]]) -> ASTCall:
     """Create an ORDER BY operation for GFQL row pipelines."""
     return ASTCall("order_by", {"keys": list(keys)})

graphistry/compute/gfql/call/validation.py

@@ -217,6 +217,13 @@ def _group_by_requires_node_cols(params: Dict[str, object]) -> List[str]:
     return out
 
 
+def _semi_apply_mark_added_node_cols(params: Dict[str, object]) -> Set[str]:
+    out_col = params.get("out_col")
+    if isinstance(out_col, str) and out_col != "":
+        return {out_col}
+    return set()
+
+
 # Parser-backed helpers stay local because tests monkeypatch parser availability
 # and capability behavior through this module.
 
@@ -271,6 +278,18 @@ def _group_by_requires_node_cols(params: Dict[str, object]) -> List[str]:
         schema_effects=NO_SCHEMA_EFFECTS,
     ),
 
+    'semi_apply_mark': _method_entry(
+        allowed_params={'binding_ops', 'join_aliases', 'out_col'},
+        required_params={'binding_ops', 'join_aliases', 'out_col'},
+        param_validators={
+            'binding_ops': is_list_of_dicts,
+            'join_aliases': is_non_empty_list_of_strings,
+            'out_col': is_non_empty_string,
+        },
+        description='Annotate active rows with correlated pattern-existence booleans',
+        schema_effects=_schema_effects(adds_node_cols=_semi_apply_mark_added_node_cols),
+    ),
+
     'order_by': _method_entry(
         allowed_params={'keys'},
         required_params={'keys'},

graphistry/compute/gfql/cypher/_boolean_expr_text.py

@@ -57,11 +57,9 @@ def boolean_expr_to_text(expr: BooleanExpr) -> str:
     if expr.op == "atom":
         return expr.atom_text or ""
     if expr.op == "pattern":
-        # Unreachable today: top-level AND leaves are lifted out by
-        # ``_split_top_level_and_pattern_leaves`` before the binder walks
-        # the tree, and patterns nested under NOT/OR/XOR are rejected
-        # earlier with E108 errors.  Contract for the defensive branch:
-        # emit raw pattern source for round-trippability.
+        # Pattern leaves may remain in expr_tree for nested OR/XOR/NOT
+        # compositions. Emit raw source text for round-trippability; lowering
+        # can rewrite these leaves to marker columns before row evaluation.
         return expr.atom_text or ""
     if expr.op == "not":
         operand = boolean_expr_to_text(expr.left) if expr.left is not None else ""

graphistry/compute/gfql/cypher/lowering.py

@@ -23,6 +23,7 @@
     order_by,
     return_,
     rows,
+    semi_apply_mark,
     serialize_binding_ops,
     select,
     skip,
@@ -5993,9 +5994,12 @@ def _is_variable_length_relationship_pattern(relationship: RelationshipPattern)
 def _reject_unsupported_variable_length_where_pattern_predicates(query: CypherQuery) -> None:
     if query.where is None:
         return
-    for predicate in query.where.predicates:
-        if not isinstance(predicate, WherePatternPredicate):
-            continue
+    predicates: List[WherePatternPredicate] = [
+        predicate for predicate in query.where.predicates if isinstance(predicate, WherePatternPredicate)
+    ]
+    if query.where.expr_tree is not None:
+        predicates.extend(_where_expr_tree_pattern_predicates(query.where.expr_tree))
+    for predicate in predicates:
         relationships = [
             element
             for element in predicate.pattern
@@ -6356,6 +6360,155 @@ def _predicate_pattern_aliases(predicate: WherePatternPredicate) -> List[str]:
     return aliases
 
 
+def _where_expr_tree_pattern_predicates(expr: BooleanExpr) -> List[WherePatternPredicate]:
+    out: List[WherePatternPredicate] = []
+    stack: List[BooleanExpr] = [expr]
+    while stack:
+        cur = stack.pop()
+        if cur.op == "pattern":
+            if cur.pattern is None:
+                raise _unsupported(
+                    "Cypher WHERE pattern predicates must include a relationship",
+                    field="where",
+                    value=cur.atom_text,
+                    line=cur.span.line,
+                    column=cur.span.column,
+                )
+            out.append(WherePatternPredicate(pattern=cur.pattern, span=cur.span, negated=False))
+            continue
+        if cur.left is not None:
+            stack.append(cur.left)
+        if cur.right is not None:
+            stack.append(cur.right)
+    return out
+
+
+def _lower_pattern_predicate_to_row_marker(
+    predicate: WherePatternPredicate,
+    *,
+    alias_targets: Mapping[str, ASTObject],
+    params: Optional[Mapping[str, Any]],
+    out_col: str,
+) -> ASTCall:
+    if len(predicate.pattern) < 3:
+        raise _unsupported(
+            "Cypher WHERE pattern predicates must include a relationship",
+            field="where",
+            value=None,
+            line=predicate.span.line,
+            column=predicate.span.column,
+        )
+
+    predicate_aliases = _predicate_pattern_aliases(predicate)
+    if not predicate_aliases:
+        raise _unsupported(
+            "Cypher WHERE pattern predicates currently require at least one shared bound alias",
+            field="where",
+            value=None,
+            line=predicate.span.line,
+            column=predicate.span.column,
+        )
+
+    introduced_aliases = sorted(alias for alias in predicate_aliases if alias not in alias_targets)
+    if introduced_aliases:
+        raise _unsupported(
+            "Cypher WHERE pattern predicates cannot introduce new aliases in this phase",
+            field="where",
+            value=introduced_aliases,
+            line=predicate.span.line,
+            column=predicate.span.column,
+        )
+
+    shared_aliases = [alias for alias in predicate_aliases if alias in alias_targets]
+    if not shared_aliases:
+        raise _unsupported(
+            "Cypher WHERE pattern predicates currently require at least one shared bound alias",
+            field="where",
+            value=predicate_aliases,
+            line=predicate.span.line,
+            column=predicate.span.column,
+        )
+
+    pattern_clause = MatchClause(
+        patterns=(predicate.pattern,),
+        span=predicate.span,
+        optional=False,
+        pattern_aliases=(None,),
+        pattern_alias_kinds=("pattern",),
+    )
+    pattern_ops = lower_match_clause(pattern_clause, params=params)
+    return semi_apply_mark(
+        binding_ops=serialize_binding_ops(pattern_ops),
+        join_aliases=shared_aliases,
+        out_col=out_col,
+    )
+
+
+def _rewrite_where_expr_patterns_to_markers(
+    *,
+    where: WhereClause,
+    alias_targets: Mapping[str, ASTObject],
+    params: Optional[Mapping[str, Any]],
+) -> Tuple[Optional[ExpressionText], List[ASTCall]]:
+    if where.expr_tree is None:
+        return None, []
+
+    pattern_preds = _where_expr_tree_pattern_predicates(where.expr_tree)
+    if not pattern_preds:
+        return _where_clause_expr_text(where), []
+
+    marker_ops: List[ASTCall] = []
+    marker_counter = 0
+
+    def _fresh_marker_col(span: SourceSpan) -> str:
+        nonlocal marker_counter
+        marker_counter += 1
+        return (
+            "__gfql_where_pattern_"
+            f"{span.line}_{span.column}_{span.end_line}_{span.end_column}_{marker_counter}__"
+        )
+
+    def _rewrite(expr: BooleanExpr) -> BooleanExpr:
+        if expr.op == "pattern":
+            if expr.pattern is None:
+                raise _unsupported(
+                    "Cypher WHERE pattern predicates must include a relationship",
+                    field="where",
+                    value=expr.atom_text,
+                    line=expr.span.line,
+                    column=expr.span.column,
+                )
+            marker_col = _fresh_marker_col(expr.span)
+            marker_ops.append(
+                _lower_pattern_predicate_to_row_marker(
+                    WherePatternPredicate(pattern=expr.pattern, span=expr.span, negated=False),
+                    alias_targets=alias_targets,
+                    params=params,
+                    out_col=marker_col,
+                )
+            )
+            return BooleanExpr(
+                op="atom",
+                span=expr.span,
+                atom_text=marker_col,
+                atom_span=expr.atom_span or expr.span,
+            )
+        if expr.op in {"atom"}:
+            return expr
+        if expr.op == "not":
+            return replace(expr, left=_rewrite(cast(BooleanExpr, expr.left)))
+        if expr.op in {"and", "or", "xor"}:
+            return replace(
+                expr,
+                left=_rewrite(cast(BooleanExpr, expr.left)),
+                right=_rewrite(cast(BooleanExpr, expr.right)),
+            )
+        return expr
+
+    rewritten = _rewrite(where.expr_tree)
+    return ExpressionText(text=boolean_expr_to_text(rewritten), span=where.span), marker_ops
+
+
 def _lower_negated_pattern_predicate_to_row_filter(
     predicate: WherePatternPredicate,
     *,
@@ -6449,7 +6602,12 @@ def lower_match_query(
     row_where: Optional[ExpressionText] = None
     row_where_predicates: List[str] = list(dynamic_row_where_predicates)
     if query.where is not None:
-        where_expr = _where_clause_expr_text(query.where)
+        where_expr, where_pattern_row_filters = _rewrite_where_expr_patterns_to_markers(
+            where=query.where,
+            alias_targets=alias_targets,
+            params=params,
+        )
+        row_pre_filters.extend(where_pattern_row_filters)
         if where_expr is not None:
             type_where = _extract_relationship_type_where(
                 where_expr,
@@ -8270,7 +8428,12 @@ def _apply_where_to_ops(
     row_pre_filters: List[ASTCall] = []
     if where is None:
         return where_out, row_expr_filters, row_pre_filters
-    where_expr = _where_clause_expr_text(where)
+    where_expr, where_pattern_row_filters = _rewrite_where_expr_patterns_to_markers(
+        where=where,
+        alias_targets=alias_targets,
+        params=params,
+    )
+    row_pre_filters.extend(where_pattern_row_filters)
     if where_expr is not None:
         type_where = _extract_relationship_type_where(
             where_expr,

graphistry/compute/gfql/cypher/parser.py

@@ -361,8 +361,8 @@ def _split_top_level_and_pattern_leaves(
     - ``others``: non-pattern conjuncts that should remain in ``expr_tree``.
     - ``has_nested_pattern``: True when a pattern atom appears in a deeper
       non-AND/non-direct-NOT context (e.g. ``OR`` with a pattern leaf, or
-      ``NOT (and-tree-of-patterns)``).  Triggers the legacy E108 reject so
-      slice 4 / De-Morgan-NOT compositions stay deferred.
+      ``NOT (and-tree-of-patterns)``).  Lowering consumes this by keeping
+      such leaves in ``expr_tree`` instead of lifting them to predicates.
     """
     if expr.op == "and":
         if expr.left is None or expr.right is None:
@@ -420,17 +420,6 @@ def _build_where_with_pattern_lift(
     expr_text: str,
     span: SourceSpan,
 ) -> WhereClause:
-    if nested_pattern:
-        raise GFQLValidationError(
-            ErrorCode.E108,
-            "Cypher WHERE pattern predicates cannot yet be mixed with generic row expressions",
-            field="where",
-            value=expr_text,
-            suggestion="Use positive top-level pattern predicates joined by AND.",
-            line=span.line,
-            column=span.column,
-            language="cypher",
-        )
     # Slice 3 (#1031): N positive patterns each become a WherePatternPredicate
     # (negated=False).  Slice 2 (#1031): N NOT-patterns each become a
     # WherePatternPredicate (negated=True) for downstream anti-semi-join
@@ -446,6 +435,9 @@ def _build_where_with_pattern_lift(
     new_expr_tree = _rebuild_and_tree(other_conjuncts)
     if new_expr_tree is None:
         return WhereClause(predicates=tuple(pattern_preds), expr_tree=None, span=span)
+    # Nested pattern leaves (OR/XOR/complex NOT contexts) stay in expr_tree;
+    # lowering rewrites them to correlated semi-apply marker columns.
+    _ = nested_pattern
     return WhereClause(
         predicates=tuple(pattern_preds),
         expr_tree=new_expr_tree,