Semantic Database Engine

An AI-powered natural language query engine that lets you ask questions to your database in plain English — no SQL required.

Point it at any MSSQL or MySQL database, index your tables, and start asking questions. The system builds a local semantic understanding of your data using ONNX embeddings and answers queries using Google Gemini as the reasoning layer.

How It Works

"How many customers are from the UK?"
         ↓
   Intent Classification  →  Count + Filter (Country: UK)
         ↓
   Metadata Query Engine  →  SELECT COUNT(*) ... WHERE Country = 'UK'
         ↓
   Result: 400 customers
         ↓
   Gemini LLM Formatting  →  "There are 400 customers from the UK."

The system classifies your question into one of five strategies — Semantic Search, Filter, Count, Aggregate, or List — then executes it deterministically. No SQL is generated by the LLM. Gemini only formats the final answer into natural language.

Features

• Natural language queries — ask in plain English, get structured answers
• Multi-strategy intent classification — automatically picks the right approach per question
• Status & geography filters — understands synonyms (England → UK, pending → Processing)
• Aggregates — sum, average, min, max on numeric columns
• Cross-table awareness — honestly reports when a question spans beyond single-table scope
• Out-of-scope rejection — doesn't hallucinate; tells you when data isn't available
• Security-first indexing — automatically excludes passwords, tokens, PII, and audit tables
• Incremental indexing — only re-indexes new or changed rows
• Self-contained executable — single .exe, no .NET runtime installation needed
• MSSQL & MySQL support — switch with one config value

Quick Start

Option A: Download the Release (Recommended)

1. Download the latest release zip from Releases
2. Extract SemanticDb.Console.exe and appsettings.json into a folder
3. Open appsettings.json and set your "GeminiApiKey" (get one free)
4. Run SemanticDb.Console.exe — on first launch it will prompt you to enter your database connection details (server, database name, username, password). These are saved automatically to data/connection.json and never need to be entered again.
5. Type index to build the semantic index
6. Start asking: ask How many orders do we have?

Option B: Build from Source

Prerequisites: .NET 8 SDK, MSSQL or MySQL database, Gemini API key

# Clone the repo
git clone https://github.com/Unknown-086/Semantic-Database-Engine.git
cd Semantic-Database-Engine

# Download the ONNX embedding model
.\scripts\download-models.ps1

# Set your GeminiApiKey in appsettings.json
# (Database connection details are entered interactively on first run)

# Build and run
dotnet build
cd src\SemanticDb.Console
dotnet run

Self-Contained Publish (No .NET Runtime Required)

dotnet publish src\SemanticDb.Console\SemanticDb.Console.csproj `
  -c Release -r win-x64 --self-contained true `
  -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true `
  -o publish-standalone

Usage

> index
Scanning tables: Categories, Customers, OrderItems, Orders, Products, SupportTickets
Indexed 6,430 documents across 6 tables.

> ask How many customers are from the UK?
There are 400 customers from the UK.

> ask What is the average order total?
The average order total is $1,256.59 across 1,500 orders.

> ask Show me completed orders from London
Found 37 orders matching criteria (Status: Completed, City: London).

> ask Tell me about quantum computing
The provided evidence does not contain any data about quantum computing.

> status
6 tables indexed, 6,430 documents, last indexed: 2/27/2026 2:14 PM

> help
Available commands: ask, index, status, test-connection, help, exit

Configuration

Database Connection (Interactive — First Run Only)

You do not need to manually edit a connection string. When you run the exe for the first time, it walks you through entering your database details:

Database engine (mssql/mysql): mssql
Server: localhost
Database name: my_database
Username: sa
Password: ********

The connection is saved to data/connection.json automatically. On all subsequent runs, the app connects without prompting again.

appsettings.json

The only thing you need to set manually is the Gemini API key. Everything else has sensible defaults:

Project Structure

src/
├── SemanticDb.Core/                 # Interfaces, models, shared contracts
├── SemanticDb.Console/              # CLI entry point and command loop
├── SemanticDb.Query/                # Intent classification and query orchestration
├── SemanticDb.VectorStore/          # HNSW vector index and metadata query engine
├── SemanticDb.Indexing/             # Table scanning and incremental indexing
├── SemanticDb.Semantics/            # ONNX embedding generation (gte-small)
├── SemanticDb.Reasoning/            # Gemini API integration for LLM answers
├── SemanticDb.Infrastructure.Mssql/ # MSSQL database adapter
├── SemanticDb.Infrastructure.MySql/ # MySQL database adapter
└── SemanticDb.Api/                  # Web API (planned for future release)

Requirements

Documentation

• Architecture & Design Decisions — technical deep-dive into the system design, pipeline, and engineering choices
• Changelog — version history and what changed

License

This project is licensed under the MIT License.

Author

Abdul Hadi — @Unknown-086