DEV Community: midegdugarova

Qdrant in Production: 10 Gotchas the Quickstart Won't Tell You

midegdugarova — Thu, 25 Jun 2026 18:56:30 +0000

The Qdrant quickstart is genuinely good — you're upserting vectors and getting
search results in five minutes. But there's a gap between "the demo works" and
"this runs in production without surprising me," and most of what lives in that
gap isn't in any single docs page. It's scattered across reference sections,
GitHub issues, and the scars of people who hit it at 2 a.m.

I collected these while ramping up on Qdrant — reading the docs end to end,
building demos, and auditing the gaps. Here are the ten that matter, ordered
roughly by when they'll bite you: your first week, your first month, your
first incident.

All code uses the current Python client API (query_points, not the deprecated
search).

Your first week

1. Payload indexing is not automatic

This is the big one. Qdrant lets you filter on any payload field out of the
box, and at demo scale it's fast — so it's easy to assume filtering "just
works." It does. It's just doing a full scan over candidate payloads,
which falls off a cliff as the collection grows.

Every field you filter on needs an explicit index:

client.create_payload_index(
    collection_name="my_docs",
    field_name="category",
    field_schema="keyword",
)

There's no warning when you filter on an unindexed field. The symptom is just
"filtered queries got slow somewhere past a few hundred thousand points." Make
payload indexes part of your collection-creation script, not an afterthought.

2. Cosine vs. dot product: normalization decides

If your embeddings are L2-normalized — and OpenAI and Cohere embeddings are —
cosine similarity and dot product give identical rankings, but dot skips
the normalization step, so it's the faster choice:

vectors_config=VectorParams(size=1536, distance=Distance.DOT)

The trap runs the other way: use DOT with un-normalized embeddings and your
results get silently biased toward vectors with larger magnitudes. No error,
just subtly wrong rankings — the worst kind of bug.

Rule of thumb: OpenAI/Cohere → DOT. Anything else, or unsure → COSINE,
which normalizes for you.

3. Collection config is forever

Vector dimensions and distance metric are immutable after
create_collection. There is no migration path — switching embedding models
means a new collection and a full re-ingest of everything.

That's worth a real decision upfront, not a default. And if you suspect you'll
ever migrate models (you will), use named vectors from day one — you can
add a new named vector for the new model and backfill, instead of rebuilding
the world:

vectors_config={
    "openai-small": VectorParams(size=1536, distance=Distance.DOT),
    # room to add "openai-large" later without a new collection
}

Your first month

4. `upsert` replaces the entire point

Qdrant has three update operations, and using the wrong one silently loses
data:

upsert — replaces the whole point: vector and all payload fields
set_payload — updates only the payload fields you pass
update_vectors — updates only the vector

The classic mistake is using upsert to "update one field." Any payload field
you didn't re-include is gone — no error, no warning. If you're patching
metadata, you want set_payload.

5. Very selective filters quietly change the algorithm

Qdrant's filtered search is smart: the query planner estimates how many points
match your filter, and if the match set is very small (think under ~1% of the
collection), it skips the HNSW index entirely and does an exact scan over the
matching points — because that's genuinely faster at that selectivity.

