fix(search): consume bfs relationship hits directly in edge_bfs_search

[kramerica-inc-dev]

fix(search): consume bfs relationship hits directly in edge_bfs_search

Summary

Completes #1500 on the path that executes today. #1500 rewrites the edge fulltext and BFS queries to consume the relationships the index/path already returned (startNode/endNode) instead of re-matching every hit by uuid against the whole graph — but its BFS hunk only lands in graphiti_core/driver/falkordb/operations/search_ops.py. That module is not reached at runtime: driver.search_interface is declared (graphiti_core/driver/driver.py) and never assigned anywhere in graphiti_core, so edge_bfs_search always falls through to the generic query in graphiti_core/search/search_utils.py. This PR applies the exact same transform there:

             UNWIND relationships(path) AS rel
-            MATCH (n:Entity)-[e:RELATES_TO {uuid: rel.uuid}]-(m:Entity)
+            WITH rel AS e, startNode(rel) AS n, endNode(rel) AS m
+            WHERE type(e) = 'RELATES_TO'
+            WITH e, n, m

Notes on the transform:

• MENTIONS filter kept explicit. The BFS pattern traverses RELATES_TO|MENTIONS, so rel can be a MENTIONS edge; the old re-MATCH filtered those out implicitly via the e:RELATES_TO label. The WHERE type(e) = 'RELATES_TO' guard preserves that (same as fix: avoid O(matches×graph) re-MATCH in edge search #1500's BFS hunk). The trailing WITH e, n, m keeps the appended filter clause (WHERE …) valid and the e/n/m bindings, filter constructor, and RETURN untouched.
• Direction/duplicates. The old undirected re-MATCH matched each edge twice (once per orientation), and RETURN DISTINCT could not collapse the swapped source/target rows. startNode/endNode yields one row per relationship in its original orientation, so this also removes the duplicated/swapped-edge symptom reported in [BUG] BFS Returns Duplicate Edges with Swapped Source/Target Nodes #789 and targeted by PR fix: use directed match in edge_bfs_search to prevent duplicate edges #1436 — on this path. [BUG] BFS Returns Duplicate Edges with Swapped Source/Target Nodes #789 additionally flags the same undirected pattern in get_embeddings_for_edges, which is out of scope here, so this PR does not claim to close it.
• Scope. Only the generic (non-Kuzu, non-Neptune) BFS branch is changed. Kuzu builds its own query earlier in the function and Neptune has its own branch; both are untouched, as is the fulltext query in this file (that hunk belongs to fix: avoid O(matches×graph) re-MATCH in edge search #1500). startNode()/endNode() are native on both engines that share this branch — Neo4j and FalkorDB (the Neptune branch in this same function already uses them in its RETURN).

Type of Change

• Bug fix
• New feature
• Performance improvement
• Documentation/Tests

Objective

The re-MATCH forces an O(matches × graph) label scan per BFS hit instead of consuming the relationship the path traversal already produced. On our production FalkorDB graph (~2.6k Entity nodes), removing this same antipattern on the fulltext path took dense-document episode processing from 15–25 min down to 1–4 min; GRAPH.PROFILE of the rewritten query resolves 572 hits in <2 ms with no scan operator (measured 2026-07-14). The BFS variant fixed here is the same shape, made worse by the undirected match doubling every row.

Testing

• Unit tests added/updated
• Integration tests added/updated
• All existing tests pass

Added tests/utils/search/test_edge_bfs_query_shape.py, a DB-free query-shape regression test mirroring the RecordingExecutor approach of #1500's tests/test_falkordb_search_ops.py: a recording driver captures the emitted Cypher. Asserts: no uuid: rel.uuid re-MATCH in the BFS query; startNode/endNode consumption present; explicit type(e) = 'RELATES_TO' guard present; e/n/m bindings still reach filters and RETURN; and the fulltext query is not rewritten by this change (formulated so it stays green after #1500 merges).

DISABLE_FALKORDB=1 DISABLE_KUZU=1 DISABLE_NEPTUNE=1 python -m pytest \
  tests/utils/search/test_edge_bfs_query_shape.py \
  tests/utils/search/test_search_security.py -q -m "not integration"
12 passed, 1 warning in 0.09s

Breaking Changes

• This PR contains breaking changes

No. Query results are identical except that the duplicated/swapped-orientation rows produced by the old undirected re-MATCH are gone; each edge is now returned once, in its stored direction.

Checklist

• Code follows project style guidelines (make lint passes — ruff format --check + ruff check clean on changed files)
• Self-review completed
• Documentation updated where necessary (n/a)
• No secrets or sensitive information committed

Related Issues

Refs #1272, #1500 (completes it on the live generic path). Related to #789 and PR #1436 (resolves the duplicate/swapped-edge symptom for edge_bfs_search; get_embeddings_for_edges from #789 remains).

[zep-cla-assistant]

Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution. For privacy information, see our Privacy Notice. You can sign the CLA by just posting a Pull Request Comment same as the below format.

---

I have read the CLA Document and I hereby sign the CLA behalf on myself, e-mail: example@example.com

or

I have read the CLA Document and I hereby sign the CLA behalf of my company, e-mail: example@example.com

Signature is valid for 6 months.

---

_{This bot will be retriggered when the Contributor License Agreement comment has been provided. Posted by the CLA Assistant Lite bot.}

[Naseem77]

@kramerica-inc-dev Verified live on FalkorDB: identical BFS results, MENTIONS edges still filtered by the type guard, and the O(matches x graph) re-MATCH is gone from the emitted query. This completes #1500 on the path that actually runs.