feat(gfql/cypher): searchAny WHERE predicate + docs (viz-filter L2-b/c)

Cypher surface: searchAny(alias, 'term'[, {caseSensitive, regex, columns}]) lifts
at lowering assembly into a search_any pre-filter + fresh marker column (the
pattern-predicate marker mechanism) — composes through AND/OR/NOT; strict opts
validation (unknown keys/bad bools/bad lists/unbound alias -> clear E108);
oracle-pinned cypher-surface cases + 4-engine parity-or-NIE incl. NOT/AND
composition; docs + CHANGELOG.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: lmeyerov

CHANGELOG.md

@@ -9,6 +9,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 <!-- Do Not Erase This Section - Used for tracking unreleased changes -->
 
 ### Added
+- **GFQL Cypher `searchAny(entity, term[, opts])` cross-column search predicate + `g.search_nodes()`/`g.search_edges()` (viz-filter L2, native on all four engines)**: True where ANY of the entity's columns matches the term — the streamgl-viz inspector's table-search semantics as a composable WHERE predicate: OR across columns; case-insensitive substring by DEFAULT (folded via lowercase, never regex — the common call avoids every engine regex limit); regex opt-in obeying the same per-engine decline rules as `=~`; dtype gate AS SEMANTICS (string columns always; integer columns iff the term is a numeric literal, per the inspector's `/^[0-9.-]+$/` gate; floats/dates/booleans reachable via the explicit `columns:` list). Options map `{caseSensitive, regex, columns}` is strict-validated (unknown keys error listing the valid ones); unbound aliases and missing explicit columns error clearly; null cells never match. Lowered like the pattern-predicate markers (a `search_any` row op + fresh marker column), so it composes through AND/OR/NOT and different node/edge terms coexist in one pipeline. Per-column matching reuses the parity-hardened `Contains` predicate on pandas/cuDF and a lowercase-fold/any_horizontal lowering on polars; oracle-pinned + 4-engine parity-or-NIE conformance cases. Python twins `g.search_nodes(term, columns=, case_sensitive=, regex=)` / `g.search_edges(...)` filter their own table and return a Plottable (polars-frame twins decline honestly for now — use the cypher op).
 - **GFQL Cypher `EXISTS { <pattern> }` pattern-existence subqueries (openCypher-standard), native on all four engines**: `WHERE EXISTS { (n)-[:R]->() }` and `WHERE NOT EXISTS { (n)--() }` now parse and run — the declarative prune-isolated building blocks for the streamgl-viz filter pipeline. An `EXISTS` body reuses the existing pattern-predicate lowering wholesale (`semi_apply_mark` / `anti_semi_apply` row ops), so pandas/cuDF worked immediately; the polars engine gains NATIVE lowerings for the semi-apply family (correlated key sets computed by the polars chain executor's named-flag columns; order-preserving `is_in` joins) plus `rows(binding_ops=...)` for the single-entity row table — previously all honest-NIE. Aliases introduced inside the braces are existentially scoped (`EXISTS { (n)--(m) }` allowed with `m` unbound outside — bare pattern predicates keep the conservative guard), inline property maps work, and the one supported inner `WHERE` form is endpoint inequality — `EXISTS { (n)--(m) WHERE m <> n }`, the drop-self-loop prune-isolated flavor (pandas/cuDF filter the correlated bindings; polars excludes self-loop edges, which is exactly the `m <> n` witness). Both prune flavors are oracle-pinned in the conformance matrix on a self-loop discriminator graph, 4-engine parity-or-NIE. Honest declines with clear errors: `EXISTS` in RETURN/WITH projections, general inner `WHERE`, multi-pattern bodies, full `MATCH..RETURN` subquery bodies, multi-alias correlation on polars.
 - **GFQL polars execution config is Python-settable and live**: `set_cpu_streaming(bool)` and `set_gpu_executor('in-memory'|'streaming')` in `graphistry.compute.gfql.lazy` (plus the public `GPU_EXECUTORS` options and `GpuExecutor` type) set the CPU-streaming / GPU-executor knobs from Python. They resolve **Python override > environment variable > default**, read **live** per collect — previously these were env-only (`GFQL_POLARS_CPU_STREAMING` / `GFQL_POLARS_GPU_EXECUTOR`) and frozen at import, so neither a Python setting nor a post-import env change took effect. `None` resets a setter to env/default.
 - **GFQL engine conversion honors the `validate`/`warn` convention**: `Engine.df_to_engine(df, engine, *, validate=, warn=)` threads the repo-wide `validate` (`'strict'`/`'strict-fast'`/`'autofix'`; `True`→strict, `False`→autofix) + `warn` protocol into the pandas→polars and pandas→cuDF converters. On a mixed-type object column that Arrow/polars/cuDF cannot represent, `strict` raises (`NotImplementedError` for polars, `ArrowConversionError` for cuDF) and `autofix` coerces the column to string and warns — the same convention as `plot()`/`upload()`. Each engine keeps its established default (polars `strict` = parity-or-raise; cuDF `autofix` = its shipped best-effort coercion, now `warn`-suppressible).

docs/source/gfql/cypher.rst

@@ -314,6 +314,18 @@ and ``RETURN`` expressions:
   ``size``, and conversions ``toInteger`` / ``toFloat`` / ``toString`` /
   ``toBoolean`` and ``coalesce``.
 - Regex ``=~`` (see WHERE Forms above).
+- ``searchAny(entity, term[, opts])`` — cross-column search predicate (WHERE
+  position; GFQL extension for the viz filter pipeline): True where ANY of the
+  entity's columns matches ``term``. Inspector semantics: OR across columns,
+  case-insensitive substring by default, regex opt-in; dtype-gated — string
+  columns always, integer columns iff the term is a numeric literal
+  (``/^[0-9.-]+$/``); floats/dates/booleans only via the explicit list. Options
+  map: ``{caseSensitive: true, regex: true, columns: ['name', ...]}`` (unknown
+  keys error, listing the valid ones). Composes with other WHERE predicates
+  through AND/OR/NOT; nodes and edges independently searchable with different
+  terms. Runs natively on all four engines; the regex path obeys the same
+  per-engine decline rules as ``=~``. Python twins:
+  :meth:`ComputeMixin.search_nodes` / :meth:`ComputeMixin.search_edges`.
 
 ``LIKE`` / ``ILIKE`` and ``BETWEEN`` are intentionally not provided — they are
 not part of Cypher or GQL; use ``=~`` / ``CONTAINS`` / ``STARTS WITH`` and

graphistry/compute/gfql/cypher/lowering.py

@@ -24,6 +24,7 @@
     order_by,
     return_,
     rows,
+    search_any,
     semi_apply_mark,
     serialize_binding_ops,
     select,
@@ -3843,6 +3844,103 @@ def _append_page_ops(
         params=params,
     )
 
+_SEARCH_ANY_CALL_RE = re.compile(
+    r"\bsearchAny\s*\(\s*([A-Za-z_]\w*)\s*,\s*"
+    r"('(?:\\.|[^'\\])*'|\"(?:\\.|[^\"\\])*\")"
+    r"\s*(?:,\s*\{([^{}]*)\})?\s*\)",
+    re.IGNORECASE,
+)
+_SEARCH_ANY_OPT_KEYS = {"casesensitive": "case_sensitive", "regex": "regex", "columns": "columns"}
+_SEARCH_ANY_COLUMNS_RE = re.compile(
+    r"^\[\s*(?:'[^']*'|\"[^\"]*\")(?:\s*,\s*(?:'[^']*'|\"[^\"]*\"))*\s*\]$")
+_SEARCH_ANY_COL_ITEM_RE = re.compile(r"'([^']*)'|\"([^\"]*)\"")
+
+
+def _parse_search_any_opts(opts_text: str, *, line: int, column: int) -> Dict[str, Any]:
+    """Parse searchAny's option map literal — strict: unknown keys error listing the
+    valid ones (persona pass: predictable options beat silent typo-tolerance)."""
+    out: Dict[str, Any] = {}
+    if not opts_text.strip():
+        return out
+    depth = 0
+    parts: List[str] = []
+    cur = ""
+    for ch in opts_text:
+        if ch in "[(":
+            depth += 1
+        elif ch in "])":
+            depth -= 1
+        if ch == "," and depth == 0:
+            parts.append(cur)
+            cur = ""
+        else:
+            cur += ch
+    parts.append(cur)
+    for part in parts:
+        m = re.match(r"\s*([A-Za-z_]\w*)\s*:\s*(.+?)\s*$", part)
+        key = m.group(1) if m else part.strip()
+        canon = _SEARCH_ANY_OPT_KEYS.get(key.lower()) if m else None
+        if m is None or canon is None:
+            raise _unsupported(
+                f"searchAny got an unsupported option {key!r}",
+                field="where",
+                value=opts_text,
+                line=line,
+                column=column,
+            )
+        val_text = m.group(2)
+        if canon in ("case_sensitive", "regex"):
+            low = val_text.lower()
+            if low not in ("true", "false"):
+                raise _unsupported(
+                    f"searchAny option {key!r} must be true or false",
+                    field="where", value=val_text, line=line, column=column,
+                )
+            out[canon] = low == "true"
+        else:
+            if not _SEARCH_ANY_COLUMNS_RE.match(val_text):
+                raise _unsupported(
+                    "searchAny option 'columns' must be a list of string literals",
+                    field="where", value=val_text, line=line, column=column,
+                )
+            out[canon] = [a or b for a, b in _SEARCH_ANY_COL_ITEM_RE.findall(val_text)]
+    return out
+
+
+def _lift_search_any_from_row_where(
+    expr: ExpressionText,
+    *,
+    alias_targets: Mapping[str, ASTObject],
+    existing_cols: AbstractSet[str],
+) -> Tuple[str, List[ASTCall]]:
+    """viz-filter L2-b: rewrite each ``searchAny(alias, 'term'[, {opts}])`` in the
+    WHERE row-expression into a fresh boolean MARKER column + a ``search_any`` row
+    pre-filter (exactly the pattern-predicate marker mechanism), so the remaining
+    boolean expression composes through AND/OR/NOT unchanged."""
+    calls: List[ASTCall] = []
+    used: set = set(existing_cols)
+
+    def _sub(m: "re.Match[str]") -> str:
+        alias, term_lit, opts_text = m.group(1), m.group(2), m.group(3) or ""
+        if alias not in alias_targets:
+            raise _unsupported(
+                f"searchAny references alias {alias!r} not bound in the active MATCH scope",
+                field="where", value=alias,
+                line=expr.span.line, column=expr.span.column,
+            )
+        term = term_lit[1:-1].replace("\\'", "'").replace('\\"', '"')
+        opts = _parse_search_any_opts(
+            opts_text, line=expr.span.line, column=expr.span.column)
+        base = f"__gfql_search_any_{expr.span.line}_{expr.span.column}_{len(calls)}__"
+        out_col = _fresh_temp_name(used, base)
+        used.add(out_col)
+        calls.append(search_any(alias=alias, term=term, out_col=out_col, **opts))
+        return out_col
+
+    new_text = _SEARCH_ANY_CALL_RE.sub(_sub, expr.text)
+    return new_text, calls
+
+
 def _append_match_row_where(
     row_steps: List[ASTObject],
     *,
@@ -6113,6 +6211,16 @@ def lower_match_query(
             span=query.where.span if query.where is not None else merged_match.span,
         )
 
+    if row_where is not None:
+        # viz-filter L2-b: lift searchAny(...) calls into search_any pre-filters +
+        # marker columns HERE (assembly level, like the pattern-predicate markers),
+        # so every LoweredCypherMatch consumer sees the lifted form.
+        lifted_text, search_calls = _lift_search_any_from_row_where(
+            row_where, alias_targets=alias_targets, existing_cols=frozenset())
+        if search_calls:
+            row_pre_filters.extend(search_calls)
+            row_where = ExpressionText(text=lifted_text, span=row_where.span)
+
     return LoweredCypherMatch(
         query=ops,
         where=where_out,

graphistry/compute/gfql/lazy/engine/polars/chain.py

@@ -353,9 +353,12 @@ def _try_native_row_op(g_cur, op):
     from graphistry.Engine import Engine
     from .row_pipeline import (
         select_polars, with_columns_polars, order_by_polars, group_by_polars,
-        unwind_polars, where_rows_polars, rows_binding_ops_polars, search_any_polars,
-        semi_apply_mark_polars, anti_semi_apply_polars,
+        unwind_polars, where_rows_polars,
     )
+    from .pattern_apply import (
+        rows_binding_ops_polars, semi_apply_mark_polars, anti_semi_apply_polars,
+    )
+    from .search import search_any_polars
 
     fn = getattr(op, "function", None)
     if _call_native_on_polars(op):

graphistry/tests/compute/gfql/cypher/test_lowering.py

@@ -2022,6 +2022,39 @@ def test_lower_exists_drop_self_flavor_emits_neq_semi_apply() -> None:
     assert sorted(anti.params.get("neq") or []) == ["m", "n"]
 
 
+def test_lower_search_any_where_emits_marker_prefilter() -> None:
+    """viz-filter L2-b: WHERE searchAny(a, 'x'[, {opts}]) lifts to a search_any row
+    pre-filter + a fresh marker column in the residual boolean expression (the
+    pattern-predicate marker mechanism), composing through AND/OR/NOT."""
+    lowered = lower_match_query(_parse_query(
+        "MATCH (a) WHERE searchAny(a, 'foo') AND a.x > 1 RETURN a.id AS id"))
+    pre = [op for op in lowered.row_pre_filters
+           if isinstance(op, ASTCall) and op.function == "search_any"]
+    assert len(pre) == 1
+    assert pre[0].params["alias"] == "a"
+    assert pre[0].params["term"] == "foo"
+    marker = pre[0].params["out_col"]
+    assert marker.startswith("__gfql_search_any_")
+    assert lowered.row_where is not None and marker in lowered.row_where.text
+    assert "searchAny" not in lowered.row_where.text
+
+    lowered2 = lower_match_query(_parse_query(
+        "MATCH (a) WHERE searchAny(a, '7', {caseSensitive: true, regex: false, columns: ['name']}) RETURN a.id AS id"))
+    op2 = [op for op in lowered2.row_pre_filters
+           if isinstance(op, ASTCall) and op.function == "search_any"][0]
+    assert op2.params.get("case_sensitive") is True
+    assert op2.params.get("columns") == ["name"]
+
+    for q, phrase in [
+        ("MATCH (a) WHERE searchAny(a, 'x', {nope: true}) RETURN a", "unsupported option"),
+        ("MATCH (a) WHERE searchAny(zzz, 'x') RETURN a", "not bound"),
+        ("MATCH (a) WHERE searchAny(a, 'x', {caseSensitive: 'yes'}) RETURN a", "true or false"),
+    ]:
+        with pytest.raises(GFQLValidationError) as exc_info:
+            lower_match_query(_parse_query(q))
+        assert phrase in exc_info.value.message, (q, exc_info.value.message)
+
+
 def test_exists_subquery_unsupported_bodies_decline_clearly() -> None:
     """viz-filter L1 v1 boundaries: inner WHERE, multi-pattern bodies, and full
     MATCH..RETURN subquery bodies decline with a clear message (never a wrong answer)."""

graphistry/tests/compute/gfql/test_engine_polars_conformance_matrix.py

@@ -426,6 +426,31 @@ def q(**kw):
         g.gfql(q(term="x", columns=["nope"]), engine="pandas")
 
 
+def test_search_any_cypher_surface_all_engines():
+    """viz-filter L2-b: the cypher WHERE searchAny(...) surface — marker lift +
+    composition with other predicates; oracle-pinned + 4-engine parity-or-NIE."""
+    import pandas as pd
+    nd = pd.DataFrame({
+        "id": [0, 1, 2, 3],
+        "name": ["Alpha", "beta", None, "gamma7"],
+        "num": pd.Series([7, 77, 3, 4], dtype="int64"),
+    })
+    ed = pd.DataFrame({"s": [0, 1], "d": [1, 2], "eid": [0, 1]})
+    g = graphistry.nodes(nd, "id").edges(ed, "s", "d").bind(edge="eid")
+    oracle = {
+        "MATCH (a) WHERE searchAny(a, 'ALPHA') RETURN a.id AS id": [0],
+        "MATCH (a) WHERE searchAny(a, '7') RETURN a.id AS id": [0, 1, 3],
+        "MATCH (a) WHERE searchAny(a, '7', {columns: ['name']}) RETURN a.id AS id": [3],
+        "MATCH (a) WHERE searchAny(a, 'a.pha', {regex: true}) RETURN a.id AS id": [0],
+        "MATCH (a) WHERE searchAny(a, 'a') AND a.num > 10 RETURN a.id AS id": [1],
+        "MATCH (a) WHERE NOT searchAny(a, 'a') RETURN a.id AS id": [2],
+    }
+    for q, expected in oracle.items():
+        pdf = _to_pd(g.gfql(q, engine="pandas")._nodes)
+        assert sorted(pdf["id"].tolist()) == expected, f"oracle drift: {q}"
+        _assert_invariant(g, q, f"searchAny-cypher {q}")
+
+
 def test_search_nodes_edges_twins():
     """g.search_nodes/search_edges (persona-pass python twins): same kernel, own table
     only, Plottable out; polars frames decline honestly."""