System Overview

Architecture

SchemaWhisper uses a simple interface and smart backend to turn your questions into SQL. It remembers past queries and understands your database structure, so every answer is accurate and helpful.

Summary

When you ask a question, SchemaWhisper looks for similar questions we've answered before and checks your database structure. It combines this information to create a smart prompt that helps the AI write accurate SQL.

We store past questions and their SQL answers in Weaviate, and your database structure (tables, columns, and how they connect) in Neo4j. This way, SchemaWhisper always knows what tables to use and how to join them correctly.

Before showing you results, SchemaWhisper can test the SQL to make sure it's safe and correct. Everything runs read-only, so your data stays protected.

Overall Orchestration
Weaviate Vector Collection

Each entry stores your question, the SQL answer, and which tables were used. When you ask something similar, SchemaWhisper finds these examples to write better SQL.

Neo4j Schema Graph

Neo4j stores how your tables connect, what each column means, and which relationships are required. This helps SchemaWhisper understand your data and write queries that make sense.

Graph & Vector Queries in Code

Getting Column Info from Neo4j

const response = (await ensureToolRegistry().invoke('neo4j_graph_query', {
  cypher: COLUMNS_BY_TABLES_QUERY,
  params: { tables },
})) as Neo4jToolResponse;
const columns = (response.records ?? [])
  .map((record) => (isRecord(record) ? record : null))
  .filter(Boolean)
  .map((record) => toTableColumn(record));

Finding Similar Questions in Weaviate

const { matches } = await weaviate.semanticSearch({
  className: 'PymntsNLSQL',
  concepts: [query],
  limit,
  fields: ['naturalLanguageQuestion', 'sQLQuery', 'tablesInSQL'],
});
const examples = matches
  .map((match) => (isRecord(match) ? match : null))
  .filter(Boolean)
  .map((match) => toExample(match));

Understanding Your Database

SchemaWhisper learns your tables, columns, and how they connect. This helps it write SQL that uses the right tables and joins.

Learning from Past Queries

We save questions and their SQL answers. When you ask something similar, SchemaWhisper uses these examples to write better SQL.

Building Smart Prompts

SchemaWhisper combines your question with database info and past examples to create a detailed prompt for the AI.

Safe Execution

Before showing results, SchemaWhisper can test the SQL to make sure it works correctly and safely.

Need a hand standing up your own NL→SQL workflow? Reach out and I’m happy to help.