The Complete Qdrant Guide

This is part one of three. It covers everything you need to do real work with Qdrant on your first day and through your first month. By the end you can start a Qdrant server, create a collection, store vectors with metadata, search by meaning, narrow results with filters, read the common errors, and keep the whole thing from leaking onto the public internet. Mid-level and Senior take the same ground further (hybrid search, quantization, clustering, operations); nothing here is thrown away.

The guide targets Qdrant v1.19.1, the stable release at the time of writing. Qdrant moves quickly, so some older tutorials on the internet show endpoints and settings that have since been deprecated. Where that matters, this guide says so and shows the current form.

Each section ends with a Try it task. Do them as you go. Vector search feels abstract until you have watched your own six points come back in a sensible order.

The problem Qdrant solves

A normal database answers exact questions. "Give me the order with id 4021." "Give me every customer where country is Egypt." The database compares values for equality or order, and a row either matches or it does not.

A lot of modern software needs a different kind of question: "give me the things most like this one." Find the support articles closest in meaning to a customer's complaint. Find the product photos that look like this photo. Find the paragraphs in our documents that are relevant to a question. None of these have an exact answer. They have a ranking.

The trick that makes this possible is the embedding. A machine learning model reads a piece of content (a sentence, an image, an audio clip) and produces a list of numbers, typically a few hundred to a few thousand of them. That list is a vector. The model is trained so that content with similar meaning lands at nearby positions in that number space. "How do I reset my password?" and "I forgot my login" end up close together, even though they share almost no words. "Quarterly revenue report" ends up far away.

Once everything is a vector, "most like this" becomes a geometry problem: given a query vector, find the stored vectors with the smallest distance to it. That is called nearest-neighbour search, and it is exactly what Qdrant does.

Qdrant (pronounced "quadrant") is an open-source vector database and vector search engine, licensed under Apache 2.0 and written in Rust. You talk to it over a REST API on port 6333 or a gRPC API on port 6334. It stores your vectors, stores a JSON object of metadata next to each one, builds an index so searches stay fast when you have millions of vectors, and lets you combine similarity with ordinary filters such as "only documents from 2025" or "only this customer's data".

The diagram is the whole idea. Notice what Qdrant is not. It does not create embeddings for you when you run it yourself; the embedding model is a separate step that runs before data reaches Qdrant. (Qdrant offers helper libraries and, on its managed cloud, server-side embedding, but the mental model stays the same: vectors in, nearest vectors out.) It is also not a replacement for your main application database. Most teams keep orders and users in a relational database and keep only the searchable representation, plus enough metadata to link back, in Qdrant.

What came before, and why a dedicated engine

You could do nearest-neighbour search without Qdrant. The naive method is to keep all vectors in a list and compare the query against every one of them. That is called a brute-force or exact scan. It gives perfect answers, and for a few thousand vectors it is perfectly fine. The cost grows linearly, though. With ten million vectors of 768 numbers each, every single query would do billions of multiplications, which is far too slow for an interactive application.

The classic fix is an approximate nearest-neighbour index. Instead of guaranteeing the exact closest vectors, it finds vectors that are almost certainly among the closest, in a tiny fraction of the time. You trade a sliver of accuracy for speed that is orders of magnitude better. Libraries such as FAISS (see the FAISS guide) implement these indexes, but a library is only the index. You still have to build storage, persistence, crash recovery, updates, deletes, metadata filtering, an API, and replication around it.

A vector database is that whole package. Other options in the same family are covered elsewhere in this catalogue: Pinecone (managed service), Weaviate, Milvus, Chroma, and pgvector (vector search inside PostgreSQL). Qdrant's particular strengths are a clean filtering model, a single flexible query API, and a Rust engine you can run as one container on a laptop and later as a cluster.

Two practical consequences shape how you use it. First, search is approximate by default. Two runs over the same data can differ at the margin, and a result you expect may occasionally be missing at the very bottom of a list. For nearly every real use that is acceptable, and you can ask for an exact search when you need one. Second, every vector in a given space must have the same length. You cannot mix 384-number vectors and 768-number vectors in the same space, because distance between them is meaningless. This catches almost every beginner once.

The mental model: collections, points, vectors, payloads

Qdrant has four nouns. Learn them precisely, because every API call is built from them.

A collection is a named set of points that you search together. It is the nearest thing to a table. You might have a collection called support_articles and another called product_images. When you create a collection you fix the length of its vectors and the distance metric it uses. Search always happens inside one collection.

A point is the central record. Every point has an ID, zero or more vectors, and an optional payload. The ID is either an unsigned 64-bit integer or a UUID string. IDs are how you update, fetch, and delete a specific point; if you upsert a point with an ID that already exists, you replace the old one.

A vector is the list of floating-point numbers. In the simplest setup each point has exactly one. Qdrant also supports several named vectors per point (for example an image vector and a text vector, each with its own length), and sparse vectors that store only the non-zero entries for keyword-style matching. Beginners start with one unnamed dense vector and add the rest later.

A payload is a JSON object attached to a point. It holds the metadata: the original text, a title, a URL, a category, a date, a price, a tenant ID, anything you want to return with results or filter by. Payload values can be strings, numbers, booleans, geo-coordinates, dates, and nested objects or arrays.

A few extra terms appear in the docs and in error messages, so meet them now.

• Segment. Inside a collection, points are stored in chunks called segments. Each segment has its own vector storage, payload storage, and indexes. You rarely touch them directly, but they explain why a brand-new collection behaves differently from a large one.
• WAL (write-ahead log). Every change is written to a log on disk before it is applied. Once Qdrant has acknowledged a write, it survives a power cut.
• Optimizer. A background process that rebuilds segments, merges small ones, cleans up deleted points, and builds indexes. It is why a collection can show a "yellow" status for a while after a big upload.
• Shard and replica. A collection can be split into shards, and shards can be copied as replicas on other servers. On one machine, the default is simply to work; you will care about these when you run a cluster.
• Alias. An extra name for a collection, which lets you swap one collection for another without changing application code. A mid-level topic.

Distance metrics and how to read a score

When you create a collection you choose how "closeness" is measured. Qdrant offers four metrics.

• Cosine compares the direction of two vectors and ignores their length. Two vectors pointing the same way score as identical even if one is much longer. Qdrant implements it by normalising each vector when you upload it and then using a dot product. Most text-embedding models are designed for cosine similarity, so it is the usual default.
• Dot is the dot product, which depends on both direction and length. Use it when the model's documentation says to, which includes some recommendation models and sparse vectors.
• Euclid is straight-line distance between the points.
• Manhattan is the sum of absolute differences along each dimension.

The most useful rule is: use the metric your embedding model was trained for. The model's documentation or model card states it. Picking a different one does not crash anything; it silently gives worse rankings.

Reading a score needs one more piece of care, because the direction differs. For Cosine and Dot, a higher score means closer. For Euclid and Manhattan the value is a distance, so a lower number means closer. This matters when you use score_threshold, a search option that discards results scoring worse than a cut-off. A threshold of 0.8 on a Cosine collection keeps the good matches; the same number on a Euclid collection means something quite different.

How Qdrant finds neighbours quickly

You can use Qdrant for a long time without knowing how the index works, but a little intuition prevents confusion about settings and about why results are "approximate".

Qdrant's index for dense vectors is HNSW, short for Hierarchical Navigable Small World. Picture a road network. To get from one city to another you do not check every road. You take a highway to get roughly close, then a regional road, then local streets. HNSW builds a layered graph over your vectors in the same spirit. The top layer has few points and long links; the lower layers have more points and shorter links. A search enters at the top, greedily hops toward the query, drops down a layer, and repeats until it reaches the bottom, where it collects the closest candidates.

Two build-time settings control the graph. m is the number of links per point (default 16); more links means better recall and more memory. ef_construct is how many candidates are considered while building (default 100); higher builds a better graph more slowly. At search time, hnsw_ef is how many candidates the search keeps track of; higher is more accurate and slower. The defaults are sensible. As a beginner, resist the urge to tune them until you can measure a problem.

Two behaviours follow from this design and surprise newcomers.

Small collections are not indexed at all. Qdrant does not build an HNSW graph for a segment until it passes an indexing threshold (10,000 KB of vector data by default, which is a few thousand vectors of typical size). Below that, a plain scan is quicker than a graph, so Qdrant just scans. If you create a six-point collection and see indexed_vectors_count of 0, nothing is broken.

Filtering and the index interact. Qdrant can combine a filter with the graph search, but it does that best when the filtered fields have a payload index. We return to this in the filtering sections, because it is the single most valuable habit to learn early.

Installing Qdrant

The fastest way to run Qdrant for learning is Docker. If Docker is new to you, read the Docker guide first; you only need to run one container, but it helps to know what a container and a volume are.

Pull the image and start the server, pinning the version so your results match this guide:

docker pull qdrant/qdrant:v1.19.1
docker run -p 6333:6333 -p 6334:6334 \
    -v "$(pwd)/qdrant_storage:/qdrant/storage:z" \
    qdrant/qdrant:v1.19.1

Read the command in pieces. -p 6333:6333 publishes the REST API and the Web UI; -p 6334:6334 publishes gRPC. The -v flag mounts a folder from your machine to /qdrant/storage inside the container, which is where Qdrant keeps all its data. Without that mount, your collections would vanish the moment the container is removed. The :z suffix asks SELinux-enabled Linux systems to relabel the folder so the container can write to it; it is harmless elsewhere. Snapshots, a backup mechanism, go to /qdrant/snapshots inside the container.

You will see log lines ending with the server listening on its ports. Leave this terminal running and open a second one for the rest of the guide. Press Ctrl+C in the first to stop the server.

On Windows

If you use Docker Desktop on Windows with WSL, do not bind-mount a Windows folder into the container. That kind of mount is not fully POSIX-compatible, and Qdrant's storage engine depends on POSIX behaviour. The documented failures are serious: vectors zeroed after a restart and panics mentioning OutputTooSmall. Use a named volume, which Docker keeps on its own Linux filesystem:

docker volume create qdrant-storage
docker run --rm -it -p 6333:6333 -p 6334:6334 \
    -v qdrant-storage:/qdrant/storage \
    qdrant/qdrant:v1.19.1

Other ways to install

Qdrant also ships as downloadable binaries for Linux, macOS (Intel and Apple Silicon), and Windows from the GitHub releases page, as a .deb package, and as an AppImage. You can build it from source with cargo build --release --bin qdrant. On Kubernetes there is a community-supported Helm chart (helm repo add qdrant https://qdrant.to/helm, then helm install qdrant qdrant/qdrant). Only 64-bit x86 and ARM64 are supported; 32-bit machines are not.

Qdrant's own documentation recommends its managed Qdrant Cloud, or its Kubernetes operator, for production. If you run it yourself with Docker, you take on high availability, backups, security, and monitoring. For learning and for single-server projects, the container above is a good start. If your employer has data-residency rules, which is common for Gulf and Egyptian organisations handling customer data, self-hosting on a server in an approved region keeps the vectors and the payloads where policy requires.

The storage rule you must know

Qdrant's data directory must be on a POSIX-compatible block filesystem, ideally SSD or NVMe. Network filesystems such as NFS and object storage such as S3 are not supported for the storage path. Since version 1.15 Qdrant checks the filesystem at start-up and warns or refuses. On macOS you may see a warning like "HFS/HFS+ filesystem support is untested". That is a warning, not an error.

Checking that the setup works

Before building anything, confirm the server is alive and which version you have. From a second terminal:

curl http://localhost:6333

The reply is a small JSON welcome message containing the title and the server version. If it says 1.19.1, you are on the version this guide describes.

curl http://localhost:6333/healthz

A healthy server answers with HTTP 200 and a short text. Two siblings exist: /livez and /readyz. Kubernetes uses them as liveness and readiness probes. They stay reachable even when you later turn on an API key, which is exactly what you want from a health check.

curl http://localhost:6333/collections

On a fresh node this returns an empty list of collections: {"result":{"collections":[]},"status":"ok", ...} plus a time field.

Now open http://localhost:6333/dashboard in your browser. This is the built-in Web UI. It lists collections, lets you inspect points, and includes a Console where you can type the same REST requests this guide uses and see responses, which is a good alternative to curl if you prefer a browser. There is also an interactive tutorial at /dashboard#/tutorial. A graphical view of the vectors helps build intuition once you have data.

Qdrant also exposes /metrics in Prometheus format. You do not need it today, but it is good to know it is there; monitoring is a mid-level topic.

Your first project: six cities and four numbers

Real embeddings have hundreds of dimensions, which makes them impossible to read. To learn the API, we use an invented toy dataset where each vector has just four numbers that we can reason about. Pretend each city is scored from 0 to 1 on four traits, in this order: sea, history, nightlife, quiet. The scores are made up for teaching; they are not data about the cities.

Step 1: create the collection

curl -X PUT 'http://localhost:6333/collections/cities' \
  -H 'Content-Type: application/json' \
  -d '{"vectors": {"size": 4, "distance": "Cosine"}}'

PUT /collections/{name} creates a collection. The body says every vector has 4 numbers and similarity is Cosine. You get {"result":true,"status":"ok",...}. Run it a second time and Qdrant refuses, because the collection already exists; creation is not silently repeated.

Step 2: insert the points

Inserting is called an upsert: insert if the ID is new, replace if it exists.

curl -X PUT 'http://localhost:6333/collections/cities/points?wait=true' \
  -H 'Content-Type: application/json' \
  -d '{
    "points": [
      {"id": 1, "vector": [0.1, 0.9, 0.7, 0.1], "payload": {"city": "Cairo", "country": "Egypt", "budget": "low"}},
      {"id": 2, "vector": [0.9, 0.7, 0.4, 0.4], "payload": {"city": "Alexandria", "country": "Egypt", "budget": "low"}},
      {"id": 3, "vector": [0.7, 0.2, 0.9, 0.3], "payload": {"city": "Dubai", "country": "UAE", "budget": "high"}},
      {"id": 4, "vector": [0.8, 0.6, 0.3, 0.8], "payload": {"city": "Muscat", "country": "Oman", "budget": "mid"}},
      {"id": 5, "vector": [0.8, 0.5, 0.6, 0.4], "payload": {"city": "Casablanca", "country": "Morocco", "budget": "mid"}},
      {"id": 6, "vector": [0.0, 0.8, 0.5, 0.6], "payload": {"city": "Amman", "country": "Jordan", "budget": "mid"}}
    ]
  }'

Each point carries an ID, a vector, and a payload, exactly the three things from the mental model. The response reports a status such as completed for the operation.

Step 3: search

Suppose a traveller wants somewhere seaside, with some history, a little nightlife, and fairly quiet. Express that as a query vector in the same four-number space, and ask for the three nearest points:

curl -X POST 'http://localhost:6333/collections/cities/points/query' \
  -H 'Content-Type: application/json' \
  -d '{"query": [0.9, 0.6, 0.3, 0.5], "limit": 3, "with_payload": true}'

POST /collections/{name}/points/query is the Query API, Qdrant's single search endpoint. The reply is abbreviated here:

{"result": {"points": [
   {"id": 2, "score": 0.99, "payload": {"city": "Alexandria", ...}},
   {"id": 4, "score": 0.97, "payload": {"city": "Muscat", ...}},
   {"id": 5, "score": 0.96, "payload": {"city": "Casablanca", ...}}
 ]}, "status": "ok", ...}

Read it like this. The points are sorted best first. Each has its id, a score (Cosine, so higher is closer), and, because we asked for with_payload, its metadata. Without with_payload: true the payload is omitted; Qdrant returns only what you request, to save bandwidth. The same goes for vectors: add "with_vector": true to get them back. The scores you see will be close to the ones above; the order is what matters. Alexandria is the best match because its profile (strong sea, good history, calm-ish) is nearly the same direction as the query.

Step 4: add a filter

Now the traveller says: only mid-budget cities.

curl -X POST 'http://localhost:6333/collections/cities/points/query' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": [0.9, 0.6, 0.3, 0.5],
    "filter": {"must": [{"key": "budget", "match": {"value": "mid"}}]},
    "limit": 3,
    "with_payload": true
  }'

Alexandria disappears, because its budget is low. The remaining mid-budget cities are ranked: Muscat, Casablanca, Amman. That is the core pattern of Qdrant in a single request: similarity decides the order, the filter decides who is allowed in.

The same project in Python

The REST API is the foundation, but most people use a client library. The official Python client is qdrant-client:

pip install qdrant-client

If you later want Qdrant's local embedding library, FastEmbed, install the extra with pip install "qdrant-client[fastembed]". We do not need it for the toy vectors. Official clients also exist for JavaScript/TypeScript (@qdrant/js-client-rest), Rust, Go, .NET, and Java; they mirror the same REST and gRPC calls.

from qdrant_client import QdrantClient
from qdrant_client.models import (
    Distance, VectorParams, PointStruct,
    Filter, FieldCondition, MatchValue,
)

client = QdrantClient(url="http://localhost:6333")

client.create_collection(
    collection_name="cities_py",
    vectors_config=VectorParams(size=4, distance=Distance.COSINE),
)

client.upsert(
    collection_name="cities_py",
    wait=True,
    points=[
        PointStruct(id=1, vector=[0.1, 0.9, 0.7, 0.1],
                    payload={"city": "Cairo", "country": "Egypt", "budget": "low"}),
        PointStruct(id=2, vector=[0.9, 0.7, 0.4, 0.4],
                    payload={"city": "Alexandria", "country": "Egypt", "budget": "low"}),
        PointStruct(id=4, vector=[0.8, 0.6, 0.3, 0.8],
                    payload={"city": "Muscat", "country": "Oman", "budget": "mid"}),
    ],
)

hits = client.query_points(
    collection_name="cities_py",
    query=[0.9, 0.6, 0.3, 0.5],
    query_filter=Filter(must=[FieldCondition(key="budget", match=MatchValue(value="mid"))]),
    limit=3,
).points

for hit in hits:
    print(hit.id, round(hit.score, 3), hit.payload["city"])

The structure mirrors the REST calls one to one. QdrantClient(url=...) connects; add api_key="..." when the server requires one. create_collection takes a VectorParams object holding the same size and distance. upsert takes PointStruct objects. query_points takes the query vector, an optional query_filter, and a limit, and its .points attribute holds the scored results. The Python client waits for writes by default, so wait=True is stating the default; keeping it is a good way to make intent obvious.

Everyday operations, grouped by what you are trying to do

All requests below are REST calls against the cities collection. Each has an equivalent in the clients and in gRPC.

Manage collections

GET /collections/cities is the one to learn. Its response shows status, points_count, indexed_vectors_count, and the configuration. The status is a traffic light: green means ready, yellow means the optimizer is busy rebuilding something (searches still work), grey means optimizations are pending but paused, which usually follows a restart, and red means an unrecoverable error.

Collection names are plain strings. Since 1.19.1, the names . and .. are rejected, and a vector size above 65,536 or an empty vector is rejected too.

Fetch, list, and count points

To fetch specific points by ID:

curl -X POST 'http://localhost:6333/collections/cities/points' \
  -H 'Content-Type: application/json' \
  -d '{"ids": [1, 2], "with_payload": true, "with_vector": false}'

To page through all points without any similarity, use scroll:

curl -X POST 'http://localhost:6333/collections/cities/points/scroll' \
  -H 'Content-Type: application/json' \
  -d '{"limit": 2, "with_payload": true}'

The response includes a next_page_offset. Pass it back as "offset" in the next request to get the next page. When next_page_offset is null, you have reached the last page. Scroll accepts a filter too, so it is the right tool for "give me every point where country is Egypt", an exact listing with no ranking.

To count points:

curl -X POST 'http://localhost:6333/collections/cities/points/count' \
  -H 'Content-Type: application/json' \
  -d '{"filter": {"must": [{"key": "country", "match": {"value": "Egypt"}}]}, "exact": true}'

Counts are approximate unless you pass "exact": true. The same note applies to the points_count and indexed_vectors_count fields in collection info: they are good for trends, not for accounting.

Update and delete points

Upserting an existing ID replaces the whole point: the vector and payload you send become the new truth. If you send a point with only a payload change and leave out the vector, you have not edited the payload; you have overwritten the record. Updating individual payload keys without touching vectors uses the dedicated payload endpoints, which you meet at the mid level. For now, the safe beginner rule is: when you upsert, send the complete point.

Deleting points by ID or by filter:

curl -X POST 'http://localhost:6333/collections/cities/points/delete?wait=true' \
  -H 'Content-Type: application/json' \
  -d '{"points": [6]}'

curl -X POST 'http://localhost:6333/collections/cities/points/delete?wait=true' \
  -H 'Content-Type: application/json' \
  -d '{"filter": {"must": [{"key": "budget", "match": {"value": "high"}}]}}'

Deletes are "soft" internally: Qdrant marks points as removed and the optimizer reclaims the space later. From your side the points vanish immediately from search.

Search by an existing point

Sometimes you want "more like this stored item" without having its vector in hand. Pass the point ID as the query:

curl -X POST 'http://localhost:6333/collections/cities/points/query' \
  -H 'Content-Type: application/json' \
  -d '{"query": 2, "limit": 3, "with_payload": true}'

This asks for the three points nearest to point 2 (Alexandria). The stored point itself is excluded from its own results.

Filtering in depth

Filters are what separate a vector database from a vector library, and Qdrant's filter language is expressive. A filter is a JSON object built from three clauses and many conditions.

The clauses combine conditions:

• must means every condition has to match (logical AND).
• should means at least one has to match (logical OR).
• must_not means none of them may match.

You can use more than one clause at a time and nest filters inside each other. This request finds mid- or low-budget cities that are not in Egypt:

{
  "filter": {
    "must": [{"key": "budget", "match": {"any": ["low", "mid"]}}],
    "must_not": [{"key": "country", "match": {"value": "Egypt"}}]
  }
}

The most common conditions are:

• match with value for an exact value, any for "one of these values", and except for "none of these".
• range with gt, gte, lt, lte for numbers, and for dates written as strings.
• match with text for full-text matching on a field that has a text index. (Qdrant also has text_any, phrase, and, since 1.19, prefix matching, which the mid-level guide covers.)
• geo_radius, geo_bounding_box, and geo_polygon for location.
• is_empty, is_null, values_count, has_id, and has_vector for structure checks.
• nested for filtering inside arrays of objects.

Nested payload keys use dot notation, for example "key": "address.city", and arrays of objects use a[].b.

Here is the Python equivalent of a two-condition filter, to show how the objects line up with the JSON:

from qdrant_client.models import Filter, FieldCondition, MatchValue, MatchAny

flt = Filter(
    must=[FieldCondition(key="budget", match=MatchAny(any=["low", "mid"]))],
    must_not=[FieldCondition(key="country", match=MatchValue(value="Egypt"))],
)

Filters apply identically to search, scroll, count, and delete. You learn the language once and reuse it everywhere. That consistency is one of the nicest things about the API.

There are two behaviours to be aware of. First, a filter on a field that does not exist in a point's payload simply does not match that point; there is no error. A typo in "key": "contry" quietly returns nothing, which makes this a classic cause of "my filter returns empty results". Second, the type matters: a number stored as the string "5" does not match the integer 5. Decide on types when you design the payload and keep them consistent.

Payload indexes: the habit that pays off first

By default a payload field is not indexed. A filter on it still works, but Qdrant has to inspect points' payloads one by one, which is fine at six points and painful at six million. A payload index is a per-field index that makes filtering on that field fast. It also helps the query planner, the part of Qdrant that decides whether to walk the HNSW graph or scan a small filtered subset directly.

