How GraphRAG SDK Stores Graphs in FalkorDB

​

The Big Picture

SDK Python Objects                    FalkorDB
──────────────────                    ────────
GraphNode          ───GraphStore───>  (:Person {id, name, ...})
GraphRelationship  ───GraphStore───>  ()-[:RELATES {fact, ...}]->()

TextChunks         ───VectorStore──>  (:Chunk {embedding: vecf32(...)})
                   ───VectorStore──>  Vector + Fulltext Indexes

Query vectors      <──VectorStore───  db.idx.vector.queryNodes(...)
Keyword queries    <──VectorStore───  db.idx.fulltext.queryNodes(...)

Duplicate entities ─EntityDeduplicator─> DETACH DELETE + edge remap

​

GraphStore — Writing Nodes and Relationships

​

Batched UNWIND MERGE

-- Nodes
UNWIND $batch AS item
MERGE (n:`Person` {id: item.id})
SET n += item.properties
SET n:__Entity__

-- Relationships (with label hints)
UNWIND $batch AS item
MATCH (a:`__Entity__` {id: item.start_id}), (b:`__Entity__` {id: item.end_id})
MERGE (a)-[r:`RELATES`]->(b)
SET r += item.properties

​

Label Hints

​

Per-Item Fallback

​

None-ID Guard

​

Property Cleaning

​

Cypher Safety

​

VectorStore — Embeddings, Indexes, and Search

​

Index Creation

CREATE VECTOR INDEX FOR (n:Chunk) ON (n.embedding)
OPTIONS {dimension:256, similarityFunction:'cosine'}

CALL db.idx.fulltext.createNodeIndex('Chunk', 'text')
CALL db.idx.fulltext.createNodeIndex('__Entity__', 'name', 'description')

CREATE VECTOR INDEX FOR ()-[e:`RELATES`]->() ON (e.embedding)
OPTIONS {dimension:256, similarityFunction:'cosine'}

​

Chunk Indexing (index_chunks)

1. Batch embed: All chunk texts are passed to the embedder via a single aembed_documents call. The underlying provider controls how these are internally batched (e.g., via a configurable batch_size) and may split them across multiple API requests.
2. Batch write: Vectors are written to Chunk nodes using UNWIND (500 per batch):
   UNWIND $batch AS item
   MATCH (c:Chunk {id: item.chunk_id})
   SET c.embedding = vecf32(item.vector)
   
3. Fallback: If batch embedding fails, chunks are embedded one at a time. If batch writing fails, items are written individually.

​

Entity Embedding Backfill (backfill_entity_embeddings)

1. Query: Find entities missing embeddings: WHERE e.embedding IS NULL
2. Embed: Batch-embed entity names via aembed_documents
3. Write: Store vectors using UNWIND:
   UNWIND $batch AS item
   MATCH (e:__Entity__ {id: item.eid})
   SET e.embedding = vecf32(item.vector)
   
4. Loop: Repeat until no more entities with NULL embeddings remain. Each batch naturally returns the next un-embedded set.

​

Relationship Embedding (embed_relationships)

1. Query: Find edges with r.embedding IS NULL AND r.fact IS NOT NULL
2. Embed: Batch-embed the fact text
3. Write: Store vectors on each edge individually (using internal FalkorDB edge IDs):
   MATCH ()-[r:RELATES]->()
   WHERE id(r) = $rid
   SET r.embedding = vecf32($vector)
   

​

Search Methods

CALL db.idx.vector.queryNodes('Chunk', 'embedding', $top_k, vecf32($vector))
YIELD node, score
RETURN node.id AS id, node.text AS text, score
ORDER BY score DESC

CALL db.idx.vector.queryNodes('__Entity__', 'embedding', $top_k, vecf32($vector))
YIELD node, score
RETURN node.id AS id, node.name AS name, node.description AS description, score
ORDER BY score DESC

-- Primary (FalkorDB >= 4.2):
CALL db.idx.vector.queryRelationships('RELATES', 'embedding', $top_k, vecf32($vector))
YIELD relationship AS r, score
RETURN r.src_name, r.rel_type, r.tgt_name, r.fact, score

