How to beginner · 3 min read

Qdrant payload filtering

Q: Qdrant payload filtering

Use Qdrant payload filtering by specifying a filter parameter in your search or query requests to restrict results based on metadata fields. The filter supports logical operators and conditions on payload keys, enabling precise vector search results.

Quick answer

Use Qdrant payload filtering by specifying a filter parameter in your search or query requests to restrict results based on metadata fields. The filter supports logical operators and conditions on payload keys, enabling precise vector search results.

PREREQUISITES

Python 3.8+
pip install qdrant-client>=1.0.0
Qdrant server running or access to Qdrant Cloud

Setup

Install the official qdrant-client Python SDK and ensure your Qdrant server is running locally or remotely. Set up your environment with the necessary API endpoint and API key if using Qdrant Cloud.

bash

pip install qdrant-client

Step by step

This example demonstrates how to perform a vector search with payload filtering using the qdrant-client in Python. The filter restricts results to points where the payload key category equals "books".

python

from qdrant_client import QdrantClient
from qdrant_client.http.models import Filter, FieldCondition, Match

# Connect to local Qdrant instance
client = QdrantClient(host="localhost", port=6333)

# Define a payload filter to match points with category == 'books'
payload_filter = Filter(
    must=[
        FieldCondition(
            key="category",
            match=Match(value="books")
        )
    ]
)

# Example vector to search
query_vector = [0.1, 0.2, 0.3, 0.4]

# Perform search with payload filtering
results = client.search(
    collection_name="my_collection",
    query_vector=query_vector,
    limit=5,
    filter=payload_filter
)

for point in results:
    print(f"ID: {point.id}, Score: {point.score}, Payload: {point.payload}")

output

ID: 123, Score: 0.95, Payload: {'category': 'books', 'title': 'Python Programming'}
ID: 456, Score: 0.92, Payload: {'category': 'books', 'title': 'Data Science Handbook'}

Common variations

You can combine multiple conditions using must, should, and must_not clauses for complex filtering. Filters support numeric comparisons, ranges, and nested logical operators.

python

from qdrant_client.http.models import Filter, FieldCondition, Match, Range

# Filter for category 'books' and rating >= 4.5
complex_filter = Filter(
    must=[
        FieldCondition(key="category", match=Match(value="books")),
        FieldCondition(key="rating", range=Range(gte=4.5))
    ]
)

results = client.search(
    collection_name="my_collection",
    query_vector=query_vector,
    limit=5,
    filter=complex_filter
)

for point in results:
    print(point.payload)

output

{'category': 'books', 'title': 'Advanced Python', 'rating': 4.7}
{'category': 'books', 'title': 'Machine Learning', 'rating': 4.8}

Troubleshooting

If no results are returned, verify your filter keys exactly match the payload keys stored in Qdrant.
Ensure your Qdrant collection has payload indexed for filtering.
Check that your vector dimension matches the collection's vector size.

✅

Key Takeaways

Use the filter parameter in Qdrant client search calls to apply payload filtering.
Combine multiple FieldCondition objects with logical operators for complex queries.
Always ensure payload keys and types match your filter conditions to get accurate results.

Verified 2026-04

Verify ↗