Qdrant in 8 Slides

This cover names the defining hazard of operating Qdrant: it rarely fails loudly. A misconfigured metric, an unindexed filter field, or vectors that won't fit RAM don't usually throw errors — they quietly degrade recall, latency, or stability, and you end up blaming your embedding model or your data when the real culprit is configuration.

That quiet-failure pattern is exactly why a named checklist is valuable. Each mistake in this post is easy to commit and easy to fix once you've seen it called out. The post is the field guide that saves you the debugging weekend you'd otherwise spend chasing the wrong cause.

The wrong distance metric is the most insidious mistake because nothing visibly breaks. If you configure euclidean distance but your embedding model was trained and normalised for cosine similarity, queries still return results and scores still look like numbers — but the ranking is subtly off, so the truly nearest items don't reliably come first.

You typically only notice when downstream quality is poor: a RAG system that retrieves mediocre chunks, a search that feels 'almost right'. The fix is to match the metric to the model. Most modern text embedders are designed for cosine or dot product; euclidean is rarely what you want for them. Check the model card before you create the collection, because the metric is fixed at creation.

Filtering on an unindexed payload field is the latency killer. When a field has no payload index, Qdrant can't use it to prune the HNSW traversal, so it falls back toward scanning — and at scale that collapses query performance. Teams routinely filter on tenant or category for months, watching queries crawl, before realising the field was never indexed.

The fix is to create a payload index on every field you filter on, and to pick the schema type that matches the field's data. This isn't optional optimisation; as post three explained, filterable HNSW depends on that index existing. Indexing filter fields should be part of your collection setup, right alongside choosing the size and metric.

This snippet is the concrete fix for the previous slide. create_payload_index registers an index on a field so Qdrant can prune by it during search. The field_schema must match the data: KEYWORD for exact string matches like tenant, INTEGER for numeric fields like year that you filter with ranges.

Getting the schema type right matters because it determines which filter operations are efficient. A KEYWORD index serves equality matches; an INTEGER index serves range queries. Indexing a numeric field as a keyword, or vice versa, leaves you slow on exactly the queries you cared about. Run these calls once after creating the collection, before you start serving filtered queries at volume.

Ignoring quantization is the mistake that ends in an out-of-memory page. Float32 vectors are large, and people treat RAM as effectively infinite until the index either spills to disk — wrecking latency — or the node simply OOMs and dies. This tends to happen suddenly, in production, as the corpus crosses some threshold.

The fix is to plan for it: for any large collection, enable scalar or binary quantization, and turn on rescoring if you need to recover the small amount of recall that compression costs. As post three covered, this cuts memory by 4x to 32x. Quantization is not an exotic optimisation reserved for giant deployments; it's standard hygiene once you're past a few hundred thousand vectors.

Querying before writes land produces the classic flaky bug. You upsert points and immediately query, but the write hasn't been applied yet, so you get stale or missing results. In a test suite this shows up as intermittent failures that pass on rerun, which is maddening to track down because the code looks correct.

The fix is to be explicit about consistency. Pass wait=True on upserts when the next operation depends on the data being visible — tests, synchronous user flows, anything read-after-write. When you're bulk-ingesting and throughput matters more than immediacy, leave it False and accept eventual consistency knowingly. The mistake isn't choosing one over the other; it's not choosing at all and being surprised by the default.

This decision tree turns the consistency question into a simple rule you can apply without thinking hard each time. If the very next query must see the write — read-after-write correctness — use wait=True and accept the small latency cost. If not, ask whether you're in a high-throughput write path: if so, prefer wait=False with batching over gRPC for speed; if not, the default behaviour is perfectly fine.

Encoding the choice as a tree prevents the two opposite errors: blindly setting wait=True everywhere and needlessly slowing bulk loads, or never setting it and getting flaky read-after-write bugs. Match the flag to the situation.

One giant collection for every tenant is the architecture mistake that's painless on day one and excruciating later. Relying solely on a tenant filter to separate customers means their vectors share the same index, per-tenant deletion is awkward, and you can't scale or move one tenant independently. Worse, a forgotten filter on a single query path can leak data across tenants.

The fix depends on scale. For strong isolation, give each tenant a separate collection. For many tenants where that's impractical, use Qdrant's multitenancy support: a tenant payload index configured so the engine physically groups points by tenant, which keeps per-tenant queries fast. Either way, enforce the tenant filter server-side, never trusting the client to send it.

This snippet shows the multitenancy fix: a payload index on tenant with is_tenant=True. That flag tells Qdrant to optimise storage and search by grouping points per tenant, so a query scoped to one tenant doesn't pay the cost of traversing everyone else's data. It's the middle path between one shared collection and a separate collection per tenant.

The is_tenant option exists precisely because the naive 'just add a filter' approach doesn't scale to many tenants. Combined with always enforcing the tenant filter on the server, this gives you both performance and isolation. Set it up when you design the collection, because retrofitting tenant structure onto a live system is far more painful.

This comparison puts every mistake beside its fix so the post resolves into an actionable contrast. Euclidean for a cosine model becomes metric-matches-the-model. Filtering unindexed fields becomes index-every-filter-field. Float32-until-OOM becomes quantize-big-collections. Query-right-after-upsert becomes wait=True-when-it-matters. One-collection-for-all-tenants becomes isolate-or-tenant-index.

Reading the two columns together is a fast self-audit: glance down the left side, and if anything describes your current setup, the cure is directly across from it. That side-by-side framing is more useful than either list alone because it pairs the symptom with the remedy.

This pre-flight checklist is the five-line summary to run before launch. Confirm the metric matches your embedding model. Confirm there's a payload index on every field you filter. Turn quantization on for large collections. Use wait=True wherever a read depends on a write. And decide your tenant-isolation strategy before you go live, not after.

Each item maps to one of the quiet failures this post dissected, and each is cheap to verify now versus expensive to diagnose in production. Treat it as a literal checklist on your deployment runbook.

The CTA closes the Qdrant day and points to the next vector-database deep dive in the series. You've now seen the concept, the stakes, the engine, a working build, and the failure modes — a complete picture of one engine. The next entry applies the same rigour to another piece of the vector-database landscape, so the comparison muscle you've built here keeps paying off. Save the set.