Hybrid Retrieval: Combining Metadata and Vector Search

Welcome back! In the previous lesson, we explored the concept of similarity search using cosine similarity to measure the similarity between text embeddings. This foundational knowledge is crucial as we delve into more advanced techniques. Now, we will focus on hybrid retrieval, a powerful approach that combines metadata and vector search to enhance search results. This technique allows us to leverage both the semantic meaning captured in vector embeddings and the structured information available in metadata. By the end of this lesson, you will understand how to implement hybrid retrieval using Qdrant, a vector database that excels in handling such tasks.

Hybrid retrieval leverages the strengths of both metadata and vector search. Metadata provides structured information that can refine search queries, while vector search uses embeddings to understand the semantic meaning of text. By combining these approaches, we can achieve more precise and relevant search outcomes. Let's explore how this works in practice.

Before we dive into the implementation, let's briefly revisit the concepts of metadata and vector search. Metadata refers to structured information that describes the content of a document, such as categories, tags, or author names. It allows us to filter and refine search queries based on specific attributes.

In this lesson, we use “hybrid retrieval” to mean combining vector similarity with payload metadata filters. In other systems, hybrid search may also refer to dense+sparse or keyword+vector score fusion.

Vector search, on the other hand, uses embeddings to capture the semantic meaning of text. By representing text as vectors, we can measure the similarity between different pieces of text, enabling us to perform semantic searches that go beyond simple keyword matching.

Combining metadata and vector search allows us to leverage the strengths of both approaches. Metadata helps us narrow down the search space, while vector search ensures that the results are semantically relevant. This synergy is what makes hybrid retrieval a powerful tool in semantic search systems.

Pipeline overview:

query text -> embedding -> Qdrant vector search -> payload metadata filter -> ranked filtered results

Let's set up some sample data using Qdrant. This will help us understand how the data is structured and how it can be queried.

In a real project, move this repeated setup into a helper such as initialize_collection(...) so later examples can focus on the query and filtering logic. We show the setup once here for clarity.

from sentence_transformers import SentenceTransformer
from qdrant_client import QdrantClient
from qdrant_client.http import models
import json
import itertools

# Config
collection_name = "hybrid-demo"
file_path = "./data/corpus.json"
batch_size = 32  # adjust as needed

# Load the embedding model
model = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")

# Load documents from JSON file
with open(file_path, "r", encoding="utf-8") as f:
    documents = json.load(f)

# Helper: chunk generator
def chunks(iterable, size):
    it = iter(iterable)
    while True:
        batch = list(itertools.islice(it, size))
        if not batch:
            break
        yield batch

# Initialize Qdrant client (in-memory for demo; replace with real endpoint in production)
client = QdrantClient(":memory:")
vector_dim = model.get_sentence_embedding_dimension()

# Recreate collection if it exists
if client.collection_exists(collection_name):
    client.delete_collection(collection_name)

client.create_collection(
    collection_name=collection_name,
    vectors_config=models.VectorParams(size=vector_dim, distance=models.Distance.COSINE)
)

# Batch encode + upsert
for batch_idx, batch_docs in enumerate(chunks(documents, batch_size)):
    texts = [doc.get("content", "") for doc in batch_docs]
    embeddings = model.encode(texts, show_progress_bar=False).tolist()

    points = [
        models.PointStruct(
            id=batch_idx * batch_size + i,
            vector=emb,
            payload={
                "title": doc.get("title", ""),
                "content": doc.get("content", ""),
                "category": doc.get("category", "unknown"),
                "tags": doc.get("tags", []),
                "date": doc.get("date", "")
            }
        )
        for i, (doc, emb) in enumerate(zip(batch_docs, embeddings))
    ]

    client.upsert(collection_name=collection_name, points=points)
    print(f"Upserted batch {batch_idx+1}, {len(points)} points")

Output:

Upserted batch 1, 32 points
Upserted batch 2, 32 points
Upserted batch 3, 32 points
Upserted batch 4, 32 points
Upserted batch 5, 22 points

In this setup, we load documents from a JSON file and initialize a Qdrant collection. The helper function batches the data, generates embeddings, and upserts the data into the collection, including metadata such as title, category, tags, and date. The expression batch_idx * batch_size + i ensures that each document gets a unique ID across all batches, avoiding any ID collisions. This data will be used in our hybrid retrieval examples.