AI

Qdrant Filters and Payload Indexes: Latency, Strict Mode, Errors

A Qdrant filter on an unindexed payload field still works, it’s just slow. On 100,000 points our selective filters cost 470 to 490 ms per search, and the same queries dropped to 5 to 6 ms once you index the fields. That gap is why payload indexes exist, and the worst mistakes you can make with them fail silently, because a wrong index type returns a wrong count instead of an error.

Original content from computingforgeeks.com - post 168074

You’ll build a 100k product collection, measure filter latency before and after indexing, and turn on strict mode so unindexed filters get rejected. Then we go through the real errors we hit with nested arrays, datetime ranges, geo points and phrase matching. Every command below was run on Ubuntu 26.04 with Qdrant 1.20.0 in November 2026, and the output is pasted as it came back.

Start Qdrant and load 100,000 products

You need Docker and Python 3 on the host, and about 16 GB of RAM if you want to reproduce the timings. The lab box was a 4 vCPU, 16 GB Ubuntu 26.04 VM. If Qdrant is not running yet, the Qdrant install guide for Ubuntu covers the package and systemd routes; here we use the official container with storage on the host. A minimal Ubuntu server lacks the venv module and jq, so install them along with Docker:

sudo apt-get update
sudo apt-get install -y docker.io python3-venv jq
sudo usermod -aG docker $USER

Log out and back in so the group change applies, then start Qdrant with its storage under your home directory:

# https://github.com/qdrant/qdrant/releases
docker run -d --name qdrant -p 6333:6333 -p 6334:6334 -v $HOME/qdrant_storage:/qdrant/storage qdrant/qdrant:v1.20.0

Those -p flags publish ports 6333 and 6334 on every interface with no API key, and Docker’s rules bypass UFW. That’s fine on a throwaway lab VM, but on anything reachable from outside, prefix them with 127.0.0.1: or follow the hardening steps linked further down.

The loader and benchmark scripts use the Python client plus FastEmbed for the dense and BM25 embeddings, so put both in a virtual environment:

python3 -m venv ~/venv
~/venv/bin/pip install -q qdrant-client==1.20.0 fastembed==0.9.1

Confirm the server version and the client versions before going further, because per-element nested indexes only exist in the newest server release, and the client should match the server.

Qdrant container running on Ubuntu with version and qdrant-client output

The server reports 1.20.0 and the client matches it, so every option used below is available. Next, create the loader. Each product gets a category, a brand, a float price, a rating, a stock flag, an RFC3339 timestamp and a geo point near one of six cities. It also gets a text description, a nested specs object and an offers array with one to three shops, because those are the shapes that cause trouble in real filters.

vim load_products.py

Paste the script as tested. Each point carries a named dense vector (BAAI/bge-small-en-v1.5, 384 dimensions) and a named BM25 sparse vector, which the hybrid section uses later:

import random
import time
from datetime import datetime, timedelta, timezone

from fastembed import SparseTextEmbedding, TextEmbedding
from qdrant_client import QdrantClient, models

N = 100_000
random.seed(42)
client = QdrantClient(url="http://localhost:6333", timeout=120)

categories = ["Laptops", "Phones", "Headphones", "Monitors", "Cameras",
              "Books", "Keyboards", "Tablets", "Speakers", "Watches"]
brands = ["Stark", "Wayne", "Acme", "Globex", "Initech", "Umbrella", "Hooli",
          "Soylent", "Tyrell", "Cyberdyne", "Wonka", "Vandelay", "Oscorp",
          "Gekko", "Duff"]
adjectives = ["lightweight", "wireless", "rugged", "compact", "noise-cancelling",
              "ultra-thin", "waterproof", "fast-charging", "budget", "premium"]
uses = ["travel", "gaming", "office work", "students", "photography",
        "running", "home studio", "commuting", "video calls", "outdoor use"]
shops = ["nairobi-hub", "berlin-store", "tokyo-depot", "austin-outlet", "online"]
cities = [(36.8219, -1.2921), (13.4050, 52.5200), (139.6917, 35.6895),
          (-97.7431, 30.2672), (-0.1276, 51.5072), (2.3522, 48.8566)]
start = datetime(2025, 11, 1, tzinfo=timezone.utc)


