Setting Up Qdrant
Qdrant is a vector database. NLQueries creates these collections in it:
| Collection | What's stored | Written by | Read by |
|---|---|---|---|
cache_<agent> |
Cached answers indexed by question embedding | the semantic cache, as questions are answered | the semantic cache; cache stats, cache list, cache clear |
doc_<source_id>_chunks |
Document chunk embeddings | doc-ingest, doc-sync-notion, doc-sync-confluence |
doc-ask |
agent_<id>_verified |
Question/SQL pairs from positively rated feedback | promote-feedback, and export-kb at the end of its run |
the question path, as example queries |
agent_<id>_schema |
Table and column description embeddings, and the agent's query capsules | tables and columns: generate_knowledge_base(..., embed=True) in the Python API (no nlqueries command passes embed=True); capsules: process-history --embed, which replaces the agent's capsules on each run |
the question path: relevant tables, and capsules as example queries |
Each collection is created on first write with 384-dimension vectors (nlqueries.config.EMBED_DIMENSIONS, a constant rather than a setting), cosine distance and INT8 scalar quantization.
Every name above uses the agent's (or source's) storage name: letters, digits, _, - and . are kept and every other character becomes _, so postgres:localhost:mydb becomes cache_postgres_localhost_mydb. The knowledge-base, feedback and session files use the same name. A connector ID and its sanitised form are therefore one agent on purpose: the CLI uses postgres:localhost:mydb, the MCP server knows the agent by its knowledge-base file name, postgres_localhost_mydb, and both reach the same files and collections. Verified examples and capsules are matched to the agent by storage name too, so a pair promoted or a capsule embedded from the CLI is used for the MCP server's questions, and the reverse.
When upgrading: a document collection written under the raw ID by an earlier release (doc_postgres:localhost:mydb_chunks) is still read, by a caller that uses that raw ID, until a collection under the new name holds the source's chunks. The next successful doc-ingest for the source writes the new name and deletes the raw-ID collection; doc-ingest --allow-empty removes both. The MCP server knows such a source only by its sanitised ID, so it reads only the new name: a document source whose ID contains a replaced character (:, /, a space) is visible to it once it has been ingested again, as it was not before either. A cache collection for an ID containing . gets a new name and starts empty; the old one is not read, because under the old rule it was also the cache of the ID with _ in place of each .. Nothing reads the old one after the upgrade; delete it in Qdrant to reclaim the space. A schema collection written under the raw ID is read the same way, separately for its two kinds of point. That applies to an ID with a character Qdrant accepts in a collection name but the storage name replaces, such as @ or a space. Qdrant refuses : in a collection name, so for a connector ID such as postgres:localhost:mydb no raw-ID schema collection could be created, and its table hints and capsules could not be stored until now. Tables and columns are read from it until generate_knowledge_base(..., embed=True) writes them under the new name and deletes it; capsules are read from the new name once process-history --embed has written them there.
Example queries. For each question the question path searches the agent's verified examples and its capsules in agent_<id>_schema, nearest first. Capsules are signed with the cache's signing key (NLQ_CACHE_SIGNING_KEY) when process-history --embed writes them, and a capsule whose signature does not verify is never shown to the model: one written into Qdrant by anything else, or one embedded before capsules were signed. A signed capsule is also left out when its text, embedded again, does not score against the question as its stored vector did, as for verified examples: the signature does not cover the vector. Every process that answers questions must have the key that signed them, as for verified examples. When the searches give no example (Qdrant out of reach, nothing embedded for the agent, or nothing near the question), the first capsules in the knowledge base file that export-kb wrote are used, most frequent first, without ranking them against the question.
Releases before capsules were signed wrote them to a collection named by QDRANT_COLLECTION (default nlqueries), which nothing read. That setting is gone; run process-history --embed once per agent, and delete the old collection in Qdrant.
Qdrant is optional — NLQueries works without it, but semantic caching, document retrieval and the vector searches above won't be available.
Check if it's already running
curl http://localhost:6333/
# Windows PowerShell: Invoke-WebRequest http://localhost:6333/
A 200 OK means it's up, and the body carries the version:
{"title":"qdrant - vector search engine","version":"1.18.2","commit":"..."}
Qdrant v1.10 or newer is required. NLQueries searches through the Universal Query API (
query_points), which Qdrant added in v1.10. Against an older server every vector search returns404— the semantic cache falls back to exact-match hits only, dynamic context injection finds nothing, and document retrieval returns nothing. Several of those paths treat a failed search as an empty result, so the symptom is a system that answers, slowly and without context, rather than one that reports an error. Check theversionabove before assuming a quiet system is a working one.Keep the client within one minor of the server.
qdrant-clientcompares the two and warns on every connection when the minor versions differ by more than one — "Qdrant client version X is incompatible with server version Y". It is a warning rather than a failure, and searches keep working, but it is easy to mistake for the fault above.requirements/core.lockpins client 1.19.0, which suits the v1.18.2 the compose file ships. If you run your own Qdrant at an older version, install a client to match it — the>=1.10floor inpyproject.tomlis about the query API existing, not about which server you point at.
(/healthz also answers, but only with the plain text healthz check passed —
it tells you the server is alive, not whether it is new enough.)
Upgrading an existing Qdrant
If your qdrant-data volume was written by v1.9.x, it must be removed. There
is no data-preserving path forward. The failure is loud — the container exits on
startup with:
Failed to deserialize segment.json: unknown variant `on_disk`,
expected `mmap` or `in_ram_mmap`
Measured, by writing a collection with v1.9.3 and reopening the same volume:
| upgraded to | result |
|---|---|
| v1.10.1 | starts, data intact |
| v1.12.4 | starts, data intact |
| v1.18.2 | panics on startup and exits |
| v1.9.3 → v1.12.4 → v1.18.2 | panics at the last hop, identically |
The last row is the one that matters: stepping one minor at a time does not carry the storage forward. Running an intermediate version postpones the reset rather than avoiding it, because nothing rewrites the old segment format on the way through.
Nor is staying on an intermediate version a migration. qdrant-client 1.19.0,
which this project locks, treats a server more than one minor behind as
incompatible and warns on every client construction — so pinning v1.12.4 buys a
warning rather than a working upgrade.
docker compose down
docker volume rm "$(basename "$PWD")_qdrant-data" # this volume only
docker compose up -d
Not docker compose down -v. That removes every named volume in the
stack, and this one also defines nlqueries-data, which holds knowledge bases,
connectors.yaml, capsules and feedback — none of which the Qdrant version has
anything to do with, and not all of which is regenerable. Name the volume.
Compose prefixes volume names with the project name, which defaults to the
directory the file sits in; docker volume ls will show the exact name if the
command above does not match.
The benchmarks stack in benchmarks/docker-compose.yaml keeps its own Qdrant and
its own volume, and was pinned to v1.9.2 — so it fails the same way, and the
command above will not match it. Started with -f benchmarks/docker-compose.yaml,
Compose takes the project name from that file's directory, so the volume is
created as benchmarks_qdrant_bench_data rather than the qdrant_bench_data
written in the file:
docker compose -f benchmarks/docker-compose.yaml down
docker volume rm benchmarks_qdrant_bench_data
Nothing in it is worth preserving — a benchmark run rebuilds its own fixtures.
What that costs. Nothing in Qdrant here is a system of record, but the parts
are not equally cheap to rebuild. The semantic cache regenerates on its own as
questions are asked. The capsules in agent_<id>_schema come back by running
nlqueries process-history --embed again, and the verified examples from
nlqueries promote-feedback (or the next export-kb), which reads the feedback
records kept outside Qdrant. Its table and column points come back only by calling
generate_knowledge_base(..., embed=True) again from Python. Document chunks need
their sources re-ingested, which is the only part that costs real time — if you
have ingested a large corpus, plan for it rather than discovering it afterwards.
Option A — Docker (recommended for local development)
docker run -d --name qdrant --restart unless-stopped \
-p 127.0.0.1:6333:6333 -p 127.0.0.1:6334:6334 \
-v qdrant_storage:/qdrant/storage \
qdrant/qdrant
The ports are bound to 127.0.0.1 so the container is reachable from this machine only. Qdrant starts with no authentication unless you give it a key, and an unauthenticated vector store is a write path into the semantic cache — cached SQL is executed against your database. Publishing it on every interface, which is what -p 6333:6333 does, offers that write path to anything that can route to the host.
NLQueries will not stop you here, because its own check reads QDRANT_URL: http://localhost:6333 is loopback, so no key is required no matter what the container publishes. The two are independent, and the bind is the half that check cannot see.
To reach Qdrant from another machine, set a key on both sides rather than widening the bind alone — QDRANT__SERVICE__API_KEY on the container and QDRANT_API_KEY for NLQueries (openssl rand -hex 32). NLQueries requires the key for any non-loopback QDRANT_URL in any case.
Data persists in the qdrant_storage named volume across restarts. Manage it with docker stop/start qdrant, docker rm -f qdrant (data preserved), or docker volume rm qdrant_storage (data deleted).
Port 6333 (HTTP REST) is what NLQueries uses; port 6334 (gRPC) is optional.
Option B — Docker Compose (bundled with the NLQueries stack)
If you're already running the NLQueries Docker Compose stack, Qdrant is included — no separate setup:
cp .env.example .env
# edit .env: set your LLM API key, QDRANT_API_KEY and NLQ_MCP_STATIC_TOKEN
# (generate each with: openssl rand -hex 32)
docker compose up
QDRANT_API_KEY and NLQ_MCP_STATIC_TOKEN ship empty in .env.example, and docker compose up refuses to start until both are set. The compose file starts Qdrant with QDRANT_API_KEY as its API key and hands the same key to the NLQueries container.
Available at http://qdrant:6333 inside the Compose network, and at http://localhost:6333 on your host (published on loopback only, unless you set BIND_ADDR). Requests from tools on the host need the key as well, sent in Qdrant's api-key header.
Option C — Qdrant Cloud (managed, no local install)
- Sign up at cloud.qdrant.io and create a cluster (free tier available)
- Copy the Cluster URL and API Key from the dashboard
- Set both:
bash export QDRANT_URL="https://<your-cluster>.qdrant.io" export QDRANT_API_KEY="<your-api-key>"
Option D — Native binary (no Docker)
# Linux
curl -L https://github.com/qdrant/qdrant/releases/latest/download/qdrant-x86_64-unknown-linux-musl.tar.gz | tar -xz
./qdrant
# macOS
brew install qdrant && qdrant
# Windows — download qdrant-x86_64-pc-windows-msvc.zip from
# https://github.com/qdrant/qdrant/releases, extract, then run:
.\qdrant.exe
Starts on port 6333 by default; data stored in ./storage relative to the binary.
Configure NLQueries to use Qdrant
export QDRANT_URL=http://localhost:6333
NLQueries creates each collection listed at the top of this page automatically on its first write.
Running Qdrant in production
How NLQueries connects
Every Qdrant client in NLQueries is built in one place (nlqueries.embeddings.qdrant_client.build_qdrant_client), from two settings:
| Setting | Default | Notes |
|---|---|---|
QDRANT_URL |
http://localhost:6333 |
The REST endpoint. A URL with no scheme, such as qdrant:6333, is plain http |
QDRANT_API_KEY |
empty | Sent by every Qdrant client NLQueries builds, and by the requests that call QDRANT_URL directly: the health checks (nlqueries health and the MCP health tool), process-history --embed's check that Qdrant is up, and the kb-stats cache count |
Nothing else is configurable: no timeout, and no gRPC. NLQueries talks REST to the port in QDRANT_URL, so port 6334 can stay unpublished.
A Qdrant that is not on this machine needs a key. localhost, 127.0.0.0/8 and ::1 count as this machine; every other host, a private Docker network included, does not. For any other QDRANT_URL, an empty QDRANT_API_KEY stops the first Qdrant call with QdrantAuthenticationRequired. There is no setting to turn this off. The reason is the semantic cache: it stores SQL that is executed against your database, so a Qdrant that anyone can write to is a way to run SQL. Set the same key on the server, as QDRANT__SERVICE__API_KEY.
Use https when the key crosses a network. A key sent to a host other than this machine over plain http:// is logged as a warning, once per URL, and not refused. Anyone on that path can read the key. Use an https:// URL (Qdrant Cloud serves one), or keep Qdrant on a network nothing else can reach, and say so with NLQ_QDRANT_PRIVATE_NETWORK=1. The Docker Compose stack does: its Qdrant is another container on Compose's own network, on the same host.
Several NLQueries processes, one Qdrant
Point every process at the same QDRANT_URL, and give them all the same two keys. Otherwise each one generates its own, under its own state directory:
NLQ_CACHE_SIGNING_KEYsigns cached answers, capsules and verified examples. An entry another process signed with a different key does not verify. It is then treated as a cache miss, or left out as an example (configuration).NLQ_CACHE_ENCRYPTION_KEY, if encryption is on. Text another process encrypted under a different key cannot be read.
What to back up
Qdrant holds nothing that cannot be rebuilt, but the parts differ in what rebuilding costs: see What that costs. Document chunks are the expensive part, because every source has to be ingested again. If you have ingested a large corpus, back Qdrant up.
Qdrant's own tools do this: its snapshot API, per collection or for the whole storage, or a copy of its storage directory (/qdrant/storage in the container) taken while Qdrant is stopped. Qdrant Cloud has backups of its own. Qdrant's documentation covers all three.
Restoring a backup restores signed and encrypted entries, which are only useful with the keys that wrote them. Keep NLQ_CACHE_SIGNING_KEY with the deployment's configuration, so a restored Qdrant still verifies. Keep NLQ_CACHE_ENCRYPTION_KEY too, but apart from the backups, as Encrypting what Qdrant stores says.
Sizing
There are no measured figures for NLQueries' footprint in Qdrant, so plan from what is stored:
- Points: one per cached answer, per document chunk, per verified example, and per table, column and capsule an agent has embedded.
- Vectors: 384 dimensions, cosine distance.
- Quantization: INT8 scalar quantization on every collection NLQueries creates, with the quantized vectors kept in RAM (
always_ram).
Document chunks are usually the largest share, and they grow with what you ingest. Watch Qdrant's own memory and disk use as a corpus grows.
The Docker Compose service
The compose file's qdrant service is a reasonable model for a single-host deployment:
- A pinned version:
qdrant/qdrant:v1.18.2. Move it deliberately, after reading Upgrading an existing Qdrant. - A required key:
QDRANT__SERVICE__API_KEYis taken fromQDRANT_API_KEY, and compose refuses to start without it. - Ports published on loopback only (
BIND_ADDR, default127.0.0.1). The NLQueries container reaches Qdrant over the compose network ashttp://qdrant:6333. - Storage in the named volume
qdrant-data. - Privileges: all Linux capabilities dropped, and
no-new-privilegesset. - A health check that opens the REST port, which
nlqueries-corewaits on before it starts.
Encrypting what Qdrant stores
Qdrant keeps the text of cached answers and of every ingested document chunk, readable by anyone with access to its storage, its snapshots or its API. With NLQ_CACHE_ENCRYPTION=true, both are encrypted with AES-256-GCM before they are stored and decrypted when they are read; searching is unchanged, since it runs on vectors computed from the text before it is encrypted.
- The key is
NLQ_CACHE_ENCRYPTION_KEY, or the fileNLQ_CACHE_ENCRYPTION_KEY_FILEnames, or one generated on the first encrypted write and kept ascache_encryption_keyin the state directory. Set your own as a random value (openssl rand -hex 32), never a password or phrase: anyone holding a copy of Qdrant's data can try guesses against it offline. When more than one process or container writes to the same Qdrant, give them all the same key: a generated one belongs to one state directory. Keep a copy, and keep it apart from Qdrant's backups, which it is there to protect. - Each chunk's text is bound to the document identifier it was ingested under: given another identifier, it does not decrypt. The collection is not part of it, so a point copied whole into another collection still decrypts there, and so does a snapshot restored under another name.
- What stays readable: the vectors, which are derived from the text and can say something about it, and the questions, SQL, document names, chunk metadata and identifiers the store searches, filters and verifies on.
- Turning it on encrypts what is written from then on. What is already stored stays readable as it is: ingest the documents again and run
nlqueries cache clear <agent>to have them stored encrypted. - Turning it off stores new text unencrypted. Encrypted text is still read while the key is available.
- Without the key, encrypted entries cannot be read: a cached answer is a miss and is answered afresh, and a document chunk is left out of retrieval, with one warning per process for each of the two. Ingesting the documents again restores them.
Verify
nlqueries health
The first check listed is Qdrant: [OK] with reachable at <host> (version …, … ms) when a request to QDRANT_URL succeeds, or [FAIL] with connection refused — is Qdrant running at <url>? when it does not. The check sends no QDRANT_API_KEY, and it reports an error response from the server with the same message as a refused connection; nlqueries health --verbose shows the underlying error. A refused connection means the port doesn't match QDRANT_URL or the container/binary isn't running — see troubleshooting.md#w3.
(nlqueries cache stats is not a connectivity check: it reports Total entries: 0 when Qdrant cannot be reached.)