Nlqueries README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Nlqueries listing page.
nlqueries-core
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 |
| 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+.
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 at least one LLM key:
Then start the stack:
This pulls nlqueries/core:latest and starts it alongside Qdrant (:6333), with the MCP server on :8080. Run CLI commands against the running stack from a second terminal:
Option B — pip install
Optional extras for specific connectors:
Option C — Clone and install from source
No Docker required — for contributing, or to run against unreleased changes:
See CONTRIBUTING.md for linting and test commands.
First query
Follow-up context is on by default; pass --new-session to start fresh or
--no-session to disable it for a one-off question.
Full walkthrough: docs/getting-started.md (or read online).
Documentation
| Doc | Covers |
|---|---|
| docs/getting-started.md (or read online) | Step-by-step setup and your first query |
| docs/cli-reference.md (or read online) | Every command and flag |
| docs/connectors.md (or read online) | Database and document connector setup, per-connector notes and caveats |
| docs/configuration.md (or read online) | Environment variables |
| docs/troubleshooting.md (or read online) | Common warnings and errors explained |
| docs/qdrant-setup.md (or read online) | Setting up Qdrant (required for embeddings, semantic cache, document search) |
| docs/mcp-authentication.md (or read online) | Authenticating the MCP server — required to serve it over a network |
| docs/architecture.md (or read online) | Module layout and request flow |
Contributing
See CONTRIBUTING.md. All contributors must sign the CLA before a PR can be merged — see CONTRIBUTOR_LICENSE_AGREEMENT.md.
License
Business Source License 1.1 — each release converts to Apache 2.0 four years after its release date.