Merge pull request #2045 from graphistry/fix/gfql-2020-alias-prefilter-alignment

fix(gfql): apply single-alias predicate pushdown masks by position (#2020)

Author: lmeyerov

CHANGELOG.md

@@ -19,6 +19,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 ### Fixed
 
 - **cuDF 26.2 compatibility: `cudf.from_pandas` replaces the removed `cudf.DataFrame.from_pandas` at the five cuDF-only product sites (`ai_utils`, `umap_utils`, `feature_utils`) and in the test fixtures (#2043)**; the three cuDF chain differential cases that disagree with the full path on cuDF 26.2 are marked expected-failure on that line with the tracking issue, so the GPU lane reports them instead of crashing before them.
+- **GFQL pandas/cuDF: several single-alias `IN` (and other pushed-down) predicates across a hop no longer raise `Unalignable boolean Series` (#2020)**: the predicate pushdown filtered an alias frame by label after an earlier pushdown had already narrowed it, while the mask it evaluated carried a fresh positional index. Rows are now kept by position, which is the contract of a mask computed on the same rows; results equal the polars engine and the scalar `=` form.
 * GFQL: two basic Cypher shapes fell off the seeded fast paths on every engine. A seeded typed hop whose RETURN projects properties of more than the destination alias (`MATCH (m {id})-[r:T]->(p) RETURN m.id, r.since, p.name`) went through the row pipeline's connected-bindings frame builder; the seeded fast path now projects any number of properties from any alias of the hop (seed node, edge, destination node) from the rows it already holds, one row per matched edge, and still declines anything beyond one hop or an absent property to the full path. A seeded single-node pattern (`MATCH (p {id}) RETURN p` / `RETURN p.a, p.b`) ran the full two-pass chain over the node table with no index consulted; a new `seeded_node_lookup` fast path resolves the seed through the resident node-id index, a resident node-property index, or one scalar scan and projects the matched rows directly. Seed resolution is shared with the seeded typed hop, so a seed predicate on an indexed property that is not the node binding now uses the property index there too. On the SNB SF0.1 fixture the IS1 text went from 19 ms to 4 ms and the node-only lookup from 14 ms to 1 ms on pandas; both shapes report `fast_path served` in `gfql_explain` on pandas, polars and cuDF.
 * GFQL: native Polars single-node lookups resolve seeds through resident node-property indexes, and a directed scalar one-hop chain whose resident node-id and adjacency indexes cover it (typed edges, destination filters, named patterns) is served by the seeded reduction used by Cypher, with full-path table order and alias flags preserved and the engagement visible in `gfql_explain` (#2033).
 * GFQL: native op-list chains (`g.gfql([n(...), e_forward(...), n(...)])`) resolve a seed predicate through the resident node-id or node-property index and serve named patterns on the chain fast path; before, a named single-node op always ran the full two-pass chain, a named seeded hop declined the fast path whenever the traversal indexes were resident (deferring to an indexed kernel that had already declined), and a seed on a property other than the node binding was a full node-table scan (#2027). The alias flag columns now sit where the full path places them.

bin/test-polars.sh

@@ -115,6 +115,7 @@ POLARS_TEST_FILES=(
     graphistry/tests/compute/gfql/cypher/test_grouped_aggregate_cross_alias.py
     # module-level `importorskip("polars")` files that previously ran in no lane at all
     graphistry/tests/compute/gfql/test_engine_polars_narrow_combine.py
+    graphistry/tests/compute/gfql/row/test_alias_prefilter_alignment_2020.py
     graphistry/tests/compute/gfql/test_engine_polars_semi_key_dedup.py
     graphistry/tests/compute/gfql/test_engine_polars_call_modality.py
     graphistry/tests/compute/gfql/test_engine_polars_gpu.py

graphistry/compute/gfql/row/pipeline.py

@@ -236,6 +236,13 @@ def is_row_pipeline_call(function: str) -> bool:
     return function in ROW_PIPELINE_CALLS
 
 
+
+def _rows_where(frame: DataFrameT, mask: SeriesT) -> DataFrameT:
+    """Keep the rows where ``mask`` is True, by position: a mask evaluated on a renamed
+    view of ``frame`` may carry a fresh RangeIndex while ``frame`` keeps the labels of an
+    earlier filter, so label alignment (``.loc``) is not the contract here."""
+    return frame[mask.values]
+
 class RowPipelineMixin:
     # Mirrors the GFQL execution-context fields declared on Plottable: this mixin
     # is also used by `_RowPipelineAdapter`, which is not a PlotterBase, so the
@@ -3929,7 +3936,7 @@ def _gfql_apply_alias_prefilter(
                 view = frame.rename(columns={c: f"{alias}.{c}" for c in frame.columns})
                 value = self._gfql_eval_string_expr(view, spec["text"])
                 mask = self._gfql_bool_mask(view, value)
-                frame = frame.loc[mask]
+                frame = _rows_where(frame, mask)
             elif kind == "search_any":
                 from graphistry.compute.gfql.search_any import search_any_mask
                 term = spec.get("term")
@@ -3974,7 +3981,7 @@ def _gfql_apply_alias_prefilter(
                         value=spec.get("columns"),
                         language="cypher",
                     )
-                frame = frame.loc[mask]
+                frame = _rows_where(frame, mask)
         return frame
 
     def _gfql_connected_bindings_state(

graphistry/tests/compute/gfql/row/test_alias_prefilter_alignment_2020.py

@@ -0,0 +1,52 @@
+"""Single-alias predicate pushdown keeps working after an earlier pushdown narrowed the frame (#2020)."""
+import pandas as pd
+import pytest
+
+import graphistry
+
+Q = ("MATCH (a)-[e]->(t) WHERE a.type IN ['person','company'] AND e.e_type IN ['sent','transfer'] "
+     "AND t.type IN ['transaction','account'] RETURN t.id AS id")
+
+
+def _graph(engine):
+    nodes = pd.DataFrame({"id": ["a", "b", "c", "tx1", "tx2"],
+                          "type": ["person", "person", "company", "transaction", "transaction"]})
+    edges = pd.DataFrame({"src": ["a", "b", "a", "tx1", "tx2"], "dst": ["b", "c", "tx1", "tx2", "c"],
+                          "e_type": ["knows", "works_at", "sent", "transfer", "received"]})
+    if engine == "polars":
+        pl = pytest.importorskip("polars")
+        nodes, edges = pl.from_pandas(nodes), pl.from_pandas(edges)
+    elif engine == "cudf":
+        cudf = pytest.importorskip("cudf")
+        nodes, edges = cudf.from_pandas(nodes), cudf.from_pandas(edges)
+    return graphistry.edges(edges, "src", "dst").nodes(nodes, "id")
+
+
+def _ids(res):
+    nodes = res._nodes
+    df = nodes.to_pandas() if hasattr(nodes, "to_pandas") else pd.DataFrame(nodes)
+    return sorted(df["id"].tolist())
+
+
+@pytest.mark.parametrize("engine", ["pandas", "polars", "cudf"])
+def test_three_in_predicates_across_a_hop_agree_on_every_engine(engine):
+    assert _ids(_graph(engine).gfql(Q, engine=engine)) == ["tx1"]
+
+
+@pytest.mark.parametrize("engine", ["pandas", "cudf"])
+def test_pushdown_on_a_frame_with_filtered_labels_matches_the_scalar_form(engine):
+    g = _graph(engine)
+    scalar = Q.replace("t.type IN ['transaction','account']", "t.type = 'transaction'")
+    assert _ids(g.gfql(Q, engine=engine)) == _ids(g.gfql(scalar, engine=engine)) == ["tx1"]
+
+
+@pytest.mark.parametrize("engine", ["pandas", "cudf"])
+def test_pushdown_on_a_non_range_indexed_node_frame(engine):
+    g = _graph("pandas")
+    nodes = g._nodes.iloc[[4, 2, 0, 3, 1]]  # labels out of order, no RangeIndex
+    if engine == "cudf":
+        cudf = pytest.importorskip("cudf")
+        nodes = cudf.from_pandas(nodes)
+        g = _graph("cudf")
+    g = g.nodes(nodes)
+    assert _ids(g.gfql(Q, engine=engine)) == ["tx1"]