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#

TopicFileQuery patternsqueries.mdPerformance tuningperformance.md

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#

WhenUseKnown constraintsFilter in query (pre-filter)Score thresholdscore_threshold parameterComplex logicCombine must, should, must_not

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

5. Search vs Scroll#

NeedUseTop-K similarsearchAll matchingscroll with filterPaginated resultsscroll with offsetExport/backupscroll all with pagination

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