Text-to-SQL with Knowledge Graphs: Solving Multi-Hop Query Problems

Gal Shubeli
Date Published: January 19, 2026
Date Updated: January 18, 2026

Highlights

Knowledge graphs map database schemas as connected structures, enabling LLMs to traverse multi-hop relationships that vector similarity search cannot discover through semantic matching alone.
QueryWeaver uses FalkorDB to store schema metadata as nodes and relationships, allowing the system to find intermediate tables like vendor_agreement that lack semantic similarity to queries.
Graph traversal solves the 5-hop query problem by walking structural paths between tables, while vector databases only retrieve semantically similar endpoints and miss the connective tissue.

For over 60 years, developers have chased Text-to-SQL conversion. Even with today’s LLMs, most solutions fail when they encounter complex enterprise schemas.

For months, I obsessed over a frustrating loop, involving late nights staring at failed SQL queries. My screen became a graveyard of syntax errors and hallucinated joins that no amount of prompt engineering could fix. I realized that even with perfect prompts, I was giving the LLM a jigsaw puzzle with no picture on the box.

Most vector-based implementations treat databases like flat shopping lists. But a database schema isn’t a list: it’s a web of connections. That was my breakthrough. What if we mapped the entire schema as a Knowledge Graph? What if we enriched the nodes with primary keys and null-handling rules and connected that to the LLM?

This became the core of QueryWeaver. Using FalkorDB, we built a system where the model doesn’t just read a dictionary: it follows a map.

Text-to-SQL Error Taxonomy

Common Text-to-SQL Error Categories

What breaks in semantic search and how QueryWeaver's Healer fixes it

🔗

Missing JOIN Paths

Vector databases retrieve semantically similar tables but miss the intermediate connective tissue required to link them structurally.

Symptom

SELECT * FROM publisher, royalty_ledger
-- Missing vendor_agreement bridge

Graph Solution

Traversal discovers all intermediate nodes on the relationship path

👻

Hallucinated Relationships

LLMs invent JOIN conditions between tables that have no actual foreign key relationships, creating syntactically valid but logically incorrect queries.

Symptom

JOIN capability_matrix ON superpower.name = capability_matrix.description
-- No actual FK relationship exists

Graph Solution

Only follows explicit edges stored in the knowledge graph schema

❌

Incorrect Table Selection

Generic table names with no semantic similarity to the query get ignored, even when they're structurally mandatory for the query path.

Symptom

Query needs stakeholder_registry but vector DB returns only superpower and budget_allocation

Graph Solution

Graph traversal includes all nodes on the shortest path regardless of naming

🔢

Value Format Mismatches

The model doesn't know how data is actually stored (e.g., "40" vs "0040"), leading to WHERE clauses that return zero results despite correct logic.

Symptom

WHERE publisher_id = '40'
-- Actual storage format is '0040'

Graph Solution

Content Awareness layer enriches nodes with actual data formatting rules

🤔

Column Ambiguity

Multiple tables contain similarly named columns (e.g., "name", "id", "date"), and the LLM selects the wrong one without proper context about table relationships.

Symptom

SELECT name FROM publisher
-- Should be publisher.legal_name not publisher.name

Graph Solution

Semantic Layer provides objective descriptions for every column based on actual data samples

Building an Architecture of Trust

Building QueryWeaver required more than just a graph. We created an Architecture of Trust. Over the past month, we developed a 10-point blueprint to move from guessing queries to calculating them:

QueryWeaver Architecture

The GPS (Knowledge Graph)

Maps schema relationships in FalkorDB so the model never guesses how tables connect. Primary keys and foreign keys become explicit edges.

The Voice (Semantic Layer)

Uses LLMs to examine actual data samples and generate objective descriptions for every node, turning a silent schema into a map of intent.

The Map (Content Awareness)

Avoids the Value Trap by telling the model not just what a column is, but how the data is styled (e.g., "40" stored as "0040").

The Navigator (Graph Traversal)

Moves beyond keyword matching. Uses graph traversal to find the Hidden Bridges between semantically unrelated but structurally required tables.

The Brain (Reasoning Buffer)

Forces the model to explain its logic in natural language before writing code, creating a traceable reasoning path.

The Memory

Uses the graph to store past successes and failures so the agent matures with every conversation, learning from previous query patterns.

The Healer

An autonomous agentic loop that catches errors, fixes the SQL, and validates the final answer before you see it.

The Stress Test: Breaking the "Superhero" Schema

To prove this architecture worked, I built a stress test that mirrored the messy reality of enterprise data.