def product(i):
    cat = random.choice(categories)
    brand = random.choice(brands)
    a1, a2 = random.sample(adjectives, 2)
    use = random.choice(uses)
    lon, lat = random.choice(cities)
    price = round(random.uniform(10, 2500), 2)
    return {
        "name": f"{brand} {a1} {cat[:-1].lower()} {i}",
        "category": cat,
        "brand": brand,
        "price": price,
        "rating": round(random.uniform(1, 5), 1),
        "in_stock": random.random() < 0.7,
        "created_at": (start + timedelta(minutes=random.randint(0, 525_600))).isoformat(),
        "location": {"lon": lon + random.uniform(-0.5, 0.5),
                     "lat": lat + random.uniform(-0.5, 0.5)},
        "description": f"{a1} {a2} {cat[:-1].lower()} by {brand} for {use}",
        "specs": {"color": random.choice(["black", "silver", "red", "blue"]),
                  "warranty_months": random.choice([6, 12, 24])},
        "offers": [{"shop": s, "price": round(price * random.uniform(0.85, 1.15), 2)}
                   for s in random.sample(shops, random.randint(1, 3))],
    }


if client.collection_exists("products"):
    client.delete_collection("products")
client.create_collection(
    collection_name="products",
    vectors_config={"dense": models.VectorParams(size=384, distance=models.Distance.COSINE)},
    sparse_vectors_config={"bm25": models.SparseVectorParams(modifier=models.Modifier.IDF)},
)

dense = TextEmbedding("BAAI/bge-small-en-v1.5")
sparse = SparseTextEmbedding("Qdrant/bm25")
payloads = [product(i) for i in range(N)]
t0 = time.time()
for b in range(0, N, 1000):
    batch = payloads[b:b + 1000]
    texts = [p["description"] for p in batch]
    dvs = list(dense.embed(texts, batch_size=256))
    svs = list(sparse.embed(texts))
    client.upsert(
        collection_name="products",
        points=[models.PointStruct(
            id=b + j,
            vector={"dense": dvs[j].tolist(),
                    "bm25": models.SparseVector(indices=svs[j].indices.tolist(),
                                                values=svs[j].values.tolist())},
            payload=batch[j]) for j in range(len(batch))],
    )
print(f"loaded {N} points in {time.time() - t0:.1f}s")

Run it. Most of the time goes into embedding on the CPU, not into Qdrant, so expect it to take a while on a small VM:

~/venv/bin/python load_products.py

On the 4 vCPU box the load took about 17 minutes. You can cut that by embedding on a GPU or by loading fewer points, since the filter behaviour shows up well below 100k. The last line of the run reports the time.

loaded 100000 points in 1051.4s

Check the collection before touching any index. The empty payload_schema is the state every new collection starts in, and it’s the state many production collections never leave. This and the other curl calls below hit the REST API on port 6333; our Qdrant REST and gRPC API guide covers the same endpoints from grpcurl, Python and Go:

curl -s localhost:6333/collections/products | jq ".result | {status, points_count, indexed_vectors_count, segments_count, payload_schema}"

Both named vectors are indexed, the dense one in HNSW and the BM25 one in Qdrant’s sparse index, which is why the indexed vector count reads close to twice the point count. No payload field is indexed yet, so every filter you run now has to read raw payloads.

{
  "status": "green",
  "points_count": 100000,
  "indexed_vectors_count": 198000,
  "segments_count": 2,
  "payload_schema": {}
}

If named vectors, distance metrics or segment counts are new to you, the Qdrant collections guide explains each field of that response before you start tuning filters.

Measure filter latency without payload indexes

Measure first so you know what the indexes buy you. The benchmark runs six filters, each 50 times after 5 warmups, and records the median exact count time plus the median and p95 of a filtered dense search with limit=10:

vim bench.py

The filters cover the common shapes: keyword plus float range, bool plus datetime, a 50 km geo radius, a selective brand plus rating pair, a broad must_not, and a nested condition on the offers array:

import statistics
import sys
import time

from fastembed import TextEmbedding
from qdrant_client import QdrantClient, models

client = QdrantClient(url="http://localhost:6333", timeout=120)
qv = next(TextEmbedding("BAAI/bge-small-en-v1.5").embed(
    ["lightweight wireless headphones for travel"])).tolist()
F, M, R = models.FieldCondition, models.MatchValue, models.Range