Create one with a single call. The field type is one of keyword (exact strings), integer, float, bool, geo, datetime, text (full-text), or uuid:

curl -X PUT 'http://localhost:6333/collections/cities/index?wait=true' \
  -H 'Content-Type: application/json' \
  -d '{"field_name": "budget", "field_schema": "keyword"}'

There is a subtlety that costs beginners real time. Qdrant builds extra graph connections for each indexed payload field, so that filtered searches do not get cut off from parts of the graph. Those connections are only created for payload indexes that exist when the graph is built. So the rule is:

Create payload indexes before you load your data, for every field you will filter on.

If you add an index after the data is in, it still speeds up filtering, but the graph does not get the extra connections until it is rebuilt. Creating the indexes first, while the collection is still empty, avoids the problem entirely. Do not index every field "just in case"; each index costs memory and slows writes. Index the fields that appear in your filters, and leave the rest.

Another reason to index: Qdrant has an optional strict mode that can reject requests which filter on unindexed fields instead of running them slowly. It is turned on by default on Qdrant Cloud. A request rejected for filtering on an unindexed field is a signal that you forgot an index, not a bug.

Named vectors and sparse vectors, briefly

You will meet two variations soon, so a short introduction avoids surprise.

Named vectors let one point hold several vectors, each with its own size and metric. Imagine a product with an image vector from a vision model and a text vector from a language model. You declare them at creation:

{"vectors": {
  "image": {"size": 4, "distance": "Dot"},
  "text":  {"size": 8, "distance": "Cosine"}
}}

When searching, say which vector space to use with "using": "image". A collection created with a single unnamed vector (as in our project) has just the default unnamed space, and you do not need using.

Sparse vectors store only the positions and values of non-zero entries, as {"indices": [1, 42], "values": [0.22, 0.8]}. They represent keyword-style signals such as BM25 or SPLADE weights, where a vocabulary of tens of thousands of terms has only a few non-zero per document. A sparse vector must be named and always uses the Dot metric. You declare the space as {"sparse_vectors": {"text": {}}}, adding "modifier": "idf" for BM25-style weighting.

Putting a dense and a sparse vector on the same point and searching both is called hybrid search, and it often beats either alone because dense vectors capture meaning while sparse ones catch exact terms and rare words. It uses the Query API's prefetch feature and is a mid-level topic. What matters today is that you know the option exists and that your collection design leaves room for it: if you suspect you will want hybrid search, name your vectors from the start.

Configuration, and how Qdrant starts

Out of the box Qdrant needs no configuration. When you do need it, there are two routes and one rule about which wins.

Qdrant reads settings from several layers, lowest priority first: built-in defaults, then config/config.yaml, then a file named after the run mode (the Docker image uses production, so config/production.yaml), then config/local.yaml, then a file passed with --config-path, and finally environment variables, which always win. YAML, TOML, JSON, and INI files are all accepted.

Environment variables use the prefix QDRANT__ and a double underscore for each level of nesting. These are the settings a beginner is most likely to touch:

For example, to run on a different log level and with telemetry off:

docker run -p 6333:6333 -p 6334:6334 \
  -e QDRANT__LOG_LEVEL=DEBUG \
  -e QDRANT__TELEMETRY_DISABLED=true \
  -v "$(pwd)/qdrant_storage:/qdrant/storage:z" \
  qdrant/qdrant:v1.19.1

If you prefer a file, mount one at /qdrant/config/production.yaml:

log_level: INFO
service:
  http_port: 6333
telemetry_disabled: true

The configuration is validated at start-up, and an invalid value aborts the launch with a message that names the key, such as invalid type: 64-bit integer -1, expected an unsigned 64-bit or smaller integer for key storage.hnsw_index.max_indexing_threads in config/production.yaml. That is helpful: read the key name in the message, fix the value, and start again.

If you use Docker Compose, a minimal file looks like this:

services:
  qdrant:
    image: qdrant/qdrant:v1.19.1
    restart: always
    container_name: qdrant
    ports:
      - "127.0.0.1:6333:6333"
      - "127.0.0.1:6334:6334"
    volumes:
      - ./qdrant_data:/qdrant/storage

Notice the 127.0.0.1: in front of the ports. It makes Qdrant reachable only from your own machine, which is the safe default for development. The next section explains why.

Many settings that tune collections (HNSW parameters, optimizer thresholds, quantization) are set per collection when you create or later update it, not in the config file. Qdrant Cloud does not allow editing the server config at all, since it manages that for you.

Securing a fresh server

This section is short but important. A self-hosted Qdrant starts with no authentication, no encryption, and listening on every network interface. The documentation says plainly that this default is not production-ready. If you run it on a cloud virtual machine with port 6333 open to the internet, anyone can read, change, or delete your collections. People have lost data this way.

Three habits keep you safe from day one.

Bind to localhost while developing. Publish ports as -p 127.0.0.1:6333:6333, as in the Compose file above. Only processes on your own machine can connect.

Set an API key before exposing the server to any network. Set the environment variable QDRANT__SERVICE__API_KEY to a long random secret. Clients then send it in a header named api-key:

curl -H 'api-key: YOUR_SECRET' http://localhost:6333/collections

In Python you pass api_key="YOUR_SECRET" to QdrantClient. Health endpoints (/healthz, /livez, /readyz) remain open so probes keep working. Keep the key out of your Git repository: inject it from your deployment platform's secret store, not from a committed file. There is also a read_only_api_key for clients that should only read.

Never expose port 6335. That is Qdrant's internal peer-to-peer port, used only between cluster nodes, and it is not protected by the API key. Do not publish it at all unless you are running a cluster, and then keep it on a private network.

API keys protect against casual access but travel in plain text unless you also enable TLS, which a beginner usually delegates to a reverse proxy or to Qdrant Cloud. Mid-level and Senior cover TLS, JWT tokens with per-collection permissions, and network policies. For a student project, "localhost only, or an API key plus a firewall" is the right amount.

Common errors and how to read them

Almost every Qdrant error comes from one of a short list of causes. Learn to read the message before searching the web.

Wrong vector length. Upserting or searching with a vector whose length does not match the collection returns an error that names the expected dimension. The collection says 768, you sent 384. The cause is nearly always a different embedding model than the one you used to create the collection. Fix the model or create a new collection.

Collection not found or already exists. Not found: Collection ... doesn't exist means a typo in the name, or you are talking to a different server than you think. The reverse, creating a collection that exists, is refused rather than overwritten. Check with GET /collections/{name}/exists.

Search returns nothing even though data exists. Work through the list. Did the write finish (use wait=true)? Is your filter key spelled correctly and of the right type? Is the collection actually empty (points_count)? Are you searching a named vector without saying "using"? Did you apply score_threshold on a Euclid collection with a similarity-style number?

Too many files open (OS error 24). Each segment holds open files, and a large collection can exceed the default operating-system limit. Raise it: docker run --ulimit nofile=10000:10000 qdrant/qdrant, or ulimit -n 10000 before starting the binary.

Filesystem warnings and panics. A message like Filesystem check failed ... FUSE filesystems may cause data corruption, or a panic mentioning OutputTooSmall, means the data folder is on a filesystem Qdrant cannot trust, such as a Windows bind mount under WSL, FUSE, or NFS. Use a named Docker volume or a local disk.

Can't open Collections meta Wal ... WouldBlock. Two Qdrant processes share one storage folder. Stop one, or give each its own folder.

Grey collection status. The optimizer has pending work but is paused, typically after a restart in the middle of optimization. Send any update to wake it, for instance PATCH /collections/{name} with {"optimizers_config": {}}, or press "Trigger Optimizers" in the Web UI.

indexed_vectors_count is 0 or lower than points_count. Not an error. Small segments are not indexed, as described earlier. Counts in collection info are approximate; use the count API with "exact": true for real numbers.

HTTP 507 or ResourceExhausted on writes. Since 1.19 Qdrant has resource quotas. When disk usage passes the configured limit it refuses writes with a message such as Disk usage is at 95% of total capacity, exceeding the configured limit of 90%. Reads keep working. Deleting points, adding disk, or raising the limit fixes it.

HTTP 429. A rate limit from strict mode was exceeded. Slow down and retry after the delay in the response.

Duplicates or gaps when paging search results. Using offset with an approximate search can show the same point twice or skip one. This is expected with approximate search. For complete, ordered listings use scroll; for search pages, fetch more results and page in your own code.

A good diagnostic routine, in order: read the exact message, check GET /collections/{name} for status and counts, then read the server log.

Putting it all together: a small search service

Here is a complete small project that follows the habits from this guide: pinned version, localhost binding, collection design before data, payload index before upload, batched upsert, and a filtered search. It uses invented four-number vectors so you can run it without an embedding model. In real work, the only line that changes is where the vectors come from.

Start the server bound to localhost:

docker run -d --name qdrant \
  -p 127.0.0.1:6333:6333 -p 127.0.0.1:6334:6334 \
  -v "$(pwd)/qdrant_storage:/qdrant/storage:z" \
  qdrant/qdrant:v1.19.1

Then the script:

from qdrant_client import QdrantClient
from qdrant_client.models import (
    Distance, VectorParams, PointStruct, PayloadSchemaType,
    Filter, FieldCondition, MatchValue,
)

NAME = "tour_guide"
client = QdrantClient(url="http://localhost:6333")

# 1. Start clean so the script can be re-run.
if client.collection_exists(NAME):
    client.delete_collection(NAME)

# 2. Design: vector length and metric are decided up front.
client.create_collection(
    collection_name=NAME,
    vectors_config=VectorParams(size=4, distance=Distance.COSINE),
)

# 3. Index the fields we will filter on BEFORE loading data.
client.create_payload_index(NAME, field_name="budget", field_schema=PayloadSchemaType.KEYWORD)
client.create_payload_index(NAME, field_name="country", field_schema=PayloadSchemaType.KEYWORD)

# 4. Load the data (a placeholder for your embedding step).
cities = [
    (1, [0.1, 0.9, 0.7, 0.1], "Cairo", "Egypt", "low"),
    (2, [0.9, 0.7, 0.4, 0.4], "Alexandria", "Egypt", "low"),
    (3, [0.7, 0.2, 0.9, 0.3], "Dubai", "UAE", "high"),
    (4, [0.8, 0.6, 0.3, 0.8], "Muscat", "Oman", "mid"),
    (5, [0.8, 0.5, 0.6, 0.4], "Casablanca", "Morocco", "mid"),
    (6, [0.0, 0.8, 0.5, 0.6], "Amman", "Jordan", "mid"),
]
client.upsert(
    collection_name=NAME,
    wait=True,
    points=[
        PointStruct(id=i, vector=v, payload={"city": c, "country": k, "budget": b})
        for i, v, c, k, b in cities
    ],
)

# 5. Search with a filter.
def recommend(preference, budget, limit=3):
    result = client.query_points(
        collection_name=NAME,
        query=preference,
        query_filter=Filter(must=[FieldCondition(key="budget", match=MatchValue(value=budget))]),
        limit=limit,
        with_payload=True,
    )
    return [(p.payload["city"], round(p.score, 3)) for p in result.points]

print(recommend([0.9, 0.6, 0.3, 0.5], "mid"))
print(recommend([0.1, 0.9, 0.6, 0.2], "low"))

Walk through what each stage teaches. Stage 1 makes the script repeatable, which matters because creation is refused when a collection already exists. Stage 2 fixes size and metric. Stage 3 creates payload indexes while the collection is empty, so the graph will get its filter-aware connections. Stage 4 uploads in one batch; for large loads you would batch 64 to 256 points per request, and use the client's upload_points helper with parallelism. Stage 5 wraps a filtered query in a function, which is the shape a web endpoint would have.

To turn this into a real application, replace the made-up vectors with an embedding model's output. Use the same model, with the same length, for the stored documents and for each query; put the original text in the payload so you can show it, because Qdrant does not keep your input text unless you store it yourself. Wrap recommend in a small FastAPI endpoint, and if the application is a question-answering system over documents, look at how LangChain and LlamaIndex use Qdrant as a vector store, and at RAGAS for measuring whether the retrieval is good.

Finally, take the project one step toward a real deployment: stop the container (docker stop qdrant), start it again (docker start qdrant), and run only the search part. The collection is still there because the storage folder survived the container. That is persistence working as designed.

What you can now do, and what comes next

You can now explain what a vector database is for and where Qdrant sits between an embedding model and your application. You know the four nouns (collection, point, vector, payload) and the first-day vocabulary around them (segment, WAL, optimizer, shard, alias). You can pick a distance metric, run Qdrant in Docker with persistent storage, verify it with a health check, and read its version. You created a collection, upserted points, searched with the Query API, filtered on payload, scrolled, counted, and deleted. You know why payload indexes come before ingestion, how to configure Qdrant through environment variables, how to lock a fresh server down, and how to read the common errors.

The habits worth keeping are few. Pin the version. Decide vector length and metric from the embedding model before creating anything. Create payload indexes before uploading data. Add wait=true to curl writes. Bind to localhost or set an API key. Use the Query API rather than the deprecated search endpoints. Store the original text or a link back in the payload.

What comes next is in the mid-level guide: updating payloads and vectors precisely, batch operations, the update_mode and conditional-update options, facets and grouping, hybrid search with dense and sparse vectors, fusion, recommendation and discovery queries, full-text indexes, quantization to shrink memory, memory tiers, snapshots and aliases for safe re-indexing, and monitoring. The senior guide covers clusters (shards, replicas, consensus), capacity planning, multi-tenancy, security in depth, upgrades (never skip a minor version), and when to choose something other than Qdrant. If you want to compare approaches, read the guides on Pinecone, Weaviate, Milvus, Chroma, and pgvector, and then decide on your own data which fits.

Sources

• Qdrant documentation
• Overview
• Installation
• Quickstart
• Collections
• Points
• Vectors
• Payload
• Indexing
• Search
• Filtering
• Configuration
• Security
• Common errors
• Web UI
• API reference
• Qdrant releases on GitHub
• Qdrant on Docker Hub

Part one of three. A twenty-five-minute review of the Beginner Detailed track, then the questions interviewers ask about Qdrant and vector search. Mid-level reviews this plus its own material; Senior reviews all three. The version referenced throughout is Qdrant v1.19.1.

The thirty-second answer

Qdrant is an open-source vector database written in Rust. You store points, each with an ID, one or more embedding vectors, and a JSON payload, inside a collection. You search by sending a query vector and getting back the nearest points, optionally restricted by a filter on the payload. It uses an HNSW graph index for fast approximate nearest-neighbour search, and it is reached over REST on port 6333 or gRPC on port 6334.

Then the line that shows you have used it: "similarity decides the order, the filter decides who is allowed in, and I create payload indexes before I load the data."

The model

Three sentences an interviewer likes to hear. First, "a vector database stores embeddings and answers nearest-neighbour queries, with metadata filtering and persistence that a bare index library lacks." Second, "search is approximate by default, so I treat exact mode as a testing tool." Third, "every vector in a collection has the same length, so the embedding model is chosen before the collection."

Commands and calls to have ready

You will not be asked to recite flags, but you should be able to produce these without looking them up.

docker run -p 6333:6333 -p 6334:6334 \
  -v "$(pwd)/qdrant_storage:/qdrant/storage:z" qdrant/qdrant:v1.19.1
curl http://localhost:6333            # welcome message with version
curl http://localhost:6333/healthz    # 200 when healthy

# create
PUT  /collections/cities              {"vectors": {"size": 4, "distance": "Cosine"}}
# insert / replace
PUT  /collections/cities/points?wait=true   {"points": [{"id": 1, "vector": [...], "payload": {...}}]}
# search
POST /collections/cities/points/query {"query": [...], "filter": {...}, "limit": 3, "with_payload": true}
# list without ranking
POST /collections/cities/points/scroll {"limit": 100, "offset": <next_page_offset>}
# count
POST /collections/cities/points/count  {"filter": {...}, "exact": true}
# payload index
PUT  /collections/cities/index        {"field_name": "budget", "field_schema": "keyword"}

The Python client equivalents: QdrantClient(url=...), create_collection(... vectors_config=VectorParams(size=..., distance=Distance.COSINE)), upsert(... points=[PointStruct(...)]), and query_points(... query=..., query_filter=Filter(...), limit=...). Say, if asked, that older tutorials use client.search() and /points/search, which are deprecated in favour of the Query API.

The classic traps and why they happen

The wrong vector length. The collection fixes the number of dimensions at creation. Sending 384 numbers to a 768-dimension collection is rejected. It happens because someone switched embedding models without creating a new collection. Say: "the vector length belongs to the model, so a model change means a re-embed and a new collection."

Scores that look like percentages. A Cosine score of 0.9 is not 90 percent relevant. Scores are only meaningful for ranking within one query on one collection. Hard-coded global cut-offs are a smell; measure them on your own data instead. Also remember that for Euclid and Manhattan a lower number means closer.

The query returns nothing. Usual causes: the write was not applied yet (raw REST and the Go and Rust clients default to wait=false), a typo in the filter key (a filter on a missing field silently matches nothing), a type mismatch ("5" versus 5), or searching a named vector without using.

An exposed, unauthenticated server. A self-hosted Qdrant starts with no authentication and no TLS and listens on all interfaces. Publishing 6333 to the internet in that state hands anyone full control. The fix is binding to 127.0.0.1, setting QDRANT__SERVICE__API_KEY, and never publishing the internal port 6335.

Data lost on container removal. The data lives in /qdrant/storage inside the container. Without a volume or bind mount, removing the container removes the collections. On Windows with WSL, use a named volume rather than a bind mount of a Windows folder, because the latter is not POSIX-compatible and can corrupt data.

Slow filtered search. Filtering on an unindexed payload field works but forces payload inspection. Even worse, if you add the index after loading, the graph's filter-aware connections are not built until it is rebuilt. The habit: payload indexes first, data second.

An empty indexed_vectors_count. Small segments are scanned rather than indexed (the default threshold is about 10,000 KB of vectors), so a toy collection shows zero indexed vectors. It is not an error.

Overwriting instead of updating. Upserting an existing ID replaces the whole point. Sending only a new payload with no vector drops the vector.

Common interview questions

What is a vector database and why not just store vectors in PostgreSQL? A vector database stores embeddings and answers nearest-neighbour queries efficiently, with filtering, updates, and persistence. Storing vectors in PostgreSQL is a legitimate option through the pgvector extension, and it is attractive when you already run PostgreSQL and your data is modest. A dedicated engine such as Qdrant is attractive when vector search is a core workload, you need strong filtering performance at scale, you want quantization and distributed deployment, or you want to scale search independently from your relational database. A strong answer names the trade-off rather than picking a winner, and it mentions that many teams keep the source of truth in a relational database and only the searchable representation in the vector store.

What is an embedding? A list of numbers produced by a model, so that content with similar meaning has vectors that are close together. The embedding model, not Qdrant, determines the quality of "similar". Qdrant stores and searches the vectors; if you run it yourself it does not create them unless you use a client helper such as FastEmbed.

How does Qdrant search quickly over millions of vectors? It builds an HNSW graph, a layered navigable graph. A search starts at the sparse top layer, hops greedily toward the query, descends through denser layers, and collects the nearest candidates at the bottom. This is approximate: it trades a tiny amount of recall for large speed gains. The controls are m (links per node, default 16), ef_construct (build effort, default 100), and hnsw_ef at query time.

Is the search exact? No, by default it is approximate. A query can ask for an exact scan, which is slower and useful for evaluating how good the approximation is. Segments below the indexing threshold are scanned anyway, so tiny collections behave exactly.

How do you choose a distance metric? Use the one the embedding model was trained for, as stated on the model card. Cosine for most text embeddings, Dot where the model says so (and always for sparse vectors), Euclid or Manhattan for distance-style models. Cosine in Qdrant normalises vectors on upload and then uses a dot product.

What is the difference between a collection and a point? A collection is the container with fixed vector length and metric; a point is one record inside it with an ID, vector(s), and payload. Search happens within a collection.

What goes in the payload and how do you use it? Metadata: the original text or a pointer to it, category, language, date, tenant. You can return it with results (with_payload) and filter on it. Filters use must, should, and must_not clauses with conditions like match and range.

Why create payload indexes before inserting data? A payload index speeds up filtering and informs the query planner. Qdrant also adds extra graph connections for indexed fields so that filtered search stays well connected, but only for indexes that exist when the graph is built. Creating them after loading means a rebuild is needed to get that benefit.

What does wait=true do? It makes a write request return only after the change is applied, so an immediate search sees it. The Python, JavaScript, .NET, and Java clients default to waiting; raw REST, Go, and Rust do not.

What is a scroll and when would you use it instead of search? Scroll pages through points, optionally filtered, in ID order without similarity ranking. Use it to export, to list everything matching a filter, or to process points in batches. It returns next_page_offset, and null means you are on the last page.

How do you keep Qdrant data safe on a laptop or a single VM? Persist storage on a POSIX block filesystem via a volume, pin the image version, bind to localhost or set an API key, and take snapshots (a mid-level topic) before upgrades. Never expose port 6335.

What happens to deleted points? They are soft-deleted at once, so they vanish from results immediately, and the optimizer later reclaims the space.

What would you check if search results look irrelevant? First the data path: that the same embedding model produced the stored vectors and the query vector, and that the metric matches the model. Then the filter: that it is not excluding good matches. Then the content: that the payload and chunking make sense. Only then touch index parameters. Most bad results are model or data problems, not index problems.

What are named vectors? Several vectors per point, each with its own size and metric, for example an image vector and a text vector. You select one at query time with using.

Where does Qdrant sit relative to RAG? In retrieval-augmented generation, Qdrant stores document chunk embeddings. At question time the question is embedded, Qdrant returns the nearest chunks, and a language model answers using them. Frameworks such as LangChain and LlamaIndex integrate it as a vector store. See the LangChain, LlamaIndex, and RAGAS guides for neighbouring topics.

How does it compare with FAISS, Pinecone, or Chroma? FAISS is an index library without a server, persistence layer, or metadata filtering; you build those yourself. Pinecone is a managed service. Chroma is an easy-to-start database aimed at prototypes. Qdrant is open source, can be self-hosted or used as a managed cloud, and has an expressive filtering model. Do not claim one is "best"; say which constraints push you toward each. The catalogue has guides for FAISS, Pinecone, and Chroma.

If your employer needs data to stay in-region, what are your options? Self-host Qdrant on infrastructure in the approved region, which keeps vectors and payloads there, or use a managed option only where its available regions satisfy the policy. Mention that embeddings can still leak information about the source text, so they deserve the same classification as the source data.

Phrases that mark a strong answer

Interviewers listen for specifics. Strong candidates say "I would pin the version", "I would check the model's recommended metric", "I would create payload indexes before ingestion", "I would not treat the score as a probability", and "I would add an API key and bind to localhost". Weak candidates say "vector databases are fast because they use AI", which is wrong: nothing in the index uses machine learning, only the embedding step does.

Be ready for an honest limits question. Say what you do not know yet: clustering, quantization, hybrid search, and snapshots are mid-level and senior topics, and you know they exist and roughly what problem each solves. That is better than bluffing.

A short worked scenario

An interviewer says: "You have 50,000 help-centre articles in Arabic and English and a user types a question. Sketch the Qdrant side."

