AI · Nov 19, 2026 · 12 min read

Qdrant 1.10: Production Vector Search, Filtering, Snapshots & Kubernetes

Learn how to deploy Qdrant for production RAG applications. Covers schema design, hybrid search, payload filtering, backups, monitoring and scaling on Kubernetes with concrete code examples and trade-

Qdrant 1.10: Production Vector Search, Filtering, Snapshots & Kubernetes

Installing and Running Qdrant 1.10

Qdrant 1.10 brings stable sparse vector support, faster on-disk indexing, and improved memory management for large collections. Begin with the official Docker image to ensure identical behavior between local development and production environments.

docker run -d --name qdrant \
  -p 6333:6333 \
  -p 6334:6334 \
  -p 6335:6335 \
  -v $(pwd)/qdrant_storage:/qdrant/storage:z \
  -e QDRANT__SERVICE__API_KEY=your-very-long-secret-key-here \
  qdrant/qdrant:v1.10.0

The -d flag runs the container in detached mode. Port 6335 exposes Prometheus metrics. Mount the storage volume with the :z option for SELinux compatibility on Linux hosts. For production Docker deployments, add resource constraints:

--cpus="4.0" --memory="16g" --memory-swap="16g"

On bare metal, download the static binary from the GitHub releases page matching v1.10.0. Create a systemd service for automatic restarts:

[Unit]
Description=Qdrant Vector Database
After=network.target

[Service]
User=qdrant
ExecStart=/usr/local/bin/qdrant --config-path /etc/qdrant/config.yaml
Restart=always
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

The config.yaml should define storage path, snapshot location, and API key. Set log_level: WARN in production to reduce noise while still capturing errors. Verify installation by calling curl http://localhost:6333/collections which returns an empty list on a fresh instance. Always run Qdrant behind a reverse proxy such as Traefik or NGINX in production to handle TLS termination and rate limiting.

Client compatibility is mandatory. Install the matching Python client with pip install qdrant-client==1.10.0. Using mismatched versions can cause deserialization errors on sparse vectors or payload filters. Pin both server and client versions in your requirements.txt and CI pipelines. Test connectivity immediately after startup with a simple collection creation command before proceeding to schema design.

Collection Design and HNSW Parameters

Collection creation determines query speed, recall accuracy, and resource consumption for the lifetime of the project. Define vectors, distance metric, and HNSW configuration explicitly rather than accepting defaults.

from qdrant_client import QdrantClient
from qdrant_client.http.models import (
    Distance, VectorParams, HnswConfigDiff, 
    OptimizersConfigDiff, ScalarQuantization, ScalarQuantizationConfig
)

client = QdrantClient(host="qdrant-production", port=6333, api_key=API_KEY)

client.create_collection(
    collection_name="knowledge_base_v1",
    vectors_config={
        "text_dense": VectorParams(
            size=1536,
            distance=Distance.COSINE,
            hnsw_config=HnswConfigDiff(
                m=16,
                ef_construct=128,
                full_scan_threshold=15000,
                max_indexing_threads=2
            )
        )
    },
    optimizers_config=OptimizersConfigDiff(
        default_segment_number=6,
        memmap_threshold=500000,
        indexing_threshold=30000,
        flush_interval_sec=30
    ),
    quantization_config=ScalarQuantization(
        scalar=ScalarQuantizationConfig(type="int8", quantile=0.99)
    )
)

The m parameter controls the number of bi-directional links per vector in the HNSW graph. Value 16 offers strong recall for 1536-dimensional embeddings while keeping memory reasonable. For 384-dimensional models such as all-MiniLM-L6-v2, reduce to m=8. The ef_construct value of 128 builds a higher quality index during upsert at the cost of slower indexing; use 64 for faster ingestion during initial backfill. full_scan_threshold set to 15000 tells Qdrant to bypass the graph entirely for small filtered result sets, which is faster than graph traversal when fewer than 15,000 points match the filter.