filters = {
    "category+price": models.Filter(must=[
        F(key="category", match=M(value="Laptops")),
        F(key="price", range=R(gte=200, lte=800))]),
    "bool+datetime": models.Filter(must=[
        F(key="in_stock", match=M(value=True)),
        F(key="created_at", range=models.DatetimeRange(gte="2026-08-01T00:00:00Z"))]),
    "geo 50km Nairobi": models.Filter(must=[
        F(key="location", geo_radius=models.GeoRadius(
            center=models.GeoPoint(lon=36.8219, lat=-1.2921), radius=50_000))]),
    "brand+rating": models.Filter(must=[
        F(key="brand", match=M(value="Stark")),
        F(key="rating", range=R(gte=4.8))]),
    "must_not Books": models.Filter(must_not=[
        F(key="category", match=M(value="Books"))]),
    "nested offer": models.Filter(must=[models.NestedCondition(nested=models.Nested(
        key="offers", filter=models.Filter(must=[
            F(key="shop", match=M(value="tokyo-depot")),
            F(key="price", range=R(lt=50))])))]),
}


def timed(fn, runs=50):
    for _ in range(5):
        fn()
    t = []
    for _ in range(runs):
        s = time.perf_counter()
        fn()
        t.append((time.perf_counter() - s) * 1000)
    t.sort()
    return statistics.median(t), t[int(len(t) * 0.95) - 1]


label = sys.argv[1] if len(sys.argv) > 1 else "run"
print(f"{label}: 50 runs per query, limit=10, times in ms")
print(f"{'query':<18} {'matches':>8} {'count p50':>10} {'search p50':>11} {'search p95':>11}")
for name, flt in filters.items():
    n = client.count("products", count_filter=flt, exact=True).count
    c50, _ = timed(lambda: client.count("products", count_filter=flt, exact=True))
    s50, s95 = timed(lambda: client.query_points(
        "products", query=qv, using="dense", query_filter=flt, limit=10))
    print(f"{name:<18} {n:>8} {c50:>10.2f} {s50:>11.2f} {s95:>11.2f}")

Run it with a label so the two runs are easy to tell apart later:

~/venv/bin/python bench.py "BEFORE payload indexes"

Read the search columns against the match counts. The selective filters (387 to 2,421 matches) sit near 480 ms, while the broad ones (10k to 90k matches) stay around 15 to 22 ms:

Qdrant filtered search latency on 100k points before any payload index

That split is the important part. When a filter matches most of the collection, the HNSW walk finds ten matching neighbours quickly even without help. When it matches about 2% of points or fewer, Qdrant cannot estimate the cardinality without an index, so the search ends up checking the payload of most points one by one. Exact counts pay that full scan every time, which is why every count took 450 to 760 ms regardless of how many points matched.

Turn on strict mode before creating indexes

Strict mode makes Qdrant refuse a filter on a field that has no suitable index, instead of quietly scanning. Turn it on first, because it doubles as a test: every error it raises tells you exactly which index a query needs. One PATCH on the collection enables it:

curl -s -X PATCH localhost:6333/collections/products -H "Content-Type: application/json" -d '{"strict_mode_config": {"enabled": true, "unindexed_filtering_retrieve": false}}'

Qdrant applies the change to the live collection, so you don’t need a restart or a reload. A plain true result confirms it.

{"result":true,"status":"ok","time":0.005569874}

Setting unindexed_filtering_retrieve to false is the part that matters for reads. It covers search, scroll and count, so any of them filtering on an unindexed field now fails instead of scanning.

Error: “Index required but not found for “brand” of one of the following types: [keyword]”

With strict mode on, the same brand filter that took 480 ms a minute ago is rejected outright. We ran a count on brand and a scroll on a price range:

curl -s -X POST localhost:6333/collections/products/points/count -H "Content-Type: application/json" -d '{"filter": {"must": [{"key": "brand", "match": {"value": "Stark"}}]}, "exact": true}'
curl -s -X POST localhost:6333/collections/products/points/scroll -H "Content-Type: application/json" -d '{"filter": {"must": [{"key": "price", "range": {"lt": 20}}]}, "limit": 1}'

Both come back as errors. Each one names the index types that would satisfy it, so you can read the fix straight off the message.

{"status":{"error":"Bad request: Index required but not found for \"brand\" of one of the following types: [keyword]. Help: Create an index for this key or use a different filter."},"time":2.665e-6}
{"status":{"error":"Bad request: Index required but not found for \"price\" of one of the following types: [float, integer]. Help: Create an index for this key or use a different filter."},"time":2.274e-6}