-- Fallback (Cypher-based cosine distance scan):
MATCH (a:__Entity__)-[r:RELATES]->(b:__Entity__)
WHERE r.embedding IS NOT NULL
WITH a, r, b, vecf32.distance.cosine(r.embedding, vecf32($vector)) AS dist
RETURN r.src_name, r.rel_type, r.tgt_name, r.fact, (1-dist) AS score
ORDER BY dist ASC LIMIT $top_k

CALL db.idx.fulltext.queryNodes('Chunk', $query_text)
YIELD node, score
RETURN node.id AS id, node.text AS text, score
ORDER BY score DESC LIMIT $top_k

​

Stored Embedding Optimization

​

ensure_indices()

​

EntityDeduplicator — Merging Duplicate Entities

​

Phase 1: Exact Name Match (Always Runs)

1. Fetch all __Entity__ nodes with their primary label (the non-__Entity__ label)
2. Group by (canonical_name, label) — the name is case-folded with accents, punctuation, inner dots (A.I. = AI) and a leading English article removed, Surname, Given un-inverted, common abbreviations expanded and one trailing legal form (Ltd, Inc) dropped; word order and the letters of non-Latin scripts are kept. Grouping by label prevents cross-type merging (Person “Paris” and Location “Paris” stay separate)
3. Fold acronyms: a 3–6 letter name joins the group of the single same-label entity whose initials it spells (AIHS / Ashford Island Historical Society). An acronym with several candidate expansions is left alone
4. For each group with duplicates:
   • Survivor: A node a declared table wrote (it carries the row’s key, so the table’s next re-sync still finds it), then a real node over a placeholder, then the long form over an acronym, then the best-connected node (most RELATES and MENTIONED_IN edges), then the longest description, then the longest name. Two nodes written from declared keys are never merged into each other, whatever they are called
   • Remap edges: All RELATES and MENTIONED_IN edges from duplicates are redirected to the survivor. The survivor is MATCHed before every MERGE — a path-MERGE with an unbound (s {id}) creates an empty ghost __Entity__ node whenever the edge does not exist yet — the RELATES MERGE is keyed on rel_type so two facts between one pair stay two edges, and RELATES source_chunk_ids are unioned rather than overwritten:
     -- Outgoing RELATES
     MATCH (dup:__Entity__ {id: $dup_id})-[r:RELATES]->(b:__Entity__)
     WHERE b.id <> $survivor_id
     MATCH (s:__Entity__ {id: $survivor_id})
     MERGE (s)-[nr:RELATES {rel_type: coalesce(r.rel_type, '')}]->(b)
     WITH r, nr, coalesce(nr.source_chunk_ids, []) AS old, coalesce(r.source_chunk_ids, []) AS contrib
     SET nr += properties(r)
     SET nr.source_chunk_ids = old + [c IN contrib WHERE NOT c IN old]
     DELETE r
     
     -- Incoming RELATES (anchored on the indexed dup lookup, not a label scan)
     MATCH (dup:__Entity__ {id: $dup_id})
     WITH dup
     MATCH (a:__Entity__)-[r:RELATES]->(dup)
     WHERE a.id <> $survivor_id
     MATCH (s:__Entity__ {id: $survivor_id})
     MERGE (a)-[nr:RELATES {rel_type: coalesce(r.rel_type, '')}]->(s)
     ... same provenance union ...
     DELETE r
     
     -- MENTIONED_IN
     MATCH (dup:__Entity__ {id: $dup_id})-[r:MENTIONED_IN]->(c:Chunk)
     MATCH (s:__Entity__ {id: $survivor_id})
     MERGE (s)-[:MENTIONED_IN]->(c)
     DELETE r
     
   • Absorb and delete in one statement: the duplicate’s source_chunk_ids are unioned into the survivor’s, its description appended to the survivor’s with " | " (each segment kept once), its name added to the survivor’s aliases when it is not a spelling variant, and every other property the survivor lacks — a typed column a table signed, is_stub — copied over, with a value already on the survivor always winning; then DETACH DELETE dup. Because the survivor is matched in the same statement, a survivor removed mid-pass makes this a no-op — the duplicate and its edges stay in place and the merge is not counted.