A good answer runs like this. Choose a multilingual embedding model and note its vector length and metric. Create one collection with that size and metric. Put the article text, language, product area, and URL in the payload. Create payload indexes on language and product_area before loading. Chunk long articles, embed each chunk, and upsert in batches with the article ID in the payload so results can be grouped back to articles. At query time, embed the question with the same model, query with a filter on language if needed, ask for a limit such as 5, return the payload text, and show the URLs. Run Qdrant with a pinned version, a persistent volume, an API key, and localhost or private network binding. Then say how you would measure quality, for example with a small set of questions and known good articles. Notice that this answer is mostly design decisions, not commands.

Follow-up questions that test understanding

Interviewers often follow a good first answer with a probe. Prepare for these.

"You said search is approximate. How would you know if it is good enough?" Run the same queries once with the default search and once with the exact option, then compare how many of the true nearest neighbours the default returned. That fraction is the recall. If it is high enough for your use, keep the defaults. Only then consider raising hnsw_ef at query time, which costs latency, before touching build-time settings.

"Your collection has ten rows and the index count is zero. Is it broken?" No. Small segments are scanned rather than indexed, and the counts are approximate anyway.

"A teammate wants one collection per customer. Thoughts?" For a beginner-level answer, say that many small collections is generally discouraged and that a single collection with a customer field in the payload, filtered on every query and indexed, is the usual starting point. Admit that the detailed multi-tenancy options are a later topic.

"The embedding model got an upgrade. What do you do?" The new vectors are not comparable with the old ones, even if the length is the same. Create a new collection, re-embed all content, load it, test it against your known queries, then switch the application over. Aliases make that switch smooth, and you can mention that you will learn them at the next level.

"What would you not store in the payload?" Anything that is large and rarely needed (put it in object storage and store a link), anything secret that should not come back from a search, and anything whose type will vary from point to point.

Sixty-second self-test

Answer out loud, then check yourself.

1. What four things does a point contain, and which are optional?
2. Why can't you put a 384-dimension vector into a 768-dimension collection?
3. Which direction is "closer" for Cosine, and which for Euclid?
4. Which endpoint do you call to search, and which older endpoints should you avoid?
5. What are the three filter clauses?
6. Why create a payload index before loading data?
7. What does wait=true change?
8. Why does indexed_vectors_count read 0 on a tiny collection?
9. What happens if you upsert an ID that exists?
10. Give three steps to make a fresh server safe to leave running.

Answers: (1) ID, one or more vectors (a point may have none), payload; vectors and payload are optional, the ID is required. (2) Vector length is fixed at collection creation, and distance between different lengths is meaningless. (3) Higher is closer for Cosine; lower for Euclid. (4) POST /collections/{name}/points/query; avoid /points/search, /points/recommend, and /points/discover. (5) must, should, must_not. (6) The extra graph connections for filtered search are only built for indexes that exist when the graph is built. (7) The request returns after the change is applied, so reads see it. (8) Segments below the indexing threshold are scanned, not indexed. (9) The whole point is replaced. (10) Bind to 127.0.0.1 or a private network, set an API key, persist storage on a proper volume, and never publish port 6335.

Part one of three. Most beginner problems with Qdrant come from four root causes: the vector length or metric does not match the embedding model, the data was loaded before the indexes existed, the server was left open to the network, or an old tutorial taught a deprecated call. Start with the mistakes, then the habits and the checklist. Version referenced: Qdrant v1.19.1.

Mistakes beginners actually make

Each entry gives the symptom, the cause, and the fix.

Wrong vector length

Symptom. An upsert or a search fails with an error naming the expected number of dimensions.

Cause. The collection was created for one embedding model, and the vectors now come from another. Qdrant fixes the vector length when you create a collection, and it cannot compare vectors of different lengths.

Fix. Read the model card for the true output length. Create the collection with that size. If you changed models, embed everything again and load it into a new collection; do not try to bend the old one. Keep the model name in your code next to the collection name so the pairing is obvious.

The wrong distance metric for the model

Symptom. Nothing crashes, but results look mediocre, and nobody can say why.

Cause. The collection was created with Cosine, Dot, Euclid, or Manhattan by habit, and the model was trained for a different one.

Fix. Use the metric stated in the model's documentation. For most text embedding models that is Cosine. Remember the direction: higher is closer for Cosine and Dot, lower is closer for Euclid and Manhattan. A model change is the only clean moment to change the metric, because the metric is fixed per collection.

Treating the score as a percentage

Symptom. A product manager asks why the best answer is "only 0.71", and someone hard-codes "reject below 0.8".

Cause. Scores are similarity values, not probabilities. Their range and spread depend on the model and the data.

Fix. Use scores to rank within one query. If you need a cut-off, measure it. Take twenty real queries, list the results you consider good and bad, look at their scores, and pick a threshold from that. Re-measure whenever the model changes. And remember that score_threshold means different things on Euclid collections, where lower is better.

Searching right after writing and getting nothing

Symptom. You upsert with curl, search immediately, and the new points are missing.

Cause. Raw REST requests, and the Go and Rust clients, default to wait=false: the request returns once the operation is accepted, not once it is applied. The Python, JavaScript, .NET, and Java clients default to wait=true, which is why the same code worked in a tutorial.

Fix. Add ?wait=true to the URL of write requests in scripts and tests, or pass wait=True in clients. In high-throughput ingestion you may deliberately use wait=false, but then do not read back immediately.

Filtering that silently returns nothing

Symptom. A search with a filter returns an empty list, but the data is clearly there.

Cause. Almost always a mismatch: a typo in the payload key, a different value spelling ("Egypt" versus "egypt"), or a different type (the string "5" versus the integer 5). A filter on a field that does not exist is not an error; it just matches nothing.

Fix. Fetch one point with with_payload: true and read the exact key and value. Then copy them into the filter. Test the filter with scroll or count before combining it with a vector query, so you know how many points it should allow.

Adding payload indexes after loading millions of points

Symptom. Filtered searches are slower than expected, or the Web UI and logs suggest an index was added late.

Cause. Payload indexes accelerate filtering, and Qdrant also builds extra graph connections for indexed fields, but only for indexes that exist when the graph is built. An index added later does not retroactively add those connections.

Fix. Decide the filter fields at design time and create their indexes while the collection is empty. If you already loaded data, create the index and then trigger a graph rebuild; the mid-level guide shows the technique. Do not index every field either; each one costs memory and slows writes.

Replacing a point when you meant to edit it

Symptom. After "updating" a payload with an upsert, searches no longer find the point, or its vector is gone.

Cause. Upserting an existing ID replaces the whole point. If the request omitted the vector, the point now has none, and a point without a vector is invisible to nearest-neighbour search.

Fix. When you upsert, send the complete point. For changing only metadata, use the payload-specific endpoints (introduced at the mid level), which change keys without touching vectors.

Using deprecated search calls from old tutorials

Symptom. Code copied from an article uses client.search(...), client.recommend(...), or POSTs to /points/search, and later it breaks or looks wrong against current documentation.

Cause. Those wrappers use endpoints that were deprecated in Qdrant 1.13.3 and removed from the API documentation in 1.19, although the server still answers them for now. The upload_records helper is deprecated as well.

Fix. Use POST /collections/{name}/points/query and, in Python, client.query_points(...), whose results live in .points. For bulk loading use upload_points or upload_collection.

Losing all data when the container is removed

Symptom. You restart your laptop or recreate the container and every collection is gone.

Cause. The data lives in /qdrant/storage inside the container. Without a volume or bind mount, it disappears with the container.

Fix. Always mount storage: -v "$(pwd)/qdrant_storage:/qdrant/storage:z". On Windows with Docker Desktop and WSL, use a named volume (docker volume create qdrant-storage, then -v qdrant-storage:/qdrant/storage) because a bind-mounted Windows folder is not POSIX-compatible and can corrupt data, with symptoms such as zeroed vectors after a restart or panics mentioning OutputTooSmall.

Starting two Qdrant processes on one folder

Symptom. The second instance dies with Can't open Collections meta Wal ... Resource temporarily unavailable.

Cause. One storage folder belongs to one process. Two containers mounted to the same folder fight over a lock.

Fix. Stop one, or give each instance its own folder or volume. If you want a second copy for experiments, use a different directory and different host ports.

Leaving a fresh server open to the internet

Symptom. Nothing visibly wrong, until strangers' collections appear, or yours are deleted.

Cause. Self-hosted Qdrant defaults to no authentication, no TLS, and listening on every interface. Publishing the ports on a public IP exposes full read and write access.

Fix. Bind to localhost for development: -p 127.0.0.1:6333:6333. Before any wider exposure, set QDRANT__SERVICE__API_KEY to a long random secret and have clients send it in the api-key header. Never publish port 6335. Keep keys out of Git; supply them from your platform's secret store.

Putting NFS, S3, or a FUSE mount under the storage path

Symptom. A startup warning or error about the filesystem, or crashes under load.

Cause. Qdrant needs a POSIX-compatible block filesystem. Network filesystems and object storage are not supported for the storage path.

Fix. Use a local SSD or NVMe, or a block volume attached to the machine. Read the filesystem warning at startup; it is there to help.

Panicking about indexed_vectors_count: 0

Symptom. The collection info shows indexed_vectors_count of 0 or lower than points_count, and you assume search is slow or broken.

Cause. Segments below the indexing threshold (10,000 KB of vector data by default) are scanned rather than indexed, because a scan is faster for small data. The counts are also approximate.

Fix. Do nothing. If you need exact counts, use the count API with "exact": true. If the collection status is grey, it is waiting to resume optimization after a restart; send any update, for instance PATCH /collections/{name} with {"optimizers_config": {}}.

Running out of file handles

Symptom. Error: Too many files open (OS error 24).

Cause. Each segment keeps files open, and the operating-system limit is lower than what a big collection needs.

Fix. Start the container with a higher limit, for example docker run --ulimit nofile=10000:10000 qdrant/qdrant, or run ulimit -n 10000 before launching the binary.

Skipping versions when upgrading

Symptom. After pulling a newer image, the server fails to start or reports storage errors.

Cause. Qdrant migrates storage one minor version at a time and does not support downgrades. Skipping minors, for example jumping from 1.15 to a later release, can leave data that the new version cannot read; RocksDB was removed in 1.18, so this matters.

Fix. Never use latest for data you care about. Pin the version tag, read the release notes, and step through each minor version's latest patch. Take a snapshot before upgrading. Upgrade client libraries first, then the server.

Habits worth adopting on day one

Pin everything. Use qdrant/qdrant:v1.19.1, not latest, and pin qdrant-client in requirements.txt. A silent upgrade is the most avoidable source of surprise.

Write down the contract. For each collection keep, in code or a README, the embedding model name, its vector length, the distance metric, and the payload fields with their types and which are indexed. Six lines of documentation save an afternoon of debugging.

Design before you load. Create the collection, then the payload indexes, then upload. In that order, every time. Put the sequence in a script so it is repeatable, and make the script delete and recreate the collection in development so reruns start clean.

Store a way back. Put the original text, or an ID and URL, in the payload. Qdrant does not keep the text you embedded unless you store it. Otherwise your search returns points that nobody can display.

Use the same embedding model for documents and queries. And use the same text preparation: the same cleaning, the same chunk size policy, the same language handling. A mismatch is the most common reason for results that "feel off".

Load in batches. For more than a handful of points, upload in batches of roughly 64 to 256 points per request rather than one point per call, and use the client's upload_points helper for large datasets.

Look at the data in the Web UI. The dashboard at http://localhost:6333/dashboard shows collections, points, and payloads, and has a Console for trying requests. Ten seconds of looking beats ten minutes of guessing.

Test the filter alone first. Run a count or scroll with just the filter to see how many points it admits. Then add the vector query.

Keep secrets out of code. API keys come from environment variables or a secret store, never from a committed file or a notebook that you share.

Use localhost by default. Publish ports to 127.0.0.1 until you have an API key, a firewall, and a reason to open up.

Measure retrieval, not just latency. Keep a short list of real questions with the results you expect. Rerun it after any change of model, chunking, or settings. Retrieval-quality tools such as RAGAS automate this later.

Learn one shape of request. Master the Query API request: query, filter, limit, with_payload, and using. Almost every advanced feature is an extension of that single request, so the investment compounds.

A debugging routine that works

When something looks wrong, go through this list in order. It resolves most beginner problems in minutes.

1. Read the exact error text. Qdrant errors usually name the limit or the key at fault.
2. Check the server and version. curl http://localhost:6333 shows the version; /healthz confirms it is up.
3. Check the collection. GET /collections/{name} shows status, points_count, vector configuration, and payload schema. Is the name right? Is it empty? Is the configured size what you think?
4. Fetch one point. Use the retrieve call with with_payload and with_vector true. Confirm the vector length, the payload keys, and the types.
5. Search without a filter. If results appear, the filter is the problem. If not, the vectors or the metric are.
6. Search with a known query. Query by the ID of a stored point: "query": <id>. It should return that point's neighbours. This takes the embedding model out of the picture.
7. Look at the log. The terminal running Qdrant prints warnings and errors, including filesystem checks and configuration failures.
8. Reproduce in the Console. If the same request works in the dashboard Console, the problem is in your client code.

Practice cards

These short exercises build fluency. Do each once, then try again without notes.

Card 1: from nothing to a search. Start Qdrant with a persistent volume, create a three-dimensional Cosine collection, upsert five points with payloads, and search. Time yourself. A first run takes ten minutes; the fifth should take two.

Card 2: break it on purpose. Send a vector of the wrong length, filter on a misspelled key, create the same collection twice, and search a collection that does not exist. Write the symptom and cause of each in your own words.

Card 3: filters. For your six-point dataset, write filters that mean: not in Egypt; budget low or mid; country is Oman and budget is mid; either Egypt or Jordan. Check each with count first.

Card 4: the persistence test. Stop the container, remove it, start a new one with the same volume, and check that your collections remain. Then start one without the volume and watch them disappear.

Card 5: lock it down. Restart with an API key, call /collections without it and with it, and confirm /healthz still answers without. Then restart with ports bound to 127.0.0.1 and try to reach it from another device on your network.

Card 6: swap the metric. Create two collections with the same vectors, one Cosine and one Euclid, run the same query, and compare the order and the direction of the scores.

Checklist before you call it done

• The Qdrant image is pinned to a specific version, and the client library version is pinned.
• Storage is mounted on a persistent volume, not a network filesystem; on Windows with WSL it is a named volume.
• The embedding model, vector length, and distance metric are documented, and the metric matches the model.
• Payload indexes exist for every field you filter on, and were created before the data was loaded.
• Writes in scripts use wait=true (or the client default) when reads follow.
• The code uses the Query API (query_points), not search, recommend, or discover.
• The payload carries what the application needs to display a result: text or a link back.
• The server is bound to localhost or a private network, and an API key is set before it is reachable from elsewhere. Port 6335 is not published.
• Nothing secret is committed to Git.
• You tested filters alone with count or scroll.
• You have a small list of real queries and expected results to rerun after changes.
• You know how to read collection status: green ready, yellow optimizing, grey paused after a restart, red error.
• You have a plan, even a simple one, for backups before any upgrade, and you know never to skip a minor version.

If you can tick every line, your Qdrant setup is in better shape than most first deployments. When you are ready for more, the mid-level guide takes you into hybrid search, quantization, snapshots and aliases, and monitoring.

This is part two of three. It picks up where Beginner ended and takes every topic from there further, then adds the machinery you have not met yet. If you can create a collection, upsert points and run a filtered query, you are in the right place. Here we explain why Qdrant behaves the way it does, so you can predict it instead of discovering it in production. Everything below is checked against Qdrant v1.19.1.

Where this picks up

Each section starts with the problem it solves and ends, in most cases, with a Try it you can do against a local container in a few minutes. Pin the version so the examples match what you read:

docker run -d --name qdrant -p 6333:6333 -p 6334:6334 \
  -v qdrant_storage:/qdrant/storage \
  qdrant/qdrant:v1.19.1

A named volume is used on purpose. It works on every platform, and on Windows with Docker Desktop it avoids the bind-mount trap described later in this guide. If you want a refresher on containers themselves, the Docker guide covers volumes and health checks.

What happens to a write

Most of the surprises people report with Qdrant, such as "I upserted it and it is not in the index yet", or "the collection is yellow for an hour", come from not knowing the path a write takes. Learn the path once and the behaviour becomes predictable.

When a request arrives, the node first appends the operation to the write-ahead log (WAL) with a sequence number. Once an operation is in the WAL it survives a crash or power loss, because on restart Qdrant replays whatever segments had not yet flushed. The WAL is small by design: storage.wal.wal_capacity_mb defaults to 32. It is a durability buffer, not a history.

After the WAL, the operation enters the update queue and is applied to an appendable segment. A segment is the internal storage unit of a shard: it owns its own vector storage, payload storage, payload indexes, ID tracker and, once built, an HNSW graph. A collection always has at least one appendable segment, which accepts new points. Other segments are non-appendable: they serve reads and accept deletes, but not inserts.

At this moment the point is searchable, but not necessarily indexed. A fresh appendable segment has no HNSW graph, so a query over it scans every vector in that segment by brute force. That is fine while the segment is small, which is the whole reason the next stage exists.

The optimizer is a set of background processes. The vacuum optimizer cleans up segments with many deleted points, the merge optimizer combines small segments, and the indexing optimizer builds HNSW and quantized data once a segment crosses indexing_threshold_kb (default 10000, where one kilobyte is roughly one 256-dimension float vector). While a segment is being rebuilt it stays readable: Qdrant wraps it in a proxy with a copy-on-write segment, so queries continue and writes are not lost.

Two facts about deletion matter in practice. Deletes are soft: a bitmask marks the point as gone, and the vacuum optimizer physically reclaims the space later (when the deleted fraction passes deleted_threshold, default 0.2, and the segment has at least vacuum_min_vector_number, default 1000, vectors). And an upsert of identical data still deletes the old copy and inserts a new one, so a nightly job that re-upserts your whole corpus unchanged generates a steady stream of vacuum work.

One more consequence: the wait flag. With wait=true the call returns after the operation is applied to the segments, which gives you read-your-writes. With wait=false it returns as soon as the operation is accepted. The Python, JavaScript, .NET and Java clients default to wait=true; Go, Rust and raw REST default to wait=false. Teams get bitten when a test written with the Python client passes and the same logic through raw REST returns stale data. Always set it explicitly.

Reading collection state without guessing

Collection info is the first place to look, and it is easy to misread. Call it and learn four fields.

curl -s http://localhost:6333/collections/docs | jq '.result | {status, optimizer_status, points_count, indexed_vectors_count, segments_count, warnings}'

status is the colour: green means ready, yellow means the optimizer is working, grey means pending optimizations that have not been triggered, red means an unrecoverable error. optimizer_status carries the detail when it is not ok.

The counts mislead people more than any other field. points_count and indexed_vectors_count are approximate. indexed_vectors_count is zero or well below points_count whenever segments are under the indexing threshold, because small segments are never HNSW-indexed: brute force is faster than graph traversal at that size. That is not an error and no setting needs fixing. If you need the real number, ask for it: POST /collections/{name}/points/count with {"exact": true}.

Since 1.16 the response also contains a warnings array, which flags configuration smells, and an update_queue section that shows points deferred in the queue. Read both before blaming the index. For memory, GET /collections/{name}/memory (added in 1.18) reports usage by structure, and the Web UI has a Memory tab on top of the same data. Treat its figures as a floor: the docs note they underestimate real RAM by roughly 10 to 15 percent.

HNSW, the query planner and why filters get slow

The only dense vector index in Qdrant is HNSW, a layered proximity graph. A search enters at the top layer, walks greedily towards the query, descends, and at the bottom layer explores a candidate list of size ef. Three build parameters set the graph's quality and cost. m is the number of edges per node (default 16). ef_construct is the candidate list used while building (default 100). full_scan_threshold (in KB, default 10000) tells the planner when a scan beats the graph. At query time you set hnsw_ef, which defaults to ef_construct; Qdrant uses max(ef, limit), so asking for 200 results always explores at least 200 candidates.

Raising m, ef_construct or hnsw_ef improves recall and costs memory, build time or latency respectively. The practical order of operations is to measure recall first. Run the same queries with "exact": true in params to get ground truth, then run them with HNSW and compare the overlap. Only tune once you have that number.

curl -s -X POST http://localhost:6333/collections/docs/points/query \
  -H 'Content-Type: application/json' -d '{
    "query": [0.12, 0.31, 0.77, 0.05],
    "limit": 10,
    "params": {"hnsw_ef": 128, "exact": false}
  }'

Filtering is where graph search gets hard. If you traverse a graph and discard nodes that fail a filter, a restrictive filter can disconnect the graph, so the search wanders and returns too few results. Qdrant's answer is filterable HNSW: for each indexed payload field it adds extra edges, so the subgraph for a given value stays connected. The crucial detail is that those edges are built only for payload indexes that exist when the graph is built. Create your payload indexes before you ingest, or you will have to rebuild.

The query planner then picks a strategy per query. It estimates the cardinality of the filter, using the payload index when there is one. If the filter matches few points (below full_scan_threshold), it skips the graph and scans just those points through the payload index, which is exact and fast. If the filter matches many, it uses filtered HNSW. Without a payload index the planner has no estimates and may scan payloads point by point, which is why a missing index is the first suspect for slow filtered search.

Two knobs help when filtered recall is poor. ACORN (added in 1.16) widens the traversal during filtered search: "params": {"acorn": {"enable": true, "max_selectivity": 0.4}}. It costs latency, so enable it per query where it matters. And payload_m plus m: 0 lets you build per-value graphs only, which is the multitenancy setup covered later.

Payload indexes and filtering in depth