The fix is the index the message lists, created in the next section. Keep strict mode on in development and staging so a new query that slips past code review fails loudly there, rather than turning into a 500 ms query under production load. The Qdrant API key, TLS and Nginx guide covers the network side of locking a public instance down; strict mode is the query-cost side.

Create payload indexes with the right type

Pick the index type from how you filter the field, not only from how it is stored. The mapping we used for this collection:

FieldFilter usedfield_schemaBuild time
categoryexact match, tenant-likekeyword, is_tenant0.80 s
brandexact match, match anykeyword0.80 s
price, ratingrangefloat0.98 s, 1.03 s
in_stocktrue or falsebool0.85 s
created_atdate rangedatetime0.99 s
locationgeo radiusgeo1.67 s
descriptionfull texttext, word tokenizer0.97 s
specs.colorexact match on nested objectkeyword0.82 s
offers[].shop, offers[].pricenested array conditionkeyword or float with nested1.06 s, 1.45 s

Every index is one PUT on the collection’s /index endpoint. The wait=true flag makes the call return only after the index is built, so the next query in a script already sees it. Below is the full set with the types we ended up with; the price and created_at lines are the corrected versions from the mistakes below.

curl -s -X PUT 'localhost:6333/collections/products/index?wait=true' -H "Content-Type: application/json" -d '{"field_name": "category", "field_schema": {"type": "keyword", "is_tenant": true}}'
curl -s -X PUT 'localhost:6333/collections/products/index?wait=true' -H "Content-Type: application/json" -d '{"field_name": "brand", "field_schema": "keyword"}'
curl -s -X PUT 'localhost:6333/collections/products/index?wait=true' -H "Content-Type: application/json" -d '{"field_name": "price", "field_schema": "float"}'
curl -s -X PUT 'localhost:6333/collections/products/index?wait=true' -H "Content-Type: application/json" -d '{"field_name": "rating", "field_schema": "float"}'
curl -s -X PUT 'localhost:6333/collections/products/index?wait=true' -H "Content-Type: application/json" -d '{"field_name": "in_stock", "field_schema": "bool"}'
curl -s -X PUT 'localhost:6333/collections/products/index?wait=true' -H "Content-Type: application/json" -d '{"field_name": "created_at", "field_schema": "datetime"}'
curl -s -X PUT 'localhost:6333/collections/products/index?wait=true' -H "Content-Type: application/json" -d '{"field_name": "location", "field_schema": "geo"}'
curl -s -X PUT 'localhost:6333/collections/products/index?wait=true' -H "Content-Type: application/json" -d '{"field_name": "description", "field_schema": {"type": "text", "tokenizer": "word", "lowercase": true, "min_token_len": 2, "max_token_len": 20}}'
curl -s -X PUT 'localhost:6333/collections/products/index?wait=true' -H "Content-Type: application/json" -d '{"field_name": "specs.color", "field_schema": "keyword"}'
curl -s -X PUT 'localhost:6333/collections/products/index?wait=true' -H "Content-Type: application/json" -d '{"field_name": "offers[].shop", "field_schema": {"type": "keyword", "nested": "offers"}}'
curl -s -X PUT 'localhost:6333/collections/products/index?wait=true' -H "Content-Type: application/json" -d '{"field_name": "offers[].price", "field_schema": {"type": "float", "nested": "offers"}}'

Each call returns a completed operation with its build time. You’ll see one line per field, and offers[].price was the slowest of the set at 1.45 seconds.

{"result":{"operation_id":130,"status":"completed"},"status":"ok","time":1.445839298}

The server-reported times for the whole index run, including the three mistakes below, add up to about 13 seconds on 100k points. Index builds this cheap are no excuse to skip them. The is_tenant flag on category tells Qdrant to lay out storage by that value, which pays off when most queries filter on it, the way a multi-tenant app filters on a customer ID. The nested parameter on the two offers[] fields indexes each array element separately, so a nested condition can use the index instead of reading the array from every point.

Error: “data did not match any variant of untagged enum PayloadFieldSchema”

This one comes from using a type name that doesn’t exist. We first tried string for the brand field, a habit from other databases:

curl -s -X PUT 'localhost:6333/collections/products/index?wait=true' -H "Content-Type: application/json" -d '{"field_name": "brand", "field_schema": "string"}'

