feat(falkordb): implement native edges for relations - #42
Merged
1 commit merged intoJun 29, 2026
Merged
1 commit merged into
1 commit merged into
Conversation
…ling placeholders
fd5b029
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
resolves #41
Summary
Remodels
FalkorDBGraphStoreso relations are stored as native FalkorDB edgesbetween object nodes instead of standalone
AGRelationnodes withsource/targetid properties. The projection becomes a real, traversable graph — connected in the
FalkorDB Browser and usable with native variable-length paths and graph algorithms —
without losing dangling-relation support or cascade semantics.
This is a behavior-preserving internal remodeling of
FalkorDBGraphStoreonly. TheGraphStorecontract, the in-memory store, and the event log are untouched, andbecause the store is a disposable projection of the event log there is no data
migration — existing runs re-replay into the new layout.
What changed
(s)-[:AGRelation {id, type, data, provenance}]->(t). The relation'stype(plus
id/data/provenance) rides on the edge as properties;source/targetare no longer stored — they fall out of the endpoints, making the graph the single
source of truth for connectivity. Traversal by kind is a property filter:
MATCH (s)-[r:AGRelation {type:'knows'}]->(t).:AGNodeendpoint label. Every endpoint carries a structural:AGNodelabel; real objects additionally carry
:AGObject.put_relationMERGEs endpointson
:AGNode(index-backed, no full scans) andput_objectpromotes the same nodein place with
SET o:AGObject.:AGNode AND NOT :AGObject— placeholder-ness is derived, never a stored flag.When the object later arrives the node is promoted in place; when a relation is
removed, any endpoint left as an orphaned placeholder (no remaining edges) is
garbage-collected.
core.graphprojector still deletes a removedobject's relations (now edges), so behavior is identical across every
GraphStore.AGNode(id)(backs endpoint MERGE),AGObject(id)(object reads),relationship-property indexes
AGRelation(id)andAGRelation(type), andAGPatch(id). A:AGNode:AGObjectnode appears in both label indexes.Security
Because the relationship type is a fixed literal (
AGRelation), every value stays abound
$param— no string interpolation and no injection surface, even foruser-supplied relation
typestrings.Tradeoff
All edges share the
AGRelationlabel and the relation kind lives in thetypeproperty, so Browser styling/filtering keys off the property rather than the edge
label. This is the price of keeping the write path injection-free and matches the
type-as-attribute shape the projection already uses.Testing
object), placeholder cleanup on relation removal, and native-edge round-tripping;
the existing
GraphStoreConformancesuite passes unchanged (same observablebehavior).
Docs / changelog
docs/guides/using-falkordb.md"How entities are stored" section for thenative-edge model, placeholders, and Cypher inspection snippets.
[Unreleased]entry toCHANGELOG.md.