Graph Schema

When you ingest documents into GraphRAG SDK, the system builds a property graph in FalkorDB. This document explains exactly what that graph looks like — what node types exist, what edges connect them, what properties they carry, and what indexes make it searchable. Understanding the graph structure helps you write custom Cypher queries, debug ingestion quality, and tune retrieval. Looking to change an existing ontology — add/drop attributes, rename labels, retype fields? See Ontology Evolution for the atomic-evolve API and the alignment invariant it enforces.

The Big Picture

┌──────────┐                   ┌──────────┐
│ Document │──PART_OF────────>│  Chunk   │
│          │                   │ (embed.) │
└──────────┘                   └─────┬────┘
                                     │
                              NEXT_CHUNK
                                     │
                               ┌─────v────┐
                               │  Chunk   │
                               │ (embed.) │
                               └──────────┘
                                     ^
                              MENTIONED_IN
                                     │
┌──────────┐                   ┌─────┴────┐
│  Person  │──RELATES────────>│  Org     │
│__Entity__│                   │__Entity__│
│ (embed.) │<──RELATES────────│ (embed.) │
└──────────┘                   └──────────┘

The graph has two layers:

Lexical layer — Document and Chunk nodes with provenance edges (the text you ingested)
Knowledge layer — Entity nodes with relationship edges (the structured knowledge extracted from that text)

The layers are connected by MENTIONED_IN edges, which link entities to the chunks where they were found.

Node Labels

Document

Purpose: Represents a source document that was ingested.

Property	Type	Description
`id`	`string`	Unique ID (auto-generated UUID)
`path`	`string`	Original file path or source identifier
Any metadata	varies	Custom metadata passed via `DocumentInfo`

Created in: Step 3 (Lexical Graph) of the ingestion pipeline.

Chunk

Purpose: A text fragment from a document. Chunks are the atomic unit of retrieval — when the system finds relevant information, it returns chunks.

Property	Type	Description
`id`	`string`	Unique ID (auto-generated UUID)
`text`	`string`	The chunk’s text content
`index`	`integer`	Position within the document (0-based)
`embedding`	`vecf32`	Vector embedding for semantic search (added in Step 9)
`start_char`	`integer`	Start character offset in the source document (if `FixedSizeChunking`)
`end_char`	`integer`	End character offset
`chunk_size`	`integer`	Configured chunk size
`chunk_overlap`	`integer`	Configured overlap

Created in: Step 3 (Lexical Graph). Embedding added in Step 9.

Entity Nodes (Person, Organization, etc.)

Purpose: Extracted knowledge entities. Each entity node has two labels: its domain type (e.g., Person) and __Entity__ (a secondary label shared by all extracted entities).

Property	Type	Description
`id`	`string`	Deterministic: `"name__type"` (e.g., `"alice__person"`)
`name`	`string`	Entity name as extracted
`description`	`string`	What the documents say the entity is: the descriptions it holds, joined with `" \| "`, or one summary of them (see below)
`embedding`	`vecf32`	Vector embedding of the entity name, written by `finalize()`’s dedup. Its absence marks a new entity pending dedup (a `pending` system record marks the rest); nothing else is written on an entity for dedup
`aliases`	`list[string]`	Other names the entity was merged under
`descriptions`	`list[string]`	The descriptions `description` joins, when there is more than one: a later mention or a merge adds its own rather than replacing
`description_summarised`	`boolean`	Set when `description` holds an LLM summary of earlier descriptions (written by `finalize()` or an ingest-time resolver)
`merged_labels`	`string`	Labels a merge added, joined with `" \| "`
`<property>__dropped`	`list`	Values of `<property>` a dedup merge displaced: the two merged entities held different values, and the one that stayed is the judge’s choice or the survivor’s (e.g. `born__dropped: [1961]`)