Qdrant’s JSON parser rejects it before the request reaches the collection.

{"status":{"error":"Format error in JSON body: data did not match any variant of untagged enum PayloadFieldSchema at line 1 column 49"},"time":0.0}

Qdrant only knows eight type names, and string is not one of them. If you match the value exactly, use keyword; if you search for words inside it, use text. The full set:

  • keyword, text, uuid
  • integer, float, bool
  • geo, datetime

Because the parser fails before anything is created, this mistake is harmless. The next two are not.

A float field indexed as integer returns the wrong count

This mistake doesn’t raise an error at all, which makes it the dangerous one. Indexing price as integer succeeds, and a range query on it then returns 1 product under 20 when there are 397. Deleting the index and recreating it as float fixes the count:

Qdrant price field indexed as integer returns 1 match, recreated as float returns 397

Strict mode was on during this run and stayed quiet, because an integer index satisfies a range filter. It cannot catch this. The only guard is a test that compares an indexed count against a known value, which is worth adding to whatever creates your collections.

Error: “Index required but not found for “created_at” of one of the following types: [datetime]”

We indexed created_at as keyword first, since the values are strings. The index builds fine, but a date range query then fails under strict mode, because a keyword index cannot answer a range:

{"status":{"error":"Bad request: Index required but not found for \"created_at\" of one of the following types: [datetime]. Help: Create an index for this key or use a different filter."},"time":2.058e-6}

To change the type, delete the index and create it again with the right schema. The delete took 0.06 seconds and the rebuild about one second on this collection.

curl -s -X DELETE 'localhost:6333/collections/products/index/created_at?wait=true'
curl -s -X PUT 'localhost:6333/collections/products/index?wait=true' -H "Content-Type: application/json" -d '{"field_name": "created_at", "field_schema": "datetime"}'

After that, the same range returns 25,147 points. With every index in place, list the payload schema to confirm each field has the type you meant and covers all 100,000 points:

curl -s localhost:6333/collections/products | jq -c ".result.payload_schema | to_entries[] | {field: .key, type: .value.data_type, points: .value.points}"

You should see eleven fields, each at 100,000 points.

Qdrant collection payload_schema listing eleven indexed fields

A points value lower than the collection’s point count means some points lack the field or hold a value of another type, so this one check catches data quality problems as well as index mistakes.

Rerun the benchmark with indexes

Run the same script again with strict mode still on. If any of the six filters lacked an index, it would fail here rather than report a slow time:

~/venv/bin/python bench.py "AFTER payload indexes"

Compare the match counts with the first run before looking at the times. They’re identical, so the indexes changed speed and not results.

Qdrant filtered search latency on 100k points after payload indexes

Here are both runs side by side, with the speedup worked out from the median search time.

FilterMatchesSearch p50 beforeSearch p50 afterSpeedupCount p50 before / after
category + price2,421484.57 ms6.30 ms77x492.17 / 4.54 ms
bool + datetime17,58420.93 ms4.27 ms4.9x757.14 / 9.83 ms
geo 50 km10,52722.13 ms5.20 ms4.3x475.50 / 10.11 ms
brand + rating387469.79 ms5.50 ms85x483.79 / 4.17 ms
must_not Books89,87315.19 ms4.84 ms3.1x456.76 / 13.71 ms
nested offer634477.47 ms6.04 ms79x474.16 / 4.87 ms

The selective filters gained the most, 77x to 85x, because the index lets the planner see that only a few hundred points qualify and search just those. Broad filters still got 3x to 5x faster. Counts improved 33x to 116x across the board, which matters if your UI shows facet counts next to the results. Every p95 after indexing stayed under 7 ms.

Combine must, should and must_not

A filter has three clause lists. Every condition in must has to match, none in must_not may match, and at least one in should has to match. That last rule surprises people: should inside a filter is a hard OR, not a ranking boost. This query asks for in-stock laptops between 200 and 800 from Stark or Wayne:

curl -s -X POST localhost:6333/collections/products/points/scroll -H "Content-Type: application/json" -d '{"filter": {"must": [{"key": "category", "match": {"value": "Laptops"}}, {"key": "price", "range": {"gte": 200, "lte": 800}}], "should": [{"key": "brand", "match": {"value": "Stark"}}, {"key": "brand", "match": {"value": "Wayne"}}], "must_not": [{"key": "in_stock", "match": {"value": false}}]}, "limit": 3, "with_payload": ["name", "brand", "price", "in_stock"]}' | jq -c '.result.points[] | {id, payload}'

