Qdrant Cheatsheet: Collections, Filters and Hybrid Search Reference

# Docker — single-node server (HTTP :6333, gRPC :6334)
docker run -p 6333:6333 -p 6334:6334 \
  -v $(pwd)/qdrant_storage:/qdrant/storage \
  qdrant/qdrant:latest

# Python client
pip install "qdrant-client>=1.10"           # core sync + async
pip install "qdrant-client[fastembed]"      # bundled ONNX embedders

# JS / TS
npm install @qdrant/js-client-rest @qdrant/js-client-grpc

# Health check
curl http://localhost:6333/healthz
# → "healthz check passed"

# Web dashboard — http://localhost:6333/dashboard

from qdrant_client import QdrantClient
from qdrant_client.models import Filter, FieldCondition, MatchValue, MatchAny, Range

client = QdrantClient(url="http://localhost:6333")

flt = Filter(
    must=[                                 # AND
        FieldCondition(key="source", match=MatchValue(value="docs")),
        FieldCondition(key="year",   range=Range(gte=2024)),
    ],
    should=[                               # OR (any one)
        FieldCondition(key="tag", match=MatchAny(any=["rag", "embed"])),
    ],
    must_not=[                             # AND NOT
        FieldCondition(key="deleted", match=MatchValue(value=True)),
    ],
)

# Filtered ANN search
hits = client.query_points(
    collection_name="kb",
    query=[0.0]*384,                       # your query vector
    query_filter=flt,
    limit=5,
    with_payload=True,
)

# Filter-only scroll (no similarity — great for paginating tags)
points, next_page = client.scroll(
    collection_name="kb",
    scroll_filter=flt,
    limit=100,
    with_payload=True,
)

from qdrant_client import QdrantClient
from qdrant_client.models import (
    VectorParams, SparseVectorParams, Distance,
    PointStruct, SparseVector, NamedVector,
    Prefetch, Fusion, FusionQuery,
)

client = QdrantClient(":memory:")

# Named vectors: one collection holds both dense + sparse, named slots
client.create_collection(
    "kb-hybrid",
    vectors_config={"dense": VectorParams(size=384, distance=Distance.COSINE)},
    sparse_vectors_config={"bm25": SparseVectorParams()},
)

# Upsert one point with both
client.upsert("kb-hybrid", points=[PointStruct(
    id="d1",
    vector={
        "dense": [0.01]*384,
        "bm25":  SparseVector(indices=[7, 42], values=[0.8, 1.2]),
    },
    payload={"text": "..."},
)])

# Hybrid query — RRF fuses dense ANN + sparse top-k server-side
res = client.query_points(
    collection_name="kb-hybrid",
    prefetch=[
        Prefetch(query=[0.0]*384, using="dense", limit=20),
        Prefetch(query=SparseVector(indices=[7,42], values=[1.0,1.0]),
                 using="bm25", limit=20),
    ],
    query=FusionQuery(fusion=Fusion.RRF),   # reciprocal rank fusion
    limit=5,
)

# Minimal Qdrant store — create, upsert, filtered query
import os
from qdrant_client import QdrantClient
from qdrant_client.models import (
    VectorParams, Distance, PointStruct,
    Filter, FieldCondition, MatchValue, PayloadSchemaType,
)
from openai import OpenAI

client = QdrantClient(url="http://localhost:6333",
                      api_key=os.getenv("QDRANT_API_KEY"))   # cloud / authed
oai = OpenAI()

NAME, DIM = "kb", 1536
if not client.collection_exists(NAME):
    client.create_collection(
        collection_name=NAME,
        vectors_config=VectorParams(size=DIM, distance=Distance.COSINE),
    )
    # Indexed payload field — without this, filters on "source" do full scans
    client.create_payload_index(NAME, "source", PayloadSchemaType.KEYWORD)

def embed(texts):
    return [d.embedding for d in
            oai.embeddings.create(model="text-embedding-3-small", input=texts).data]

docs = [
    {"id": 1, "text": "Qdrant is a Rust vector DB.",     "source": "blog"},
    {"id": 2, "text": "RAG joins retrieval with gen.",   "source": "docs"},
    {"id": 3, "text": "Payload indexes speed filters.",  "source": "docs"},
]
vecs = embed([d["text"] for d in docs])

client.upsert(NAME, points=[
    PointStruct(id=d["id"], vector=v, payload=d) for d, v in zip(docs, vecs)
])

q = embed(["what is RAG?"])[0]
res = client.query_points(
    collection_name=NAME,
    query=q, limit=2,
    query_filter=Filter(must=[FieldCondition(
        key="source", match=MatchValue(value="docs"))]),
    with_payload=True,
)
for p in res.points:
    print(f"{p.score:.3f}  [{p.payload['source']}]  {p.payload['text']}")