[Bug]: FalkorDB PropertyGraphStore not creating MENTIONS relationships between Chunk and Entity nodes

[douglasrfaisal-gl]

Bug Description

When using PropertyGraphIndex with FalkorDBPropertyGraphStore, the MENTIONS relationships are not being created between Chunk nodes and Entity nodes during indexing, even though entity extraction works correctly.

Expected Behavior:

• Chunk nodes should have MENTIONS relationships pointing to all Entity nodes extracted from that chunk
• Pattern: (Chunk)-[:MENTIONS]->(Entity)

Actual Behavior:

• Chunk nodes and Entity nodes are created successfully
• Entity nodes have triplet_source_id property set correctly
• No MENTIONS relationships are created
• Query MATCH (c:Chunk)-[r:MENTIONS]->(e) RETURN * returns 0 results

Root Cause:

The issue is in the upsert_nodes method of FalkorDBPropertyGraphStore (lines 240-242). The Cypher query attempts to access nested properties ($data.properties.triplet_source_id) after a CALL {} block, but FalkorDB doesn't properly handle this nested parameter access in this context. The WHERE clause fails silently, preventing the MERGE statements from executing.

Version

0.14.10

Steps to Reproduce

1. Setup FalkorDB

docker run -p 3000:3000 -p 6379:6379 -v $PWD/data:/data falkordb/falkordb:latest

2. Install Dependencies

pip install llama-index-core llama-index-graph-stores-falkordb llama-index-llms-openai llama-index-embeddings-openai

3. Run Reproduction Script

"""Minimal reproduction of FalkorDB MENTIONS relationship bug."""

import uuid
from llama_index.core import Settings
from llama_index.core.indices.property_graph import PropertyGraphIndex
from llama_index.core.indices.property_graph.transformations import (
    DynamicLLMPathExtractor,
    ImplicitPathExtractor,
)
from llama_index.core.schema import TextNode
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding
from llama_index.graph_stores.falkordb import FalkorDBPropertyGraphStore


# Initialize LLM and embedding models
llm = OpenAI(model="gpt-4o-mini", temperature=0.0)
embed_model = OpenAIEmbedding(model="text-embedding-3-small")

Settings.llm = llm
Settings.embed_model = embed_model

# Initialize FalkorDB property graph store
graph_store = FalkorDBPropertyGraphStore(
    url="redis://localhost:6379",
    database="test_mentions_bug",
)

# Create PropertyGraphIndex
index = PropertyGraphIndex.from_existing(
    llm=llm,
    embed_model=embed_model,
    kg_extractors=[
        ImplicitPathExtractor(),
        DynamicLLMPathExtractor(llm=llm, max_triplets_per_chunk=10),
    ],
    embed_kg_nodes=False,
    property_graph_store=graph_store,
)

# Create and index a simple text node
node = TextNode(
    id_=str(uuid.uuid4()),
    text="Python was created by Guido van Rossum in 1991.",
    metadata={"document_id": "doc_001"},
)

print("Indexing node...")
index.insert_nodes([node])
print("✓ Indexing complete")

# Check for MENTIONS relationships
print("\n=== Checking for MENTIONS relationships ===")
results = graph_store.structured_query(
    "MATCH (c:Chunk)-[r:MENTIONS]->(e:__Entity__) "
    "RETURN c.id AS chunk_id, e.name AS entity_name"
)

print(f"Found {len(results)} MENTIONS relationships")
if len(results) == 0:
    print("❌ BUG CONFIRMED: No MENTIONS relationships created!")
    
    # Verify entities were created
    entities = graph_store.structured_query(
        "MATCH (e:__Entity__) RETURN e.name AS name, "
        "properties(e).triplet_source_id AS triplet_source_id"
    )
    print(f"\nEntities created: {len(entities)}")
    for e in entities:
        print(f"  - {e['name']} (triplet_source_id: {e['triplet_source_id']})")
    
    # Verify chunks were created
    chunks = graph_store.structured_query("MATCH (c:Chunk) RETURN c.id AS id")
    print(f"\nChunks created: {len(chunks)}")
    for c in chunks:
        print(f"  - {c['id']}")
else:
    print("✓ MENTIONS relationships found:")
    for r in results:
        print(f"  - Chunk {r['chunk_id'][:20]}... MENTIONS {r['entity_name']}")

# Cleanup
graph_store.structured_query("MATCH (n) DETACH DELETE n")

4. Observe the Bug

Expected Output:

Found 3 MENTIONS relationships
  - Chunk abc123... MENTIONS Python
  - Chunk abc123... MENTIONS Guido van Rossum
  - Chunk abc123... MENTIONS 1991

Actual Output:

Found 0 MENTIONS relationships
❌ BUG CONFIRMED: No MENTIONS relationships created!

Entities created: 3
  - Python (triplet_source_id: abc123-def456-...)
  - Guido van Rossum (triplet_source_id: abc123-def456-...)
  - 1991 (triplet_source_id: abc123-def456-...)

Chunks created: 1
  - abc123-def456-...

Relevant Logs/Tracbacks

[douglasrfaisal-gl]

Proposed Fix:

if entity_dicts:
    for entity_dict in entity_dicts:
        self.structured_query(
            f"""
            MERGE (e:`__Entity__` {{id: $data.id}})
            SET e += $data.properties
            SET e.name = $data.name
            WITH e, $data.properties.triplet_source_id AS tsid, $data.embedding AS embedding
            SET e:{entity_dict["label"]}
            WITH e, tsid, embedding
            CALL {{
                WITH e, embedding
                WITH e, embedding
                WHERE embedding IS NOT NULL
                SET e.embedding = vecf32(embedding)
                RETURN count(*) AS count
            }}
            WITH e, tsid
            WHERE tsid IS NOT NULL
            MERGE (c:Chunk {{id: tsid}})
            MERGE (e)<-[:MENTIONS]-(c)
            """,
            param_map={"data": entity_dict},
        )

[dosubot]

Your proposed Cypher fix is correct for FalkorDB: extracting triplet_source_id as tsid before the CALL {} block ensures the variable is available for the subsequent MERGE statements, which resolves the silent failure in relationship creation. This approach matches Cypher scoping rules and is a known workaround for FalkorDB's limitations with nested parameter access after subqueries.

One thing to note: the current FalkorDB test suite only verifies MENTIONS relationships when created explicitly via upsert_relations, not automatically via upsert_nodes when an entity has a triplet_source_id. To fully validate your fix, you should add a test that upserts a chunk and entities (with triplet_source_id), then asserts that the MENTIONS relationships are created as expected—similar to the pattern used in the Nebula property graph store tests source.

No side effects or regressions are expected from this change, as it only alters variable scoping in the query and does not affect other logic. This fix will make FalkorDB's behavior consistent with other supported graph stores.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}