A payload index is a per-field structure that speeds up filtering and gives the planner accurate estimates. It is not automatic. You create it explicitly, per field, with a type: keyword, integer, float, bool, geo, datetime, text or uuid. Index only fields you filter on. Every index costs memory (roughly twice the size of the indexed field's data) and write time.

curl -s -X PUT 'http://localhost:6333/collections/docs/index?wait=true' \
  -H 'Content-Type: application/json' \
  -d '{"field_name": "tenant_id", "field_schema": {"type": "keyword", "is_tenant": true}}'

The simple form, "field_schema": "keyword", is fine for most fields. The parameterised forms give you finer control, and several came in recent releases:

• integer accepts {"type": "integer", "lookup": false, "range": true}: turn off exact lookup when you only ever use ranges, and the reverse.
• keyword accepts "prefix": true, which accelerates {"match": {"prefix": "..."}} conditions (new in 1.19). Without it, a prefix condition on that field is rejected where strict mode is on.
• text accepts a tokenizer (word, whitespace, prefix or multilingual), lowercase, token length bounds, ascii_folding, a Snowball stemmer, stopwords and phrase_matching.
• "enable_hnsw": false skips the extra graph edges for that field. Use it for fields you filter on rarely, so the graph stays small.
• "memory": "cold" moves the index off the heap.
• is_tenant and is_principal are optimisation hints: tenant for the field that partitions your data, principal for the field you range-filter and order by most.

Filters compose with must (AND), should (OR) and must_not (NOR), and they nest. Most conditions you will meet are match (with value, any, except, text, text_any, phrase, prefix), range (also on datetime strings), the geo conditions, values_count, is_empty, is_null, has_id, has_vector, and nested for arrays of objects. Nested keys use dot notation (a.b) and a[].b for arrays. Version 1.19 added a slice condition, {"slice": {"index": 3, "total": 8}}, which carves the collection into deterministic partitions: use it to scroll one collection from eight workers in parallel, or to draw a stable sample.

A trap worth stating plainly: filtering on an unindexed field still works, it is just slow. In v1.19.1, the behaviour of is_null, is_empty and phrase matching on unindexed fields was also fixed, so if you saw odd results there on an older server, upgrade. The remedy for slowness is an index plus, where you want to forbid the slow path entirely, strict mode with unindexed_filtering_retrieve: false, which turns a silent slow query into an immediate, readable error.

Beyond search, filters power other reads. Scroll pages through points matching a filter; it returns next_page_offset, and null means you are on the last page. Add order_by to sort by an indexed field, with direction and start_from, but note it requires a range-capable index and disables next_page_offset. Facets (POST /collections/{name}/facet) count distinct values of a field under a filter, which is how you build a "filter by brand" sidebar without scanning; the field needs a keyword-style index, and "exact": false gives a fast estimate.

from qdrant_client import QdrantClient, models

client = QdrantClient(url="http://localhost:6333")

client.create_payload_index(
    collection_name="docs",
    field_name="published_at",
    field_schema=models.PayloadSchemaType.DATETIME,
)

page, next_offset = client.scroll(
    collection_name="docs",
    scroll_filter=models.Filter(must=[
        models.FieldCondition(key="published_at", range=models.DatetimeRange(gte="2026-01-01T00:00:00Z")),
    ]),
    limit=100,
    with_payload=["title", "published_at"],
)

Updating data without clobbering it

Beginner taught upsert. The first production bug most teams hit is an upsert that wipes data, because upserting an existing ID replaces the whole point. Any vector you leave out becomes null, and the payload you send replaces the old one. If you only want to change part of a point, use the partial operations.

The payload calls accept either explicit points or a filter, so "mark everything from this source as archived" is one request, with no read-modify-write loop. PUT /points/vectors touches only the named vectors, which is how you re-embed one vector space of a multi-vector point without disturbing the others.

Two newer controls solve concurrency problems. update_mode on upsert (since 1.17) takes upsert (the default), insert_only or update_only. Use insert_only for idempotent ingestion where a retried batch must not overwrite newer data, and update_only where a missing point should stay missing. update_filter (since 1.16) makes an update conditional, for example "only write if version is lower than mine". Here is the trap: if you combine update_filter with the default upsert mode, a point that does not exist is simply inserted, because there was nothing to filter. Pair it with update_mode: "update_only".

curl -s -X PUT 'http://localhost:6333/collections/docs/points?wait=true' \
  -H 'Content-Type: application/json' -d '{
    "points": [{"id": 42, "vector": [0.1, 0.2, 0.3, 0.4], "payload": {"version": 7}}],
    "update_mode": "update_only",
    "update_filter": {"must": [{"key": "version", "range": {"lt": 7}}]}
  }'

To apply several changes in order, use POST /collections/{name}/points/batch with an operations list. The operation names are upsert, delete, update_vectors, delete_vectors, set_payload, overwrite_payload, delete_payload and clear_payload. They run in sequence, which makes them a good fit for "delete the old chunks of a document, then upsert the new ones" without a window where the document is half there.

Point IDs are unsigned 64-bit integers or UUIDs. For documents split into chunks, derive a deterministic UUID from the document ID and chunk number (a name-based UUID works well). That makes re-ingestion idempotent: the same chunk always overwrites itself instead of piling up duplicates.

The Query API: prefetch, hybrid search and re-ranking

There is one search endpoint to learn, POST /collections/{name}/points/query, along with its /batch and /groups variants. The older /points/search, /points/recommend and /points/discover routes (and the Python client's search(), recommend() and discover() that wrap them) were deprecated in v1.13.3. They were dropped from the OpenAPI spec in 1.19 but the handlers still answer, so old code works while new code should not use them. Everything they did is a query value now: a vector, a point ID, {"recommend": ...}, {"discover": ...}, {"context": ...}, a fusion, a formula, order_by or sample.

The idea that unlocks the rest is prefetch. A prefetch is a sub-query whose results feed the main query. The main query then either re-scores those candidates against another vector or fuses the lists. Prefetches nest, so you can describe a multi-stage pipeline in one request. The rule to remember: a prefetch limit must be at least the main limit plus offset, or you will starve the outer stage.

Hybrid search is the common case. You keep a dense vector for meaning and a sparse vector for exact terms, query both, and fuse:

{
  "prefetch": [
    {"query": {"indices": [1, 42], "values": [0.22, 0.8]}, "using": "sparse", "limit": 20},
    {"query": [0.01, 0.45, 0.67], "using": "dense", "limit": 20}
  ],
  "query": {"rrf": {}},
  "limit": 10
}

A sparse vector is {"indices": [...], "values": [...]} with equal-length arrays and unique indices. It must be a named vector, its distance is always Dot, and the collection declares it under sparse_vectors. For BM25-style weighting set "modifier": "idf" so Qdrant applies inverse document frequency at query time from the collection's statistics.

Fusion has two flavours. RRF (reciprocal rank fusion) uses ranks only, so it needs no score normalisation: {"rrf": {"k": 60}} tunes the damping constant, and {"rrf": {"weights": [3.0, 1.0]}} (since 1.17) lets one list count more than another. DBSF ({"fusion": "dbsf"}) normalises scores by their distribution before summing. RRF is the safe default when the two score scales are unrelated. In a collection with several shards, the fusion must be the main query, not buried inside a prefetch, for results to merge across shards correctly.

Multi-stage search trades cost for precision. Prefetch with a small or truncated vector (a Matryoshka-style prefix) to get a wide candidate set cheaply, then re-score with the full vector, and optionally again with a multivector (ColBERT-style late interaction). Vectors used only for rescoring do not need a graph, so set m: 0 on them and save the build cost. A multivector is a matrix of same-sized vectors per point configured with multivector_config: {"comparator": "max_sim"}, and it has a hard cap: the number of sub-vectors times the vector size must stay below 1,048,576.

Three other query shapes are worth knowing by name.

• Grouping (/points/query/groups) returns the best hits per value of a payload key, so you can show one result per document instead of five chunks of the same one. Only keyword and integer keys work, and there is no offset.
• MMR (maximal marginal relevance, {"nearest": [...], "mmr": {"diversity": 0.5, "candidates_limit": 100}}) trades some similarity for diversity, which suits recommendation and RAG context windows full of near-duplicates.

Search parameters sit under params: hnsw_ef, exact, indexed_only, quantization (with ignore, rescore, oversampling), acorn, and, new in 1.19, idf.corpus, a filter that defines which documents count toward IDF statistics. That last one matters for multitenancy: without it, one tenant's vocabulary skews another's term weights. If the corpus filter matches nothing, every term gets the same weight, so verify it with a test query.

Memory tiers and capacity arithmetic

The question every operator asks is "how much RAM will this need?" Qdrant lets you answer it with arithmetic, and v1.19 gave you a single control for where each structure lives.

All data is always persisted on disk. The memory tier only decides what stays in RAM. There are three: pinned (on the heap, never evicted), cached (memory-mapped and pre-warmed into the OS page cache at startup) and cold (memory-mapped, not pre-warmed, so the first reads hit disk). You set it with a memory key on each structure: dense vectors, the HNSW index, quantized vectors, the sparse index, the payload and payload indexes. The defaults are sensible: dense vectors cached, HNSW cached, payload cold, payload indexes pinned, sparse index pinned, and quantized data pinned if the originals are cached and cold if the originals are cold. pinned is rejected for dense vectors and payloads.

Version 1.19 deprecated the older keys in favour of this one, and they are not auto-converted, so a config you wrote last year keeps its old keys until you change them. The mapping is: on_disk on vectors becomes memory; hnsw_config.on_disk becomes hnsw_config.memory; quantization always_ram becomes memory: pinned; sparse index.on_disk becomes index.memory; and on_disk_payload becomes payload.memory. The old mmap_threshold setting is legacy as well, and you will still see it in some pages; express the intent with memory: cold instead.

curl -s -X PUT http://localhost:6333/collections/docs \
  -H 'Content-Type: application/json' -d '{
    "vectors": {"size": 768, "distance": "Cosine", "memory": "cold"},
    "hnsw_config": {"memory": "cached"},
    "quantization_config": {"scalar": {"type": "int8", "quantile": 0.99, "memory": "pinned"}},
    "payload": {"memory": "cold"}
  }'

For capacity planning, work from base = points * replication_factor and add the pieces:

Add roughly 20 percent headroom for RAM and disk, and keep each node under about 80 percent of physical RAM. A worked example from the docs: one million points of 768 dimensions at replication 2, float32, cached, no quantization and a 1 KB cold payload, needs about 7.3 GB of RAM and 10.8 GB of disk. Quantizing to 4-bit TurboQuant, pinned, with the originals cold, drops the vector RAM from about 5.7 GB to about 0.7 GB.

If your monitoring shows resident memory far above what you planned, check before concluding there is a leak. With cached and cold structures the operating system's page cache counts towards the process, which is normal. Cap it with the container memory limit; the Kubernetes guide explains how limits and requests interact with that behaviour.

Quantization and smaller datatypes

Once the arithmetic says the vectors do not fit, you shrink them. There are two levers and they stack: change the stored datatype, or add a quantized copy.

Datatypes change the originals themselves. float32 is the default at 4 bytes per dimension. float16 halves it with, per the docs, practically no loss for most models. uint8 takes one byte but requires values already in the 0 to 255 range. turbo4, new in 1.19, stores 4 bits per dimension (about one eighth of float32) and is for dense vectors only.

Quantization keeps the originals and stores a compressed copy next to them. Candidates are scored against the small copy, which is fast and fits in RAM, and then optionally rescored against the originals. Keeping the originals is deliberate: they are needed for re-indexing and for rescoring. Four methods exist:

{"turbo":   {"bits": "bits4", "memory": "pinned"}}
{"scalar":  {"type": "int8", "quantile": 0.99, "memory": "pinned"}}
{"binary":  {"encoding": "two_bits", "query_encoding": "scalar8bits", "memory": "pinned"}}
{"product": {"compression": "x16", "memory": "pinned"}}

Scalar int8 gives about 4x compression with small accuracy loss. TurboQuant (1.18) gives 8x at its default bits4 and goes down to bits2, bits1_5 and bits1; the docs suggest 4-bit as a sensible default. Binary quantization is the cheapest to evaluate and suits high-dimensional embeddings, and in recent versions it has one-and-a-half and two-bit encodings plus asymmetric query encodings that recover accuracy. Product quantization reaches up to 64x but loses the most accuracy and is slower to compute. Pick by measuring recall on your data, not by reading rankings.

Rescoring is on by default only for binary and TurboQuant at 1, 1.5 and 2 bits. For the other methods you opt in per query, and you can widen the candidate pool with oversampling:

{
  "query": [0.12, 0.31, 0.77, 0.05],
  "limit": 10,
  "params": {"quantization": {"rescore": true, "oversampling": 2.0}}
}

Oversampling 2.0 means "fetch twice as many candidates from the quantized copy, then rescore against the originals and keep the best ten". The cost-optimised recipe from the docs is: quantized vectors pinned in RAM, originals cold on fast local storage, and storage.performance.io_uring: auto so cold reads are asynchronous on Linux. Prefer that setting over the older async_scorer. If the HNSW graph itself must sit on disk, the inline-storage option in the HNSW config stores vectors next to the edges for locality, but do not use it when the graph is in RAM, and pair it with 4-bit or smaller quantization.

You can change quantization on a live collection with PATCH /collections/{name} and a new quantization_config (or the string "Disabled"). The optimizer then rebuilds segments in the background, so expect a yellow status and extra CPU while it works.

Multitenancy: one collection, many customers

A SaaS product often has thousands of customers who each search only their own data. The tempting design is a collection per customer. The FAQ calls that an antipattern: each collection carries fixed overhead, segments and open files, and Qdrant Cloud caps a cluster at 1,000 collections by default. Pick one of three designs instead.

Partition by payload is the default for many small tenants. Put every tenant in one collection, add a tenant_id payload field, index it with is_tenant: true, and filter every query on it. The is_tenant hint lets Qdrant co-locate a tenant's vectors on disk, which speeds up tenant-scoped reads. For the best latency, build graphs per tenant only with "hnsw_config": {"payload_m": 16, "m": 0}. The trade-off is that queries across all tenants become slower, because the global graph no longer exists.

curl -s -X PUT http://localhost:6333/collections/shared \
  -H 'Content-Type: application/json' -d '{
    "vectors": {"size": 768, "distance": "Cosine"},
    "hnsw_config": {"payload_m": 16, "m": 0}
  }'

curl -s -X PUT 'http://localhost:6333/collections/shared/index' \
  -H 'Content-Type: application/json' \
  -d '{"field_name": "tenant_id", "field_schema": {"type": "keyword", "is_tenant": true}}'

Create the index before uploading, for the same reason as before: the per-tenant edges are built only for indexes that exist at graph-build time.

User-defined sharding suits a few large tenants. Create the collection with "sharding_method": "custom", create a shard key per tenant, and send "shard_key": "tenant_a" on every read and write. Each tenant then lives on its own shards, which isolates load, but the physical shard count is shard_number times the number of keys times replication, so it does not scale to thousands of tenants. Point IDs are unique only within a shard key, and reusing an ID across keys is unsupported.

Tiered multitenancy (1.16) combines both. Small tenants share a default fallback shard key and you address them with {"fallback": "default", "target": "tenant_a"}. When a tenant grows (the docs suggest around 20,000 points as the threshold), you promote it: create its shard key in the Partial state with shards_number: 1, copy its points with replicate_points, then delete its data from the fallback. Keep dedicated shards below roughly 1,000 per cluster, and remember the fallback shard must fit on one node.

A security point deserves emphasis. JWT payload filters, which once let a token force a tenant filter, were removed in 1.16. Per-collection JWTs can restrict which collection a token touches, but they cannot inject a tenant filter inside one. Your application, not the token, must add tenant_id to every query, ideally in one shared wrapper function that is covered by tests, because one missing filter leaks data across customers. For Gulf and Egyptian employers with data-residency obligations, this is also a reason to deploy self-hosted Qdrant or a regional cloud cluster in the region where the data must stay, and to keep tenant data from different jurisdictions in separate clusters rather than in separate filters.

Aliases and zero-downtime reindexing

Embedding models change, chunking strategies change, and some index parameters cannot be altered in place. You need a way to rebuild without an outage. An alias is an extra name for a collection, and the key property is that alias changes are atomic.

The blue/green pattern: your application always queries the alias docs. Behind it sits docs_v1. To change the embedding model, create docs_v2 with the new vector size, populate it from your source of truth (never from docs_v1, whose vectors came from the old model), run your evaluation against docs_v2 directly, and then switch the alias in one request:

curl -s -X POST http://localhost:6333/collections/aliases \
  -H 'Content-Type: application/json' -d '{
    "actions": [
      {"delete_alias": {"alias_name": "docs"}},
      {"create_alias": {"collection_name": "docs_v2", "alias_name": "docs"}}
    ]
  }'

Both actions apply together, so there is no instant at which docs points nowhere. Rollback is the same request in reverse. List aliases with GET /aliases or GET /collections/{name}/aliases. Keep docs_v1 until you are confident, then delete it; remember it still occupies disk and RAM in the meantime, and migrations need space for both.

Two limits to plan around. Aliases are not included in collection snapshots, so back up your alias map separately (or re-create it in your deployment scripts). And the old init_from option for copying data at collection creation was removed in 1.16: for Qdrant-to-Qdrant copies use snapshots, or the Migration Tool, which also moves data from other vector databases and from open-source Qdrant to Cloud:

docker run --net=host --rm -it registry.cloud.qdrant.io/library/qdrant-migration qdrant \
  --source.url 'http://localhost:6334' --source.collection 'docs_v1' \
  --target.url 'https://cluster.example.com:6334' --target.api-key "$QDRANT_API_KEY" \
  --target.collection 'docs_v1' --migration.batch-size 64

Version 1.18 also added the ability to add or remove named vectors on an existing collection with PUT and DELETE /collections/{name}/vectors/{vector_name}. That covers the case where you want to add a second embedding (say, a sparse vector) without rebuilding. It does not cover changing the dimension of an existing vector; that still needs a new collection.

Snapshots, backups and upgrades

A vector index is derived data, but rebuilding it from embeddings can take days and cost real money, so you still back it up. The tool is the snapshot: a .snapshot tar archive. A collection snapshot covers one collection on one node. A full storage snapshot covers all collections but works on single nodes only. In a distributed cluster you therefore take a collection snapshot on every node, because each node holds different shards.

# create, list, download
curl -s -X POST http://localhost:6333/collections/docs/snapshots
curl -s http://localhost:6333/collections/docs/snapshots
curl -s -o docs.snapshot http://localhost:6333/collections/docs/snapshots/<snapshot-name>

# restore from a URL or file, into a new or empty collection
curl -s -X PUT http://localhost:6333/collections/docs_restored/snapshots/recover \
  -H 'Content-Type: application/json' \
  -d '{"location": "file:///qdrant/snapshots/docs/<snapshot-name>", "priority": "snapshot"}'

The priority field is the trap. It has three values: replica (the default), snapshot and no_sync. The default prefers the data already on the node, so restoring into a new, empty collection with the default leaves you with an empty collection: the empty "replica" won. Use "priority": "snapshot" whenever the snapshot should win. You can also upload a file with POST /collections/{name}/snapshots/upload?priority=snapshot, sending it as the multipart field snapshot.

Snapshots can be stored on S3-compatible storage by setting storage.snapshots_config.snapshots_storage: s3 and the s3_config block (bucket, region, endpoint, and keys, which you should supply through environment variables such as QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__ACCESS_KEY). Pod role-based authentication is supported since 1.15. Remember one limit: the data directory itself must be on a local block filesystem; only snapshots may go to object storage.

The rules for versions are strict, and they are the part people learn the hard way:

• Never skip a minor version. Go through the latest patch of each minor: from 1.15 to 1.17 means every node first reaches 1.16.3. This applies to single nodes too, because data migrations run at each step. RocksDB was fully removed in 1.18, so jumping across that boundary on old data fails with storage errors.
• Downgrades are not supported, because the storage migration cannot be reversed.
• A node on 1.N talks only to nodes on 1.(N-1) or 1.N during a rolling upgrade.
• A snapshot restores only onto the same minor version or the next one. A 1.18.1 snapshot restores onto 1.18.x or 1.19.x, not onto 1.20 or later directly.
• Upgrade client SDKs before the server. The upgrade page promises compatibility across three minor versions; the FAQ suggests staying within one. Follow the stricter rule.

The procedure for Docker is docker pull, docker stop, docker run with the same volume. For Compose, change the image tag and restart. For Helm, helm upgrade qdrant qdrant/qdrant --version <target>, which performs a rolling StatefulSet update (see the Helm guide for how to review values before upgrading). With replication factor two or more on every collection, a rolling restart is zero-downtime; otherwise expect a short outage. Take snapshots first. Version 1.17 also changed the gRPC vector output format, so any client that parses raw gRPC needs updating alongside the server.

Sharding, replication and consistency

A single node is a fine development setup and a poor production one. In a cluster, each collection is split into shards, and each shard can have replicas on other nodes. Understanding what is and is not replicated through consensus tells you what can fail.

Qdrant uses Raft, but only for cluster metadata: topology and collection operations. Point operations do not go through Raft. A write goes to all active replicas of the shard in parallel, and there is no fixed primary. Any node can coordinate a request: it fans out to the relevant shards, merges the results and answers. Consequently, with two nodes you lose high availability for collection operations (Raft needs a strict majority), and the production standard is three or more nodes with replication factor two or more.

Enable distributed mode with cluster.enabled: true, or the environment variable QDRANT__CLUSTER__ENABLED=true. The first peer starts with --uri and the others join with --bootstrap:

./qdrant --uri 'http://qdrant_node_1:6335'
./qdrant --bootstrap 'http://qdrant_node_1:6335' --uri 'http://qdrant_node_2:6335'

Check with GET /cluster and see where a collection's shards live with GET /collections/{name}/cluster. Port 6335 carries peer traffic and must never be reachable from outside.

Self-hosted Qdrant also does not rebalance on its own, so after adding a node you move shards yourself. Shard count is fixed at creation (resharding is Cloud-only), so aim for a multiple of your node count, such as twelve.

curl -s -X POST http://localhost:6333/collections/docs/cluster \
  -H 'Content-Type: application/json' -d '{
    "move_shard": {"shard_id": 1, "from_peer_id": 111, "to_peer_id": 222, "method": "wal_delta"}
  }'

The transfer methods differ. stream_records is the robust default: it streams points and re-indexes on the target, with weak ordering. snapshot carries the built index and quantization (so no re-indexing) and needs extra disk and the REST port. wal_delta replays only the missing operations to an existing replica and is what automatic recovery of a dead replica uses first. If the delta cannot be resolved, Qdrant falls back to stream_records, or to a snapshot since 1.18. By default one incoming and one outgoing transfer run at a time per node, which you can tune with incoming_shard_transfers_limit and outgoing_shard_transfers_limit.

Consistency is tunable per request. On writes, ordering is weak (default), medium or strong, and the collection's write_consistency_factor says how many replicas must confirm. If fewer active replicas exist than that factor, the write fails, and it may have been partially applied: retry it. On reads, consistency accepts all, majority, quorum or an integer, with a default of 1. Two newer tools help latency. read_fan_out_delay_ms (collection param, 1.17) sends a read to a second replica only if the first has not answered within the delay; set it near your p95 latency. And the X-Qdrant-Route-Affinity header (1.19) pins reads to one replica, so repeated queries hit warm caches and users see stable results.

Configuration management and securing a deployment

A fresh self-hosted Qdrant has no authentication, no TLS, and listens on all interfaces with CORS enabled. The docs say plainly that this is not production-ready. Securing it is a small, ordered list of changes, and getting the configuration into version control correctly matters as much as the changes.

Configuration layers, lowest to highest priority: embedded defaults, config/config.yaml, config/{RUN_MODE}.yaml (the Docker image sets RUN_MODE=production, so config/production.yaml), config/local.yaml, a file passed with --config-path, and finally environment variables, which always win. Variables use the QDRANT__ prefix and __ for nesting: QDRANT__SERVICE__API_KEY, QDRANT__CLUSTER__ENABLED=true, QDRANT__STORAGE__PERFORMANCE__IO_URING=auto. The config is validated at startup and an invalid value aborts it with a message naming the key, so a typo fails the deploy early instead of misbehaving later. Qdrant Cloud does not allow editing the config.

A sound pattern is to commit a non-secret production.yaml and inject secrets as environment variables from your secret manager (see the Vault guide):

log_level: INFO
service:
  host: 0.0.0.0
  enable_tls: true
  jwt_rbac: true
  enable_snapshot_url_recovery: false
tls:
  cert: /qdrant/tls/cert.pem
  key: /qdrant/tls/key.pem
storage:
  performance:
    io_uring: auto
telemetry_disabled: true

Authentication has three key slots: service.api_key (full access), read_only_api_key, and alt_api_key (added in 1.17 for rotation). Clients send the key in the api-key header, or as Authorization: Bearer <token>. The health endpoints /healthz, /livez and /readyz stay open even with a key set, so probes keep working.

JWT RBAC (jwt_rbac: true) gives you scoped tokens. They are signed HS256 using the api_key, so rotating the api_key invalidates every issued token. Claims include exp (checked with a 30-second leeway), access ("r", "m", or a per-collection list such as [{"collection": "docs", "access": "r"}]), value_exists for revocation by payload lookup, and sub, which appears in the audit log. A collection-scoped token cannot create or delete collections, read /metrics or /telemetry, or use full snapshots. Use read-only per-collection tokens for services that only search.

