Structured Data Knowledge Graph: Your Tables and Your Documents in One Graph

FalkorDB's GraphRAG-SDK now ingests CSV, TSV, PSV and tab files through a "record path" that writes each row as typed nodes and edges into the same FalkorDB graph as documents, with no LLM call per row. Tables are declared once in the ontology via TableMapping, Column and Link classes, so an employees.csv row becomes a Person node with an INTEGER age and a WORKS_AT edge to an Organization, and a finalize() step joins near-identical names. The SDK matters because it lets teams combine structured tables and prose in one knowledge graph for retrieval instead of keeping text beside a table.

Your tables and your documents, one knowledge graph. FalkorDB GraphRAG-SDK turns your tables and documents into one structured data knowledge graph, writing every CSV row onto the same node a document about that entity would use. Declare once what a table's columns mean, and each row becomes typed nodes and edges, with no LLM call per row. Here is how it works, how to use it, and the questions it lets you ask. The whole architecture in 39 seconds. Two kinds of source, two paths in, one node in FalkorDB, one answer out.Cyan: written by a table · Amber: from prose · Violet: the SDK 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: employees.csv | employee id | full name | age | job title | org id | |---|---|---|---|---| | E-1 | Alice Smith | 34 | Engineer | ORG-42 | | E-2 | Bob Jones | 45 | Analyst | ORG-42 | | E-3 | Carol White | 29 | Designer | ORG-42 | orgs.csv | org id | org name | country | |---|---|---| | ORG-42 | Acme Corp | Norway | | ORG-7 | Globex | United Kingdom | What goes in. Each employees.csv row becomes a Person with an INTEGER age you can average, and its org id becomes a WORKS AT edge to that Organization . A .csv , .tsv , .psv or .tab file takes the record path automatically. 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. python 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. | Field | What it does | |---|---| | source | The file this mapping describes, matched on its name. That name also prefixes every property the table writes, except the three join fields §03 . | | label | The label each row becomes. | | name | The column holding the row's name. The node id is built from it, which is what joins a row to a document that mentions the same name. | | key | The column that identifies a row, such as an employee id. Links and re-syncs find rows through it, and it identifies the row when no name is given. | | properties | {name: Column col, type } , or a bare string for STRING . Types: STRING , INTEGER , FLOAT , BOOLEAN , DATE , LIST . | | links | Columns that point at other entities. Each becomes an edge, creating a placeholder node if the target hasn't been loaded yet §04 . | 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: Tables never overwrite each other If employees.csv and payroll.csv both declare grade , they write employees grade and payroll grade . finalize reports the overlap under property conflicts , with how many people actually disagree. A document never overwrites a declared value If the report calls Alice "the engineer", that goes into her description. employees title still reads Engineer , exactly as HR exported it. Cleanup is exact When a table drops a column, re-syncs, or is removed, the SDK takes back precisely what that table wrote: its prefixed columns and the key it gave the node. Conflicts are kept, never guessed Both values stay under their own table's name, and the report shows where to settle it at the source. A report can be acted on; a wrong merge can't be undone. 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: | finalize reports | What it tells you | |---|---| | entities deduplicated | How many entities were joined across sources, by rule or by the judge | | probable duplicates | Look-alike names it left separate, each with the rule that matched them, ready to review | | property conflicts | Properties two tables both supply, with how many entities disagree | 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. | employee id | full name | age | job title | org id | | |---|---|---|---|---|---| | E-1 | Alice Smith | 34 | Engineer | ORG-42 | | | E-2 | Bob Jones | 45 | Analyst | ORG-42 | | | E-3 | Carol White | 29 | Designer | ORG-42 | | 3 records 3 people 3 edges first write | employee id | full name | age | job title | org id | | |---|---|---|---|---|---| | E-1 | Alice Smith | 35 | Engineer | ORG-42 | updated | | E-2 | Bob Jones | 45 | Analyst | ORG-42 | removed | | E-3 | Carol White | 29 | Designer | ORG-42 | | | E-4 | Dan Brown | 41 | Engineer | ORG-42 | new | 3 records written 3 chunks deleted 1 entities deleted True replaced existing Re-sync in motion. The new export is written as a fresh snapshot: changed rows take their new values and new rows arrive. The removed row is the clever part, because nothing is left in the file to say it's gone. 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. python 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 Do I need a different API to ingest a CSV? No. ingest is the same call for a PDF and a table. A .csv , .tsv , .psv or .tab file takes the record path on its extension, and its TableMapping is found by file name in the ontology. Can I add tables to a graph I already built from documents? Yes. Add a TableMapping to your ontology and ingest the table, and your document graph becomes a structured data knowledge graph. Each row lands on the node your documents already created for that name and label, adds its typed columns, and links to the rest of the graph. Then run finalize to join the names that are spelled a little differently. Does ingesting a table use an LLM? Not per row. A declared mapping is applied by code, so every row is written with no model call. A table with no declaration gets one proposal call for the whole file. finalize then builds embeddings for the new names in batches, as it does for any ingest, and asks the LLM judge only about genuinely uncertain pairs. What if my table and my documents spell names differently? The same name under the same label, in any letter case, is one node from the very first write. finalize joins variants such as Acme Corp Ltd and Acme Corp by rule, and an LLM judge decides the uncertain pairs, reading the row's declared values beside the document's description. The table's node stays, keeps its columns and gains the description. Can I load from a database or Parquet instead of CSV files? Yes. Any tabular source plugs in through a RecordLoaderStrategy : a Parquet file, a database cursor, or rows you already hold in memory. You ingest it under a table name such as readings.csv , which finds its mapping, and everything else typed columns, links, re-sync works the same. 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. github.com/FalkorDB/GraphRAG-SDK https://github.com/FalkorDB/GraphRAG-SDK 1. a FalkorDB server, with its browser on :3000 docker run -p 6379:6379 -p 3000:3000 \ falkordb/falkordb 2. the SDK, with PDF support pip install "graphrag-sdk litellm,pdf " 3. run the script, then open the graph python ingest.py open http://localhost:3000 Authors - Software Engineer at FalkorDB, working across AI, GraphRAG, and developer platforms. He builds graph-powered AI solutions, contributes to GraphRAG, Snowflake integrations, and MCP tooling, and develops full-stack products while driving automation, testing, and open-source initiatives with Python and TypeScript. - Gal is a Software and AI Engineer, leading the development of GraphRAG-SDK, a specialized toolkit for building Graph Retrieval-Augmented Generation GraphRAG systems. It integrates knowledge graphs, ontology management, and state-of-the-art LLMs to deliver accurate, efficient, and customizable RAG workflows.