Project case study
ML - Systems · 2025
LLM-to-SQL Analytics POC with DuckDB
Node.js proof-of-concept that routes natural-language questions to safe, pre-defined SQL analytics functions over a DuckDB-backed dataset, then returns results in natural language using an OpenAI LLM.
Highlights
- Built a lightweight analytics stack with Node.js + DuckDB over a CSV-backed view for fast local querying.
- Used an LLM as a JSON-only router to select a single allowed query function, reducing prompt-to-SQL risk.
- Returned human-readable answers by executing parameterized SQL and formatting results consistently.
Gallery
What
Built a proof-of-concept assistant that answers natural-language analytics questions by translating intent into database queries and returning results in plain English.
Instead of generating arbitrary SQL, the system routes user requests to a small set of approved analytics functions to keep execution predictable and safe.
How
Initialized an in-memory DuckDB instance and created a CSV-backed VIEW (fraud_data) for fast querying without standing up external infrastructure.
Implemented a SQL layer with whitelisted functions (total records, fraud count, year summary) using parameterized queries to avoid injection and ensure consistent outputs.
Used an OpenAI model as a strict JSON-only router that selects exactly one function to call and optionally extracts parameters such as a tax/form year.
Wrapped everything in a simple CLI runner that initializes the data layer, calls the LLM router, executes the chosen SQL function, and formats a natural-language response.
Results
Demonstrated reliable end-to-end behavior: natural language questions were mapped to the correct analytics function and answered with database-grounded results.
Reduced text-to-SQL risk by constraining the LLM to structured routing decisions rather than free-form query generation.
Delivered a small, modular architecture (data layer, SQL layer, LLM router, runner) that can be extended with additional safe analytics functions.