Zero-downtime key rotation is four steps: set the new key as alt_api_key and do a rolling restart; switch clients to the new key; promote the new key to api_key and remove alt_api_key with another rolling restart; re-issue JWTs.

Network and runtime hardening: bind to 127.0.0.1 locally (-p 127.0.0.1:6333:6333) and to a private address in production; enable TLS with service.enable_tls and the tls block (add cluster.p2p.enable_tls with tls.ca_cert for peer traffic); run the -unprivileged image or a non-root user with a read-only root filesystem, mounting volumes only at /qdrant/storage and /qdrant/snapshots; and block egress with a Kubernetes NetworkPolicy or an internal Docker network, allowing only ports 6333 to 6335 between peers and cluster DNS. That egress block mitigates server-side request forgery through snapshot recovery, which is also why you should set enable_snapshot_url_recovery: false unless you need it. Since 1.18 you can also set service.enforce_internal_auth: true so peers verify the forwarded key on the internal port, but enable it only after every node is upgraded, and still keep 6335 private. Audit logging (audit: block, 1.17) writes JSON logs to ./storage/audit, daily rotation, seven files kept; set trust_forwarded_headers: true only behind a proxy you control.

Strict mode and quotas: guardrails for a shared cluster

When many teams or tenants share a cluster, one bad query can hurt everyone. Qdrant provides two layers of guardrails: strict mode per collection, and quotas per cluster.

Strict mode (strict_mode_config, set at creation or with PATCH) rejects requests that break limits you define. The most useful keys: max_query_limit caps limit; max_timeout caps request time; search_max_hnsw_ef and search_allow_exact stop someone from forcing exhaustive search; unindexed_filtering_retrieve and unindexed_filtering_update forbid filtering on fields with no index; max_payload_index_count, filter_max_conditions and condition_max_size bound filter complexity; upsert_max_batchsize caps batch size; max_points_count and the collection size caps bound growth; and read_rate_limit and write_rate_limit (operations per minute per replica) answer with HTTP 429 and a retry delay. Enabling strict mode with no limits set has no effect, so set at least a few. Qdrant Cloud enables it by default, and since 1.16 self-hosted no longer explicitly disables it by default either.

curl -s -X PATCH http://localhost:6333/collections/docs \
  -H 'Content-Type: application/json' -d '{
    "strict_mode_config": {
      "enabled": true,
      "max_query_limit": 200,
      "unindexed_filtering_retrieve": false,
      "write_rate_limit": 6000
    }
  }'

Quotas (1.19) protect the node itself. PUT /quotas sets cluster-wide limits such as max_disk_usage_percent and max_resident_memory_percent, with a release_margin_percent so a node does not flap at the boundary. When a write cannot land, clients get HTTP 507 or gRPC ResourceExhausted, with a message like "Disk usage is at 95% of total capacity, exceeding the configured limit of 90%". Reads are never blocked, and deleting points is always allowed, whereas deleting vectors or payload keys is rejected because it does not free space reliably. Once you set quotas through the API, storage.quotas in the config file is ignored. The older strict-mode max_resident_memory_percent is deprecated in favour of quotas.

Observability and debugging beyond the basics

You cannot run a vector database on feelings. Qdrant exposes Prometheus-format metrics at /metrics on each node, so scrape every peer, not the load balancer. Since 1.17 a dedicated metrics port is available so that scrape traffic can be firewalled separately. Metric names have no prefix unless you set service.metrics_prefix (for example qdrant_), so choose that before you build dashboards. Per-collection API metrics come with /metrics?per_collection=true (1.18). See the Prometheus guide and Grafana guide for scraping and dashboards, and the OpenTelemetry guide for tracing your own client calls.

A starter set of series to alert on, with the question each answers:

For Kubernetes probes, use /readyz for readiness and /livez for liveness. Do not use a search query as a probe.

When a specific request is slow, three endpoints help. The slow request log, GET /profiler/slow_requests?limit=20&request=search (1.16, needs manage access), records shard operations over 50 ms, keeps 32 entries per request type, and holds them in memory per node, so query each node. GET /collections/{name}/optimizations shows what the optimizer is doing. And /telemetry and /cluster/telemetry show shard transfer progress.

Bulk ingest, testing and CI

Loading millions of vectors well is mostly about not fighting the optimizer. The docs' guidance: batches of 64 to 256 points per request, 2 to 4 parallel workers (about one per shard), and 2 to 4 shards per machine for large uploads. Create payload indexes first, and for datasets bigger than RAM upload straight into cold vectors. The Rust client is the fastest; in Python use upload_points or upload_collection with parallel and max_retries. upload_records is deprecated.

from qdrant_client import QdrantClient, models

client = QdrantClient(url="http://localhost:6333", timeout=60)

def points(rows):
    for i, (doc_id, vec, meta) in enumerate(rows):
        yield models.PointStruct(id=doc_id, vector=vec, payload=meta)

client.upload_points(
    collection_name="docs",
    points=points(load_rows()),
    batch_size=128,
    parallel=4,
    max_retries=3,
)

For testing, run a real Qdrant. Do not mock the client for retrieval logic, because the behaviours that bite (filters, scores, thresholds) live in the server. A disposable container per test session is cheap. Qdrant Edge, an in-process build for Python and Rust that uses the same storage format, is useful for unit tests and embedded apps without a server, but check its feature coverage against what your production queries use.

services:
  qdrant:
    image: qdrant/qdrant:v1.19.1
    ports: ["6333:6333"]
    healthcheck:
      test: ["CMD-SHELL", "bash -c ':> /dev/tcp/127.0.0.1/6333' || exit 1"]
      interval: 5s
      timeout: 3s
      retries: 10

A CI job should start the container, wait for /readyz, create collections from the same schema code production uses, load a small fixed fixture, and assert on the results of a handful of golden queries, including filtered ones and one tenant-isolation case. Keep the schema as code, such as one function that returns the collection config, so tests and production cannot drift. Pin the server image tag to the minor you run in production and bump both in the same pull request. When you bump, run the suite against the intermediate minor versions as well, since the rule is that upgrades step through each one.

Putting it all together

Here is a realistic mid-level deployment, built from the pieces above: a multi-tenant document search service with hybrid retrieval, shared by a few hundred customers, running on three self-hosted nodes.

1. Design the schema as codeOne function returns the collection config: a named dense vector (float16, cold originals with pinned scalar quantization), a named sparse vector with idf, m: 0 and payload_m: 16, and 6 shards with replication factor 2.
2. Create indexes firstA keyword index with is_tenant: true on tenant_id, a datetime index on published_at, and a prefix-enabled keyword on sku, all before any data is loaded.
3. Ingest idempotentlyDeterministic UUIDs per chunk, update_mode: "upsert" for normal loads, batches of 128 with 4 workers, wait=true set explicitly.
4. Query through one wrapperAn alias, a function that always injects the tenant filter, hybrid prefetch plus RRF, and a per-tenant idf.corpus filter.
5. Guard itStrict mode with a query limit and no unindexed filtering, JWT per service, TLS, a private network, and quotas at 90 percent disk.
6. Observe and back upScrape every node, alert on dead replicas and optimizations that never finish, and snapshot each node nightly to S3-compatible storage.
7. Change safelyReindex into docs_v2, evaluate it with fixed queries, switch the alias atomically, and upgrade one minor at a time with SDKs first.

Where you are now

You can explain a write from WAL to optimized segment, read collection status honestly, build hybrid queries, size memory by arithmetic, choose a quantization by measurement, partition tenants safely, reindex with an alias switch, and upgrade, back up and lock down a deployment. The Senior level covers owning Qdrant as a platform: failure modes under load, which component breaks first, upgrade governance and when another store is the better answer. The FastAPI guide is a natural next stop if you wrap Qdrant behind an API.

Sources

• Qdrant documentation
• Installation
• Upgrades
• Collections
• Points
• Payload
• Indexing
• Quantization
• Storage
• Multitenancy
• Bulk upload
• Search
• Filtering
• Hybrid queries
• Search relevance
• Memory tiers
• Quotas
• Configuration
• Security
• Snapshots
• Capacity planning
• Monitoring
• Slow request log
• Optimizer
• Distributed deployment
• Consistency guarantees
• Node failure recovery
• Common errors
• Release notes

This is part two of three for interviews. At this level, interviewers stop asking "what is a collection" and start handing you a situation: something is slow, something is missing, something must change without downtime. They are listening for whether you reason from how Qdrant works, and whether you measure before you change things. Every answer below is written the way a strong candidate would say it, followed by what separates it from a weak one. The facts are checked against Qdrant v1.19.1.

How to answer scenario questions

A reliable shape for any scenario answer has four beats. First, say what you would observe before acting: the collection status, a metric, the slow request log. Second, name the likely causes in order of probability instead of one favourite. Third, give the fix and its cost. Fourth, say how you would verify it worked. Candidates who skip the first beat and jump to "increase hnsw_ef" tend to lose the interviewer early, because tuning without measurement is the most common mistake in vector search.

Keep one more habit: when you name a setting, name the version-sensitive detail if there is one. Qdrant changed a lot recently, and showing that you know the current form (the Query API instead of /points/search, memory instead of on_disk) signals real, recent experience.

Scenario questions

Filtered search got slow after a data load. What do you check first?

Start with the cheapest observations. Ask whether the filtered fields have payload indexes, since filtering on an unindexed field still works but forces the planner to guess and possibly scan payloads. Check the collection status: if it is yellow, the optimizer is still building segments, and unindexed segments are searched by brute force. Look at indexed_vectors_count against points_count, remembering both are approximate and that small segments are legitimately never indexed.

Then the subtler cause. Filterable HNSW builds its extra edges only for payload indexes that exist when the graph is built. If the team loaded data first and added the index afterwards, the graph lacks those edges, so filtered recall and speed suffer. The fix is to bump ef_construct by one with a PATCH to force a rebuild, and not revert it. After that I would check disks (the docs recommend local SSD with high IOPS), the size of limit and offset, and the slow request log at /profiler/slow_requests to find the exact operations.

To make the problem fail fast next time, I would enable strict mode with unindexed_filtering_retrieve: false.

What a strong answer covers that a weak one misses: the index-before-ingest ordering, the status colour, the slow request log, and a preventive guardrail. A weak answer says "add more RAM".

A query returns far fewer results than the limit, but only with a filter. Why?

Two explanations. The filter may genuinely match few points; verify with a count using the same filter and exact: true. If many points match but search returns too few, suspect the graph traversal. Plain HNSW traversal followed by discarding non-matching nodes can disconnect for a restrictive filter. Qdrant's filterable HNSW and the query planner mitigate this, but only for indexed fields, and ACORN (params.acorn, added in 1.16) widens the traversal for filtered queries at a latency cost. A third possibility is a score threshold: for Euclid, lower is closer, so a score_threshold copied from a cosine setup quietly drops everything.

We changed the embedding model. How do we roll it out without downtime?

Create a new collection for the new model, because vector size and meaning change and you cannot convert in place. Populate it from the source documents, not from the old collection, since the old vectors belong to the old model. Evaluate it against a fixed query set. Then switch an alias with the atomic POST /collections/aliases request that deletes the old alias and creates the new one in one call. The application always queries the alias. Rollback is the same request reversed. Keep the old collection until confident, remembering that both consume disk and RAM, and that aliases are not part of collection snapshots, so the alias map belongs in deployment code.

Strong answers add: evaluation before switching, atomicity, the capacity cost of running two collections, and the removal of init_from in 1.16 (so copying is done by snapshot or the Migration Tool, not at creation).

An upsert "lost" the vectors of some points. What happened?

Upserting an existing ID replaces the whole point. If the new request omitted a named vector, that vector is now null, and the payload was replaced too. The fix going forward is to use the partial operations: PUT /points/vectors to update only listed vectors, and POST /points/payload to set payload keys. For retries and concurrent writers, I would use update_mode: "insert_only" for idempotent ingestion, or update_only plus an update_filter for conditional updates. And I would mention the trap that update_filter with the default upsert mode inserts a missing point.

After restoring a snapshot, the new collection is empty. Why?

The default restore priority is replica, which prefers data already on the node. When restoring into a new, empty collection, the empty replica wins. Use "priority": "snapshot". I would also check the version rule: a snapshot restores only onto the same minor version or the next one, so a snapshot from two minors back fails. In a cluster, snapshots are per node, so I would confirm I had restored every node's snapshot and not just one.

The node's memory looks far higher than we planned. Is it a leak?

Probably not. With cached and cold structures, the operating system's page cache counts towards the resident size, and pre-loading at startup inflates it further. Cap it with a container memory limit and look at GET /collections/{name}/memory for real structure sizes, remembering the docs say it underestimates by about 10 to 15 percent. Then do the arithmetic: vectors (points * replication * dims * bytes), HNSW (base * m * 2 * 4 * 1.2), the always-resident ID tracker (52 bytes per point), payload and indexes. If the plan truly exceeds RAM, reduce it with quantization and tiers: quantized vectors pinned, originals cold.

A strong answer separates page cache from heap, and does the sums. A weak one restarts the pod.

The cluster is slow to respond but CPU is low. Where do you look?

I would check whether reads are hitting disk: process_major_page_faults_total, the tier of the structures, and disk IOPS. Halving the share of vectors in RAM roughly doubles latency, so a recently cold collection explains a lot. Next, whether a replica is dead or recovering (collection_dead_replicas, collection_active_replicas_min), since fewer healthy replicas concentrates load. Then whether clients go through a load balancer: without one, all traffic can pile onto one node. Finally the slow request log on each node, since it is per node and in memory.

Heavy ingestion is hurting search latency. What do you change?

Writes and optimizers compete with reads for CPU and disk. I would first confirm with collection_running_optimizations and the optimizations endpoint that indexing is the contention. Then reduce the pressure in order of least risk: smaller upload batches and fewer parallel workers, optimizer_cpu_budget at about half the vCPUs, and max_optimization_threads at 1 per shard. On the read side, indexed_only stops searches from brute-forcing unindexed segments, and prevent_unoptimized (experimental, used with wait=false) throttles writes until the optimizer catches up. Where possible I would schedule the bulk load for off-peak hours or load into a new collection and switch an alias, so users never query a half-indexed collection.

Trade-off questions

Dense, sparse or hybrid?

Dense vectors capture meaning but can miss exact terms such as part numbers, names or rare jargon. Sparse vectors with the idf modifier give BM25-like keyword matching and are exact on terms. Hybrid search combines them with a prefetch for each and a fusion on top. I would pick hybrid when queries mix natural language and identifiers, which describes most enterprise and Arabic-English mixed corpora, and I would justify it with a measurement on real queries rather than a preference. The cost is a second index and a more complex query. In a multi-shard collection the fusion has to be the main query for correct merging.

RRF or DBSF?

RRF uses ranks only, so it needs no calibration between unrelated score scales and is the safe default. It accepts k and, since 1.17, weights to favour one list. DBSF normalises each list's scores by distribution before summing, which can use score magnitude information that RRF discards, but it depends on the score distributions being well behaved. I would start with RRF, evaluate DBSF only if there is evidence that score magnitude matters, and decide on the evaluation set.

Quantization or a smaller datatype?

They are different levers. A datatype change (float16, uint8, turbo4) shrinks the stored originals themselves. Quantization adds a compressed copy next to the originals and optionally rescores against them. Datatype changes are simpler and float16 is close to lossless per the docs. Quantization lets you keep originals cold on disk and the small copy pinned in RAM, which is the cost-optimised layout. Choose by recall measured on your own data: scalar int8 for about 4x, TurboQuant bits4 for about 8x, binary for the cheapest scoring, product quantization for up to 64x with the largest accuracy loss. Rescoring and oversampling buy back recall at some latency.

Collection per tenant, payload partition, or custom shards?

A collection per tenant is the documented antipattern: each collection has fixed overhead and Qdrant Cloud caps clusters at 1,000 collections by default. For many small tenants, one collection with a tenant_id index marked is_tenant: true and a mandatory filter is the default. For a few very large tenants, user-defined sharding gives isolation but multiplies physical shards. Tiered multitenancy (1.16) combines them: small tenants on a fallback shard key, promoted to dedicated shards at around 20,000 points. The security caveat to volunteer: JWT payload filters were removed in 1.16, so the application must inject the tenant filter on every query.

Self-hosted or Qdrant Cloud?

Self-hosting gives control and data residency, which matters for Gulf and Egyptian employers who must keep data in-country, and it removes per-hour cloud costs. In exchange you own high availability, load balancing, backups, security, upgrades, and manual shard moves and replication, since the Helm chart lacks the operator's automatic rebalancing, resharding and backup features. Cloud, Hybrid Cloud (your infrastructure, their control plane) and Private Cloud (operator, no cloud connection) cover that spectrum. I would decide on residency, team capacity to operate stateful systems, and the cost of an incident.

Qdrant, pgvector or a different store?

If the data already lives in Postgres, the corpus is modest and the team knows SQL, pgvector avoids a second system. Qdrant earns its place when you need filtered high-recall search at scale, hybrid and multi-stage queries, quantization and tiering, or multitenancy features. Say what you would measure: p95 latency under filter, recall, memory per million vectors, operational load.

Operational questions

How do you upgrade a three-node cluster?

Never skip a minor version: step through the latest patch of each minor, because storage migrations run at each step, and downgrades are unsupported. Upgrade client SDKs first. Take a snapshot of every node. With replication factor two or more on every collection, restart nodes one at a time, waiting for the node to rejoin and replicas to return to Active before the next. For Helm, helm upgrade qdrant qdrant/qdrant --version <target> performs the rolling update. Verify with GET /cluster, /readyz and the replica metrics. A gap in the answer I watch for: forgetting that the 1.18 removal of RocksDB makes skipping across that boundary fail.

How would you back up and test a restore?

Snapshots on every node, since a collection snapshot covers one node, shipped to S3-compatible storage, plus the alias map and the collection configuration kept as code. The test is the point: periodically restore into a scratch cluster with "priority": "snapshot" and run golden queries. A backup nobody restored is a hope.

What would you alert on?

Dead or fewer-than-expected replicas, an optimizer that stays busy for hours, open file descriptors against their limit, quota_exceeded, rising p95 latency on the main route, and pending consensus operations. Scrape every node individually, because /metrics is per node, and set service.metrics_prefix before building dashboards.

How do you secure a self-hosted deployment?

The defaults have no auth, no TLS and bind to all interfaces, so: set an API key through an environment variable, enable TLS, use JWT RBAC with read-only per-collection tokens for search services, bind to a private address, keep port 6335 internal, run the unprivileged image with a read-only filesystem, block egress, and set enable_snapshot_url_recovery: false unless you need it. Rotate keys with alt_api_key in four steps. Mention that rotating api_key invalidates JWTs, since they are signed with it.

Version-awareness questions

Which search endpoints should new code use?

Only the Query API: POST /collections/{name}/points/query, plus /batch and /groups. The older search, recommend and discover routes were deprecated in 1.13.3, removed from the OpenAPI spec in 1.19, and their handlers still respond today, so legacy code keeps working but new code should not depend on them. Python's search() wraps the old routes, so use query_points().

What changed with memory settings in 1.19?

A single memory parameter (pinned, cached, cold) replaced on_disk, always_ram and on_disk_payload. The old keys still work and are not converted automatically. Strong candidates also know mmap_threshold is legacy and that pinned is rejected for dense vectors and payloads.

Rapid-fire checks

Be ready for one-line answers. REST is 6333, gRPC 6334, peer traffic 6335 and it must stay private. The ID is an unsigned 64-bit integer or a UUID. Cosine is dot product on normalised vectors. A sparse vector must be named and always uses Dot. wait=true is the default in Python, JS, .NET and Java, but not in Go, Rust or raw REST. Raft covers metadata only; point writes go to all active replicas in parallel. Resharding is Cloud-only, and shard_number is fixed at creation. Two nodes give no collection-operation HA. Snapshots are per node and restore to the same or next minor only.

What interviewers reward, and what they punish

They reward measurement first: exact search as a recall baseline, the slow request log, status colours. They reward knowing the ordering rules that cause real bugs: payload indexes before ingest, snapshot priority, SDKs before servers, one minor at a time. They reward naming costs: quantization loses recall, replication multiplies RAM, an alias switch needs capacity for two collections. And they reward saying what you do not know, then how you would find out.

They punish single-cause answers, unmeasured tuning, mocking the vector store in tests, treating indexed_vectors_count as exact, ignoring tenant isolation in the application layer, and describing deprecated APIs as current.

A short self-test

Answer these aloud without notes. Why can a restored snapshot be empty? Which parameter makes update_filter safe? What happens to the graph if you add a payload index late? Why is the first filtered query after a restart slow on a cold collection? Which tool moves a collection from one embedding model to another with no downtime? If you hesitate on any, reread the matching section of the detailed guide.

This is part two of three for tips. These are the mistakes people make once Qdrant is already running at work, the practices that pay off most, cards to practise on, and recipes you can paste into a terminal. Everything is checked against Qdrant v1.19.1. Where a mistake has a symptom, a cause and a fix, they are given in that order, because the symptom is what you will actually see.

Errors at this level

The upsert that erased vectors

Symptom: after a metadata refresh job, some points return no results from vector search, or a named vector is null. Cause: upserting an existing ID replaces the whole point, so any vector or payload you omitted is gone. Fix: use PUT /points/vectors for vectors and POST /points/payload for payload keys. For ingestion that may be retried, use update_mode: "insert_only", and for conditional changes use update_only with update_filter. Using update_filter alone, with the default mode, inserts a point that does not exist.

The payload index created after the data

Symptom: filtered queries are slow or return too few results even though you "added the index". Cause: the extra HNSW edges that keep filtered search connected are built only for payload indexes that exist when the graph is built. Fix: create indexes before ingestion. If it is too late, bump ef_construct by one with PATCH /collections/{name} to force a rebuild and leave it at the new value.

Reading indexed_vectors_count as truth

Symptom: alarm because the number is zero or lower than points_count. Cause: segments under the indexing threshold (10000 KB) are intentionally not HNSW-indexed, and the counts are approximate. Fix: use POST /collections/{name}/points/count with "exact": true when you need a real number, and look at status and the optimizations endpoint when you need to know whether indexing is progressing.

The empty restore

Symptom: a snapshot restore reports success and the collection is empty. Cause: the default priority is replica, which favours existing data, and the new collection had none. Fix: "priority": "snapshot" for restores into a new or empty collection.

The grey collection after a restart

Symptom: status grey, message "optimizations pending, awaiting update operation". Cause: the node restarted mid-optimization. Fix: any update triggers it, for example PATCH /collections/{name} with {"optimizers_config": {}}.

Skipping a minor version

Symptom: storage errors after upgrading across several minors, especially across 1.17 to 1.18. Cause: migrations run one minor at a time and RocksDB was removed in 1.18. Fix: step through the latest patch of every minor, SDKs first, snapshots before. Downgrades are not supported, so the plan is forward only.

Two nodes on one storage directory

Symptom: Can't open Collections meta Wal: Os { code: 11, kind: WouldBlock ... }. Cause: two processes share a storage path. Fix: one volume per node.

Bind-mounting a Windows folder

