Merge pull request #1838 from graphistry/fix/gfql-index-engine-mismatch-diagnostic

fix(gfql): explain engine-mismatched index scans

Author: lmeyerov

graphistry/compute/gfql/index/api.py

@@ -81,6 +81,38 @@ def _trace_active() -> bool:
     return _get_trace_steps() is not None
 
 
+def _engine_mismatch_reason(
+    registry: GfqlIndexRegistry, direction: HopDirection, engine: Engine
+) -> Optional[str]:
+    """Describe a trace-only adjacency-index engine mismatch, if present.
+
+    Indexes intentionally remain engine-specific: falling back to the scan is the
+    correct execution behavior. This helper makes that otherwise silent decline
+    visible to ``gfql_explain`` without changing planner policy.
+    """
+    needed: Sequence[AdjacencyIndexKind]
+    if direction == "forward":
+        needed = (EDGE_OUT_ADJ,)
+    elif direction == "reverse":
+        needed = (EDGE_IN_ADJ,)
+    else:
+        needed = (EDGE_OUT_ADJ, EDGE_IN_ADJ)
+    mismatches = [
+        (kind, idx)
+        for kind in needed
+        for idx in (registry.get(kind),)
+        if isinstance(idx, AdjacencyIndex) and idx.engine != engine
+    ]
+    if not mismatches:
+        return None
+    kinds = ", ".join(kind for kind, _ in mismatches)
+    engines = ", ".join(sorted({idx.engine.value for _, idx in mismatches}))
+    return (
+        f"resident {kinds} index engine={engines}, requested engine={engine.value} "
+        "-> scan"
+    )
+
+
 def _record_indexed_traversal(
     *,
     seam: str,
@@ -598,7 +630,7 @@ def _bail(reason: str) -> Optional[Plottable]:
             "path": "index" if result is not None else "scan",
             "decision_reason": (
                 "frontier below cost gate -> index" if result is not None
-                else "index path not applicable -> scan"
+                else _engine_mismatch_reason(registry, direction, engine) or "index path not applicable -> scan"
             ),
         }))
     return result

graphistry/tests/compute/gfql/index/test_index.py

@@ -11,7 +11,8 @@
 import pytest
 
 import graphistry
-from graphistry.compute.ast import n, e_forward
+from graphistry.compute.ast import n, e_forward, e_reverse
+from graphistry.compute.gfql.index.api import _engine_mismatch_reason
 from graphistry.compute.gfql.index import (
     CreateIndex, DropIndex, ShowIndexes, index_op_from_json, parse_index_ddl,
     get_registry,
@@ -1180,3 +1181,63 @@ def spy(series, rows, eng):
     monkeypatch.setenv("GFQL_INDEX_CANDIDATE_EDGE_MASK", "0")
     gi.hop(nodes=seeds, **kwargs)
     assert not seen, "OFF side still gathered candidate rows — the switch does nothing"
+
+
+@pytest.mark.parametrize(
+    "index_kinds, edge, expected_kinds",
+    [
+        (("edge_out_adj",), e_forward, "edge_out_adj"),
+        (("edge_in_adj",), e_reverse, "edge_in_adj"),
+    ],
+)
+@pytest.mark.parametrize(
+    "resident_engine, requested_engine",
+    [("pandas", "polars"), ("polars", "pandas")],
+)
+def test_explain_reports_bidirectional_engine_mismatch(
+    graph, index_kinds, edge, expected_kinds, resident_engine, requested_engine
+):
+    """#1767: a valid foreign-engine index must explain its scan, not fail silently."""
+    pytest.importorskip("polars")
+    gi = graph
+    for index_kind in index_kinds:
+        gi = gi.create_index(index_kind, engine=resident_engine)
+    shown = gi.show_indexes()
+    assert all(bool(valid) for valid in shown["valid"].tolist())
+
+    report = gi.gfql_explain(
+        [n({"id": 0}), edge(hops=1)],
+        index_policy="use",
+        engine=requested_engine,
+    )
+
+    assert report["used_index"] is False, report
+    assert report["decision_reason"] == (
+        f"resident {expected_kinds} index "
+        f"engine={resident_engine}, requested engine={requested_engine} -> scan"
+    ), report
+
+
+@pytest.mark.parametrize(
+    "resident_engine, requested_engine",
+    [("pandas", "polars"), ("polars", "pandas")],
+)
+def test_engine_mismatch_reason_reports_all_undirected_indexes(
+    graph, resident_engine, requested_engine
+):
+    """The undirected diagnostic reports every valid resident foreign-engine index."""
+    from graphistry.Engine import Engine
+
+    pytest.importorskip("polars")
+    gi = graph
+    for index_kind in ("edge_out_adj", "edge_in_adj"):
+        gi = gi.create_index(index_kind, engine=resident_engine)
+    shown = gi.show_indexes()
+    assert all(bool(valid) for valid in shown["valid"].tolist())
+
+    reason = _engine_mismatch_reason(get_registry(gi), "undirected", Engine(requested_engine))
+
+    assert reason == (
+        "resident edge_out_adj, edge_in_adj index "
+        f"engine={resident_engine}, requested engine={requested_engine} -> scan"
+    ), reason