Scroll returns points in ID order, so the first three hits happen to be Wayne laptops. All of them are in stock and inside the price window.

{"id":171,"payload":{"name":"Wayne noise-cancelling laptop 171","brand":"Wayne","price":506.65,"in_stock":true}}
{"id":545,"payload":{"name":"Wayne waterproof laptop 545","brand":"Wayne","price":504.53,"in_stock":true}}
{"id":647,"payload":{"name":"Wayne compact laptop 647","brand":"Wayne","price":673.92,"in_stock":true}}

The counts prove the point. The full filter matches 229 points; the same filter without the should list matches 1,679. If should were a soft preference, both would return 1,679. When you want “match either value”, match.any on one field is shorter and gave 13,407 for Stark or Wayne across the whole collection:

curl -s -X POST localhost:6333/collections/products/points/count -H "Content-Type: application/json" -d '{"filter": {"must": [{"key": "brand", "match": {"any": ["Stark", "Wayne"]}}]}, "exact": true}' | jq -c .result

If you need a real boost, where matching items rank higher but others still appear, that belongs in the query (a score formula or a rerank stage), not in the filter.

Filter nested objects and arrays

Use a dot path for an object and [] for an array. specs.color reaches into the specs object; offers[].shop reaches into every element of the offers array. The trap is what two conditions on the same array mean:

Qdrant nested filter on offers array returning 634 against 675 for flat offers[] keys

The flat version returned 675 products, and the nested condition returned 634. The difference comes from how each one reads the array:

  • flat offers[] keys: any element is tokyo-depot, any element is under 50
  • nested on offers: one element is tokyo-depot and under 50

So the 41 extra rows are products where another shop is cheap, which is the wrong answer if your user asked where it’s cheap at tokyo-depot. Nothing in the response tells you so, because both queries are valid. Use nested whenever two conditions describe one array element, and index the fields with the nested parameter so the query stays fast.

Error: “Index required but not found for “offers.shop””

Dropping the brackets is an easy typo. Under strict mode, offers.shop is rejected because no index has that exact key:

{"status":{"error":"Bad request: Index required but not found for \"offers.shop\" of one of the following types: [keyword]. Help: Create an index for this key or use a different filter."},"time":0.000001815}

Turn strict mode off and the same query returns {"count":0}, while offers[].shop returns 40,086. That silent zero is the strongest argument for keeping strict mode on: write the key as offers[].shop, exactly as it was indexed.

Get datetime and geo ranges right

Datetime range values must be RFC3339 strings, and in a geo point the lon key holds longitude and lat holds latitude, the reverse of how most people say coordinates. We tried the formats people actually send, plus a swapped geo center:

Qdrant datetime range formats and swapped geo coordinates returning zero

Four formats returned the same 25,147: a Z timestamp, a timestamp with no zone, the same instant written as +03:00, and a bare date. A value with no zone is read as UTC, and so is a bare date at midnight. That’s convenient, but it shifts your windows if your users think in local time:

  • 2026-07-31 to 2026-08-01, bare dates: 271 points
  • the same window in Z: 271 points
  • the same day in +03:00: 283 points

Send explicit offsets from the application so a “today” filter in Nairobi does not start three hours late. The swapped geo center is quieter still: {"lon": -1.2921, "lat": 36.8219} is still a valid coordinate pair, just thousands of kilometres from Nairobi, so the query returns 0 instead of 10,527, with no error.

Error: “’08/01/2026′ does not match accepted datetime format (RFC3339)”

A US style date is rejected at parse time. That’s the good kind of failure, because you find it on the first request.

{"status":{"error":"Format error in JSON body: '08/01/2026' does not match accepted datetime format (RFC3339). Example: 2014-01-01T00:00:00Z at line 1 column 92"},"time":0.0}

An epoch number is worse. {"gte": 1785542400} is parsed as a numeric range, so under strict mode it fails with Index required but not found for "created_at" of one of the following types: [float, integer]. With strict mode off it returned all 100,000 points without any error, which is a wrong answer for a filter meant to start on 1 August 2026. Convert epochs to RFC3339 in the client before they reach the filter.

Use full-text and phrase matching