Symptom: zeroed vectors after restart, or a panic mentioning OutputTooSmall. Cause: the mount is not fully POSIX-compatible, and the same applies to NFS and FUSE. Fix: a named Docker volume or a local block filesystem.

Too many open files

Symptom: Error: Too many files open (OS error 24). Cause: each segment holds open files. Fix: docker run --ulimit nofile=10000:10000 qdrant/qdrant, or ulimit -n 10000 before starting the binary. Watch process_open_fds against process_max_fds.

Multiprocessing with the Python gRPC client

Symptom: StatusCode.UNAVAILABLE with sendmsg: Socket operation on non-socket (88). Cause: gRPC channels do not survive a fork. Fix: multiprocessing.set_start_method("forkserver") or "spawn", or use REST, the async client, or upload_points(parallel=...).

Write failures with too few replicas

Symptom: writes fail when a node is down. Cause: fewer active replicas than write_consistency_factor, and the write may have been partially applied. Fix: retry once replicas recover, and size replication so one failure does not break the factor.

Using removed or deprecated APIs

Symptom: copy-pasted code from older tutorials uses /points/search, client.search(), upload_records, init_from or on_disk. Cause: these are deprecated, and init_from was removed in 1.16. Fix: query_points(), upload_points, snapshots or the Migration Tool, and the memory parameter.

Practices that pay off most, in order of leverage

1. Measure recall against exact search before tuning anything. Run a few hundred real queries with "exact": true as ground truth and compare the overlap with the indexed results. Every later decision (quantization, hnsw_ef, m) is only meaningful against that number. This single habit prevents more bad tuning than any other.

2. Create the schema, indexes and aliases from code, in the right order. One function builds the collection config, then payload indexes, then the alias. Tests and production call the same function. The ordering rules (indexes before data, SDKs before servers) are encoded once instead of remembered.

3. Always filter by tenant in one place. If you have tenants, there is exactly one function that builds queries, it always adds the filter, and a test proves tenant A cannot read tenant B. JWTs cannot enforce this inside a collection since 1.16.

4. Query through aliases. The application never knows a collection's real name. That gives you blue/green reindexing, atomic rollback and room to change the model.

5. Set wait explicitly and choose consistency deliberately. Client defaults differ by language. For correctness tests use wait=true; for bulk loads use wait=false with batching.

6. Turn on guardrails early. Strict mode with max_query_limit and unindexed_filtering_retrieve: false is cheap, and it converts silent slowness into immediate, readable errors. Add quotas at about 90 percent disk so a full disk degrades gracefully instead of crashing.

7. Pin versions and test upgrades one minor at a time. Pin qdrant/qdrant:v1.19.1, never latest, and run your suite against each intermediate minor on a copy before touching production.

8. Plan memory with arithmetic and tiers. Do the sums (vectors, HNSW, ID tracker, payload, indexes, 20 percent headroom), then place structures deliberately: quantized vectors pinned, originals cold, payload cold. Review the plan whenever the corpus doubles.

9. Scrape every node and alert on trends. /metrics is per node. Alert on dead replicas, a long-running optimizer, file descriptors, quota_exceeded and latency percentiles by route.

10. Rehearse restores. A snapshot you have never restored is an assumption. Restore into a scratch environment with "priority": "snapshot" on a schedule.

Reading symptoms: a quick diagnosis guide

When something is wrong, resist the urge to change a setting. Work from the symptom to the cheapest observation, and only then to a fix. The mapping below covers most of what you will meet.

Queries are slow only with a filter. Look for a missing payload index first, then for an index added after the data, then for a restrictive filter that needs ACORN. If slowness is spread across all queries instead, look at tiers and disk: a cold structure after a restart means first reads come from disk, and process_major_page_faults_total will show it.

Results look worse after a change. Compare against exact search before blaming the model. Quantization without rescoring, a lower hnsw_ef, or a lower m all reduce recall quietly, and so does an unintended score_threshold. For Euclid the direction is reversed, so a threshold designed for cosine drops everything.

Pagination shows duplicates or gaps. That is not a bug: HNSW is approximate, and offset-based pages are computed independently. Paginate on the client, use exact search for small sets, or exclude IDs already shown with must_not and has_id.

The collection is yellow for a long time. The optimizer is rebuilding segments. Check GET /collections/{name}/optimizations to see whether work is queued or running. If you are loading data at the same time, expect it to take longer; reduce upload parallelism or wait.

Memory is high but nothing is wrong. With cached and cold tiers the page cache is counted, and the figure rises after pre-warming. Look at structure sizes, cap with a container limit, and do the arithmetic before you resize a node.

A node will not start. Read the first error line. A config validation failure names the offending key and aborts, which is by design. A filesystem error means the storage is on an unsupported mount. A memory crash loop needs QDRANT__STORAGE__LOW_MEMORY_MODE=no_populate or recovery mode, then a smaller configuration.

HTTP 429 or 507. A 429 means a strict-mode rate limit and carries a retry delay, so your client should back off and retry. A 507 (gRPC ResourceExhausted) means a quota stopped a write, usually disk. Deletes of points are still allowed and reads are never blocked, so free space by deleting points or dropping collections, then raise the quota or add capacity.

Habits worth adopting

Keep a golden query set. Twenty to a few hundred real queries with expected results are worth more than any benchmark. Run them in CI, after upgrades, after quantization changes and after reindexing. The set is also what you hand to an evaluation tool such as RAGAS when the question is about answer quality rather than retrieval alone.

Write down your capacity plan. A short document with the arithmetic for vectors, graph, ID tracker, payload and indexes, the headroom, the tier choices and the date you last checked it against GET /collections/{name}/memory. When a new embedding model with more dimensions arrives, the plan tells you immediately what it costs.

Decide shard counts with growth in mind. On self-hosted Qdrant the shard count is fixed at creation and resharding is Cloud-only, so pick a number that divides evenly across the node counts you may reach, such as twelve. Keep it a multiple of the current node count.

Treat configuration as code. Commit non-secret config, inject secrets as QDRANT__... environment variables, and let startup validation catch typos. Do not hand-edit a running node, because the next restart will not remember it.

Use the Web UI for looking, not for changing. The dashboard at /dashboard has a REST console, a memory view and an optimization timeline that make debugging fast. Make changes through scripts that live in version control.

Prefer idempotent writes. Deterministic UUIDs per chunk, update_mode chosen deliberately and batches you can safely retry. Ingestion jobs fail halfway in real life, and the cost of re-running should be zero.

Respect data residency. For teams in the Gulf and Egypt, decide early which region holds the data, and keep that choice visible in your deployment code. Embeddings can leak information about the source text, so treat the vectors as sensitive as the documents.

Mistakes in application code

Some of the costliest problems live in the client, not the server. Creating a new QdrantClient for every request wastes connections and, with gRPC, channels; create one per process and share it. Leaving the timeout at its default on large uploads causes spurious failures; set it explicitly and retry with backoff. Requesting with_vectors=True on every query ships kilobytes you never use, so ask only for the payload fields you display, using with_payload with an include list. Sending very large limit values to "get everything" is slow and, with strict mode, rejected; use scroll with pagination instead, or slice filters to scroll in parallel.

Another frequent one is embedding at query time with a different model or normalisation than at ingest time. Nothing errors if the dimensions match, but the results are quietly poor. Store the model name and version in collection metadata and in the payload, and fail loudly on a mismatch. Finally, do not store secrets or personal data in payloads casually: payloads are returned to anyone whose token can read the collection, and they travel in snapshots. Treat a snapshot file like a database dump: encrypt it at rest, restrict who can download it, and delete old ones on a schedule rather than letting them accumulate on the node's disk.

Practice cards

Each card is a ten-minute exercise against a local container pinned to v1.19.1.

Operational recipes

Check health and version

curl -s http://localhost:6333/            # welcome message with the server version
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:6333/readyz
curl -s http://localhost:6333/collections | jq '.result.collections[].name'

Inspect a collection properly

curl -s http://localhost:6333/collections/docs | jq '.result | {status, optimizer_status, points_count, indexed_vectors_count, segments_count, warnings}'
curl -s -X POST http://localhost:6333/collections/docs/points/count \
  -H 'Content-Type: application/json' -d '{"exact": true}'
curl -s "http://localhost:6333/collections/docs/optimizations?with=queued,completed,idle_segments"
curl -s http://localhost:6333/collections/docs/memory

Create the schema in the right order

from qdrant_client import QdrantClient, models

client = QdrantClient(url="http://localhost:6333")

client.create_collection(
    collection_name="docs_v1",
    vectors_config={"dense": models.VectorParams(size=768, distance=models.Distance.COSINE)},
    sparse_vectors_config={"sparse": models.SparseVectorParams(modifier=models.Modifier.IDF)},
)

client.create_payload_index(
    "docs_v1", "tenant_id",
    models.KeywordIndexParams(type="keyword", is_tenant=True),
)
client.create_payload_index("docs_v1", "published_at", models.PayloadSchemaType.DATETIME)

client.update_collection_aliases(change_aliases_operations=[
    models.CreateAliasOperation(create_alias=models.CreateAlias(collection_name="docs_v1", alias_name="docs")),
])

A tenant-safe hybrid query

def search(client, tenant_id, dense, sparse, limit=10):
    tenant = models.Filter(must=[models.FieldCondition(key="tenant_id", match=models.MatchValue(value=tenant_id))])
    return client.query_points(
        collection_name="docs",
        prefetch=[
            models.Prefetch(query=sparse, using="sparse", filter=tenant, limit=30),
            models.Prefetch(query=dense, using="dense", filter=tenant, limit=30),
        ],
        query=models.FusionQuery(fusion=models.Fusion.RRF),
        limit=limit,
        with_payload=True,
    ).points

Notice that the filter appears on each prefetch. A filter only on the outer query would not constrain the candidates the prefetches fetch.

Inspect the optimizer and unstick a grey collection

# check what the optimizer is doing before you touch anything
curl -s "http://localhost:6333/collections/docs/optimizations?with=queued,completed"

# trigger a grey collection
curl -s -X PATCH http://localhost:6333/collections/docs \
  -H 'Content-Type: application/json' -d '{"optimizers_config": {}}'

Snapshot and restore into a new name

curl -s -X POST http://localhost:6333/collections/docs/snapshots
curl -s -X PUT http://localhost:6333/collections/docs_restored/snapshots/recover \
  -H 'Content-Type: application/json' \
  -d '{"location": "file:///qdrant/snapshots/docs/<snapshot-name>", "priority": "snapshot"}'

Start a hardened local container

docker run -d --name qdrant \
  -p 127.0.0.1:6333:6333 -p 127.0.0.1:6334:6334 \
  --ulimit nofile=10000:10000 \
  -e QDRANT__SERVICE__API_KEY="$QDRANT_API_KEY" \
  -e QDRANT__SERVICE__ENABLE_SNAPSHOT_URL_RECOVERY=false \
  -v qdrant_storage:/qdrant/storage \
  qdrant/qdrant:v1.19.1

Binding to 127.0.0.1 means the container is not reachable from other machines, which is the right default on a laptop. For containers and volumes in general, see the Docker guide.

Find slow requests

curl -s -H "api-key: $QDRANT_API_KEY" \
  "http://localhost:6333/profiler/slow_requests?limit=20&request=search"

This returns shard operations over 50 ms, 32 entries per request type, held in memory on that one node, so run it against each node in a cluster.

Quick capacity check

python3 - <<'PY'
points, repl, dims, bpd, m = 1_000_000, 2, 768, 4, 16
base = points * repl
vectors = base * dims * bpd
hnsw = base * m * 2 * 4 * 1.2
ids = base * 52
total = (vectors + hnsw + ids) * 1.2
print(f"vectors {vectors/1e9:.1f} GB, hnsw {hnsw/1e9:.1f} GB, ids {ids/1e9:.2f} GB, with headroom {total/1e9:.1f} GB")
PY

This covers vectors, graph and ID tracker only. Add payload and indexes from your own sizes, and compare the result with GET /collections/{name}/memory on a loaded sample.

A final checklist before you call it production-ready

• Payload indexes exist for every filtered field, and were created before ingestion.
• The server is pinned to a version, and the client library is at the same or a newer minor.
• Auth is on, TLS is on, port 6335 is private, and secrets arrive through environment variables.
• Strict mode and quotas are set, and a missing tenant filter cannot reach production because a test covers it.
• Every node is scraped, alerts exist for replicas and optimizers, and probes use /readyz and /livez.
• Snapshots run on every node, and a restore has been rehearsed with "priority": "snapshot".
• The application queries an alias, and the reindex plan is written down.
• The upgrade plan lists every intermediate minor, with SDKs first.

This is part three of three. The earlier levels taught you to build a collection, filter it, run hybrid queries and operate a cluster you were handed. This level is about being the person who answers for it: the team that runs Qdrant as a service for other teams, who file tickets when search is slow, when a disk fills, or when an upgrade is due. The version assumed throughout is Qdrant 1.19.1.

The questions change. Instead of "how do I get recall up", you ask which component fails first when ten teams share a cluster, what a node loss costs in minutes and in data, what a compromised client key can reach, and which of your defaults will be wrong in a year.

Where this picks up

I am starting with how a write travels through the system, because every failure in this guide is some interruption of that path.

The write path and what it implies

When a client sends an upsert, the receiving node first writes the operation to the write-ahead log (WAL) with a sequence number, and only then does the operation enter the update queue and get applied to an appendable segment. Once an operation is in the WAL it survives a power loss; that is the durability promise, and it is the reason a restart replays recent operations instead of losing them. The WAL capacity defaults to 32 MB, which tells you the log is a recovery buffer, not an archive.

After application the point is searchable, but it lives in an appendable segment that has no HNSW graph yet. Search over such a segment is a brute-force scan. Behind the scenes, the optimizers build the graph, the quantized copy and the memory-mapped files, and swap the new segment in while the old one stays readable through a proxy and a copy-on-write segment. So there are three states for any recent write: durable, searchable but slow to search, and fully indexed. Capacity incidents almost always come from the gap between the second and third.

Deletes are soft. A bitmask marks the old record, and the vacuum optimizer later reclaims it once the deleted fraction passes deleted_threshold (0.2 by default). An upsert of identical data still deletes the old copy and inserts a new one, so a pipeline that re-upserts a whole corpus nightly "to be safe" creates the same churn as a real change, and the optimizers will spend their CPU on it.

Raft consensus in Qdrant covers cluster metadata only: topology and collection operations such as creating a collection or moving a shard. Point writes do not go through Raft. They fan out in parallel to all active replicas of the shard with no fixed primary. This matters for failure analysis. Losing Raft quorum stops you from changing the cluster (creating collections, moving shards) but does not by itself stop searching or upserting into existing collections, while losing replicas of a shard affects data operations without touching consensus. Any node can coordinate a request: it fans out to the shards, merges the results and answers, so a load balancer in front of the nodes is part of the design, not an accessory.

Two details from the write path deserve a place in your runbooks. First, the default update queue length was lowered from one million to 200 in 1.19, so a burst of writes now meets back-pressure much sooner than older documentation suggests; where the low-latency-search page still mentions a million pending updates, follow the release note. Second, the Python, TypeScript, .NET and Java clients default to wait=true while Go, Rust and raw REST default to wait=false; if you enable the experimental optimizers_config.prevent_unoptimized, a wait=true writer can hang, so tell client teams to use wait=false there.

Memory: the resource you actually plan around

You met memory tiers in the mid-level guide. Here they become a cost model. Since 1.19 every large structure carries one memory parameter with three values: pinned (on the heap, never evicted), cached (memory-mapped and pre-warmed into the OS page cache at startup) and cold (memory-mapped, not pre-warmed). All data is always persisted on disk; the tier controls only how much of it you pay for in RAM.

The defaults are worth memorising because they explain surprising bills. Dense vectors and the HNSW graph are cached. Quantized vectors are pinned when the originals are cached and cold when the originals are cold. The sparse index is pinned, the payload is cold, and payload indexes are pinned. pinned is rejected for dense vectors and for payloads, which stops the most expensive mistake by construction. The older keys (on_disk, always_ram, on_disk_payload, hnsw_config.on_disk and so on) still work but are deprecated and are not converted automatically, so a platform with years of collection definitions will have a mix of styles; make "migrate to memory" an explicit task rather than a surprise.

The capacity-planning page gives you the arithmetic. With base = points * replication_factor:

Add roughly 20 percent headroom on RAM and disk, and keep each node below about 80 percent of physical RAM. The documented worked example: one million points, 768 dimensions, replication factor two, float32, cached, no quantization and a 1 KB cold payload comes to about 7.33 GB of RAM and 10.76 GB of disk. Using 4-bit TurboQuant pinned with the originals cold drops the vector RAM from 5.72 GB to 0.72 GB. That single configuration change is the largest cost lever in the product, which is why the platform should offer it as a named profile instead of leaving each team to rediscover it.

Quantization is a compressed copy kept beside the originals, never instead of them, because the originals are needed for re-indexing and rescoring. Candidates are scored on the compressed copy and then rescored on the originals. Rescoring is on by default only for binary and TurboQuant at 1, 1.5 and 2 bits; for scalar, product and the 4-bit TurboQuant default you choose it explicitly with params.quantization.rescore. If a team reports that recall dropped after you "just turned on quantization", this default is the first thing to check.

{
  "vectors": {
    "size": 768,
    "distance": "Cosine",
    "memory": "cold",
    "datatype": "float16"
  },
  "quantization_config": { "turbo": { "bits": "bits4", "memory": "pinned" } },
  "hnsw_config": { "m": 16, "ef_construct": 100, "memory": "cached" },
  "payload": { "memory": "cold" }
}

A word of caution on the "cold" end of the range. The documentation notes that halving the number of vectors held in RAM roughly doubles latency, and recommends local SSD with at least 50,000 IOPS for disk-backed work. Cold storage on a slow volume looks fine in a demo and fails under concurrency. Qdrant also requires a POSIX-compatible block filesystem; NFS and object storage are unsupported, and since 1.15 the server checks the filesystem at startup and refuses or warns accordingly.

Finally, learn to read RSS correctly. With cold and cached structures the resident size includes the page cache, which looks like a leak and is not one. Cap it with container memory limits, and treat GET /collections/{name}/memory as a guide that underestimates real RAM by about 10 to 15 percent.

Scaling: which component breaks first

Ask "what breaks first" in a fixed order, because the answer is usually the same across tenants and you can alert on it before users notice.

Disk comes first on write-heavy clusters. Migrations and snapshot restores need twice the source's disk on the target, snapshots live in a separate directory, and the vacuum optimizer needs room to rebuild segments while the old ones still exist. A node at 90 percent disk is already in trouble during an optimization, and since 1.19 you can make the failure deliberate rather than accidental with resource quotas, covered in the governance section.

RAM comes second. The ID tracker is resident at 52 bytes per point per replica; with a billion replicated points that is tens of gigabytes before a single vector is loaded. The rough ceiling for one node is about 100 million vectors, and the point of the formulas above is to know in advance which of your collections will hit it.

Optimizer CPU comes third, and it is the subtle one. Indexing competes with search for cores. Symptoms are search latency that rises during ingestion and a collection that stays yellow for hours. The documented levers are to set optimizer_cpu_budget to about half the vCPUs, to cap max_optimization_threads at 1 per shard, to use smaller write batches, and to make readers tolerate unindexed data with indexed_only or protect them with prevent_unoptimized. The cpu_cores_used metric added in 1.19.1 gives you a direct measurement instead of inference from host graphs.

Open files and mmaps come fourth. Each segment holds files open, so a node with many collections and shards hits the process limit with Too many files open (OS error 24). Raise the limit (for example --ulimit nofile=10000:10000 in Docker) and alert on process_open_fds against process_max_fds, and on process_open_mmaps against system_max_mmaps. The second pair is a kernel limit, vm.max_map_count, that surprises people who only raised the first.

Shard count is the decision you cannot revisit on self-hosted Qdrant. shard_number defaults to the node count at creation time and cannot be changed afterwards; resharding is a Cloud feature. The guidance is to create at least two shards per node, or twelve if you expect growth, because twelve divides evenly across 1, 2, 3, 4, 6 and 12 nodes. Keep the shard count a multiple of the node count so load stays even. A platform that creates collections with the default on a three-node cluster has quietly capped itself at three shards of growth.

Replication has a similar trap. Changing replication_factor on an existing self-hosted collection does nothing by itself; you add replicas with the replicate_shard cluster operation, and self-hosted Qdrant does not rebalance shards automatically. If your capacity plan says "add nodes when full", the plan includes a person running shard moves. Limit concurrent transfers with incoming_shard_transfers_limit and outgoing_shard_transfers_limit (both default to 1) so a rebalance does not starve production traffic.

For bulk loads the guidance is specific: batches of 64 to 256 points per request, two to four parallel threads (about one per shard), two to four shards per machine for very large uploads, payload indexes created before uploading, and straight to the cold tier when the dataset exceeds RAM. The Rust client is the fastest. The collections page also describes setting indexing_threshold: 0 to speed an initial load and re-enabling it afterwards, with a warning that the PATCH can block while optimizers finish; treat that as a one-off migration technique, not a standing configuration.

Distributed operation: placement, replication and consistency

A cluster is enabled with cluster.enabled: true (or QDRANT__CLUSTER__ENABLED=true). The first peer starts with --uri 'http://qdrant_node_1:6335' and the others join with --bootstrap. GET /cluster shows the peers and the Raft status, and GET /collections/{name}/cluster shows where each shard lives. Internal traffic uses port 6335, which must never be public.

Placement is either automatic, using consistent hashing of point IDs, or user-defined with sharding_method: "custom" and a shard_key. User-defined placement is what you use when tenants map to physical shards; it is also the one that makes the shard count arithmetic harder, because physical shards equal shard_number times the number of keys times the replication factor.

Consistency in Qdrant is tunable per request, and a platform team should pick defaults and document them. For reads the consistency parameter accepts all, majority, quorum or an integer, and defaults to 1: ask one replica and return its answer. For writes, ordering is weak by default, with medium and strong available, and the collection's write_consistency_factor says how many replicas must acknowledge. Two consequences matter. A write issued when fewer replicas are active than write_consistency_factor fails, and may have been partially applied, so clients must treat that error as retryable and writes as idempotent (upserting the same ID again is, which is one reason to use deterministic IDs). And since replicas may disagree briefly, a read after a write can return stale data unless you use wait=true plus a stronger read consistency or the 1.19 X-Qdrant-Route-Affinity header, which pins a client's reads to one replica so it sees a consistent sequence.

Latency hedging is also available: read_fan_out_delay_ms, set around your p95 latency, sends the same read to a second replica only if the first is slow. A value of 0 disables it. There is also read_fan_out_factor, which always fans out; the documentation does not recommend it because it multiplies load.

Failure modes and recovery

The useful way to study failure is by what the cluster does on its own, and what it leaves for you.

A replica goes dead and comes back. Replica states are Active, Dead and Partial. A dead replica that returns recovers automatically using the wal_delta transfer method, which replays only the operations it missed. The WALs hold about 64 MB of recent operations, so a replica that was away too long cannot be caught up that way; Qdrant then falls back to stream_records, or, since 1.18, to a snapshot-based transfer. stream_records is the robust default and re-indexes on the target; snapshot carries the built index and quantization across, so it is faster to become useful but needs extra disk and the REST port; wal_delta works only for an existing shard.