Created in: Step 7 (Write). __Entity__ label is automatically added. Embedding is written during finalize(). An entity stays the same size however often it is mentioned. Which chunks mention it, where, and what each says it is are on its MENTIONED_IN edges, one per chunk; the node holds no chunk list. Its descriptions are bounded twice: a write adds at most up to 20 on the node (past that, a mention’s description is kept on its edge only; a write never cuts what a node already holds), and finalize(), after dedup, tries to replace the descriptions of every entity holding more than 5 with one LLM summary of them, marked description_summarised. A summary that fails leaves them as they are, listed in FinalizeResult.description_summary_failures, and the next finalize() tries again. What a deleted or updated document said is taken off. Before delete_document() or update() removes a document’s chunks, it records what their mention edges said, with the rest of its crash-safe cleanup state; the cleanup then drops exactly that text from the entities’ descriptions, keeping anything a remaining chunk still says, and fills the places this frees on a full node (20) from what the remaining chunks say. No LLM call. If something else writes an entity’s description meanwhile, the entity is read again; one that keeps changing is logged and left, since the delete or update has already taken effect. A summarised entity cannot have text taken out of its summary: when the removed text is no longer said by any remaining edge and every remaining edge records what its chunk said (has said_version; a table row’s edge, which never says anything, does not count), it is rebuilt from them (and summarised again by the next finalize()); otherwise its summary is kept, and the removed text beside it is still dropped. Graphs written by an earlier version keep their entities’ source_chunk_ids lists and descriptions. MENTIONED_IN edges are what the SDK reads for provenance; the update and delete paths still trim the old lists. Their mention edges carry no said_version — and keep none when a later write adds a description to one — so text a document ingested by an earlier version wrote cannot be taken off on its delete: it is kept, as before this version, and a summarised entity with such an edge is never rebuilt from its edges. Default entity types (11): Person, Organization, Technology, Product, Location, Date, Event, Concept, Law, Dataset, Method Entities below the NER confidence threshold get the special label Unknown.

SDK system nodes

Besides your data, the graph holds a small, fixed set of the SDK’s own nodes under two labels: __GraphRAGConfig__ (the embedding model and vector size the graph was written with) and __GraphRAGProcessing__ (dedup work in progress — the run lock, the entities whose dedup check is owed, and an interrupted run’s merge plan; a finished run leaves only what is still owed). They have no edges and no vector, so no traversal or search reaches them, and get_statistics() does not count them. No dedup marker or bookkeeping is written on your entities — only their name vectors, and what a merge folds into the survivor. See Storage.

Edge Types

PART_OF (Document -> Chunk)

Purpose: Provenance — tracks which document a chunk came from.

Property	Type	Description
`index`	`integer`	Chunk position within the document

NEXT_CHUNK (Chunk -> Chunk)

Purpose: Sequential ordering — preserves the reading order of chunks within a document. Used to fetch neighboring chunks for context expansion. No additional properties.

MENTIONED_IN (Entity -> Chunk)

Purpose: Co-occurrence — links entities to the chunks where they were extracted. This is a critical edge for retrieval: when you find an entity, you can traverse to its source chunks.

Property	Type	Description
`spans`	`list[integer]`	Where the chunk names the entity, flat: `[start, end, start, end, ...]` (character offsets in the chunk’s `text`)
`description`	`string`	What this chunk says the entity is: the extraction model’s description, or the sentence around the spans when it gave none. Joined with `" \| "` when there is more than one
`descriptions`	`list[string]`	The same descriptions, each whole, when there is more than one: the chunk described the entity twice, or a merge or a remap put two mentions on one edge. A write adds up to 20; a merge keeps both edges’
`said_version`	`integer`	Set when this version creates the edge: it records everything its chunk put on the entity’s description. An edge an earlier version wrote has none, even after a later write (a backfill) adds a description

Deduplicated by (entity_id, chunk_id). Written once and deleted with its chunk, so what a deleted document said can be taken off its entities’ descriptions.

RELATES (Entity -> Entity)