A text index tokenizes the field so match.text finds points containing all the query words in any order. On this collection, “wireless travel” matched 2,018 descriptions. Phrase search, which needs the words adjacent and in order, requires the index to store positions, and the error says so plainly:

{"status":{"error":"Bad request: Index required but not found for \"description\" of one of the following types: [text (with phrase_matching: true)]. Help: Create an index for this key or use a different filter."},"time":0.000002415}

Recreate the text index with phrase_matching enabled. Creating an index on a field that already has one replaces it:

curl -s -X PUT 'localhost:6333/collections/products/index?wait=true' -H "Content-Type: application/json" -d '{"field_name": "description", "field_schema": {"type": "text", "tokenizer": "word", "lowercase": true, "phrase_matching": true}}'

It completed in 1.3 seconds. Phrase “wireless travel” then returned 0, which is correct, since the generator never puts those two words next to each other. Phrase “noise-cancelling budget” returned 1,073, and the plain text match still returned 2,018. Pick text when word order doesn’t matter and enable phrase matching only on fields where it does, since storing positions makes the index larger.

Error: “Substring matching is not allowed”

Strict mode also blocks match.substring on any field, indexed or not, because it reads every value. A substring search for “Stark” on name returned:

{"status":{"error":"Bad request: Substring matching is not allowed, used for \"name\": it scans every value of the field, with or without an index. Help: Use a prefix match or a full-text match instead."},"time":0.000002088}

Move that search to a text index with the prefix tokenizer, or to a plain match.text, as the message suggests. Without strict mode the substring query runs, so you’d only notice it as a slow endpoint once the collection grows.

Run filtered hybrid search with prefetch

Hybrid search runs a dense and a sparse query as prefetches and fuses them. A filter set on the outer query is propagated into every prefetch, so one filter is enough when all stages share the same constraint; a per-prefetch filter is for when they differ. This script sets the filter on each prefetch explicitly and compares dense only, dense plus BM25 fused with Reciprocal Rank Fusion, and BM25 candidates reranked by the dense vector, all limited to in-stock headphones:

vim hybrid.py

The using argument names which vector each stage reads, and it’s required here because the collection has two named vectors:

import statistics
import time

from fastembed import SparseTextEmbedding, TextEmbedding
from qdrant_client import QdrantClient, models

client = QdrantClient(url="http://localhost:6333")
dense_model = TextEmbedding("BAAI/bge-small-en-v1.5")
sparse_model = SparseTextEmbedding("Qdrant/bm25")

q = "noise-cancelling headphones for commuting"
dv = next(dense_model.embed([q])).tolist()
sv = next(sparse_model.embed([q]))
sparse_q = models.SparseVector(indices=sv.indices.tolist(), values=sv.values.tolist())
in_stock = models.Filter(must=[
    models.FieldCondition(key="in_stock", match=models.MatchValue(value=True)),
    models.FieldCondition(key="category", match=models.MatchValue(value="Headphones")),
])


def dense():
    return client.query_points("products", query=dv, using="dense",
                               query_filter=in_stock, limit=5, with_payload=["description"])


def hybrid():
    return client.query_points(
        "products",
        prefetch=[
            models.Prefetch(query=dv, using="dense", filter=in_stock, limit=50),
            models.Prefetch(query=sparse_q, using="bm25", filter=in_stock, limit=50),
        ],
        query=models.FusionQuery(fusion=models.Fusion.RRF),
        limit=5, with_payload=["description"],
    )


def rerank():
    return client.query_points(
        "products",
        prefetch=models.Prefetch(query=sparse_q, using="bm25", filter=in_stock, limit=200),
        query=dv, using="dense", limit=5, with_payload=["description"],
    )


for name, fn in [("dense", dense), ("hybrid RRF", hybrid), ("bm25->dense", rerank)]:
    print(f"-- {name}")
    for p in fn().points:
        print(f"  {p.id:>6}  {p.score:.4f}  {p.payload['description']}")
print()
for name, fn in [("dense", dense), ("hybrid RRF", hybrid), ("bm25->dense", rerank)]:
    for _ in range(5):
        fn()
    t = []
    for _ in range(50):
        s = time.perf_counter()
        fn()
        t.append((time.perf_counter() - s) * 1000)
    print(f"{name:<12} p50={statistics.median(t):6.2f} ms")

