Qdrant - Vector Similarity Search Engine

High-performance vector database written in Rust for production RAG and semantic search.

When to use Qdrant

Use Qdrant when:

Building production RAG systems requiring low latency Need hybrid search (vectors + metadata filtering) Require horizontal scaling with sharding/replication Want on-premise deployment with full data control Need multi-vector storage per record (dense + sparse) Building real-time recommendation systems

Key features:

Rust-powered: Memory-safe, high performance Rich filtering: Filter by any payload field during search Multiple vectors: Dense, sparse, multi-dense per point Quantization: Scalar, product, binary for memory efficiency Distributed: Raft consensus, sharding, replication REST + gRPC: Both APIs with full feature parity

Use alternatives instead:

Chroma: Simpler setup, embedded use cases FAISS: Maximum raw speed, research/batch processing Pinecone: Fully managed, zero ops preferred Weaviate: GraphQL preference, built-in vectorizers Quick start Installation

Python client

pip install qdrant-client

Docker (recommended for development)

docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant

Docker with persistent storage

docker run -p 6333:6333 -p 6334:6334 \ -v $(pwd)/qdrant_storage:/qdrant/storage \ qdrant/qdrant

Basic usage from qdrant_client import QdrantClient from qdrant_client.models import Distance, VectorParams, PointStruct

Connect to Qdrant

client = QdrantClient(host="localhost", port=6333)

Create collection

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

Insert vectors with payload