Optimizers control background segment merging. Setting default_segment_number to 6 balances parallelism with overhead on a machine with 8-16 cores. memmap_threshold of 500000 vectors moves larger segments to disk, freeing RAM for the index. Enable scalar int8 quantization to reduce memory footprint by approximately four times with minimal recall loss when the quantile is tuned to 0.99. Test quantization impact by comparing search results with and without it on a validation set of 500 queries before enabling in production. Create the collection once and reuse it; altering vector size after creation requires a full data migration.

Choose shard count during creation using shards_number=4 for most workloads. Each shard operates independently, allowing parallel query execution. Increase shards only when a single node cannot keep up with ingestion or query load. Monitor shard distribution with the collection info endpoint after creation.

Payload Indexing and Advanced Filtering

Without payload indexes, every filtered search performs a full scan of matching segments. Create indexes for every field used in production filters.

client.create_payload_index(
    collection_name="knowledge_base_v1",
    field_name="tenant_id",
    field_schema="keyword"
)

client.create_payload_index(
    collection_name="knowledge_base_v1",
    field_name="created_at",
    field_schema="integer"
)

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

client.create_payload_index(
    collection_name="knowledge_base_v1",
    field_name="doc_type",
    field_schema="keyword"
)

Keyword indexes support exact matches and set inclusion. Integer indexes enable range filters on timestamps stored as Unix seconds. After indexing, construct complex filters combining multiple conditions with must, should, and must_not clauses.

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

filter_obj = Filter(
    must=[
        FieldCondition(key="tenant_id", match=MatchAny(any=["org_9876", "org_5432"])),
        FieldCondition(key="created_at", range=Range(gte=1704067200, lte=1735689600)),
        FieldCondition(key="category", match=MatchAny(any=["docs", "blog"])),
        FieldCondition(key="doc_type", match=MatchValue(value="markdown"))
    ]
)

results = client.search(
    collection_name="knowledge_base_v1",
    query_vector=query_embedding,
    query_filter=filter_obj,
    limit=15,
    offset=0,
    with_payload=["title", "url", "chunk_id"],
    with_vector=False,
    score_threshold=0.76
)

The score_threshold of 0.76 removes low-relevance matches before they reach the LLM context window. Include only required payload fields to reduce network transfer. For multi-tenant systems, always filter by tenant_id first to prevent data leakage. Measure filter selectivity using the with_count=True parameter during development to ensure indexes are effective. Drop unused indexes with client.delete_payload_index() to reclaim memory. Rebuild indexes during low-traffic periods using the force parameter if payload distribution changes significantly after bulk imports.

Hybrid Search: Dense + Sparse Vectors

Combine semantic dense vectors with sparse keyword vectors in a single collection for hybrid retrieval. Define the configuration at creation time.

client.create_collection(
    collection_name="hybrid_knowledge_v1",
    vectors_config={
        "dense": VectorParams(size=1536, distance=Distance.COSINE),
        "sparse": SparseVectorParams(modifier="idf")
    }
)

Upsert both vector types together. Sparse vectors are built from token weights, often using SPLADE or a custom BM25 implementation.

point = {
    "id": 42,
    "vector": {
        "dense": dense_embedding_list,
        "sparse": {
            "indices": [15, 289, 1240, 5821, 9324],
            "values": [1.45, 0.82, 2.13, 0.67, 1.05]
        }
    },
    "payload": {
        "title": "Implementing rate limiting in FastAPI",
        "tenant_id": "org_9876",
        "created_at": 1717200000
    }
}
client.upsert(collection_name="hybrid_knowledge_v1", points=[point])

Execute hybrid search by providing both vectors and a fusion strategy. Use Reciprocal Rank Fusion or a weighted sum of scores. Start with weights 0.65 for dense and 0.35 for sparse. Adjust after measuring nDCG on a held-out validation dataset containing both semantic and keyword queries. Sparse vectors add only 4-9% storage overhead while dramatically improving performance on queries containing product codes, error strings, or proper nouns. Disable sparse vectors for purely semantic use cases to reduce indexing time. Monitor the ratio of sparse versus dense contribution in production logs and adjust weights quarterly as content distribution evolves.