A node is lost for good. Self-hosted Qdrant will not re-replicate on its own. The sequence is to remove the dead peer with DELETE /cluster/peer/{peer_id} (adding ?force=true if it refuses), start a replacement with --bootstrap, and run replicate_shard for each shard that lost a copy. If a shard had only one replica there is nothing to copy, and your only route is a snapshot. This is exactly the situation that replication factor 2 prevents and that a platform must refuse to allow for production collections, for example by checking collection_active_replicas_min in a policy job.

# remove a dead peer, then copy a shard to the replacement
curl -X DELETE "http://qdrant-1:6333/cluster/peer/$DEAD_PEER_ID?force=true"

curl -X POST "http://qdrant-1:6333/collections/docs/cluster" \
  -H "api-key: $QDRANT_API_KEY" -H "Content-Type: application/json" \
  -d '{"replicate_shard": {"shard_id": 3, "from_peer_id": 111, "to_peer_id": 222, "method": "snapshot"}}'

Consensus is damaged. If peers disagree or a node has stale Raft state, POST /cluster/recover forces a consensus snapshot to be taken to repair a peer. This is a last resort and belongs in a playbook with a named approver, not in a script.

A node will not start. Two situations come up repeatedly. Out-of-memory on startup produces a crash loop; the way out is recovery mode (QDRANT_ALLOW_RECOVERY_MODE=true for the Docker image, or QDRANT__STORAGE__RECOVERY_MODE for the binary), which loads metadata only so you can delete a collection, or QDRANT__STORAGE__LOW_MEMORY_MODE=no_populate (or no_resident) to start without populating caches while you shrink the configuration. And Can't open Collections meta Wal ... Resource temporarily unavailable means two instances share one storage directory, which in Kubernetes usually means a volume mounted to two pods.

The storage is lying. The FUSE, NFS and Windows-bind-mount cases produce panics such as OutputTooSmall in the gridstore code, or vectors that read as zeros after a restart. This is not a Qdrant bug to report; it is a filesystem the product does not support. Move to a block volume.

The collection is grey. After a restart during optimization, a collection can show grey with optimizations pending but paused. Any update resumes them; the documented trigger is PATCH /collections/{name} with {"optimizers_config": {}}.

Backups deserve their own paragraph because the intuition is wrong. Snapshots are per node: a collection snapshot captures only the shards on the node that made it, so a distributed collection needs one snapshot per node, taken at a time you can reason about. Aliases are not part of collection snapshots. Full-storage snapshots are only for single-node deployments. Snapshots restore only onto the same minor version or the next. Snapshots can be written to S3-compatible storage through snapshots_config, with role-based auth for pods supported since 1.15, which is how you get them off the node. The Qdrant Migration Tool and the experimental Listener node type are the other routes, the latter for accumulating writes without serving search. A restore that you have never rehearsed is a hope, so schedule a recovery drill and use "priority": "snapshot" when restoring into a new collection; the default replica priority prefers the empty existing data and leaves you with an empty collection.

The security model, end to end

Start from the honest default: a self-hosted Qdrant starts with no authentication and no TLS, bound to 0.0.0.0, with CORS enabled. The documentation says plainly that this is not production-ready. Qdrant Cloud is secure by default; a self-hosted platform inherits the work of making it so.

There are three layers of identity. service.api_key grants manage access and service.read_only_api_key grants read-only access; clients send either as an api-key header or an Authorization: Bearer token. Second, jwt_rbac: true enables role-based tokens. They are signed with HS256 using the api_key as the secret, so rotating the key invalidates every issued token. Claims include exp (checked with a 30-second leeway), access ("r" or "m" globally, or a per-collection list with "r" or "rw"; absent means manage), value_exists for revocation by payload lookup, and sub, which appears in the audit log. Third, the internal port.

The internal peer port, 6335, is documented as never protected by the API key. Since 1.18 you can set service.enforce_internal_auth: true so peers verify the forwarded key, but it is opt-in and you must enable it only after every node is upgraded, because mixed clusters will otherwise reject each other. Whether or not you do, keep 6335 reachable only by peers. The Helm chart and Cloud already block public access to it.

Scoped tokens have sharp edges worth teaching in reviews. A collection-scoped token cannot create or delete collections, read /telemetry or /metrics, or touch full snapshots, and creating or deleting a payload index needs rw on the collection. Payload filters in JWTs were removed in 1.16, and tokens that use them are now rejected. That means a JWT cannot force a tenant filter on queries inside a shared collection; the application tier must add the filter, which has a direct consequence for multitenancy below.

Key rotation without downtime works because of alt_api_key (1.17): set the new key as alt_api_key and roll the cluster; switch the clients; promote the new key to api_key, remove the alternate and roll again; then re-issue the JWTs, since they were signed with the old key. Build this as a runbook and rehearse it, because the first real rotation is usually triggered by a leak.

Transport. service.enable_tls with tls.cert and tls.key secures client traffic; cluster.p2p.enable_tls secures peers and needs tls.ca_cert; verify_https_client_certificate turns on client mTLS. Certificates reload every cert_ttl seconds (3600 by default), for REST only. Bind to a private interface in production, or to 127.0.0.1 locally.

The supply chain and the egress path. 1.18 added service.enable_snapshot_url_recovery, default true, which lets the server fetch a snapshot from a URL; with that enabled, anyone who can call the recovery endpoint can ask your server to make requests from inside your network. Set it to false unless you use it, and block egress at the network layer using an internal Docker network or a Kubernetes NetworkPolicy that allows only 6333 to 6335 between peers plus cluster DNS. 1.19 also fixed a path traversal in S3-based snapshots, and 1.19.1 rejects . and .. as collection names; both are reminders that the upgrade cadence is a security control.

Hardening. Use the -unprivileged image or run as a non-root user, a read-only root filesystem with writable volumes only at /qdrant/storage and /qdrant/snapshots, and secrets through environment variables (QDRANT__SERVICE__API_KEY, QDRANT__SERVICE__READ_ONLY_API_KEY, and the S3 keys) instead of committed YAML. Turn off usage statistics with telemetry_disabled: true where your data-residency policy requires it; the default sends them to Qdrant. For organisations in the Gulf and Egypt with residency obligations, the practical implication is that the deployment target (your own region, Hybrid Cloud with your infrastructure, or Private Cloud with no cloud connection) is a compliance decision, and it is much cheaper to choose it before data lands.

Audit logging (1.17) writes JSON to ./storage/audit, rotated daily and keeping seven files by default, with tracing IDs from x-request-id, x-tracing-id or traceparent. Since 1.18 it records the method path and tracing ID and has a POST /audit/logs query API, which needs manage access. Set trust_forwarded_headers: true only behind a proxy you control, otherwise callers can forge the identity written to the log.

Multi-tenancy: choosing the isolation model

Every team that shares your cluster is a tenant, and so are their customers if they build multi-customer products. There are three models, and the right one depends on how many tenants there are and how unequal they are.

Partition by payload is the default recommendation for many small tenants. One collection, a tenant field in every point, a keyword or UUID index on that field declared with is_tenant: true, and a tenant filter on every query. The tenant index tells Qdrant to co-locate each tenant's vectors, which improves locality. You can go further with hnsw_config: {"payload_m": 16, "m": 0}, which builds per-tenant graphs only; the trade-off is that queries across all tenants become slower, so do not use it where a global search is needed. In 1.19, BM25 inverse document frequency can be scoped per tenant with params.idf.corpus, so one tenant's vocabulary does not skew another's scores; if the corpus filter matches nothing, every term receives the same weight, which is a quiet way to lose relevance.

The sharp edge is that isolation here is entirely in your application tier. Because JWT payload filters were removed in 1.16, a token can restrict a caller to a collection but cannot force a tenant filter inside it. A missing filter in one service leaks another tenant's data. That is why the platform should put a thin gateway or a client library in front that injects the tenant filter, and why the design review checklist asks where the filter is added.

{
  "field_name": "tenant_id",
  "field_schema": { "type": "keyword", "is_tenant": true }
}

User-defined sharding suits a few large tenants. Create the collection with sharding_method: "custom", give each tenant a shard key, and send shard_key on every request. Physical shards are shard_number times the keys times the replication factor, so a hundred tenants can become a very large number of shards on a small cluster. Point IDs are unique per shard key only; reusing an ID across keys is documented as an unsupported anti-pattern, so keep IDs globally unique anyway.

Tiered multitenancy (1.16) combines the two. Small tenants live in a shared fallback shard key, usually named default, and are addressed with {"fallback": "default", "target": "<tenant>"}. When a tenant grows (the documented threshold is about 20,000 points), you promote it: create its own shard key with initial_state: "Partial", one shard and replication factor one, then run replicate_points with a filter to copy its data, then delete its data from the fallback. Keep the number of dedicated shards under about 1,000 per cluster, and remember that the fallback shard must fit on one node. This is the model most platform teams end up on, because tenants are never uniform.

What not to do is create one collection per tenant. The FAQ calls it an anti-pattern, each collection carries fixed overhead and open files, and Qdrant Cloud caps clusters at 1,000 collections by default. It tempts platform teams because it gives easy per-tenant deletion and per-tenant API keys; the answer is tiered multitenancy plus filtered deletes, not a thousand collections.

Cost: the levers in order of leverage

Cost in a vector database is mostly memory, then disk, then replicas, then people. The levers, from largest to smallest effect for a typical retrieval workload, are these.

First, quantization with originals kept cold. The documentation suggests 4-bit TurboQuant at 8 times compression as a default; int8 scalar gives 4 times and product quantization goes up to 64 times with the largest quality cost. The cost lives in recall, so measure it on your queries and decide the rescoring setting deliberately. Second, vector datatype: float16 is described as virtually lossless and halves vector storage, uint8 quarters it where your embeddings suit it, and turbo4 stores originals at 4 bits per dimension for dense vectors only, about one eighth the size, in 1.19. Third, tiers: pin the quantized copy and leave originals cold, enable io_uring: auto under storage.performance so cold reads use asynchronous I/O on Linux, and use inline storage in the HNSW configuration when the graph must be cold, but not when it is in RAM, and pair it with 4-bit or smaller quantization.

Fourth, index only what you filter on. Payload indexes cost about twice the field size and each adds filterable-HNSW edges, so set enable_hnsw: false where a field is used only for scroll or ordering, and memory: "cold" for rarely used indexes. Payloads are cold by default; do not change that without evidence. Fifth, replication multiplies everything, so use factor two for production and be able to justify a third replica per collection. On Qdrant Cloud, remember that disk cannot be shrunk after it has been increased, a one-way door that belongs in the approval process for resizing.

Upgrades and migrations without surprises

The version policy is strict, and it shapes how you run the platform. Never skip a minor version. Upgrade to the latest patch of each intermediate minor first: going from 1.15 to 1.17 means every node reaches 1.16.3 first, and this applies to single-node deployments too, so that data migrations run. A node on 1.N is compatible only with nodes on 1.(N-1), which sets the width of a rolling upgrade. Downgrades are unsupported, because storage migration is irreversible. RocksDB was removed entirely in 1.18 in favour of Gridstore, so a cluster still on 1.15 has real work ahead.

Client libraries come first. The upgrade page says SDKs are tested against the latest three minor versions and recommends upgrading SDKs before the server; the FAQ asks for the client to stay within one minor of the server. Teach the stricter rule. Specific changes also bite clients: the gRPC vector output format changed in 1.17, so gRPC consumers must upgrade libraries.

A safe upgrade has a repeatable shape:

1. Read the release notes for each minor between your version and the target, looking for removed endpoints and changed defaults.
2. Take snapshots from every node, remembering they restore only onto the same or next minor.
3. Upgrade client libraries in the consuming services and release them.
4. Upgrade one node at a time, waiting for the collection status to return to green and replicas to be active before moving on. With replication factor 2 or more on every collection this is zero downtime; otherwise expect a short outage.
5. Repeat for each minor, then enable opt-in controls such as enforce_internal_auth only after the last node is upgraded.

On Docker the mechanics are docker pull, docker stop and docker run with the same volume; on Compose, bump the tag; on Helm, helm upgrade qdrant qdrant/qdrant --version <v>, which performs a rolling StatefulSet update. The community Helm chart does not provide the operator features of Cloud and Private Cloud (zero-downtime optimized restarts, resharding, automatic rebalancing, backup and disaster recovery, and protection against data loss on downscale), so in a self-hosted Kubernetes deployment those become your procedures.

Deprecations deserve a ledger. At 1.19.1 your list should include the legacy on_disk, always_ram and on_disk_payload keys in favour of memory; mmap_threshold, now legacy; strict-mode max_resident_memory_percent, replaced by quotas; the BM25 language: "none" setting; and the old search, recommend and discover endpoints. That last case is instructive. The eight REST routes were removed from the OpenAPI spec in 1.19, but their handlers still serve traffic, and the matching gRPC methods are marked deprecated. The 1.17 notes had announced removal in 1.18.x, which did not happen. So the correct policy is not "wait for removal": it is to move every client to POST /collections/{name}/points/query now. The Python client's search(), recommend() and discover() methods wrap those routes, so a code search for them is a cheap and valuable audit.

Removed features matter for migrations. init_from on collection creation, the Lock API and JWT payload filters were removed in 1.16. To copy data between clusters now, use the Qdrant Migration Tool, which also moves data from other vector databases and from open-source Qdrant to Cloud, or use snapshots.

docker run --net=host --rm -it registry.cloud.qdrant.io/library/qdrant-migration qdrant \
  --source.url 'http://localhost:6334' --source.collection 'src' \
  --target.url 'https://<cluster>:6334' --target.api-key '<key>' \
  --target.collection 'dst' --migration.batch-size 64

For reindexing a live collection (a new embedding model, a changed distance metric), the standard pattern is blue/green with aliases: build docs_v2 beside docs_v1, verify it, then swap with one atomic alias request that deletes the old alias and creates the new one. Applications refer only to the alias. Aliases are not captured in collection snapshots, so keep their definitions in version control. Since 1.18 you can add or remove named vectors on an existing collection with PUT and DELETE /collections/{name}/vectors/{vector_name}, which avoids a full rebuild for additive changes.

Governance: quotas, strict mode and observability

Governance means the platform enforces its promises so you do not have to negotiate each one. Qdrant gives you three mechanisms.

Strict mode is per collection and is on by default in Qdrant Cloud. It rejects unbounded work: max_query_limit, max_timeout, search_max_hnsw_ef, search_allow_exact, search_max_oversampling and search_max_batchsize bound queries; unindexed_filtering_retrieve and unindexed_filtering_update set to false stop filters on unindexed fields from running as full scans; max_payload_index_count, condition_max_size and filter_max_conditions limit filter complexity; upsert_max_batchsize, max_collection_vector_size_bytes, max_collection_payload_size_bytes and max_points_count bound size; and read_rate_limit and write_rate_limit (operations per minute per replica) answer with HTTP 429 and a retry delay. Enabling strict mode with no limits does nothing, which is a common trap. The practical posture for a shared platform is to make "unindexed filtering off" the default, because it converts a silent latency problem into an immediate, readable error. Note that 1.19.1 closed a hole where a scroll with no limit bypassed max_query_limit, a reminder to patch.

Resource quotas (1.19) are cluster-wide: PUT /quotas with max_disk_usage_percent, max_resident_memory_percent and release_margin_percent, readable with GET /quotas. When a node passes a limit, writes that would increase usage fail with HTTP 507 or gRPC ResourceExhausted, while reads are never blocked, and deletes of points remain allowed (deleting vectors or payload keys is rejected). The release margin gives hysteresis, so a node does not flap. Once quotas are set through the API, the config file's storage.quotas is ignored, which is worth knowing before you debate which is the source of truth. Strict mode's own max_resident_memory_percent is deprecated in favour of these.

Observability starts at /metrics, in Prometheus format, per node: scrape every peer directly rather than through the load balancer, or you will see one node's numbers and call them the cluster's. Useful series include collection_active_replicas_min, collection_dead_replicas, collection_running_optimizations, collection_indexed_only_excluded_points, the rest_responses_* and grpc_responses_* histograms, process_open_fds, cluster_pending_operations_total, quota_exceeded{resource} and cpu_cores_used. Add ?per_collection=true for per-collection API metrics, which is how you attribute load to a tenant, and service.metrics_prefix if your metrics store needs a namespace. A dedicated metrics port exists since 1.17, so you can keep it off the data path. Kubernetes probes should use /healthz, /livez and /readyz, which answer even when an API key is set.

For diagnosis there is more: GET /profiler/slow_requests records shard operations over 50 ms, 32 entries per type, in memory and per node, so it is lost on restart; /telemetry and /cluster/telemetry show shard transfer progress; collection info has warnings and an update_queue; and the audit log answers who did what.

Incident playbooks

Playbooks should open with the symptom the on-call person sees, and name the first command. These are the ones worth writing before you need them.

Writes failing with 507. A quota tripped. Run GET /quotas to find which node and resource, free space by deleting points or dropping collections, add capacity, or raise the limit deliberately. The message includes the percentage and, inside the margin, the level the node must fall below before writes resume. Do not raise the limit as the first move; the quota is a warning that arrived before the disk was full.

Search latency doubled after ingestion. Check collection_running_optimizations and the optimizations endpoint to see whether indexing is competing with search. Look at GET /collections/{name}/memory for tiers that were moved to cold, and at process_major_page_faults_total. Then the slow request log for the offending queries. Remediation is in this order: throttle the writer, lower max_optimization_threads, add indexed_only for latency-critical readers, and only then scale out.

Filtered queries are slow or time out. The usual cause is a missing payload index. Create it, remember a payload index created after ingest needs an HNSW rebuild (the documented trick is to bump ef_construct by one with PATCH and leave it), and consider strict mode so the next unindexed filter fails fast.

A node is down. Confirm replicas elsewhere are active with collection_active_replicas_min. If the node returns soon, do nothing and watch the wal_delta recovery. If it will not, follow the lost-node sequence above. Never let two nodes share a storage directory while you improvise.

A key has leaked. Rotate with alt_api_key, revoke JWTs by rotating the signing key, and read the audit log for activity under the compromised identity. The audit log's sub claim is why every service should get its own JWT subject.

Collection stuck grey or yellow. Grey means paused optimizations after a restart, resumed by any update such as PATCH with an empty optimizers_config. A collection that stays yellow means the optimizer is busy or starved; check CPU budget and disk space before anything else.

Where Qdrant stops

Honest boundaries make the platform credible. Qdrant is a vector search engine with strong filtering, hybrid retrieval and operational controls; it is not a general database. Cases where you should look elsewhere or add a component are these.

When the data of record must be transactional and the vectors are a small addition, a Postgres extension such as the one in the pgvector guide may be simpler, because it keeps vectors beside relational data and one backup story. When the corpus is small enough to live in memory in a single process and you want a library, not a service, FAISS is the comparison. If you want a fully managed service without running anything, compare Pinecone, and for another self-hosted option with its own scaling model, Weaviate and Milvus. For prototypes, Chroma is lighter. Qdrant's own answer for embedded use is Qdrant Edge, an in-process build that reads server shard snapshots.

Within Qdrant, know the hard limits: a rough ceiling around 100 million vectors per node, a dense dimension of at most 65,535 (1.19.1 rejects larger sizes and empty vectors), multivector matrices where number_of_sub_vectors * vector_size must stay under 1,048,576, group-by only on keyword and integer fields without offset, and shard counts that are fixed at creation on self-hosted deployments. Approximate search also means paginating with offset can show duplicates or gaps; page on the client, use exact: true, or exclude seen IDs with must_not and has_id.

Running Qdrant as a platform for other teams

A platform is a contract: what you promise, what teams must do, and how disputes are settled. Write it down.

Offer profiles, not parameters. Three or four named collection templates (hot, balanced, archival, multi-tenant) with fixed tiers, quantization, shard counts and strict mode, supplied by a repository of declarative definitions applied by CI. Teams choose a profile and a name. Free-form collection creation through production credentials is where drift starts.

Separate identities by role. The platform has manage credentials; ingestion services have read-write JWTs scoped to their collections; query services have read-only JWTs. Give each a sub, and expire them. Remember tokens are signed with the API key, so protect that key above all.

Publish service levels you can measure. Availability of search, p95 latency at a stated query rate and filter shape, ingestion freshness (time from write to searchable), and recovery objectives for restore. Freshness is the one teams forget and the one the write path makes subtle, since a write is searchable before it is indexed.

Put guardrails in the gateway and in strict mode. The gateway injects tenant filters and rejects the old search routes; strict mode rejects unbounded queries; quotas keep the node alive. All three should fail in a way that tells the caller what to change.

Make changes boring. An upgrade calendar with one minor at a time, a deprecation ledger, a client-library support policy, and a standing recovery drill. Announce breaking changes with the release note links.

The review checklist

Use these in design reviews and pull requests for anything that touches the Qdrant platform.

Capacity and cost. Is there a calculation using the capacity formulas, with 20 percent headroom and a 80 percent RAM ceiling? Are tiers set deliberately, with quantized copies pinned and originals cold where cost matters? Is the shard count a multiple of the node count and chosen with growth in mind? Is replication factor at least two?

Correctness. Are payload indexes created before ingestion, and only for fields that are filtered? Are queries on the Query API rather than the deprecated routes? Is rescoring a conscious choice? Are writes idempotent with deterministic IDs, and are failures retried? Does ingestion handle the wait default of its client?

Security. Is authentication on, TLS on, and the bind address private? Is 6335 unreachable from outside? Are JWTs scoped, with a sub, and is the signing key stored as a secret? Is enable_snapshot_url_recovery false unless needed, and is egress restricted? Is the image unprivileged with a read-only filesystem? Is telemetry setting consistent with policy?

Multitenancy. Where is the tenant filter added, and can a bug skip it? Is is_tenant set? Is the model (payload, shard key, tiered) justified by tenant sizes?

Operations. Are metrics scraped per node? Are alerts defined for disk, open files, dead replicas and quota breaches? Is there a snapshot schedule covering every node, shipped off the node, with a tested restore using snapshot priority? Is the upgrade path documented, one minor at a time, with SDKs first?

Governance. Is strict mode on with explicit limits and unindexed filtering off? Are quotas configured? Is there an owner for each collection?

The complete picture

The stack has four layers: a storage engine (WAL, segments, optimizers), a search layer (Query API, filters, fusion, rescoring), a cluster layer (shards, replicas, metadata-only consensus) and the operator controls (auth, TLS, quotas, strict mode, metrics, snapshots, version policy). Every incident interrupts one layer, so trace each proposed change down and ask which resource it adds to.

Where the series leaves you

You can now explain Qdrant from the write-ahead log up to the platform contract, size a cluster with the documented formulas, choose a multitenancy model for a given tenant shape, secure a self-hosted deployment against its insecure defaults, plan an upgrade across several minors, and run a recovery. Where to go next depends on the questions that remain. For retrieval quality, read the RAGAS guide and evaluate your retrieval before tuning HNSW. To trace queries through your stack, see Langfuse and OpenTelemetry. For the cluster itself, the Kubernetes and Helm guides cover the platform Qdrant runs on, and Prometheus and Grafana cover the metrics you will alert on. For shipping changes safely, Argo CD and Terraform are where declarative collection profiles and infrastructure are managed.

The habit this level asks of you is simple: write down what you promised, measure it, and rehearse the failure before it happens.

Sources

• Qdrant documentation
• Installation
• Upgrades
• Common errors
• Production checklist
• Capacity planning
• Security
• Snapshots
• Collections
• Quantization
• Storage
• Multitenancy
• Configuration
• Memory tiers
• Quotas
• Monitoring
• Distributed deployment
• Consistency guarantees
• Node failure recovery
• Release v1.19.1
• Default configuration, v1.19.1
• Qdrant Helm chart
• Qdrant Migration Tool