client.upsert( collection_name="documents", points=[ PointStruct( id=1, vector=[0.1, 0.2, ...], # 384-dim vector payload={"title": "Doc 1", "category": "tech"} ), PointStruct( id=2, vector=[0.3, 0.4, ...], payload={"title": "Doc 2", "category": "science"} ) ] )

Search with filtering

results = client.search( collection_name="documents", query_vector=[0.15, 0.25, ...], query_filter={ "must": [{"key": "category", "match": {"value": "tech"}}] }, limit=10 )

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

Core concepts Points - Basic data unit from qdrant_client.models import PointStruct

Point = ID + Vector(s) + Payload

point = PointStruct( id=123, # Integer or UUID string vector=[0.1, 0.2, 0.3, ...], # Dense vector payload={ # Arbitrary JSON metadata "title": "Document title", "category": "tech", "timestamp": 1699900000, "tags": ["python", "ml"] } )

Batch upsert (recommended)

client.upsert( collection_name="documents", points=[point1, point2, point3], wait=True # Wait for indexing )

Collections - Vector containers from qdrant_client.models import VectorParams, Distance, HnswConfigDiff

Create with HNSW configuration

client.create_collection( collection_name="documents", vectors_config=VectorParams( size=384, # Vector dimensions distance=Distance.COSINE # COSINE, EUCLID, DOT, MANHATTAN ), hnsw_config=HnswConfigDiff( m=16, # Connections per node (default 16) ef_construct=100, # Build-time accuracy (default 100) full_scan_threshold=10000 # Switch to brute force below this ), on_disk_payload=True # Store payload on disk )

Collection info

info = client.get_collection("documents") print(f"Points: {info.points_count}, Vectors: {info.vectors_count}")

Distance metrics Metric Use Case Range COSINE Text embeddings, normalized vectors 0 to 2 EUCLID Spatial data, image features 0 to ∞ DOT Recommendations, unnormalized -∞ to ∞ MANHATTAN Sparse features, discrete data 0 to ∞ Search operations Basic search

Simple nearest neighbor search

results = client.search( collection_name="documents", query_vector=[0.1, 0.2, ...], limit=10, with_payload=True, with_vectors=False # Don't return vectors (faster) )

Filtered search from qdrant_client.models import Filter, FieldCondition, MatchValue, Range

Complex filtering

results = client.search( collection_name="documents", query_vector=query_embedding, query_filter=Filter( must=[ FieldCondition(key="category", match=MatchValue(value="tech")), FieldCondition(key="timestamp", range=Range(gte=1699000000)) ], must_not=[ FieldCondition(key="status", match=MatchValue(value="archived")) ] ), limit=10 )

Shorthand filter syntax

results = client.search( collection_name="documents", query_vector=query_embedding, query_filter={ "must": [ {"key": "category", "match": {"value": "tech"}}, {"key": "price", "range": {"gte": 10, "lte": 100}} ] }, limit=10 )

Batch search from qdrant_client.models import SearchRequest

Multiple queries in one request

results = client.search_batch( collection_name="documents", requests=[ SearchRequest(vector=[0.1, ...], limit=5), SearchRequest(vector=[0.2, ...], limit=5, filter={"must": [...]}), SearchRequest(vector=[0.3, ...], limit=10) ] )

RAG integration With sentence-transformers from sentence_transformers import SentenceTransformer from qdrant_client import QdrantClient from qdrant_client.models import VectorParams, Distance, PointStruct

Initialize

encoder = SentenceTransformer("all-MiniLM-L6-v2") client = QdrantClient(host="localhost", port=6333)

Create collection

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

Index documents

documents = [ {"id": 1, "text": "Python is a programming language", "source": "wiki"}, {"id": 2, "text": "Machine learning uses algorithms", "source": "textbook"}, ]

points = [ PointStruct( id=doc["id"], vector=encoder.encode(doc["text"]).tolist(), payload={"text": doc["text"], "source": doc["source"]} ) for doc in documents ] client.upsert(collection_name="knowledge_base", points=points)

RAG retrieval

def retrieve(query: str, top_k: int = 5) -> list[dict]: query_vector = encoder.encode(query).tolist() results = client.search( collection_name="knowledge_base", query_vector=query_vector, limit=top_k ) return [{"text": r.payload["text"], "score": r.score} for r in results]

Use in RAG pipeline

context = retrieve("What is Python?") prompt = f"Context: {context}\n\nQuestion: What is Python?"

With LangChain from langchain_community.vectorstores import Qdrant from langchain_community.embeddings import HuggingFaceEmbeddings

embeddings = HuggingFaceEmbeddings(model_name="all-MiniLM-L6-v2") vectorstore = Qdrant.from_documents(documents, embeddings, url="http://localhost:6333", collection_name="docs") retriever = vectorstore.as_retriever(search_kwargs={"k": 5})

With LlamaIndex from llama_index.vector_stores.qdrant import QdrantVectorStore from llama_index.core import VectorStoreIndex, StorageContext

vector_store = QdrantVectorStore(client=client, collection_name="llama_docs") storage_context = StorageContext.from_defaults(vector_store=vector_store) index = VectorStoreIndex.from_documents(documents, storage_context=storage_context) query_engine = index.as_query_engine()

Multi-vector support Named vectors (different embedding models) from qdrant_client.models import VectorParams, Distance

Collection with multiple vector types

client.create_collection( collection_name="hybrid_search", vectors_config={ "dense": VectorParams(size=384, distance=Distance.COSINE), "sparse": VectorParams(size=30000, distance=Distance.DOT) } )

Insert with named vectors

client.upsert( collection_name="hybrid_search", points=[ PointStruct( id=1, vector={ "dense": dense_embedding, "sparse": sparse_embedding }, payload={"text": "document text"} ) ] )

Search specific vector

results = client.search( collection_name="hybrid_search", query_vector=("dense", query_dense), # Specify which vector limit=10 )

Sparse vectors (BM25, SPLADE) from qdrant_client.models import SparseVectorParams, SparseIndexParams, SparseVector

Collection with sparse vectors

client.create_collection( collection_name="sparse_search", vectors_config={}, sparse_vectors_config={"text": SparseVectorParams(index=SparseIndexParams(on_disk=False))} )

Insert sparse vector

client.upsert( collection_name="sparse_search", points=[PointStruct(id=1, vector={"text": SparseVector(indices=[1, 5, 100], values=[0.5, 0.8, 0.2])}, payload={"text": "document"})] )

Quantization (memory optimization) from qdrant_client.models import ScalarQuantization, ScalarQuantizationConfig, ScalarType

Scalar quantization (4x memory reduction)

client.create_collection( collection_name="quantized", vectors_config=VectorParams(size=384, distance=Distance.COSINE), quantization_config=ScalarQuantization( scalar=ScalarQuantizationConfig( type=ScalarType.INT8, quantile=0.99, # Clip outliers always_ram=True # Keep quantized in RAM ) ) )

Search with rescoring

results = client.search( collection_name="quantized", query_vector=query, search_params={"quantization": {"rescore": True}}, # Rescore top results limit=10 )

Payload indexing from qdrant_client.models import PayloadSchemaType

Create payload index for faster filtering

client.create_payload_index( collection_name="documents", field_name="category", field_schema=PayloadSchemaType.KEYWORD )

client.create_payload_index( collection_name="documents", field_name="timestamp", field_schema=PayloadSchemaType.INTEGER )

Index types: KEYWORD, INTEGER, FLOAT, GEO, TEXT (full-text), BOOL

Production deployment Qdrant Cloud from qdrant_client import QdrantClient

Connect to Qdrant Cloud

client = QdrantClient( url="https://your-cluster.cloud.qdrant.io", api_key="your-api-key" )

Performance tuning

Optimize for search speed (higher recall)

client.update_collection( collection_name="documents", hnsw_config=HnswConfigDiff(ef_construct=200, m=32) )

Optimize for indexing speed (bulk loads)

client.update_collection( collection_name="documents", optimizer_config={"indexing_threshold": 20000} )

Best practices Batch operations - Use batch upsert/search for efficiency Payload indexing - Index fields used in filters Quantization - Enable for large collections (>1M vectors) Sharding - Use for collections >10M vectors On-disk storage - Enable on_disk_payload for large payloads Connection pooling - Reuse client instances Common issues

Slow search with filters:

Create payload index for filtered fields

client.create_payload_index( collection_name="docs", field_name="category", field_schema=PayloadSchemaType.KEYWORD )

Out of memory:

Enable quantization and on-disk storage

client.create_collection( collection_name="large_collection", vectors_config=VectorParams(size=384, distance=Distance.COSINE), quantization_config=ScalarQuantization(...), on_disk_payload=True )

Connection issues:

Use timeout and retry

client = QdrantClient( host="localhost", port=6333, timeout=30, prefer_grpc=True # gRPC for better performance )

References Advanced Usage - Distributed mode, hybrid search, recommendations Troubleshooting - Common issues, debugging, performance tuning Resources GitHub: https://github.com/qdrant/qdrant (22k+ stars) Docs: https://qdrant.tech/documentation/ Python Client: https://github.com/qdrant/qdrant-client Cloud: https://cloud.qdrant.io Version: 1.12.0+ License: Apache 2.0