[BUG] BFS max_depth Parameter Ignored in Search Queries

[paveljakov]

Summary

The bfs_max_depth parameter in BFS search configurations is completely ignored, causing BFS searches to always traverse 1-3 hops regardless of the specified depth limit.

What I was trying to do

I was attempting to perform a breadth-first search with bfs_max_depth=1 to find only direct neighbors (1-hop relationships) of a center node.

What I expected to happen

When setting bfs_max_depth=1, the BFS search should only return nodes and edges that are exactly 1 hop away from the center node.

What actually happened

The BFS search returned nodes and edges up to 3 hops away from the center node, completely ignoring the bfs_max_depth=1 setting.

Root Cause

The Cypher queries in both node_bfs_search and edge_bfs_search functions have hardcoded path lengths of {1,3} instead of using the bfs_max_depth parameter.

Code Analysis

In graphiti_core/search/search_utils.py:

Node BFS Query (line ~450):

MATCH (origin:Entity|Episodic {uuid: origin_uuid})-[:RELATES_TO|MENTIONS]->{1,3}(n:Entity)

Edge BFS Query (line ~295):

MATCH path = (origin:Entity|Episodic {uuid: origin_uuid})-[:RELATES_TO|MENTIONS]->{1,3}(n:Entity)

Problem: Both queries use hardcoded {1,3} instead of using the bfs_max_depth parameter.

Parameter is passed but unused:

records, _, _ = await driver.execute_query(
    query,
    params=filter_params,
    bfs_origin_node_uuids=bfs_origin_node_uuids,
    depth=bfs_max_depth,  # ← This parameter is passed but never used in the query
    group_ids=group_ids,
    limit=limit,
    routing_='r',
)

Code Sample Demonstrating the Issue

from graphiti_core.search.search_config import (
    SearchConfig, 
    NodeSearchConfig, 
    NodeSearchMethod,
    NodeReranker
)

# Configuration specifying max depth of 1
config = SearchConfig(
    node_config=NodeSearchConfig(
        search_methods=[NodeSearchMethod.bfs],
        reranker=NodeReranker.rrf,
        bfs_max_depth=1  # Should only search 1 hop
    )
)

# This search will return nodes up to 3 hops away, not 1
results = await graphiti.search(
    query="test",
    config=config,
    center_node_uuid="some-center-node-uuid",
    group_ids=["test-group"]
)

# Expected: Only direct neighbors (1 hop)
# Actual: Neighbors up to 3 hops away

Expected Fix

The Cypher queries should use the bfs_max_depth parameter:

Node BFS Query:

MATCH (origin:Entity|Episodic {uuid: origin_uuid})-[:RELATES_TO|MENTIONS]->{1,$depth}(n:Entity)

Edge BFS Query:

MATCH path = (origin:Entity|Episodic {uuid: origin_uuid})-[:RELATES_TO|MENTIONS]->{1,$depth}(n:Entity)

Additional Context

This bug affects:

• node_bfs_search() in graphiti_core/search/search_utils.py (line ~429)
• edge_bfs_search() in graphiti_core/search/search_utils.py (line ~278)

The impact is that users cannot control the depth of BFS traversal, leading to:

1. Performance issues when expecting shallow searches
2. Incorrect results when precise depth control is needed
3. Confusion about why the bfs_max_depth parameter appears to do nothing

Environment

• Graphiti Version: Latest main branch
• Database: Neo4j (also affects FalkorDB)
• Python Version: 3.10+

Severity

Medium - Feature completely non-functional, but workarounds exist (custom queries)

Labels

• bug
• search
• bfs
• help wanted

[onestardao]

This looks like a parameter propagation failure in the BFS execution chain, which aligns with ProblemMap No.4 in our diagnostic set (semantic parameter loss between planner and executor).

Root cause: max_depth is parsed at the configuration level but never injected into the query generator. In your code snippet, both BFS node and edge queries are hardcoded to depth 3, bypassing the passed-in max_depth value.

Why it’s deceptive: it passes initial tests if the hardcoded depth happens to match the intended setting, but silently ignores custom parameters in production.

Suggested fix path:

Replace hardcoded depth values in BFS query templates with a bound variable from the search config.

Add a regression test that asserts max_depth changes are reflected in the generated Cypher queries for both nodes and edges.

Consider logging a warning when max_depth in config does not match the depth in query templates.

If you’d like, I can share the full ProblemMap No.4 entry — it includes a symbolic patch approach that we’ve used to resolve this exact parameter-loss pattern across multiple BFS implementations.

[claude[bot]]

@paveljakov Is this still an issue? Please confirm within 14 days or this issue will be closed.

[claude[bot]]

@paveljakov Is this still an issue? Please confirm within 14 days or this issue will be closed.

[claude[bot]]

@paveljakov Is this still an issue? Please confirm within 14 days or this issue will be closed.