I took the Superhero database from the BIRD Benchmark (the industry gold standard). In its original form, it was too clean. I expanded it into a 60-table case, adding the boring connective tissue found in real organizations: vendor agreements, stakeholder registries, and resource logs.

Vector vs Graph for Text-to-SQL

Aspect

Vector Database

Knowledge Graph

Data Representation

Semantic embeddings (high-dimensional vectors)

Nodes (tables) and edges (relationships)

Multi-Hop Queries

Fails to find intermediate tables

Traverses relationships to find all paths

Generic Table Names

Misses tables with no semantic similarity

Finds structurally mandatory bridges

Schema Understanding

Treats schema as flat documents

Maps schema as connected structure

Query Accuracy

Broad but often incomplete results

Precise, structurally complete results

Best For

Simple, single-table queries

Complex joins and traversals

Data Representation

Vector Database

Semantic embeddings (high-dimensional vectors)

Knowledge Graph

Nodes (tables) and edges (relationships)

Multi-Hop Queries

Vector Database

Fails to find intermediate tables

Knowledge Graph

Traverses relationships to find all paths

Generic Table Names

Vector Database

Misses tables with no semantic similarity

Knowledge Graph

Finds structurally mandatory bridges

Schema Understanding

Vector Database

Treats schema as flat documents

Knowledge Graph

Maps schema as connected structure

Query Accuracy

Vector Database

Broad but often incomplete results

Knowledge Graph

Precise, structurally complete results

Best For

Vector Database

Simple, single-table queries

Knowledge Graph

Complex joins and traversals

The difference between vector-based retrieval and our graph-powered retrieval was stark.

“The real breakthrough in Text-to-SQL comes when you stop treating the schema as a document to embed and start treating it as a graph to traverse.”
— Roi Lipman, CTO of FalkorDB

The Missing Link (The "Generic" Table)

The Value Trap Example

The Missing Link: Generic Table Problem

How vector databases fail when table names lack semantic similarity to queries

Query Example

"Which publishers have received royalty payments above $5000?"

Vector DB Failure

Found publisher and royalty_ledger tables through semantic similarity.

Missed the vendor_agreement bridge table because "vendor agreement" has zero semantic connection to "royalty payments."

Result: Incomplete SQL with missing JOIN path

Graph Victory

QueryWeaver saw no physical path between publisher and royalty_ledger except through vendor_agreement.

Retrieved the bridge because graph structure mandated it as the only connection.

Result: Complete, accurate SQL query

The 5-Hop Nightmare

"List superpowers with associated budget allocations"

Vector DB Failure

Found the two endpoints: superpower and budget_allocation.

Missed middle tables like stakeholder_registry because "stakeholder" has no semantic link to "superpowers."

Result: Failed to construct multi-hop query

Graph Victory

Performed multi-hop traversal: superpower → capability_matrix → stakeholder_registry → resource_requisition → budget_allocation

Found stakeholder_registry simply because it was the only road connecting the entities.

Result: Correct 5-table JOIN query

The Verdict: Stop Guessing, Start Weaving

This journey taught me a lesson: Vectors find the “What” (the nouns), but Graphs find the “How” (the logic).

QueryWeaver isn’t just a Text-to-SQL converter: it’s a Reasoning Engine for Data. Every answer it gives is:

Mapped by a Knowledge Graph
Governed by a strict Constitution of logical rules
Verified and healed by an autonomous Healer agent
Interpreted by an intelligent Analyst layer

The needle in the wood is no longer hidden: it’s illuminated.

Explore the project and join the build: https://www.queryweaver.ai/

Learn more about the benchmark used in this experiment: BIRD Benchmark (https://bird-bench.github.io/)

FAQ

Why do vector databases fail at multi-hop Text-to-SQL queries?

Vector databases use semantic similarity to retrieve tables. They miss intermediate tables with generic names that have no semantic relationship to the query but are structurally required.

How does graph traversal improve Text-to-SQL accuracy?

Graph traversal walks the actual foreign key relationships between tables, discovering all intermediate nodes on the path between query entities regardless of semantic similarity.

What makes QueryWeaver different from standard Text-to-SQL solutions?

QueryWeaver stores the entire schema as a knowledge graph in FalkorDB, enriches nodes with metadata, and uses graph algorithms to find structurally mandatory tables for complex joins.

References and citations

BIRD Benchmark: Cross-Domain Text-to-SQL Evaluation – https://bird-bench.github.io/
FalkorDB Documentation: Graph Database for LLM Applications – https://docs.falkordb.com/
QueryWeaver Project – https://www.queryweaver.ai/

Gal Shubeli

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.