perf(gfql/cypher): single-alias predicate pushdown in the row pipeline (L4)

[lmeyerov]

What

A disjunctive / searchAny WHERE collapses the whole MATCH onto the row pipeline, which materializes the full (a)-[e]->(b) binding table (O(E) joins) before filtering. This adds a lowering pass that attaches conjuncts referencing exactly one alias (and standalone searchAny ops) to rows(alias_prefilters={alias:[spec]}) as an advisory hint; the binding builder pre-filters each alias frame before the join.

Redundant-filter safety (why it's correct on every engine)

The hint is additive — the post-join where_rows / search_any ops are left in place:

• Engines whose row builder honors the hint (pandas / cuDF via RowPipelineMixin) pre-filter each alias frame before the binding join and win.
• Engines that ignore it (polars' native rows_binding_ops_polars, the shortestPath scalar builder) run the unchanged post-filter and stay correct.

A pushed conjunct is a literal sub-conjunct of the retained AND, so the pre-filter can only remove rows the post-filter also removes — never a result change, on any engine (present or future). Application reuses the SAME evaluator (_gfql_eval_string_expr + _gfql_bool_mask) and the SAME search_any_mask kernel, so semantics (incl. 3-valued NULL) are byte-identical.

Guards (skip pushing a conjunct/op)

OPTIONAL / reentry / row-guard / procedure / seed-row / multi-graph programs; shortestPath scalar bindings; multihop edge aliases; and any conjunct naming an internal __gfql_/__cypher_ column (EXISTS / searchAny markers + reentry carries read falsely single-alias).

Results (pandas, seed=7; base = pass-disabled)

scenario	@100k	@1m
search_edges	2.9×	4.62× (7.1s→1.5s)
panel_filters	1.32×	1.47× (24.9s→17.0s)
combined	1.97×	—
search_nodes	1.1×	—
exists_prune	no-op (EXISTS not pushable)	—

Byte-identical result multisets. search_edges keeps its full win (post-filter search on the small post-join table is cheap); panel_filters gives back part of the win because the retained where_rows re-evaluates string predicates on the post-join table (a documented follow-on reclaims it via an executor handshake).

Scope

polars/polars-gpu already NIE the multi-node rows op for these disjunctive-WHERE row queries (pre-existing), so this accelerates the pandas + cuDF row-pipeline lanes; polars correctness is preserved by the retained post-filter.

Tests

• New test_row_pushdown.py: 17 tests — parity pre/post pass (pandas + cuDF via TEST_CUDF) on edge/node search, panel, undirected, combined; guard no-push on EXISTS-marker / multi-alias / shortestPath; pass internals.
• cuDF lane validated on dgx (RAPIDS 26.02): 17/17 passed.
• Full cypher+row+conformance suite: 1942 passed; the 4 conformance reds (regex_unicode_trick[ceil/floor/round-filter], categorical_searchany) are pre-existing — verified failing on the clean base commit and with the pass disabled.

🤖 Generated with Claude Code