nlqueries/nlqueries

**NLQueries Core** is an open-source natural language to SQL engine — see nlqueries.com. It turns plain-English questions into validated SQL, builds a self-updating YAML knowledge base from your schema and query history, and exposes everything as an MCP server your AI assistant can call directly. It also answers questions from your documents (PDF, Word, Excel, Notion, Confluence) and can blend both in a single hybrid answer.
Links
- **Website** — nlqueries.com
- **Documentation** — nlqueries.com/docs/
- **Getting started** — nlqueries.com/docs/getting-started.html
- **Supported databases** — nlqueries.com/databases/
- **PyPI** — nlqueries-core
- **Docker Hub** — nlqueries/core
---
Features
| Capability | Description |
|---|---|
| **Database connectors** | PostgreSQL, MySQL, Snowflake, BigQuery, Redshift, SQL Server / Azure SQL, DuckDB, SQLite — plus a generic SQLAlchemy connector for any other SQLAlchemy-reachable database, driven by a connection URL |
| **Document connectors** | PDF, Word, Excel, Notion, Confluence — ask questions over ingested documents with citations |
| **Query pipeline** | Filter, cluster, and parameterize query history into reusable QueryCapsule templates |
| **Knowledge base** | Auto-generated YAML schema + capsule file, with coverage reporting via kb-stats |
| **Multi-agent orchestration** | Routes each question to a SQL agent, document agent, or both in parallel (hybrid) |
| **Conversational follow-ups** | Carries context across questions so a follow-up like "and by region?" resolves against the previous query — on by default in nlqueries query, reset with --new-session |
| **Semantic cache** | Returns previously-answered similar questions in under 50 ms, no LLM or DB round-trip |
| **Embedding daemon** | Keeps the embedding model resident in memory — ~10 ms per call instead of ~9 s |
| **Feedback loop** | Rate an answer with feedback, review with feedback-stats, and promote-feedback the thumbs-up ones — their SQL is re-validated against the current schema and blended into later prompts as verified examples |
| **Regression checks** | eval re-asks the agent's own mined capsules — and a golden question set too, with --golden — then checks the generated SQL parses and references only tables the agent knows |
| **dbt import** | import-dbt merges dbt model and column descriptions into the knowledge base |
| **LLM client** | Anthropic, OpenAI, Amazon Bedrock, or any LiteLLM-supported provider |
| **MCP server** | Query execution and schema/knowledge lookup exposed as MCP tools for Claude, Cursor, etc. |
| **CLI** | nlqueries (or the shorter nlq alias) — connect, build, query, and inspect from your terminal |
See docs/architecture.md (or read online) for how these pieces fit together.
---
Quickstart
**Prerequisite:** Python 3.11–3.14.
Option A — Docker (recommended)
Pulls the published nlqueries/core image from Docker Hub — no clone required, just the compose file:
Create a .env file next to it with one LLM key, a Qdrant key and an MCP
token. All three are required — compose refuses to start without
QDRANT_API_KEY or NLQ_MCP_STATIC_TOKEN:
The MCP server is reachable over the network, so it requires that token: