Qdrant

When to Use

User needs vector similarity search, semantic search, or recommendation systems. Agent handles collection design, point insertion, filtered queries, and index optimization.

Quick Reference

Core Rules

1. Collection Setup

• Set vector dimension to match embedding model (e.g., OpenAI ada-002 = 1536)
• Choose distance metric deliberately: Cosine for normalized embeddings, Dot for raw scores, Euclid for absolute distance
• Wrong dimension = silent failures with zero results

2. Payload Strategy

• Store filterable metadata as payload fields
• Index payload fields used in filters: create_payload_index
• Don't store large blobs in payloads — use external storage + reference ID

3. Batch Operations

• Insert points in batches of 100-1000, not one by one
• Use upsert to handle duplicates by ID
• Parallel uploads with wait=false then verify with collection info

4. Filtering vs Post-Filtering

• Pre-filtering reduces search space = faster
• Post-filtering on results = slower, may miss relevant items

5. Search vs Scroll

6. Index Optimization

• HNSW parameters: increase m for recall, increase ef_construct for index quality
• Default m=16, ef_construct=100 works for most cases
• For millions of vectors: enable on_disk storage
• Use quantization (scalar or product) to reduce memory 4-8x

7. Multi-Tenancy

• Payload field for tenant ID + filter on every query
• Or separate collections per tenant (simpler isolation, harder to manage)
• Never expose one tenant's data to another

Common Traps

• Creating collection with wrong vector size → all searches return empty
• Forgetting wait=true on insert → querying before data indexed
• Using scroll without limit → memory exhaustion on large collections
• Not indexing payload fields → filter queries scan entire collection
• Storing embeddings in payload instead of vector field → defeats purpose