The Problem: Your Team Has Questions, Your Data Has Answers, and SQL Sits in Between
In 2026, most companies still funnel every analytical question through one or two people who know SQL. A marketing manager wants to know which campaign drove the most qualified leads last quarter. An operations lead needs to see which fulfillment region is running behind. Both wait two days for a dashboard update or a ticket response. The bottleneck is not the database. It is the translation layer between a business question and a query.
Gartner's research on AI-powered analytics (The Future of Analytics: AI-Powered Insights Without Code) confirms what most operations leads already feel: natural language interfaces are actively reducing the barrier to entry for business intelligence, letting non-technical users derive insights without writing a single line of SQL. The architecture I am going to describe here is a practical implementation of that shift.
What the System Actually Does
The core idea is straightforward. A user types a question in plain English. A reasoning model interprets that question, generates a valid SQL query against a local DuckDB instance, executes it, and returns a formatted answer. The user never sees the query. They just see the result.
DuckDB is the right choice for this layer because it runs in-process, requires no server, and handles analytical queries against CSV, Parquet, and JSON files with minimal configuration. You point it at a file, and it treats that file as a table. For teams that already export reports from HubSpot, Stripe, or their ERP into flat files, this means zero migration work. The files they already have become queryable immediately.
The reasoning model sits between the user's question and the DuckDB execution layer. Its job is translation: take a natural language question, understand the available columns and types, and produce a syntactically correct query. This is where the architecture gets interesting. The model needs context about the table structure to generate accurate queries. We pass that context as part of the system prompt, injecting the column names, types, and a few sample rows so the LLM knows what it is working with before it writes anything.
Streamlit handles the front end. It gives you a browser-based interface in roughly 30 lines of Python, which means non-technical users get a clean input box and a rendered table without anyone building a custom UI. For teams that prefer to stay in their communication tools, the same pipeline connects to Telegram via a webhook, so users can ask questions directly in a group chat and receive answers inline.
Architecture: Three Discrete Stages
I want to be specific about the component boundaries here, because this is where most first-pass builds go wrong.
The first stage is context loading. On startup, the system reads the target file, infers the column types, and constructs a metadata block. This block gets prepended to every prompt sent to the reasoning model. Without it, the LLM guesses at column names and produces queries that fail silently or return wrong results.
The second stage is query generation. The user's question arrives, gets combined with the metadata block, and goes to the LLM. The model returns a SQL string. Nothing else happens at this stage. We do not execute yet. We validate first: check that the query references only columns that exist, that it does not attempt writes or deletes, and that it parses without syntax errors. This guard step catches the majority of model errors before they touch the database.
The third stage is execution and formatting. DuckDB runs the validated query and returns a result set. The system formats that result as a table or a plain-text summary depending on the row count, then sends it back to the interface. For Telegram delivery, the formatting step converts the result to a message-safe string before posting to the chat.
I learned the value of explicit stage separation the hard way. When we built the first version of our Autonomous SDR pipeline, we used a flat architecture where research, scoring, and writing all reported to a single orchestrator. It worked fine at five leads. At fifty, the scorer sat idle waiting on research that had nothing to do with scoring. Splitting into discrete components with defined handoff contracts between them cut end-to-end processing time and made each piece independently testable. The same principle applies here: if query generation and execution share a single function, you cannot test them independently, and failures become hard to trace. Keep the stages separate.
Implementation Considerations
The metadata injection approach works well for files with fewer than fifty columns. Beyond that, the context block grows large enough to push against token limits and degrade generation quality. For wider tables, consider passing only the columns most likely to be relevant to the user's domain, or building a column-selection step that filters the metadata before injection.
Prompt design matters more than model choice here. The system prompt needs to specify the exact output format you expect: SQL only, no explanation, no markdown fencing, no commentary. Any deviation from that format breaks the validation step. We found that adding a one-shot example to the system prompt, showing a sample question and the exact SQL response format, reduced malformed outputs significantly during testing. The example does not need to match the user's actual data; it just needs to demonstrate the expected structure.
Telegram integration introduces a latency consideration worth naming honestly. The round trip from message receipt to webhook processing to LLM call to DuckDB execution to reply typically takes three to eight seconds depending on query complexity and model response time. For synchronous chat, that feels slow. Users who expect instant responses may find it frustrating. If your team's questions are complex enough to warrant multi-second processing, the tradeoff is acceptable. If they mostly ask simple aggregation questions, a pre-built dashboard will feel faster and require less maintenance. This pipeline earns its place when the question space is unpredictable and a fixed dashboard cannot anticipate what users will ask.
Security is the other honest limitation. Because the system generates and executes SQL dynamically, you need strict controls on what the model is allowed to do. Read-only database connections, query allowlisting, and output size limits are not optional. A misconfigured instance that allows writes, or one exposed to untrusted users, is a real risk. Build the guard layer before you expose this to anyone outside your immediate team.
Connecting This to Automation Infrastructure
This kind of natural language query agent does not live in isolation. In most operational contexts, it sits downstream of data collection pipelines: n8n workflows that pull CRM exports, sync product analytics, or aggregate support ticket volumes into flat files that DuckDB can read. The query agent becomes the read layer on top of whatever your automation infrastructure writes.
If you are already running n8n for back-office orchestration, adding this agent means your team can interrogate the outputs of those pipelines without opening a spreadsheet or waiting for a scheduled report. That connection between automation and analysis is where the real time savings accumulate. We have written about the broader pattern of AI back-office automation and the lessons that come from building these systems in production, if you want to see how the pieces fit together at a larger scale.
For teams evaluating whether to build this themselves or use a pre-assembled pipeline, our full blueprint catalog covers a range of automation architectures that follow the same discrete-component design described here.
What the Build Actually Looks Like
The Python surface area for this system is smaller than most developers expect. The Streamlit interface is roughly 25 lines. The DuckDB connection and query execution is another 15. The prompt construction and LLM call is 20 to 30 lines depending on how much validation logic you inline. The Telegram webhook handler adds another 20 lines if you want that channel.
The complexity is not in the code volume. It is in the prompt engineering, the validation logic, and the metadata construction. Those three pieces determine whether the system produces reliable answers or plausible-sounding wrong ones. Spend your time there, not on the interface layer.
One practical note on model selection: a smaller, faster classification model works well for simple aggregation questions. For questions that require joins across multiple inferred relationships, or that involve ambiguous column names, a reasoning model with stronger instruction-following produces noticeably better query output. We run a two-tier approach in our own builds: route simple questions to the faster model, escalate complex ones to the reasoning layer. This keeps median latency low without sacrificing accuracy on hard queries.
What We'd Do Differently
Build the validation layer before anything else. In our first pass, we wired the LLM output directly to DuckDB execution and spent two days debugging silent failures where the model returned syntactically valid but semantically wrong queries. A validation step that checks column references against the actual metadata block before execution would have caught those immediately. Build it first, not as an afterthought.
Version the metadata block separately from the prompt. As the underlying files change, column names drift, types shift, and new fields appear. If the metadata block is hardcoded into the system prompt, every file change requires a prompt update. Generating the metadata block dynamically at runtime from the actual file means the system stays accurate without manual maintenance. We would have saved significant debugging time by treating the metadata as a runtime artifact from the start.
Add a query explanation step for non-technical users. The current architecture returns results but not reasoning. A non-technical user who gets an unexpected number has no way to audit what the system actually asked. Adding an optional "show me what you queried" toggle, which surfaces the generated SQL in a collapsed section, builds trust and helps users catch cases where their question was interpreted differently than they intended. We plan to add this to our next iteration of the build.
