[BUG] add_triplet() does not save edges with FalkorDB provider

[javflocor]

Bug Summary

When using graphiti.add_triplet() with FalkorDB, edges ARE created successfully but the source_node_uuid and target_node_uuid properties on the relationship are stored as None instead of the actual node UUIDs.

Impact

• Severity: High
• Affected Provider: FalkorDB only (Neo4j works correctly)
• Version: graphiti-core 0.21.0

Consequences:

• Edge deduplication may fail (can't match edges by source/target UUIDs)
• Edge filtering by UUID doesn't work correctly
• Data integrity issues when validating edge relationships
• Inconsistent behavior compared to Neo4j provider

Root Cause

File: graphiti_core/models/edges/edge_db_queries.py
Function: get_entity_edge_save_bulk_query()
Lines: 129-133

Issue 1: MATCH vs MERGE (Fixed with this proposal for PR)

The original query used MATCH to find source and target nodes, which would fail if nodes didn't exist. This needs to be changed to MERGE (lines 129-130) to ensure nodes are created if they don't exist.

Change: MATCH → MERGE for both source and target node lookups

Issue 2: Missing UUID Fields in SET Statement (Fixed with this proposal for PR)

The FalkorDB Cypher query explicitly lists properties in the SET statement but omits source_node_uuid and target_node_uuid:

case GraphProvider.FALKORDB:
    return """
        UNWIND $entity_edges AS edge
        MERGE (source:Entity {uuid: edge.source_node_uuid})
        MERGE (target:Entity {uuid: edge.target_node_uuid})
        MERGE (source)-[r:RELATES_TO {uuid: edge.uuid}]->(target)
        SET r = {
            uuid: edge.uuid,
            name: edge.name,
            group_id: edge.group_id,
            fact: edge.fact,
            episodes: edge.episodes,
            created_at: edge.created_at,
            expired_at: edge.expired_at,
            valid_at: edge.valid_at,
            invalid_at: edge.invalid_at,
            fact_embedding: vecf32(edge.fact_embedding)
        }
        WITH r, edge
        RETURN edge.uuid AS uuid
    """

Why This is FalkorDB-Specific

Neo4j uses SET e = edge which copies all properties from the edge dictionary:

case _:  # Neo4j
    return """
        UNWIND $entity_edges AS edge
        MATCH (source:Entity {uuid: edge.source_node_uuid})
        MATCH (target:Entity {uuid: edge.target_node_uuid})
        MERGE (source)-[e:RELATES_TO {uuid: edge.uuid}]->(target)
        SET e = edge    # ← Copies ALL properties
        RETURN edge.uuid AS uuid
    """

FalkorDB requires explicit property listing, and the source_node_uuid and target_node_uuid fields were accidentally omitted.

Proposed Fix

Two changes needed in the FalkorDB case:

1. Change MATCH to MERGE (lines 129-130) - Ensures nodes exist before creating relationships
2. Add missing UUID fields (line 132) - Stores source and target UUIDs in edge properties

Complete fixed query:

case GraphProvider.FALKORDB:
    return """
        UNWIND $entity_edges AS edge
        MERGE (source:Entity {uuid: edge.source_node_uuid})
        MERGE (target:Entity {uuid: edge.target_node_uuid})
        MERGE (source)-[r:RELATES_TO {uuid: edge.uuid}]->(target)
        SET r = {
            uuid: edge.uuid,
            source_node_uuid: edge.source_node_uuid,    # ADD THIS
            target_node_uuid: edge.target_node_uuid,    # ADD THIS
            name: edge.name,
            group_id: edge.group_id,
            fact: edge.fact,
            episodes: edge.episodes,
            created_at: edge.created_at,
            expired_at: edge.expired_at,
            valid_at: edge.valid_at,
            invalid_at: edge.invalid_at,
            fact_embedding: vecf32(edge.fact_embedding)
        }
        WITH r, edge
        RETURN edge.uuid AS uuid
    """

Test Case

Reproduction

from graphiti_core import Graphiti
from graphiti_core.driver.falkordb_driver import FalkorDriver
from graphiti_core.nodes import EntityNode
from graphiti_core.edges import EntityEdge
from datetime import datetime, timezone

driver = FalkorDriver(host='localhost', port=6379, database='test_db')
graphiti = Graphiti(graph_driver=driver)

# Add triplet
result = await graphiti.add_triplet(
    source_node=EntityNode(
        name="Person A",
        group_id="test",
        labels=["Entity", "Person"],
        created_at=datetime.now(timezone.utc)
    ),
    edge=EntityEdge(
        name="knows",
        source_node_uuid="",
        target_node_uuid="",
        group_id="test",
        fact="Person A knows Person B",
        fact_embedding=None,
        episodes=[],
        valid_at=datetime.now(timezone.utc),
        invalid_at=None,
        created_at=datetime.now(timezone.utc),
        expired_at=None
    ),
    target_node=EntityNode(
        name="Person B",
        group_id="test",
        labels=["Entity", "Person"],
        created_at=datetime.now(timezone.utc)
    )
)

# Verify edge properties
query = """
MATCH (source:Entity)-[r:RELATES_TO]->(target:Entity)
WHERE r.group_id = 'test'
RETURN
    source.uuid AS source_uuid,
    target.uuid AS target_uuid,
    r.source_node_uuid AS stored_source_uuid,
    r.target_node_uuid AS stored_target_uuid
"""

result = await driver.execute_query(query)
# Result: stored_source_uuid and stored_target_uuid are None (BEFORE FIX)
# Result: stored_source_uuid and stored_target_uuid match source_uuid and target_uuid (AFTER FIX)

Expected Behavior (After Fix)

source_uuid: bf29de8d-a3e8-41d8-b078-d3e191c35457
target_uuid: 3794242a-1749-4567-b2e7-6cefb06d38b3
stored_source_uuid: bf29de8d-a3e8-41d8-b078-d3e191c35457
stored_target_uuid: 3794242a-1749-4567-b2e7-6cefb06d38b3

Actual Behavior (Before Fix)

source_uuid: bf29de8d-a3e8-41d8-b078-d3e191c35457
target_uuid: 3794242a-1749-4567-b2e7-6cefb06d38b3
stored_source_uuid: None
stored_target_uuid: None

Investigation Details

The UUIDs are correctly populated in the edge_data dictionary before being passed to the query (verified in bulk_utils.py:207-208):

edge_data: dict[str, Any] = {
    'uuid': edge.uuid,
    'source_node_uuid': edge.source_node_uuid,    # Populated correctly
    'target_node_uuid': edge.target_node_uuid,    # Populated correctly
    'name': edge.name,
    'fact': edge.fact,
    # ... other fields
}

The issue is purely in the Cypher query's SET statement, which doesn't include these fields in the FalkorDB case.

Additional Notes

Changes Made in This Fix

Before (Current Code):

• Lines 129-130: Uses MATCH which fails if nodes don't exist
• Lines 132-133: SET statement missing source_node_uuid and target_node_uuid

After (Fixed Code):

• Lines 129-130: Changed to MERGE - creates nodes if they don't exist
• Line 132: Added source_node_uuid and target_node_uuid to SET statement

Why Both Changes Matter

1. MATCH → MERGE: Prevents query failure when nodes don't exist yet

   • Original behavior: Query fails silently if nodes aren't found
   • Fixed behavior: Nodes are created automatically, edge is always created

2. Missing UUID fields: Critical for edge metadata integrity

   • Affects edge deduplication logic
   • Breaks filtering edges by source/target UUID
   • Causes data integrity validation issues

Testing

Both fixes have been tested locally with real-world data (fundraising knowledge graph) and verified working correctly. Edges now have proper UUID metadata and are created reliably.

Environment

• graphiti-core: 0.21.0
• FalkorDB: Latest (Docker container)
• Python: 3.11
• OS: macOS

Related Files

• graphiti_core/models/edges/edge_db_queries.py (lines 124-136)
• graphiti_core/utils/bulk_utils.py (lines 206-209)

---

Priority: High - Affects data integrity for FalkorDB users
Complexity: Low - Simple 2-line addition to existing query
Testing: Verified fix works correctly with real-world test cases

[danielchalef]

@galshubeli @gkorland would y'all be up for taking a look at this? Thanks!

[schizoidcock]

@galshubeli @gkorland would y'all be up for taking a look at this? Thanks!

I have a falkordb graphiti only implementation and yes, thats a critical bug as i revised the code with claude code and this was his answer

● Analysis Complete

After examining our current implementation, here's what I found:

The Issue Claims:

The bug report says that source_node_uuid and target_node_uuid properties are stored as None in edge relationships when using
add_triplet() with FalkorDB.

Our Current Implementation:

In edge_db_queries.py:

1. Single edge save (line 58-74):
   MATCH (source:Entity {uuid: $edge_data.source_uuid})
   MATCH (target:Entity {uuid: $edge_data.target_uuid})
   MERGE (source)-[e:RELATES_TO {uuid: $edge_data.uuid}]->(target)
   SET e.uuid = $edge_data.uuid,
   e.name = $edge_data.name,

   ... other properties ...

Problem: ❌ Does NOT set source_node_uuid or target_node_uuid on the edge

2. Bulk edge save (line 84-100):
   MATCH (source:Entity {uuid: edge.source_node_uuid})
   MATCH (target:Entity {uuid: edge.target_node_uuid})
   MERGE (source)-[r:RELATES_TO {uuid: edge.uuid}]->(target)
   SET r.uuid = edge.uuid,
   r.name = edge.name,

   ... other properties ...

Problem: ❌ Does NOT set source_node_uuid or target_node_uuid on the edge

3. Edge return query (line 105-118):
   e.uuid AS uuid,
   n.uuid AS source_node_uuid, # Retrieved from node
   m.uuid AS target_node_uuid, # Retrieved from node
   Workaround: This retrieves the UUIDs from the connected nodes, not from edge properties

Conclusion:

YES, THIS ISSUE NEEDS TO BE IMPLEMENTED

The issue is REAL and VALID. Our current implementation:

• ✅ Uses MATCH (should be changed to MERGE for robustness)
• ❌ Does NOT store source_node_uuid and target_node_uuid as edge properties
• ⚠️ Relies on connected nodes for UUID retrieval (which works but is fragile)

The bug exists in both single and bulk save operations. While we can retrieve the UUIDs by traversing the graph, the edge
properties themselves don't contain these values, which causes:

• Edge deduplication failures
• Edge filtering issues
• Data integrity problems

[javflocor]

Important Clarification on the Bug Behavior (Progressive local Fix)

I want to clarify the progressive failure I observed, which shows why BOTH fixes are critical:

Stage 1: Original Code (MATCH + No UUID properties)

Result: Nothing created at all with add_triplet()

• No nodes visible in graph
• No edges visible in graph
• add_triplet() appeared to return success but nothing persisted

Why: MATCH fails when nodes don't exist, entire query aborts

---

Stage 2: After MATCH → MERGE Fix ONLY

Result: Skeleton nodes created, but incomplete

• Could see 2 nodes in FalkorDB Browser, but they only had UUIDs (like "9b00e7ed-78fb-...")
• Nodes had NO name, NO summary, NO other entity properties
• Edge existed structurally (could traverse in graph visualization)
• BUT edge was NOT properly linked to entities in Graphiti's logic

Why: MERGE creates skeleton nodes with only {uuid: ...} property. The edge is created, but without source_node_uuid and target_node_uuid in edge properties, Graphiti's deduplication and entity resolution can't find these nodes to populate them with full entity data.

---

Stage 3: After BOTH Fixes (MERGE + UUID properties)

Result: Complete functionality

• Nodes created with full entity data (name, summary, attributes)
• Edges properly linked with complete metadata
• Entity deduplication works
• Searchable and queryable as expected

---

PROGRESSION

The MERGE fix alone creates a subtle, hard-to-debug issue:

• Nodes appear to exist (you can see them by UUID)
• Edges appear to exist (graph structure is there)
• But entities are "orphaned" - Graphiti can't find them to populate/update them
• This leads to duplicate entities and broken deduplication
• I only realized after looking into the FalkorDB in the browser trying to find the triplet I had just added

Both fixes are required for proper functionality:

1. MERGE ensures node creation
2. UUID properties on edges enable Graphiti to link edges back to entities for updates/deduplication

This progressive failure might be confusing for other users debugging the issue, so I wanted to clarify what I observed at each stage. I am not a developer, I was just using Graphiti + FalkorDB for a specific use case I am working on (as a user) and after realizing about the error, I fixed it locally with the help of Claude Code and then raised the issue in GitHub to be confirmed by professionals.

Hope this helps clarify the bug behavior!

[galshubeli]

Hi @javflocor, thanks for the informative issue. We looking into it.

[galshubeli]

@javflocor you are right about the get_entity_edge_save_bulk_query, we’ve pushed a fix in #1013

I believe the add_triplet method is being used incorrectly in your reproduction section. Could you try the PR branch using the following reproduction steps:

from graphiti_core import Graphiti
from graphiti_core.driver.falkordb_driver import FalkorDriver
from graphiti_core.nodes import EntityNode
from graphiti_core.edges import EntityEdge
from datetime import datetime, timezone

driver = FalkorDriver(host='localhost', port=6379, database='test_db')
graphiti = Graphiti(graph_driver=driver)

# Add triplet
    source_node=EntityNode(
            name="Person A",
            group_id="test",
            labels=["Entity", "Person"],
            created_at=datetime.now(timezone.utc)
        )
    target_node=EntityNode(
            name="Person B",
            group_id="test",
            labels=["Entity", "Person"],
            created_at=datetime.now(timezone.utc)
        )
    # Add triplet
    result = await graphiti.add_triplet(
        source_node=source_node,
        target_node=target_node,
        edge=EntityEdge(
            name="knows",
            source_node_uuid=source_node.uuid,
            target_node_uuid=target_node.uuid,
            group_id="test",
            fact="Person A knows Person B",
            fact_embedding=None,
            episodes=[],
            valid_at=datetime.now(timezone.utc),
            invalid_at=None,
            created_at=datetime.now(timezone.utc),
            expired_at=None
        ),
)

# Verify edge properties
query = """
MATCH (source:Entity)-[r:RELATES_TO]->(target:Entity)
WHERE r.group_id = 'test'
RETURN
    source.uuid AS source_uuid,
    target.uuid AS target_uuid,
    r.source_node_uuid AS stored_source_uuid,
    r.target_node_uuid AS stored_target_uuid
"""

result = await driver.execute_query(query)
# Result: stored_source_uuid and stored_target_uuid are None (BEFORE FIX)
# Result: stored_source_uuid and stored_target_uuid match source_uuid and target_uuid (AFTER FIX)

[javflocor]

@galshubeli

Thanks so much for the quick response and for pushing the fix in #1013! I just tested the PR branch and can confirm everything works perfectly!!

I installed the PR branch directly from GitHub:
pip install git+https://github.com/getzep/graphiti.git@refs/pull/1013/head

Ran the exact reproduction steps you provided, and got the expected results:
stored_source_uuid matches source_uuid: True
stored_target_uuid matches target_uuid: True

PR #1013 fix is working correctly. The edge properties now correctly store the node UUIDs in FalkorDB.

Thanks again for the responsive fix! Really appreciate the quick turnaround and clear communication. The detailed reproduction steps were super helpful.

Cheers

Javier

[danielchalef]

Thanks, everybody! @prasmussen15 would you pls review and merge?