​

Phase 2: Fuzzy Embedding Match (Optional)

1. Fetch all surviving entities with their labels
2. Batch-embed entity names
3. Normalize vectors and compute pairwise cosine similarity in blocks (1000 entities per block to avoid OOM)
4. Merge pairs above the similarity threshold (default: 0.95 — at 0.90 the pass wrongly merged 2 of 33 hard-negative pairs for no added recall), but only within the same label (no cross-type merging)
5. Remap and delete as in Phase 1

​

Phase 3: Resolver Across Sources (Default in finalize())

​

Phase 4: LLM-Judged Cross-Document Dedup (Default in finalize())

1. Embed every entity’s name (written to e.embedding and kept for retrieval; finalize() runs backfill_entity_embeddings() afterwards for whatever is still missing one) and its description (written to e.description_embedding with e.description_embedding_hash, the digest of the text it was computed from, the embedder’s model_name and the vector’s dimension — a later run reuses the vector while the hash still matches, and re-embeds what a merge or a re-ingest changed or another model embedded; a cached vector of another dimension than the ones embedded now is re-embedded with a warning, not dropped); an entity with no description is nominated by name only
2. Nominate candidate pairs through three LLM-free doors: top-10 name neighbours at cosine ≥ 0.65, top-10 description neighbours at ≥ 0.55, and “A’s name appears inside B’s description”
3. Group candidates into dense sets of at most 8: more than half of a set’s pairs must be nominated edges, so a chain A–B–C–D where only neighbours are similar (exactly half) cannot form; an edge left between two sets is its own 2-member set. Whole sets are packed into prompts of ≤ 3,000 tokens; the entity text is rendered one line per entity, flattened and quoted, and the prompt tells the model it is untrusted document data
4. Judge, pass 1 — the LLM partitions each set into same-referent groups; names, labels and descriptions only, no similarity scores shown
5. Judge, pass 2 (judge_vote=True, the default) — the same sets, members shuffled and reversed; an answer that changes with the order is a guess. With judge_vote=False there is no second pass: the first pass’s groups are the agreed pairs and nothing is linked for disagreement (a cross-set pair, step 7, is still linked, with agreement=1)
6. Both passes agree → merge (with judge_vote=False: the single pass groups them), through the same absorb path as Phase 1: survivor by the Phase 1 rank (a table’s row over a mention, then degree, then longest description); every member’s description kept in descriptions and joined with " | " in description; other names kept in aliases; source_chunk_ids and missing properties carried; edges remapped to the survivor first, then the loser deleted. On top of that the survivor gains every member’s label, as Cypher labels and on record in merged_labels, so a later merge carries them on. Agreements are unioned within one set only: two sets that share a member (a straddling edge) never chain into one merge, the cross-set pair is linked instead. Two keyed rows, a mention two rows could own, and any pair a resolver remembered as DISTINCT_FROM are never put to the judge, never grouped with each other through a third member, and never merged or linked. If the DISTINCT_FROM pairs cannot be read at all, the phase does not run — an unavailable protection set is not an empty one — and last_judge_stats reports skipped_reason; the resolver and fuzzy phases follow the same rule
7. Only one pass agrees → link: a SAME_AS edge (source='llm_judge', agreement=1; for a pair agreed on across two sets, agreement is the number of passes that saw it — 2 with the vote, 1 without, so agreement=2 always means both passes agreed) between the two; both nodes and both descriptions stay. A set whose prompt failed in either pass is left unjudged — its pairs are neither merged nor linked
8. Neither → nothing

​

FalkorDB-Specific Notes

​

Vector Storage

SET n.embedding = vecf32($vector)

​

Vector Search API

db.idx.vector.queryNodes('Label', 'property', $top_k, vecf32($vector))

db.idx.vector.queryRelationships('RELATES', 'embedding', $top_k, vecf32($vector))

​

Graph Deletion

await rag.graph_store.delete_all()  # Uses GRAPH.DELETE internally

​

Retry Behavior

​

File Reference