This is correct behavior, but it produces a confusing symptom: "search is
fast usually, slow sometimes," depending on which filter a user happens to
pick. If you have a dimension that's always extremely selective — per-tenant
data is the classic case — consider making it a separate collection (or using
Qdrant's multitenancy patterns) instead of filtering one giant one.

6. Set `score_threshold`, or your RAG pipeline will hallucinate politely

By default, search returns the limit nearest results no matter how far
away they are. Ask about something your collection knows nothing about, and
you still get back the top 5 "closest" chunks — which are garbage — and your
LLM will confidently synthesize an answer from them.

The fix is one parameter plus one honest code path:

results = client.query_points(
    collection_name="my_docs",
    query=query_vector,
    limit=5,
    score_threshold=0.7,
).points

if not results:
    return "I don't have information about that."

A threshold around 0.7 is a reasonable starting point for OpenAI embeddings,
but calibrate it per model — score distributions vary a lot. The empty-results
branch is not an edge case; it's the feature.

Your first incident

7. HNSW tuning: know which knob to turn first

Three parameters control the recall/speed/memory trade-off:

ef (search time) — beam width during search. Tune this first: it needs no rebuild and is often all you need.
ef_construct (default 100) — beam width during index build. Higher = better graph quality, but 3–5× slower ingest. Requires rebuild.
m (default 16) — edges per node. Higher = better recall and more memory, permanently. Requires rebuild.

So the debugging sequence when recall is too low: raise ef → if that's not
enough, raise ef_construct and rebuild → only then touch m. Going straight
to m=64 because a blog post said so costs you memory forever.

8. Snapshots are your backup primitive — and they don't schedule themselves

Self-hosted Qdrant has no automatic backups. The primitive is the snapshot:

client.create_snapshot(collection_name="my_docs")

Three things to internalize before the incident, not during:

Nothing triggers snapshots for you. Cron it, or it doesn't happen.
A snapshot on the same disk as the data protects you from nothing. Ship it off-node.
Replication is not backup. replication_factor > 1 in distributed mode gives you high availability — it cheerfully replicates your bad deploy's deletions too.

(Qdrant Cloud handles backups for you — this one is squarely a self-hosting
gotcha.)

Two you'll be glad you knew

9. Sparse vectors are a different type, and hybrid search is a query shape

Sparse vectors (for BM25-style keyword matching) are not "dense vectors with a
different flag." They're configured separately (sparse_vectors_config with
SparseVectorParams) and use their own value type
(SparseVector(indices=[...], values=[...])).

And hybrid search isn't a magic hybrid=True parameter — it's a query shape:
two prefetch sub-queries (one dense, one sparse) fused with Reciprocal Rank
Fusion:

client.query_points(
    collection_name="my_docs",
    prefetch=[
        models.Prefetch(query=dense_vector, using="dense", limit=20),
        models.Prefetch(
            query=models.SparseVector(indices=[...], values=[...]),
            using="sparse",
            limit=20,
        ),
    ],
    query=models.FusionQuery(fusion=models.Fusion.RRF),
)

Once you see it as composition rather than configuration, the whole Query API
makes more sense.

10. One point can carry many vectors

The model that finally clicked for me: a Qdrant point is not "a vector with
metadata." It's an entity that can hold multiple named dense vectors and
sparse vectors simultaneously:

vector={
    "text": text_embedding,
    "image": image_embedding,
    "sparse": SparseVector(indices=[...], values=[...]),
}

That's text search, image search, and keyword search over the same objects
from one collection — no syncing three stores, no duplicate payloads. If
you're designing a multimodal or hybrid system, this is the feature to design
around from the start (see gotcha #3: you can't bolt it on later without a
re-ingest).

The pattern underneath

Almost every item on this list is the same lesson wearing different clothes:
Qdrant's defaults are tuned for the demo, and production is a set of
explicit decisions — index your filter fields, pick your distance metric on
purpose, choose the right update operation, schedule your own snapshots,
threshold your own scores.

None of these are flaws; they're the configuration surface of a tool that
trusts you. But the quickstart can't make those decisions for you, and the
worst failures here are the silent ones. Better to meet them in a blog post
than in an incident channel.

Vector Search for Web3 Developers: Searching NFT Metadata with Qdrant

midegdugarova — Thu, 25 Jun 2026 18:40:07 +0000

If you've built anything on-chain, you know how NFT search works today: exact-match
filters. Background = Neon City. Rarity = Legendary. Eyes = Laser. Marketplaces
are basically faceted databases — pick your traits, get your grid.

That's perfect when you know exactly what you want. But it falls apart the moment a
user thinks in vibes instead of attributes:

"Show me a brooding warrior glowing with electric light."

There's no vibe = brooding trait. The words "brooding," "glowing," and "electric"
might not appear in a single NFT's metadata. Exact-match search returns nothing.

This is the gap vector search fills — and it's a tool most Web3 developers
haven't reached for yet. I'm going to show you how to add semantic search to NFT
metadata in about 40 lines of Python, with no API keys, no Docker, and no cloud
account. Then I'll show you the part that actually matters for marketplaces:
combining semantic search with the trait filters you already use.

Who I am, briefly: I spent the last few years doing developer relations in
blockchain. I'm now working in AI infrastructure, and the overlap between the two
worlds is bigger than either side realizes. This post is one example.

