How to beginner · 3 min read

How to query Qdrant collection

Q: How to query Qdrant collection

Use the official qdrant-client Python SDK to query a Qdrant collection by connecting to the Qdrant server, then call search on the collection with your query vector and parameters. This returns the nearest vectors and their payloads matching your query.

Quick answer

Use the official qdrant-client Python SDK to query a Qdrant collection by connecting to the Qdrant server, then call search on the collection with your query vector and parameters. This returns the nearest vectors and their payloads matching your query.

PREREQUISITES

Python 3.8+
Qdrant server running (local or cloud)
pip install qdrant-client>=1.7.0

Setup

Install the official qdrant-client Python SDK and ensure your Qdrant server is running locally or remotely. Set environment variables if needed for connection parameters.

bash

pip install qdrant-client>=1.7.0

Step by step

This example demonstrates connecting to a local Qdrant instance, querying a collection named my_collection with a sample vector, and printing the nearest neighbors with their payloads.

python

from qdrant_client import QdrantClient
import os

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

# Define your query vector (example 4-dimensional vector)
query_vector = [0.1, 0.2, 0.3, 0.4]

# Perform a search on the collection 'my_collection'
search_result = client.search(
    collection_name="my_collection",
    query_vector=query_vector,
    limit=5  # number of nearest neighbors to return
)

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

output

ID: 123, Score: 0.98, Payload: {'name': 'item1', 'category': 'A'}
ID: 456, Score: 0.95, Payload: {'name': 'item2', 'category': 'B'}
ID: 789, Score: 0.93, Payload: {'name': 'item3', 'category': 'A'}
ID: 101, Score: 0.90, Payload: {'name': 'item4', 'category': 'C'}
ID: 112, Score: 0.89, Payload: {'name': 'item5', 'category': 'B'}

Common variations

You can query Qdrant collections remotely by specifying api_key and url parameters in QdrantClient. Also, you can filter results by payload using the filter parameter. For async querying, use qdrant-client async API.

python

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

# Remote connection example
client = QdrantClient(
    url=os.environ["QDRANT_URL"],
    api_key=os.environ["QDRANT_API_KEY"]
)

# Query vector
query_vector = [0.1, 0.2, 0.3, 0.4]

# Filter to only return points where payload field 'category' equals 'A'
filter_condition = Filter(
    must=[FieldCondition(key="category", match=Match(value="A"))]
)

search_result = client.search(
    collection_name="my_collection",
    query_vector=query_vector,
    limit=5,
    filter=filter_condition
)

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

output

ID: 123, Score: 0.98, Payload: {'name': 'item1', 'category': 'A'}
ID: 789, Score: 0.93, Payload: {'name': 'item3', 'category': 'A'}

Troubleshooting

If you get connection errors, verify your Qdrant server is running and reachable at the specified host and port.
If no results are returned, check that your collection name is correct and that vectors have been indexed.
For authentication errors, ensure your api_key environment variable is set correctly when connecting remotely.

✅

Key Takeaways

Use the official qdrant-client Python SDK to query collections efficiently.
Specify collection_name, query_vector, and limit to get nearest neighbors.
Use filter to narrow down search results by payload conditions.
Ensure your Qdrant server is running and accessible before querying.
Remote queries require setting url and api_key in QdrantClient.

Verified 2026-04

Verify ↗