Run it the same way as the benchmark. It prints the top five for each approach, then times each one over 50 runs.

~/venv/bin/python hybrid.py

Watch the IDs at the top of each list, since they show what the sparse side adds.

Qdrant dense, hybrid RRF and BM25 then dense rerank results with p50 latency

RRF promoted point 1721, a Vandelay “budget noise-cancelling headphone … for commuting” that the dense query didn’t rank in its top five, because BM25 scored the exact words highly. RRF scores are rank based (0.5312, 0.5000) and cannot be compared with cosine scores. The fused query cost 6.68 ms against 4.16 ms for dense alone, and the rerank 5.92 ms, so on filtered data hybrid adds about 2.5 ms. For a RAG pipeline that’s a cheap way to catch exact product names and error codes; the self-hosted RAG build with Qdrant and Ollama is where this pattern plugs in.

To confirm the propagation, we moved the filter out of both prefetches and onto the outer call as query_filter=in_stock, leaving the rest of hybrid() the same apart from printing the category and stock flag. The fused top five came back identical, every hit an in-stock headphone:

    1721  0.5312  Headphones True  budget noise-cancelling headphone by Vandelay for commuting
   54853  0.5000  Headphones True  budget noise-cancelling headphone by Initech for commuting
     486  0.3718  Headphones True  noise-cancelling compact headphone by Gekko for commuting
   41369  0.3596  Headphones True  noise-cancelling compact headphone by Vandelay for commuting
   15932  0.3167  Headphones True  noise-cancelling compact headphone by Tyrell for commuting

So you can keep one filter on the outer query and let Qdrant push it down, which leaves less to keep in sync when the filter changes.

Error: “Wrong input: Not existing vector name error”

On a collection with named vectors, a query without using looks for the unnamed default vector, which doesn’t exist. A raw REST query with a 384 element vector and no using returned:

{"status":{"error":"Wrong input: Not existing vector name error: "},"time":0.000251364}

The empty name after the colon is the hint. Add "using": "dense" to the request body, or using="dense" in the Python client, and the query goes through.

Apply this to a production collection

Index every field your application filters on, and nothing else. Each index costs memory and a build on every segment, and an unused one buys nothing. For a new collection, the order that worked here is:

  1. create the collection
  2. enable strict mode
  3. create the payload indexes
  4. load data and run the application’s real queries
  5. check payload_schema types and point counts

The Qdrant indexing documentation recommends creating payload indexes right after the collection and before ingesting data, because the extra HNSW edges for filtered search are only generated once a payload index exists. On an existing collection, add them anyway: we built eleven over 100k loaded points in seconds, and every filter above got faster. The filter-aware graph edges still need an HNSW rebuild, which the docs trigger by raising ef_construct by one, and that rebuild is expensive, so schedule it for a quiet window on a large collection. Keep the filtering reference open for the condition syntax, and the Qdrant commands cheat sheet for the API calls around it.

The verdict from this lab is short. Unindexed selective filters cost close to half a second on only 100k points and will get worse as the collection grows, while the eleven correct indexes took about 11 seconds to build and brought every query under 7 ms at p95. The errors are easy to fix once you see them, so turn on strict mode and let it show you. The wrong results are the real risk: an integer index on floats, a flat array condition, a swapped geo pair and an epoch timestamp all returned a count without complaint. Test those counts against known values before trusting them, and if you’re starting the series here, the Qdrant setup and search overview covers the basics this guide builds on.

Keep reading

Ollama Models Cheat Sheet: Best Models by VRAM, Tested (PDF) AI Ollama Models Cheat Sheet: Best Models by VRAM, Tested (PDF) Open Source LLM Comparison Table (2026) AI Open Source LLM Comparison Table (2026) Claude Code Cheat Sheet: Commands, Shortcuts and Flags (PDF) AI Claude Code Cheat Sheet: Commands, Shortcuts and Flags (PDF) Dual GPU LLM Build: PCIe x8/x8 vs x16/x4, PSU and Cooling AI Dual GPU LLM Build: PCIe x8/x8 vs x16/x4, PSU and Cooling MCP vs RAG vs Agent Skills: When to Use Each AI MCP vs RAG vs Agent Skills: When to Use Each MariaDB High Availability Cluster: Galera, HAProxy, Keepalived Databases MariaDB High Availability Cluster: Galera, HAProxy, Keepalived

Leave a Comment

Press ESC to close