The idea in one sentence

Turn each NFT's text into a list of numbers (an embedding) that captures its
meaning, store those numbers in a vector database, and search by meaning instead
of by exact string match.

If you've heard "embeddings" and "vectors" thrown around and tuned out — that's the
whole concept. A model reads "a fluffy lavender bunny in cotton-candy clouds" and
produces a 384-number fingerprint. Two NFTs with similar meaning get similar
fingerprints, even if they share no words. Search becomes "find the closest
fingerprints."

The stack (and why it's zero-friction)

Qdrant — an open-source vector database written in Rust. We'll run it in-memory so there's nothing to install or host.
FastEmbed — runs the embedding model locally. No OpenAI key, no rate limits, no per-call cost.

That combination matters. Every "intro to vector search" tutorial I tried as a
newcomer wanted an OpenAI key, a Pinecone account, and a Docker daemon before I
could see a single result. Here you clone and run.

pip install "qdrant-client[fastembed]"

Step 1: The data

Real NFT metadata lives on IPFS or comes from an indexer like The Graph. For the
demo, data/nfts.json has 15 NFTs across three collections — cyberpunk samurai,
kawaii animals, and mystical relics — each shaped like standard marketplace metadata:

{
  "token_id": 1,
  "name": "Neon Ronin #001",
  "collection": "Neon Ronin",
  "description": "A masterless samurai cloaked in a rain-soaked trench coat, his katana humming with electric blue plasma...",
  "traits": {"Background": "Neon City", "Weapon": "Plasma Katana", "Armor": "Trench Coat", "Rarity": "Legendary"}
}

Step 2: Turn metadata into something searchable

Embedding models read text, so we flatten the structured metadata into one string —
the description carries the vibe, the traits add concrete detail:

def nft_to_text(nft: dict) -> str:
    traits = ", ".join(f"{k}: {v}" for k, v in nft["traits"].items())
    return f"{nft['name']}. {nft['description']} Traits: {traits}."

Step 3: Embed and index

from fastembed import TextEmbedding
from qdrant_client import QdrantClient
from qdrant_client.models import Distance, VectorParams, PointStruct

embedder = TextEmbedding(model_name="BAAI/bge-small-en-v1.5")  # 384-dim, local
client = QdrantClient(":memory:")                              # nothing to host

client.create_collection(
    collection_name="nft_metadata",
    vectors_config=VectorParams(size=384, distance=Distance.COSINE),
)

texts = [nft_to_text(n) for n in nfts]
vectors = list(embedder.embed(texts))

client.upsert(
    collection_name="nft_metadata",
    points=[
        PointStruct(id=n["token_id"], vector=v.tolist(), payload=n)
        for n, v in zip(nfts, vectors)
    ],
)

We store the full metadata as the payload. That's what lets us return rich
results and filter on traits in a moment.

Step 4: Search by meaning

def search(query, limit=3, query_filter=None):
    qv = next(embedder.embed([query]))
    return client.query_points(
        collection_name="nft_metadata",
        query=qv.tolist(),
        query_filter=query_filter,
        limit=limit,
    ).points

Now the payoff. Remember: none of these query words appear verbatim in the
metadata.

Query: "a brooding warrior glowing with electric light"
  0.691  Neon Ronin #103   A wandering swordsman bathed in soft teal light...
  0.670  Neon Ronin #014   A cybernetic warrior with a chrome jaw and glowing red optics...
  0.643  Neon Ronin #156   An armored general clad in glowing crimson nano-plates...

Query: "an adorable soft fluffy companion"
  0.680  Pastel Critter #210   An impossibly fluffy lavender bunny...
  0.658  Pastel Critter #299   A sleepy yellow duckling curled inside a teacup...

Query: "a cursed artifact with dark power"
  0.726  Ancient Relic #007   A weathered golden amulet inscribed with forgotten runes...
  0.711  Ancient Relic #019   A cracked obsidian dagger... humming with dark energy.

Three vibe-based queries, three clean separations across collections. The model
understood "brooding warrior" maps to samurai, "fluffy companion" maps to cute
animals, and "cursed artifact" maps to the obsidian necrotic dagger — without a
single shared keyword.

Step 5: The part that matters for marketplaces

Pure semantic search is a nice demo. But marketplaces live on trait filters, and
your users won't give those up. The good news: you don't have to choose. Qdrant
filters the candidate set by traits and ranks by semantic similarity in one query.

from qdrant_client.models import Filter, FieldCondition, MatchValue

legendary_only = Filter(
    must=[FieldCondition(key="traits.Rarity", match=MatchValue(value="Legendary"))]
)

search("powerful and regal", query_filter=legendary_only)

Query: "powerful and regal" + filter Rarity = Legendary
  0.532  Pastel Critter #251   A chubby peach-colored hamster wearing a tiny crown...
  0.519  Neon Ronin #156       An armored general clad in glowing crimson nano-plates...
  0.501  Neon Ronin #001       A masterless samurai... katana humming with electric blue plasma.

Two things happened here. First, the filter did its job — only Legendary-tier NFTs
came back. Second, and this is my favorite result: the top hit is a crowned
hamster. The model connected "regal" to "wearing a tiny crown" — across the
cute/fierce divide, with zero shared words. That's the difference between matching
strings and matching meaning.

This is the mental model shift for Web3 devs: your existing trait filters become the
structured layer, and vector search adds a semantic layer on top. Same query, both
worlds.

Going to production

The only line that changes is the client:

# Local dev:
client = QdrantClient(":memory:")

# Self-hosted:  docker run -p 6333:6333 qdrant/qdrant
client = QdrantClient(url="http://localhost:6333")

# Qdrant Cloud:
client = QdrantClient(url="https://YOUR-CLUSTER.qdrant.io", api_key="...")

Indexing, search, and filtering are identical.

Bonus: pointing it at a real collection

The sample data is curated so the demo runs instantly, but you'll want real
metadata. Here's the part I like as a Web3 dev: you don't need OpenSea's API, an
Alchemy key, or even web3.py. NFT metadata lives on-chain — just read tokenURI
off the contract with a plain JSON-RPC call.

import requests

SELECTOR_TOKEN_URI = "0xc87b56dd"  # keccak256("tokenURI(uint256)")[:4]

def token_uri(rpc_url, contract, token_id):
    data = SELECTOR_TOKEN_URI + format(token_id, "064x")
    payload = {"jsonrpc": "2.0", "id": 1, "method": "eth_call",
               "params": [{"to": contract, "data": data}, "latest"]}
    result = requests.post(rpc_url, json=payload, timeout=30).json()["result"]
    # decode the ABI string: [32b offset][32b length][bytes]
    raw = bytes.fromhex(result[2:])
    length = int.from_bytes(raw[32:64], "big")
    return raw[64:64 + length].decode()

Resolve the URI (it'll be ipfs://, an HTTPS gateway, or an on-chain data:
URI), fetch the JSON, flatten its attributes, and index it exactly like before.
The repo's fetch_nfts.py does all of this and then runs the same search on real
Azuki tokens:

Query: "someone holding a sword or katana"
  0.593  Azuki #7    Hair: Orange Samurai, Headgear: Full Bandana...
  0.578  Azuki #10   Hair: Green Samurai, Headgear: Black Bucket Hat...

The query said "katana"; the results are the Samurai-haired Azukis. No shared
word — the model just understood the connection. One honest caveat worth knowing:
real PFP collections usually leave description empty and put everything in
attributes, so semantic search runs over trait combinations ("a character with
pink hair holding a katana") rather than prose. That's the real shape of NFT
metadata, and vector search handles it cleanly.

Where this goes next

NFT metadata is the friendly on-ramp, but the same pattern unlocks a lot of Web3
problems that exact-match search can't touch:

"NFTs like this one" recommendations — search with an existing token's vector.
Natural-language marketplace search — let users describe what they want.
On-chain text search — ENS profiles, DAO proposals, governance threads.
Wash-trading / anomaly detection — find outliers by vector distance.

The full, runnable code is on GitHub: github.com/midegdugarova/web3-nft-vector-search.
Clone it, point it at a real collection's metadata, and you've got semantic NFT
search in an afternoon.

If you're building at the Web3 × AI intersection, I'd genuinely like to hear what
you're working on — find me at github.com/midegdugarova.