Building a Production RAG Pipeline

Integrate Qdrant into a FastAPI backend for a complete retrieval service. Create a reusable dependency:

from fastapi import Depends
from qdrant_client import QdrantClient

def get_qdrant_client():
    return QdrantClient(
        host="qdrant",
        port=6334,
        api_key=API_KEY,
        timeout=10.0,
        prefer_grpc=True
    )

class Retriever:
    def __init__(self, client: QdrantClient = Depends(get_qdrant_client)):
        self.client = client
    
    def retrieve(self, query: str, tenant_id: str, top_k: int = 9):
        embedding = embedding_model.embed_query(query)
        
        filter_obj = Filter(must=[
            FieldCondition(key="tenant_id", match=MatchValue(value=tenant_id))
        ])
        
        search_result = self.client.search(
            collection_name="hybrid_knowledge_v1",
            query_vector=embedding,
            query_filter=filter_obj,
            limit=top_k,
            score_threshold=0.74
        )
        
        context_items = []
        for hit in search_result:
            context_items.append({
                "content": hit.payload.get("content", ""),
                "title": hit.payload.get("title", ""),
                "score": hit.score
            })
        return context_items

Use gRPC for lower latency in high-throughput services. Add Redis caching of embeddings using a hash of the normalized query plus tenant_id. Set cache TTL to 300 seconds for semi-static documentation. Implement retry logic with exponential backoff around the search call to survive brief Qdrant restarts. Limit payload size returned by specifying exact fields. After retrieval, pass the context_items to an LLM prompt template that includes source attribution to reduce hallucinations. Log query latency, result count, and average score for later analysis. This pattern supports hundreds of requests per second when combined with connection pooling in the QdrantClient.

Automated Snapshots and Disaster Recovery

Configure scheduled snapshots to protect against data loss. Use the REST API or the official CLI tool.

curl -X POST http://localhost:6333/collections/knowledge_base_v1/snapshots \
  -H "api-key: your-key"

Create a cron job running every four hours on a dedicated snapshot node to avoid impacting query performance. Upload completed snapshots to S3 immediately using a script that calls aws s3 cp. Retain the last five snapshots locally and the last 30 in cold storage. Recovery steps are:

  1. Provision a new collection with identical vector and payload configuration.
  2. Call the recover endpoint with the snapshot location.
  3. Verify collection status reaches “green” using the collection info endpoint.
  4. Update aliases to point traffic to the recovered collection.

Document exact commands in your runbook and test end-to-end recovery every quarter. Snapshot creation time scales linearly with collection size; a 50 GB collection typically completes in under 12 minutes on SSD storage. Monitor snapshot success via Prometheus metric qdrant_snapshot_success_total.

Monitoring with Prometheus and Grafana

Enable the metrics endpoint and scrape it. Add this job to prometheus.yml:

- job_name: qdrant
  static_configs:
    - targets: ['qdrant-internal:6335']
  metrics_path: /metrics

Track these critical metrics: search latency histograms by collection and filter type, RAM usage per node, active optimizers, gRPC error rates, and disk I/O. Build a Grafana dashboard with panels for P50/P95/P99 latency, vectors indexed per minute, and filtered query ratio. Set alerts for latency above 150 ms for 5 minutes, memory usage above 80%, or optimizer runs exceeding 10% of uptime. Use Grafana annotations to mark deployments and snapshot times for correlation. Log query examples that exceed latency thresholds to a separate Elasticsearch index for later optimization analysis. This monitoring setup catches performance regressions within minutes of introduction.

Deploying on Kubernetes with Helm

Use the official Helm chart for repeatable deployments. Add the repository and install with production values:

