A table already knows what its columns mean

Real knowledge is half prose and half table. The board report is a PDF; the org chart is an HR export. The incident write-up is Markdown; the asset inventory is a CSV.

A table carries two things a document doesn't: a stable key for every row and a known type for every column. GraphRAG-SDK keeps both, and that is what makes a structured data knowledge graph more than text beside a table. Tables take their own path into the same FalkorDB graph, the record path, which reads each row exactly as declared and builds the same node and edge shapes retrieval already understands. These are the two tables the examples build on:

Declare it once, in the ontology

A table of entities is declared with three classes: TableMapping, Column and Link. A mapping binds one file to one label, names the column that identifies a row and the column holding its name, types the other columns, and turns any column holding another entity's key into an edge. It lives in Ontology.​tables, next to the entity types, because a mapping is schema.

import asyncio
from graphrag_sdk import (Column, ConnectionConfig, Entity, GraphRAG, Link,
                          LiteLLM, LiteLLMEmbedder, Ontology, TableMapping)

ONTOLOGY = Ontology(
    entities=[Entity(label="Person"), Entity(label="Organization")],
    tables=[
        TableMapping(
            source="employees.csv",     # matched on the file name
            label="Person",
            name="full_name",           # what a document would call her
            key="employee_id",          # what identifies the row
            properties={"age": Column("age", "INTEGER"),
                        "title": "job_title"},  # a bare string is a STRING column
            links=[Link("WORKS_AT", to="Organization", by="org_id")],
        ),
        TableMapping(
            source="orgs.csv", label="Organization",
            name="org_name", key="org_id",
            properties={"country": "country"},
        ),
    ],
)

async def main():
    async with GraphRAG(
        connection=ConnectionConfig(host="localhost", graph_name="acme"),
        llm=LiteLLM(model="openai/gpt-5.5"),
        embedder=LiteLLMEmbedder(model="openai/text-embedding-3-large", dimensions=256),
        embedding_dimension=256,
        ontology=ONTOLOGY,
        enable_cypher=True,
    ) as rag:
        await rag.ingest("employees.csv")    # rows → people + WORKS_AT edges
        await rag.ingest("orgs.csv")         # fills in the organizations they point at
        await rag.ingest("acme_report.pdf")  # a document, exactly as before
        await rag.finalize()                 # joins near-identical names, reports the rest

asyncio.run(main())

There is no mapping= argument. A table takes the record path on its extension and its declaration is found by file name, so ingesting a table looks exactly like ingesting a PDF. finalize() runs once after loading: it builds the embeddings and indexes, joins names that match without being identical, and reports anything worth a look.

Checked before anything is written

The mapping is checked against the file's real header, and every cell against its declared type, before a single write. A mapping that doesn't fit raises MappingError with the reason, and the graph stays exactly as it was. FLOAT refuses nan and inf, so one bad cell can never turn an average into NaN. Numbers are read the way the exporting system meant them: 1,234.56 and the German 1.234,56 are both 1234.56. Pass strict_​mapping=True to insist that every column in the file is mapped.

A row and a sentence land on one node

This is the design the whole feature turns on. A row doesn't get a separate record node parked beside the entity. It writes directly onto the same entity node that documents create, so a fact from the table and a fact from the text are one hop apart: the same node.

The bridge is the name. A row's node id is compute_​entity_​id(name, label), the exact function document extraction already uses. When employees.csv and acme_​report.​pdf both name Alice Smith as a Person, both compute alice_​smith__​person and write to the same node from the very first write.

Every column carries the name of the table that wrote it

Two sources writing one node need something to keep them from overwriting each other. GraphRAG-SDK encodes ownership in the property name: every property a table writes is stored as <table>__​<property>, where the table is the file's name, lower-cased, without its folder or extension. So age from employees.csv is stored as employees__age. Documents never write these prefixed properties. A table writes just three unprefixed fields, the ones the SDK uses to join: name, entity_key and is_stub. Here is what each source wrote on the node:

finalize() joins the names that don't match letter for letter

Names that differ only in letter case are already one node. For the rest, finalize() works in order, cheapest step first:

When a pair is merged, the table's node is the one that stays, because it's the one the next re-sync finds by key. It keeps the table's values, gains the document's description, and keeps the other spelling in aliases. Two rows with their own keys are never merged: a declared key has already said they're two different things. Every decision is visible in the finalize() report:

A foreign key is an edge, not a string

An HR export describes a person, the company they work for, and the employment between them. Link("WORKS_​AT", to="Organization", by="org_​id") says org_id points at an organization, and every row gets a WORKS_AT edge. It's stored the way every other relationship in the graph is stored (a RELATES edge with rel_​type: "WORKS_​AT"), so retrieval, traversal and text-to-Cypher need to learn nothing new.

And when the organization hasn't been loaded yet, nothing has to wait:

