Qdrant

Qdrant is a community skill for building vector search applications using the Qdrant vector database, covering collection management, point storage, similarity search, payload filtering, and clustering for retrieval-augmented generation and recommendation systems.

What Is This?

Overview

Qdrant provides tools for storing and querying vector embeddings through a high-performance vector database with rich filtering capabilities. It covers collection management that configures vector dimensions, distance metrics, and storage optimization for different workloads, point storage that upserts vectors with structured payload data for metadata-enriched retrieval, similarity search that finds nearest vectors using HNSW indexing with configurable precision, payload filtering that combines vector similarity with structured conditions on metadata fields, and clustering that groups similar vectors for data exploration and analysis. The skill enables developers to build production vector search with advanced filtering.

Who Should Use This

This skill serves ML engineers building RAG pipelines with metadata-rich retrieval, backend developers adding semantic search to applications, and data teams building recommendation systems that combine embedding similarity with structured filters.

Why Use It?

Problems It Solves

Pure vector similarity search returns irrelevant results when metadata constraints like date ranges or categories are not applied. Self-hosted vector databases require careful index tuning for consistent query performance at scale. RAG applications need both semantic matching and exact attribute filtering in a single query. Storing vectors alongside rich metadata in separate systems creates synchronization challenges.

Core Highlights

Collection manager configures vector indexes with customizable distance metrics. Point store upserts vectors with typed payload fields for filtered retrieval. Search engine combines nearest neighbor queries with payload filtering. HNSW index provides configurable speed and accuracy trade-offs for queries.

How to Use It?

Basic Usage

from qdrant_client import (
  QdrantClient)
from qdrant_client\
  .models import (
    Distance,
    VectorParams,
    PointStruct,
    Filter,
    FieldCondition,
    MatchValue)

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

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

client.upsert(
  collection_name=
    'documents',
  points=[
    PointStruct(
      id=1,
      vector=
        [0.1] * 384,
      payload={
        'topic': 'python',
        'source': 'docs'}),
    PointStruct(
      id=2,
      vector=
        [0.2] * 384,
      payload={
        'topic': 'rust',
        'source': 'blog'})])

results = client.search(
  collection_name=
    'documents',
  query_vector=
    [0.15] * 384,
  query_filter=Filter(
    must=[
      FieldCondition(
        key='topic',
        match=MatchValue(
          value=
            'python'))]),
  limit=5)

Real-World Examples

from qdrant_client import (
  QdrantClient)
from qdrant_client\
  .models import (
    Filter,
    FieldCondition,
    Range)

class QdrantRetriever:
  def __init__(
    self,
    collection: str,
    client:
      QdrantClient
  ):
    self.collection = (
      collection)
    self.client = client

  def search(
    self,
    query_vector:
      list[float],
    top_k: int = 5,
    min_score:
      float = 0.7,
    filters: dict
      = None
  ) -> list[dict]:
    conditions = []
    if filters:
      for key, val in (
        filters.items()
      ):
        conditions.append(
          FieldCondition(
            key=key,
            match=
              MatchValue(
                value=
                  val)))
    qf = Filter(
      must=conditions
    ) if conditions \
      else None
    hits = (
      self.client.search(
        collection_name=
          self.collection,
        query_vector=
          query_vector,
        query_filter=qf,
        limit=top_k,
        score_threshold=
          min_score))
    return [{
      'id': h.id,
      'score': h.score,
      'payload':
        h.payload}
      for h in hits]

Advanced Tips

Use payload indexes on frequently filtered fields to speed up queries that combine vector similarity with metadata conditions. Configure HNSW parameters like ef_construct and m to balance index build time against query accuracy for your workload. Use named vectors to store multiple embedding types per point enabling hybrid search across different representation models.

When to Use It?

Use Cases

Build a RAG pipeline with metadata filtering that retrieves relevant documents constrained by source type and date range. Create a semantic search engine that finds similar items while filtering by category and availability. Implement a recommendation system combining user embedding similarity with business rule filters.

Related Topics

Qdrant, vector database, semantic search, RAG, HNSW, similarity search, and embedding retrieval.

Important Notes

Requirements

Qdrant server running locally or in the cloud for vector storage. qdrant-client Python package for API communication. Embedding model for generating vector representations from source data.

Usage Recommendations

Do: create payload indexes on fields used in filter conditions to improve query performance. Use batch upsert for bulk ingestion to reduce API overhead. Set score thresholds to filter low-relevance results from search responses.

Don't: store large text blobs in payload fields when external storage with ID references is more efficient. Use exact search mode on large collections since approximate HNSW search provides near-identical results with much lower latency. Create a new collection for each query when a single collection with payload filtering serves the same purpose.

Limitations

HNSW index build time increases with collection size and configuration parameters. Complex multi-field filter queries can slow down search when payload indexes are not configured. Memory usage scales with the number of vectors and payload data stored in the collection.