helm install qdrant-prod qdrant/qdrant \
  --namespace vector-db \
  --create-namespace \
  --set replicaCount=3 \
  --set persistence.enabled=true \
  --set persistence.size=200Gi \
  --set resources.limits.cpu=6 \
  --set resources.limits.memory=24Gi \
  --set service.apiKey=your-very-long-secret-key-here \
  --set tolerations[0].key=dedicated \
  --set tolerations[0].value=vector \
  --set affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution[0].labelSelector.matchExpressions[0].key=app \
  --set affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution[0].labelSelector.matchExpressions[0].operator=In \
  --set affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution[0].labelSelector.matchExpressions[0].values[0]=qdrant

The anti-affinity rule spreads replicas across nodes. Use a dedicated storage class with high IOPS. Configure HorizontalPodAutoscaler based on custom latency metrics via Prometheus adapter. Include a PodDisruptionBudget to maintain at least two replicas during voluntary evictions. Update the Helm values file in Git and use ArgoCD or Flux for GitOps deployment. After deployment, run a validation job that inserts test vectors, performs filtered hybrid searches, and asserts latency below 80 ms before marking the release healthy.

Security Hardening for Production Clusters

Never run without an API key. Rotate keys every 90 days using a secrets manager. Enable TLS at the ingress level with automatic certificate renewal via cert-manager. For strict environments, configure internal mTLS between application pods and Qdrant pods using SPIFFE. Apply Kubernetes NetworkPolicy that allows traffic only from your application namespace on ports 6334 and 6335. At the application level, validate tenant_id on every write and read. Use collection aliases to abstract collection names from client code. Audit API access by forwarding Qdrant logs to a centralized system and alerting on any search with limit greater than 50 or missing tenant filter. These controls satisfy SOC2 and ISO 27001 requirements when combined with infrastructure scanning.

Performance Tuning and Capacity Planning

Calculate memory with the formula: (dimension × 4 bytes × vector_count × 1.35) plus index overhead of roughly 30%. For two million 1536-dim vectors expect approximately 16 GiB RAM per replica with replication factor three. Set flush_interval_sec=20 for write-heavy workloads. Batch upserts in groups of 50-100 points to maximize throughput. Use multiple concurrent upsert workers but limit total threads to available cores minus two. For query optimization, increase ef search parameter to 64 on latency-tolerant endpoints. Enable on-disk storage for segments larger than 300 MB. Re-index quarterly during maintenance windows to incorporate new quantization improvements. Track index build time and recall weekly to detect degradation.

Common Production Pitfalls and Solutions

Pitfall one: missing payload indexes on high-cardinality fields. Solution: write a pre-flight script that checks collection info and fails CI if required indexes are absent. Pitfall two: oversized payloads slowing down queries. Solution: store only metadata in Qdrant and keep full documents in PostgreSQL, joining on a stable ID. Pitfall three: single replica failure causing downtime. Solution: maintain replication factor of at least three and use readiness probes. Pitfall four: unbounded growth without archiving. Solution: implement a monthly job that moves vectors older than 18 months to a cold collection and creates a final snapshot before deletion. Pitfall five: using REST instead of gRPC in high QPS services. Solution: switch to gRPC and observe 25-40% latency reduction. Address each pitfall with automated checks rather than documentation alone.

Scaling to Tens of Millions of Vectors

At ten million vectors, deploy a minimum six-node cluster with replication factor three. Increase shard count to eight per collection. Use dedicated storage nodes with local NVMe drives. Configure max_optimization_threads per node to prevent CPU contention. Monitor segment count and trigger manual optimization only when necessary. For ingestion spikes, temporarily raise indexing thresholds and use multiple parallel importer processes. Implement read replicas by directing non-critical traffic to follower nodes when available in future versions. Archive older data into separate collections with relaxed indexing parameters. These steps keep P95 latency under 120 ms even at 30 million vectors when hardware is correctly provisioned and indexes are maintained.

Keep reading

Related Articles