Part three of three. A senior interview for a Qdrant platform role is rarely about syntax. You are asked to design a service, to run an incident out loud, and to persuade someone who controls the budget. This file is organised in those three parts, with model answers that show the reasoning an interviewer is listening for. The version assumed is Qdrant 1.19.1. About fifty minutes with a partner reading the prompts.

How to answer at this level

Three habits separate strong answers from competent ones. First, ask for numbers before you design: points, dimensions, queries per second, write rate, tenant count, and what freshness and recovery targets the business expects. Qdrant's cost is set by memory formulas, so a design without numbers is a guess, and saying so is a good sign. Second, name the failure mode of each choice, not only its benefit. Third, state what you would measure to know you were wrong.

A short opening you can reuse: "Qdrant is an open-source vector database written in Rust. It stores points (an ID, one or more vectors, a JSON payload) in collections, indexes dense vectors with HNSW, and filters on payload indexes. At scale my concerns are memory placement, shard counts that cannot be changed later, and the operational surface: security defaults, upgrades that cannot be skipped or reversed, and recovery."

Part one: system-design prompts

Prompt 1: A shared vector platform for twelve product teams

The question. "Design a self-hosted Qdrant service that twelve teams will use for retrieval-augmented generation and product search. What do you decide first?"

A strong answer. Start by separating the decisions that are reversible from those that are not. Shard count on self-hosted Qdrant is fixed at collection creation, so I choose it first: at least two shards per node, or twelve if growth is plausible, because twelve divides across 1, 2, 3, 4, 6 and 12 nodes. The cluster is three or more nodes with a replication factor of two or more, since two nodes cannot make collection changes with one down and one node is not for production.

Next, tenancy. Twelve teams are not twelve tenants for the purposes of data; the question is whether each team's customers share collections. I would give each team its own collections, created from a small set of profiles (hot, balanced, archival, multi-tenant) held in version control and applied by CI, so memory tiers, quantization, shard count and strict mode are decided by the platform, not by each team's first guess.

Then trust. Self-hosted Qdrant starts with no authentication, no TLS and a public bind. I enable the API key and JWT RBAC, issue per-service tokens scoped to collections with read or read-write access, enable TLS for clients and peers, keep port 6335 private, set enable_snapshot_url_recovery: false, and restrict egress. Then governance: strict mode with unindexed filtering off and query limits, plus cluster quotas so a runaway writer causes 507s on writes rather than a full disk.

Finally operations: scrape /metrics on each node, alert on disk, open files, dead replicas and non-green collections, snapshot every node to S3-compatible storage, and rehearse a restore.

What the interviewer listens for. Irreversible decisions first, a security baseline that acknowledges insecure defaults, and profiles instead of free-form parameters. A weaker answer lists features without ordering them.

Follow-up: "What would make you buy instead of build?" If nobody can be on call for a database. The documentation recommends Qdrant Cloud, Hybrid Cloud (managed control plane on your infrastructure) or the Private Cloud operator for production, because Docker and Compose leave high availability, load balancing, backups and security to you. The community Helm chart lacks resharding, automatic rebalancing, backup and disaster recovery, zero-downtime optimized restarts and protection against data loss on downscale. I would put those missing features next to the price and let leadership see the exchange.

Prompt 2: Multi-tenant SaaS with five thousand customers

The question. "Each customer has between 100 and 5 million documents. How do you isolate them in Qdrant?"

A strong answer. The distribution is the clue. Five thousand collections is the anti-pattern: the FAQ calls a collection per user an antipattern, every collection costs files and overhead, and Cloud caps clusters at 1,000 collections by default. Instead, tiered multitenancy: small customers share a fallback shard key and are addressed with {"fallback": "default", "target": "<tenant>"}; a keyword index on the tenant field with is_tenant: true co-locates each tenant's data. When a customer passes about 20,000 points, I promote them: create a dedicated shard key with initial_state: "Partial", one shard, replication factor one, run replicate_points with a filter from the fallback key to the new one, and then delete their points from the fallback. I keep dedicated shards under roughly a thousand, remembering that the fallback shard must fit on one node.

The critical caveat is where isolation lives. JWT payload filters were removed in 1.16, so a token cannot force a tenant filter inside a shared collection. The application must add the filter, and a missing filter is a data leak. I put a gateway or shared client library in front that injects the tenant, and I write a test that queries as tenant A and asserts nothing from tenant B returns.

Follow-up: "How do relevance scores behave across tenants?" For sparse BM25 retrieval, inverse document frequency is computed over the corpus; since 1.19 params.idf.corpus takes a filter, so I scope it per tenant. If that filter matches nothing, every term gets the same weight, so I test that the corpus filter is non-empty.

Prompt 3: Cutting the memory bill by seventy percent

The question. "The cluster holds 200 million 1024-dimensional vectors and RAM is the main cost. What do you change, and how do you know it is safe?"

A strong answer. Compute first. Float32 vectors at 1024 dimensions are 4 KB each, so 200 million is about 800 GB before replication and before the HNSW graph. The first lever is quantization with cold originals: keep the compressed copy pinned and the full vectors cold, so RAM carries the compressed copy and the graph while disk carries the originals used for rescoring. The documentation suggests 4-bit TurboQuant at 8 times compression as the default, int8 scalar gives 4 times, product quantization goes up to 64 times. The second lever is datatype: float16 is described as virtually lossless. The third is I/O: storage.performance.io_uring: auto lets cold reads use asynchronous I/O on Linux. If the HNSW graph itself must be cold, inline storage helps, but only paired with 4-bit or smaller quantization and not when the graph is in RAM.

How I know it is safe: a labelled query set, recall at ten compared across variants, and the latency distribution under realistic concurrency, because halving the vectors in RAM roughly doubles latency. I check the rescoring setting explicitly, since it is on by default only for binary and TurboQuant at 1, 1.5 and 2 bits. I roll out one collection at a time and keep the original configuration as a rollback.

What the interviewer listens for. Arithmetic before action, recall measured on real queries, and awareness that quantization is a copy beside the originals, not a replacement. Seventy percent is plausible; promising it without measurement is not.

Prompt 4: Zero-downtime embedding model change

The question. "Teams want to switch embedding models. Documents are live. How?"

A strong answer. Vectors from different models are not comparable, so this is a reindex. I create a new collection with the new dimension and metric, backfill it from the source of truth (not from the old collection, since the old vectors cannot be converted), dual-write new changes, evaluate quality on a labelled set, and then switch an alias atomically: one request deletes the old alias and creates the new one, so applications never see a gap. Aliases are not part of collection snapshots, so I keep their definitions in version control. For an additive change, such as a second named vector for a new model, 1.18 lets you add a named vector to an existing collection with PUT /collections/{name}/vectors/{vector_name}, so I can run both models side by side and cut over per query path.

I would also mention capacity: during the overlap, memory and disk are doubled for that collection, and the backfill competes with production for optimizer CPU, so I throttle it and consider building with indexing deferred, remembering the warning that a PATCH can block while optimizers finish.

Part two: incident response

Answer these in a fixed shape: what I check first, what I conclude, what I do, and what I do afterwards.

Incident 1: Writes return HTTP 507

Check first. GET /quotas and the quota_exceeded{resource} metric to find the node and the resource. Conclude. A resource quota introduced in 1.19 tripped, so the system is protecting itself; reads are not blocked, and point deletion is still allowed, while deleting vectors or payload keys is rejected. Do. Free space by deleting points or dropping collections, add capacity, or raise max_disk_usage_percent deliberately; the message shows the level the node must fall below before it accepts writes again, because of the release margin. After. Alert earlier than the quota, find why growth was unplanned, and review the capacity numbers.

Incident 2: A node dies and will not come back

Check first. Whether every shard on it has an active replica elsewhere, using collection_active_replicas_min and the per-collection cluster view. Conclude. If yes, there is no data loss and the risk is a second failure. If a shard had a single replica, that data is only in snapshots. Do. Remove the dead peer with DELETE /cluster/peer/{peer_id} (adding force=true when needed), start a replacement with --bootstrap, and run replicate_shard for each shard, because self-hosted Qdrant will not re-replicate on its own. Limit concurrent transfers so production is not starved. After. A policy check that refuses production collections with replication factor one.

Incident 3: Search latency tripled after a bulk load

Check first. collection_running_optimizations, the optimizations endpoint, and CPU use; cpu_cores_used on 1.19.1. Conclude. Indexing is competing with queries, and many recent points are in appendable segments searched by brute force. Do. Throttle the loader, reduce max_optimization_threads, set optimizer_cpu_budget to about half the cores, use indexed_only for latency-critical readers, and if needed use prevent_unoptimized with wait=false writers. After. Schedule bulk loads, load with payload indexes already created, and separate ingestion from serving in the capacity plan.

Incident 4: An API key was committed to a public repository

Check first. Whether the key is the manage key, the read-only key or a JWT, and read the audit log for activity under it. Do. Rotate with no downtime: set the new key as alt_api_key and roll the cluster, switch the clients, promote it to api_key, remove the alternate and roll again, then re-issue JWTs because they are signed with the old key and are invalidated by the rotation. Tighten network policy, since the key is useless to an attacker who cannot reach the port. After. Move secrets into environment variables from a secret store, give each service its own token subject, and shorten token lifetimes.

Incident 5: Search results leaked another tenant's data

Check first. Whether the offending query went through the gateway or called Qdrant directly, and which code path built the filter. Conclude. The isolation boundary is application code, because JWTs cannot enforce tenant filters inside a collection. Do. Contain by disabling the path, identify affected tenants using the audit log and tracing IDs, and patch the filter injection. After. Centralise filter injection, add the cross-tenant test to CI, and consider moving the largest or most sensitive tenants to dedicated shard keys, which narrows the blast radius.

Incident 6: The upgrade went wrong halfway

Check first. Which nodes are on which version, and whether the step skipped a minor. A node on 1.N is compatible only with 1.(N-1), so a mixed cluster more than one minor wide is itself the problem. Do. Do not attempt a downgrade; storage migration is irreversible and unsupported. Finish the upgrade of the remaining nodes if the cluster is healthy, or restore from the pre-upgrade snapshots onto the same minor if data is damaged. After. The runbook gains a mandatory snapshot step and a canary node, and clients upgrade first.

Part three: arguing a trade-off to leadership

Leadership wants the decision, the cost, the risk and what you need from them. Lead with the decision, then the numbers.

"Why not just use Pinecone, or a Postgres extension?" Decide on facts. A Postgres extension (see the pgvector guide) is the right answer when the data is relational, the vector count is modest and one backup story is valuable. A managed service such as Pinecone removes operations at a price and with a data-location question. Qdrant earns its place when you need rich payload filtering, hybrid retrieval, control over memory tiers and quantization, or self-hosting for data-residency reasons. For employers in the Gulf and Egypt, where residency and sovereignty are real constraints, the deployment target is part of the argument, and Hybrid Cloud or Private Cloud may meet it while keeping some operations managed.

"Why are we paying for three nodes when traffic fits on one?" Because availability and maintenance are the requirement, not traffic. Two nodes cannot make collection changes when one is down; three nodes with replication factor two survive a node loss and allow rolling upgrades with no downtime. The price of the second and third node is the price of being able to upgrade on a Tuesday.

"Can we skip two versions to catch up?" No, and give the reason in one sentence: storage migrations run per minor and cannot be undone, so each intermediate minor must be installed on every node. Translate that into time: one maintenance window per minor, with snapshots before each, which is why an upgrade cadence is cheaper than a catch-up project.

"Why do we need a platform team, not just a Helm chart?" The chart installs; it does not provide resharding, automatic rebalancing, backup and disaster recovery, or protection against data loss on downscale. Those are procedures you will own. Present the choice as a staffing question with figures.

"The savings from quantization are huge; why not use the most aggressive setting everywhere?" Because savings are measured in memory and risk in recall, and recall is the product. I propose a profile ladder, test each rung on real queries, and approve the aggressive rung only where the labelled evaluation shows the loss is acceptable.

Common questions, short answers

What is the difference between a shard and a replica? A shard is a partition of a collection's points; a replica is a copy of a shard on another node.

Does Raft carry my writes? No. Consensus covers cluster metadata (topology, collection operations). Point writes go to all active replicas in parallel with no fixed primary.

What does wait=true guarantee? The call returns after the operation has been applied; with the Python, JS, .NET and Java clients it is the default, and with Go, Rust and raw REST it is not.

How do I restore a snapshot into a new collection? Use priority snapshot; the default replica prefers the existing, empty data. The snapshot must come from the same minor version or the previous one.

What can I not do on self-hosted Qdrant that Cloud offers? Resharding and automatic rebalancing are Cloud features, and changing replication_factor on an existing collection does not add replicas by itself.

What a strong answer covers that a weak one misses

A weak answer describes features. A strong answer orders decisions by reversibility, quotes capacity numbers, names the insecure defaults, says where isolation really lives in each tenancy model, and distinguishes what the cluster repairs itself (a returning replica) from what the operator must do (replacing a lost node). It states limits honestly, such as no native per-tenant encryption that you can cite, no downgrades, and no resharding without Cloud. And it ends every design with the metrics that would prove the design wrong.

Sixty-second self-test

Answer aloud, without notes.

1. Which Qdrant decision on a self-hosted cluster cannot be changed after creation, and what do you choose to leave room for growth?
2. Name the three memory tiers and the default tier of dense vectors, quantized vectors and payloads.
3. What does Raft cover, and what does it not?
4. Why can a JWT not enforce tenant isolation inside a collection?
5. List the steps of a zero-downtime key rotation.
6. What is the rule for upgrading across several minor versions, and what is the rollback story?
7. Which endpoint is the single search interface, and which deprecated routes should clients stop using?
8. What status colour is a collection after a restart interrupted optimization, and what clears it?
9. What do you do first when writes return 507?
10. Why must you scrape every node's /metrics instead of the load balancer?

If you hesitated on more than two, reread the matching section of the senior detailed guide. The tips file lists the production traps that turn these answers into habits.

Part three of three. At this level the problems are not failed queries. They are traps that stay quiet for months and then arrive together: a disk that fills during an optimization, an upgrade that cannot be undone, a tenant filter forgotten in one service. Start with the trap table, then the platform habits, then the review checklists you can paste into a pull request template. The version assumed is Qdrant 1.19.1.

Production traps that appear at scale

Everything from the beginner and mid tips still applies. These are the ones that need volume, time or several teams to show up.

The pattern worth noticing is that most of these are defaults that suit one machine and fail across a team. Shard count, replication factor, load balancing, quotas and the insecure bind address all have one-node-friendly defaults.

Three traps worth a longer explanation

Shard count is a one-way door. On self-hosted Qdrant, shard_number defaults to the node count at creation and cannot be changed later; resharding is Cloud-only. A team that creates a production collection on a three-node cluster with the default has three shards, and the only way to spread across six nodes is a full migration. The guidance is at least two shards per node, or twelve for growth, and keep it a multiple of the node count. Bake this into your collection templates so no one chooses it from memory.

A snapshot is not a cluster backup. A collection snapshot covers one node's shards. A distributed collection needs one per node, aliases are excluded, and full-storage snapshots are single-node only. Teams find this out during the restore. The fix is a scheduled job that snapshots every node, ships the files off the node to S3-compatible storage, records the alias definitions separately, and runs a restore into a scratch cluster on a schedule.

Quantization can silently lower recall. Compression is a copy beside the originals, and rescoring against the originals is on by default only for binary and TurboQuant at 1, 1.5 and 2 bits. Choose int8, product, or 4-bit TurboQuant and rescoring is your decision. Teams turn on quantization, see the memory graph drop, and learn about the recall loss from users. Measure recall on a labelled set before and after, and set params.quantization.rescore and oversampling deliberately.

Security traps

The security defaults deserve their own table because the failure is quiet: a cluster that works perfectly while exposed.

Two further notes. The upgrade cadence is itself a security control: 1.19 fixed a path traversal in S3-based snapshots, and 1.19.1 rejects . and .. as collection names and closed a case where a scroll with no limit bypassed max_query_limit. A platform stuck three minors behind carries known holes. And test that controls refuse: from outside the network, try ports 6333, 6334 and 6335, and use a read-only token to attempt a write. A control that has never been seen to refuse something is still untested.

Platform-ownership habits

These are the practices that separate a platform from a shared server, in rough order of leverage.

1. Offer profiles, not knobs. Three or four named collection templates, in version control, applied by CI. Each fixes memory tiers, quantization, shard count, replication, strict mode and payload index rules. Teams pick one and a name. When a profile improves, you migrate everyone by changing one file.

2. Make the safe path the default path. A gateway or client library that injects the tenant filter, sets with_payload sensibly, uses the Query API, retries idempotently and sets timeouts. If the easy way to call Qdrant is also the safe way, you review less.

3. Alert on leading indicators. Disk percentage against the quota, open files against the limit, dead replicas, collections that are not green, optimizations running for a long time, and update queue depth. These precede incidents; query latency follows them.

4. Scrape every node. /metrics is per node. Scraping through a load balancer shows one node at random, and the cluster looks healthy while one peer is not. Use ?per_collection=true to attribute load, and service.metrics_prefix to namespace metrics in a shared store.

5. Rehearse recovery. Quarterly: stop a node and watch recovery, replace a node with --bootstrap and replicate_shard, restore a snapshot with snapshot priority into scratch, rotate the API key using alt_api_key. Record how long each took. These numbers are your recovery objectives.

6. Keep a deprecation ledger. At 1.19.1 it lists the legacy on_disk, always_ram and on_disk_payload keys (now memory), mmap_threshold, strict-mode max_resident_memory_percent, the BM25 language: "none" setting, upload_records in the Python client, and the old search, recommend and discover endpoints. Review it at every minor release and assign owners to each item.

7. Pin and rehearse upgrades. Pin image tags to a full version such as qdrant/qdrant:v1.19.1 (never latest in production), take snapshots, upgrade SDKs first, then nodes one at a time, one minor at a time. Keep a canary cluster that is always one minor ahead.

8. Use the slow request log early. GET /profiler/slow_requests records shard operations over 50 ms, 32 entries per type, in memory on each node. It is lost on restart, so capture it during an incident, not after.

9. Keep the inventory. Every collection with an owner, a profile, a replication state and a last-restore date. A collection without an owner is a finding, because it will outlive its project and keep costing memory.

10. Prefer fewer, larger collections. Fixed per-collection overhead and the per-user collection anti-pattern say the same thing: scale with tenants inside collections, not with collections.

Review checklist: a pull request that changes a collection

Paste into the pull request template for any change to a collection definition, a client call, or an ingestion job.

1. Profile. Does it use a platform profile? If not, why not, and who approved the exception?
2. Sizing. Is there a calculation from the capacity formulas: points, dimensions, bytes per dimension, replication, HNSW, ID tracker, payload and payload indexes, with 20 percent headroom?
3. Tiers. Are memory settings explicit and using the current key rather than the deprecated on_disk, always_ram or on_disk_payload?
4. Shards. Is shard_number a multiple of the node count and sized for growth? Is replication factor at least two?
5. Indexes. Are payload indexes created before data is loaded, and limited to fields that are filtered? Is is_tenant set on the tenant field? Is enable_hnsw: false used where a field is only ordered or scrolled?
6. Queries. Does every query use POST /collections/{name}/points/query (or its batch and groups variants), never the deprecated routes or the client methods that wrap them? Is limit bounded? Is with_payload restricted to what the caller needs?
7. Rescoring. If quantization is on, is rescoring and oversampling set on purpose, with recall measured on a labelled set?
8. Writes. Are IDs deterministic so retries are safe? Is wait set intentionally for the client in use? Are batches within 64 to 256 points? Is update_mode stated where conditional updates are used?
9. Tenancy. Where is the tenant filter added, and what test proves another tenant's data cannot return?
10. Strict mode. Are limits explicit, and is unindexed filtering disabled?
11. Tests. Is there a test that fails if a required payload index is missing?

Review checklist: a design document

Use these questions to review a design document before it is approved. Each needs a written answer, not a nod.

Requirements. What are the peak queries per second, write rate, point count, dimensions and growth over twelve months? What freshness (time from write to searchable) and recovery objectives are required?

Placement. What is the deployment target (self-hosted, Cloud, Hybrid Cloud, Private Cloud) and does it satisfy data-residency rules for the regions involved? Who is on call?

Capacity. Do the formulas fit within 80 percent of RAM per node and with disk headroom, including the doubled space needed during migrations and restores? What is the plan when the cluster is full?

Availability. Is the cluster three or more nodes with replication factor two or more? What are the consistency settings for reads and writes, and what does a client do on a write failure?

Security. Is authentication on, TLS on, 6335 isolated, egress restricted, snapshot URL recovery off, secrets in a store, and an audit trail enabled? How is the API key rotated?

Data movement. How is the data loaded, how is it backed up from every node, where do snapshots go, and when was a restore last tested? What is the plan for changing the embedding model, using aliases?

Evolution. What is the upgrade path from the current version, naming every minor? Which deprecated features does the design rely on, and what happens when they are removed?

Exit. If Qdrant stopped fitting (a transactional need, a much larger scale, an operations burden), what is the alternative, and how would the data move? The Qdrant Migration Tool and a scroll-based export give the answer a concrete shape.

A design that answers all of these in writing has already survived most of its incidents.

Practice cards

Work through these with a colleague. Each is a short scenario with a first move.

Card 1. A team reports that adding a payload filter made queries ten times slower in production but not in staging. What do you check? Whether the filtered field has a payload index in production, whether it was added after ingestion without a rebuild, and whether strict mode would have rejected the query.

Card 2. You are asked to double the number of nodes next quarter. What do you check first? The shard count of each collection. If it equals the old node count, the new nodes cannot take a share without shard moves, and self-hosted Qdrant does not rebalance automatically.

Card 3. A tenant's data appears in another tenant's results. What is your first suspicion? A missing or wrong tenant filter in application code. JWTs cannot enforce it inside a collection, so the filter is the isolation boundary.

Card 4. An upgrade from 1.17 to 1.19 is requested for next week. What is the plan? Check release notes for 1.18 and 1.19, snapshot every node, upgrade clients, move every node to 1.18.3 first, then to 1.19.1, one node at a time, enabling enforce_internal_auth only afterwards if desired.

Card 5. Search latency is fine until nightly ingestion. What are your levers in order? Throttle the writer, reduce optimization threads, set the optimizer CPU budget, use indexed_only on readers, and only then add nodes.

Card 6. Finance asks why the bill went up after you enabled replication. Replication multiplies RAM and disk, and the factor is in the capacity formula. Show the before and after, and the failure it prevents.

A short checklist to keep

• Three or more nodes, replication factor two or more, and a load balancer
• Shard count chosen for growth, as a multiple of the node count
• Authentication, TLS and a private bind before the first user
• Per-service JWTs with a sub, and a rehearsed alt_api_key rotation
• Payload indexes before ingestion; strict mode with unindexed filtering off
• Quantization measured for recall; rescoring decided
• Snapshots from every node, shipped off the node, restored in drills
• Metrics scraped per node, alerts on disk, files, replicas and status
• Upgrades one minor at a time, SDKs first, snapshots first
• A deprecation ledger, an inventory and a runbook for each playbook

For retrieval quality work that sits on top of this platform, continue with RAGAS, and for tracing queries through your applications see Langfuse.