Purpose: All extracted relationships between entities. This is the only relationship type used for knowledge edges.

Property	Type	Description
`rel_type`	`string`	Original relationship type (e.g., `"WORKS_AT"`, `"LOCATED_IN"`)
`fact`	`string`	Human-readable fact: `"(Alice, WORKS_AT, Acme Corp): Alice is a senior engineer"`
`description`	`string`	Relationship description from LLM
`keywords`	`string`	Comma-separated terms for fulltext search
`weight`	`float`	Confidence: 1.0 = explicit, 0.5 = implied, 0.2 = weak inference
`src_name`	`string`	Source entity name
`tgt_name`	`string`	Target entity name
`source_chunk_ids`	`list[string]`	Chunks containing evidence for this relationship
`spans`	`string` (JSON)	Character offsets of the evidence sentence (omitted when coreference resolution rewrites the chunk)
`embedding`	`vecf32`	Vector embedding of the `fact` text (added during `finalize()`)

Why a Single RELATES Edge Type?

You might expect separate edge types like WORKS_AT, LOCATED_IN, and MARRIED_TO. Instead, all relationships use the single RELATES type with the original type stored in the rel_type property. Here’s why:

Index efficiency. Each edge type in FalkorDB needs its own vector index. With potentially hundreds of LLM-generated relationship types, you’d need hundreds of indexes. One RELATES type means one vector index that covers all relationships.
Consistent retrieval. The retrieval system searches all relationships at once via the RELATES edge vector index. Having a single type means one query covers everything.
No information loss. The original type is preserved in rel_type and appears in the fact string, so you can still filter by type in custom Cypher queries:
MATCH (a:Person)-[r:RELATES {rel_type: "WORKS_AT"}]->(b:Organization) RETURN a.name, b.name

Indexes

The SDK creates 5 standard indexes during finalize() (or ensure_indices()). All are idempotent — safe to create repeatedly.

Vector Indexes (3)

Target	Property	Purpose
`Chunk` nodes	`embedding`	Semantic search over text passages
`__Entity__` nodes	`embedding`	Semantic search over entity names
`RELATES` edges	`embedding`	Semantic search over relationship facts

Syntax:

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

Fulltext Indexes (2)

Target	Properties	Purpose
`Chunk` nodes	`text`	Keyword search over text passages
`__Entity__` nodes	`name`, `description`	Keyword search over entity names and descriptions

Syntax:

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)

FalkorDB keeps one fulltext index per label, so the two __Entity__ statements build a single index over name and description. They are separate statements so that an existing index on one field cannot stop the other from being added.

The Provenance Chain

The graph structure ensures complete traceability from any answer back to its source:

Answer
  ↑ (generated by LLM from context)
Chunk text passages
  ↑ MENTIONED_IN (entity → chunk where it was found)
Entity relationships (RELATES)
  ↑ extracted from chunks
Chunk nodes
  ↑ PART_OF (document → chunk)
Document node
  ↑ (original source file)
Your Document

This is the Zero-Loss Data principle: every piece of source material is traceable in the graph. When the retrieval system provides context to the LLM, it can always point back to which document and which chunk the information came from.

Defining Your Own Schema

A GraphSchema tells the extraction pipeline which entity and relationship types to look for, and the pruning step uses it to filter non-conforming data.

Basic Schema

from graphrag_sdk import GraphSchema, EntityType, RelationType

schema = GraphSchema(
    entities=[
        EntityType(label="Person", description="A human being"),
        EntityType(label="Organization", description="A company or institution"),
    ],
    relations=[
        RelationType(label="WORKS_AT", description="Employment relationship"),
    ],
)

Schema with Patterns

Patterns define which source-target pairs are valid for each relationship type. They are specified directly on RelationType:

