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─> one query: every edge moved, then DETACH DELETE

​

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'}

CREATE FULLTEXT INDEX FOR (n:Chunk) ON (n.text)
CREATE FULLTEXT INDEX FOR (n:__Entity__) ON (n.name)
CREATE FULLTEXT INDEX FOR (n:__Entity__) ON (n.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', $fetch_k, vecf32($vector))
YIELD node, score
RETURN node.id AS id, node.text AS text, (1-score) AS score
ORDER BY score DESC, id

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

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

-- Fallback (Cypher-based cosine distance scan):
MATCH (a:__Entity__)-[r:RELATES]->(b:__Entity__)
WHERE r.embedding IS NOT NULL
WITH a, r, b, vec.cosineDistance(r.embedding, vecf32($vector)) AS dist
RETURN r.src_name AS src, r.rel_type AS type, r.tgt_name AS tgt, r.fact AS 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, id LIMIT $top_k

​

Stored Embedding Optimization

​

ensure_indices()

​

EntityDeduplicator — Merging Duplicate Entities

​

Phase 1: Exact Name Match (Always Runs)

1. Fetch the pending entities with their primary label (the non-__Entity__ label), and their 10 nearest names from the vector index — searched from the vector stored on each entity — that could share a group with them (same canonical name or an acronym pair); when all 10 do, the lookup widens tenfold for that entity (up to 1,000), so twenty mentions of one name are all found
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:
   • Who decides: when a group holds a node a declared table wrote, it merges here by rule, with no LLM. A group of extracted mentions only is handed to the judge (Phase 2) instead — the same spelling is evidence, not proof (Paris, France and Paris, Texas) — and so is a group holding an entity whose nearest-name search did not finish: a second row of the name may lie past what it found
   • 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
   • The merge (applied from the sealed plan): one generated query per duplicate. The SDK reads which relationship types the duplicate has, and generates a block per type and direction that moves those edges to the survivor with the write path’s own keys — RELATES keyed on rel_type with source_chunk_ids unioned rather than overwritten, every other type on its endpoints with SET r += properties, except that a MENTIONED_IN edge to a chunk the survivor also mentions keeps both edges’ spans and descriptions (each once, each whole); an edge between the duplicate and the survivor is dropped rather than turned into a self-loop. The survivor is bound before every MERGE (a path-MERGE with an unbound (s {id}) creates an empty ghost __Entity__ node), and every pattern expands from the bound duplicate (anchored on a labelled far end, the planner scans the whole label). In the same query the duplicate’s source_chunk_ids (on entities written by an earlier version) are unioned into the survivor’s, its description is joined onto the survivor’s with " | " (each member kept once, in descriptions), its name is 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 — is copied over. A property both hold with different values is a collision, and neither value is lost: the one the judge chose stays (its KEEP, on a judged merge), otherwise the survivor’s, and the other is appended to <property>__dropped on the survivor — a list that later merges add to (two list values are unioned instead); FinalizeResult.dedup_collisions names each. Then DETACH DELETE. The query re-checks that nothing it was generated from has changed — a relationship type it has no block for, a property of the duplicate added, removed or changed, a new value on the survivor for one of those keys, or a label added to or removed from either node — and writes nothing if so; the merge is read and generated again. An entity deleted, re-keyed or renamed since it was judged makes the merge changed: skipped, and its group decided again next run

​

Phase 2: Judged Cross-Document Dedup

1. Nominate candidate pairs without an LLM: the 5 nearest names of each pending entity from the __Entity__ vector index at cosine ≥ 0.5 (searched from the stored vectors, 250 entities per query, one result row each), plus the same-spelling pairs of extracted mentions and the ambiguous acronym/long-form pairs Phase 1 handed over. Descriptions are not embedded
2. 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 one set (agreements in separate sets still chain, step 4); 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 — name, labels, up to 5 existing aliases, description, and the values it holds for the attributes your ontology declares for its type(s) (born: 1960; role: "CEO") — flattened and quoted, and the prompt tells the model it is untrusted document data. Each prompt opens with the types its members carry and their declared attributes (only those types, not the whole ontology); a node already merged under two types shows the attributes of both
3. Judge — the judge partitions each set into same-referent groups (no similarity scores shown) and gives each group of two or more its best name, copied from the members’ names and aliases. Two different values of a fact that does not change (a birth or founding date, a birthplace, an identifier) mean different entities; a value only one side holds is not a contradiction; a value that changes over time (an age, a title) is weak evidence. Where a group’s members disagree on an attribute, the judge also says whose value the merged entity keeps (| KEEP: born=1): a member number, never a value it writes itself. Measured on a small labelled set (gpt-4.1, 3 runs each): namesakes told apart only by a birth year or birthplace were merged every time without the values shown, and kept apart every time with them; the same person with a changed age or title still merged. The answer lists only groups of two or more (SET 1 GROUP: 1, 4 | NAME: …), or SET 2 NONE for a set where nothing merges; a member no line lists is a different entity from the rest of its set. Leaving out the one-member lines cut answer tokens by about two thirds (measured on the 6-document experiment: 569 → 194 tokens, 4 → 2 calls), and the model, freed of them, stopped the slip that had kept Tim Cook and Timothy Cook apart. The answer ends with the line END: since unlisted members count as different, an answer cut short after a group line would otherwise turn the groups it never reached into “different” verdicts. Without END, the set of a last group line is unanswered (a last NONE line closed its set, so a forgotten END there costs nothing). LLMJudge usually reuses the GraphRAG LLM, so an output limit set on it for short answers (max_tokens) is raised to 4,096 for judge calls (LLMJudge(min_output_tokens=) sets the floor; None keeps the LLM’s own limit, for a server with a small context window); it never sets a limit itself, since a reasoning model spends output tokens on thought. (This step describes LLMJudge; a judge of your own gets the same sets as JudgeSets and answers with SetVerdicts.) Whatever the judge, an answer counts only when it is clean — no member the set lacks, no member in two groups, no merged name or KEEP on a one-member group; a set without one — a failed call, a malformed answer, or one cut before END — is asked again (retry=True; LLMJudge then asks it on its own), up to 2 more times. Every set is judged before anything is merged
4. Resolve over the whole run: agreements are unioned across sets — “AAPL” = “Apple Inc.” in one set and “Apple Inc.” = “Apple” in another become one group — but never into a group holding a pair the judge kept apart in a set, or a protected pair (two keyed rows, a mention two rows could own; neither is ever put to the judge). A group that holds a member of a set that never got a usable answer is held: that answer could still change it, so nothing in it merges and its pending members are checked again (one held only because of a neighbour’s failed set gets its judged attempt back)
5. Same → merge, by the Phase 1 rules and the same single query: survivor by the Phase 1 rank; every member’s description kept; other names kept in aliases; provenance and missing properties carried; every edge moved. The survivor gains every member’s label, as Cypher labels and on record in merged_labels, and takes the judge’s name for the group when it is one of the members’ own names or aliases (its old name moves to aliases, and its name vector is replaced; the id does not change; a table row keeps its declared name). The rename is the group’s last operation in the plan
6. Different → nothing is written to the entities: the pending entity’s check is complete, and the pair is put to the judge again only if a later pending entity brings it into a set

​

Running alongside update() and deletes

​

SDK system nodes

​

FalkorDB-Specific Notes

​

Version

​

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