A link only ever adds its key to a node; it never overwrites a name or value the organization's own table supplied. Seeing both employees__​org_​id and orgs__org_id on one node tells you the link and the organization's own row met. Any placeholder still waiting for its table is listed by finalize() under unresolved_​references.

A table is a snapshot, not an addition

Documents accumulate. Tables get regenerated. Friday's employees.csv is the new truth, and rows that vanished from it should vanish from the graph. So ingesting a table that's already in FalkorDB re-syncs it: the same ingest() call, and the result tells you what changed.

result = await rag.ingest("employees.csv")   # Friday: re-sync
result.replaced_existing  # True: this table was already in the graph
result.chunks_deleted     # 3: Monday's rows, replaced in one atomic swap
result.entities_deleted   # 1: Bob left the file, and his node left the graph

result = await rag.ingest("employees.csv")   # nothing changed
result.no_op              # True: recognised by its hash, nothing rewritten

The new export is written alongside the old one and swapped in atomically, so queries never see a half-loaded table. A departed row's node goes too, unless a document still mentions it: a person the board report still talks about keeps the report's description and loses only the employees__* columns. That's the prefixed-property design paying off a second time.

• The hash covers the mapping too. Changing a declared type or adding a column rewrites the table. The hash is saved last, only when every write succeeded, so a load that stopped part-way is never mistaken for a finished one.
• Tables stay tables. update() knows a table from a document, so updating employees.csv re-syncs its rows rather than re-reading it as text.
• Removal is exact. drop_​table("employees.​csv") deletes the table's rows, strips every property it wrote from the nodes that remain, and takes its mapping out of the ontology.
• Same name, same table. A table is identified by its file name, so /​exports/​2026-09/​employees.​csv re-syncs employees.csv, wherever it arrives from.

The questions a structured data knowledge graph can answer

Declared column types are what make a question like "what is the average age of employees at Acme Corp?" answerable. There's no passage to retrieve for that; it's a query. A mapping adds its typed columns to the ontology, so with enable_​cypher=True the text-to-Cypher path can see them and write the query for you.

answer = await rag.completion("Who works at the company that reported the revenue miss, "
                              "and how old are they?")
print(answer.answer)

# or run Cypher yourself, using the prefixed property names
rows = await rag.query(
    "MATCH (p:Person)-[r:RELATES]->(o:Organization) "
    "WHERE r.rel_type = 'WORKS_AT' AND o.name = 'Acme Corp' "
    "RETURN avg(p.employees__age)")
# [[35.0]] after Friday's re-sync

Text-to-Cypher handles the prefixed names without being told, because each column's description in the ontology names the column and the table it came from.

No mapping? It proposes one. Another source? Bring a loader.

A table nobody mapped still belongs in the graph. Ingest one and the SDK proposes a mapping: one model call for the whole table, never one per row.

The model sees every column's measured type, fill and uniqueness across the whole file, a few sample rows, and what the graph already holds: its labels, relationship types and mapped tables. Then everything it suggests is held to the data. A key must be unique and complete, a column must exist, a link must point at a label the graph knows, and a type stricter than the data allows is relaxed to fit. A suggestion that doesn't hold goes back to the model with the exact reason. The result is listed in the finalize() report under proposed_​mappings, and your own TableMapping replaces it the moment you declare one. No model configured? The SDK still loads every column with an inferred type, keyed by the first column that is unique and fully filled.

import pandas as pd
from graphrag_sdk import DocumentInfo, RecordBatch, RecordLoaderStrategy, TextLoader

# free text that happens to live in columns: read it as a document instead
await rag.ingest("support_tickets.csv", loader=TextLoader())

# any table source: Parquet here, or a database cursor, or rows in memory
class ParquetRecordLoader(RecordLoaderStrategy):
    def __init__(self, path):
        self.path = path

    async def load_records(self, source, ctx) -> RecordBatch:
        frame = pd.read_parquet(self.path)
        frame = frame.astype(object).where(frame.notna(), None)  # empty cells → None
        return RecordBatch(
            open_records=lambda: iter(frame.to_dict("records")),
            columns=list(frame.columns),
            document_info=DocumentInfo(uid=source, path=source),
        )

# "readings.csv" is the table's name: it finds the mapping and takes the record path
await rag.ingest("readings.csv",
                 record_loader=ParquetRecordLoader("exports/readings.parquet"))

Out of the box, CsvRecordLoader detects comma, semicolon, tab and pipe delimiters on its own. Each row is kept as a record on the table's document, so update(), delete_​document(), apply_​changes() and drop_table() all understand tables, and rename_​entity() carries a table's mapping along with the label. Rows stay out of the vector index, so a million-row table adds a million typed rows to the graph rather than a million vectors. Rows are reached through their entities and through Cypher, which is exactly what typed columns are for.

Frequently asked questions

Declare a table. Ask a question.

Point it at a CSV you already have, add one TableMapping, and ask the questions only a structured data knowledge graph can answer, using your tables and your documents together.