schema = GraphSchema(
    entities=[
        EntityType(label="Person"),
        EntityType(label="Organization"),
        EntityType(label="Location"),
    ],
    relations=[
        RelationType(label="WORKS_AT", patterns=[("Person", "Organization")]),
        RelationType(label="LOCATED_IN", patterns=[("Organization", "Location")]),
    ],
)

A relationship with an empty patterns list is allowed between any entity types.

Open Schema Mode

If you create an empty schema (GraphSchema()), the pipeline operates in open schema mode:

The LLM extracts any entities and relationships it finds
The pruning step is skipped entirely
The 11 default entity types are used for NER

This is good for exploration. For production, a defined schema produces cleaner, more consistent graphs.

Inspecting the Graph

Statistics

stats = await rag.graph_store.get_statistics()
# Returns: node_count, edge_count, entity_types, relationship_types,
#          graph_density, embedded_relationship_count, mention_edge_count,
#          relates_edge_count

Raw Cypher Queries

# Find all Person entities
result = await rag.graph_store.query_raw(
    "MATCH (p:Person) RETURN p.name, p.description LIMIT 10"
)

# Find relationships between two entities
result = await rag.graph_store.query_raw(
    "MATCH (a:Person {name: 'Alice'})-[r:RELATES]->(b) "
    "RETURN a.name, r.rel_type, b.name, r.fact"
)

# Count mentions per entity
result = await rag.graph_store.query_raw(
    "MATCH (e:__Entity__)-[m:MENTIONED_IN]->(c:Chunk) "
    "RETURN e.name, count(m) AS mentions "
    "ORDER BY mentions DESC LIMIT 20"
)

File Reference

File	What it contains
`core/models.py`	GraphSchema, EntityType, RelationType, PropertyType
`storage/graph_store.py`	Node/relationship upserts, label hints, statistics
`storage/vector_store.py`	Index creation, vector search, fulltext search
`ingestion/pipeline.py`	Lexical graph construction, pruning logic
`ingestion/extraction_strategies/entity_extractors.py`	Default entity types, compute_entity_id()

Home

Pipeline

Ontology

Reference

The Big Picture

Node Labels

Document

Chunk

Entity Nodes (Person, Organization, etc.)

SDK system nodes

Edge Types

PART_OF (Document -> Chunk)

NEXT_CHUNK (Chunk -> Chunk)

MENTIONED_IN (Entity -> Chunk)

RELATES (Entity -> Entity)

Why a Single RELATES Edge Type?

Indexes

Vector Indexes (3)

Fulltext Indexes (2)

The Provenance Chain

Defining Your Own Schema

Basic Schema

Schema with Patterns

Open Schema Mode

Inspecting the Graph

Statistics

Raw Cypher Queries

File Reference

​The Big Picture

​Node Labels

​Document

​Chunk

​Entity Nodes (Person, Organization, etc.)

​SDK system nodes

​Edge Types

​PART_OF (Document -> Chunk)

​NEXT_CHUNK (Chunk -> Chunk)

​MENTIONED_IN (Entity -> Chunk)

​RELATES (Entity -> Entity)

​Why a Single RELATES Edge Type?

​Indexes

​Vector Indexes (3)

​Fulltext Indexes (2)

​The Provenance Chain

​Defining Your Own Schema

​Basic Schema

​Schema with Patterns

​Open Schema Mode

​Inspecting the Graph

​Statistics

​Raw Cypher Queries

​File Reference

The Big Picture

Node Labels

Document

Chunk

Entity Nodes (Person, Organization, etc.)

SDK system nodes

Edge Types

PART_OF (Document -> Chunk)

NEXT_CHUNK (Chunk -> Chunk)

MENTIONED_IN (Entity -> Chunk)

RELATES (Entity -> Entity)

Why a Single RELATES Edge Type?

Indexes

Vector Indexes (3)

Fulltext Indexes (2)

The Provenance Chain

Defining Your Own Schema

Basic Schema

Schema with Patterns

Open Schema Mode

Inspecting the Graph

Statistics

Raw Cypher Queries

File Reference