Skip to content

Add QdrantSearchOperator for vector similarity search#69673

Open
YAshhh29 wants to merge 6 commits into
apache:mainfrom
YAshhh29:feature/qdrant-search-operator
Open

Add QdrantSearchOperator for vector similarity search#69673
YAshhh29 wants to merge 6 commits into
apache:mainfrom
YAshhh29:feature/qdrant-search-operator

Conversation

@YAshhh29

@YAshhh29 YAshhh29 commented Jul 9, 2026

Copy link
Copy Markdown
Contributor

The Qdrant provider today lets users write vectors into a collection
(QdrantIngestOperator) but has no operator for the other half of a RAG
pipeline: reading them back out. Users who want to run a similarity search
from a DAG have to reach into hook.conn.query_points directly and remember
to convert the returned pydantic ScoredPoint objects into plain dicts so
Airflow can serialize them to XCom -- a footgun that shows up as a cryptic
serialization error at runtime.

This PR adds QdrantSearchOperator, a first-class task that closes that
gap. Every other vector-DB provider (Pinecone, Weaviate) is missing the
same operator; Qdrant is the leanest of the three (its hook doesn't even
have a search method today), so it's the cleanest place to start.

How I found and verified this gap

This isn't tied to an existing issue -- I discovered it by auditing the
operator surface of every AI/ML provider in Airflow (openai, cohere,
pinecone, weaviate, qdrant, pgvector), the same audit approach behind
#69408 and #69534. For each provider I compared what the hook/client can
do to what's actually exposed as operators.

The pattern that jumped out: every vector-DB provider is missing a
search operator
. Users can ingest with a proper operator but must fall
back to raw hook calls to query. That's the retrieval half of RAG living
outside the Airflow abstraction.

Before writing a line of code I confirmed:

  1. No competing work in flight. GitHub search returned 0 open PRs and
    0 open issues mentioning "qdrant search" -- greenfield, no one else
    was building this.
  2. The upstream API is stable and modern. qdrant-client 1.18.0
    (the provider pins >=1.17.1) exposes query_points with every one
    of the 9 named parameters this operator forwards; the older search()
    method is deprecated and slated for removal.
  3. The response contract is what I assumed. QueryResponse.points
    is List[ScoredPoint], and ScoredPoint.model_dump() produces the
    id/score/payload/vector/version/shard_key/order_value dict shape
    the operator promises callers.
  4. The provider's registry auto-discovers by module, not by class.
    python-modules in provider.yaml covers any class in
    operators/qdrant.py, so adding one needs zero registry edits.

Only then did I write the code, in the small incremental steps you can
see in the six commits (hook -> hook tests -> operator -> operator tests
-> example DAG -> docs).

Design decisions

  • A hook method + a thin operator, not just an operator. A new
    QdrantHook.search() wraps QdrantClient.query_points and converts
    each returned ScoredPoint to a plain dict via model_dump(). The
    operator is a ~10-line delegate on top. This mirrors the operator/hook
    split every other provider uses -- and gives tests a clean seam to
    mock at.
  • XCom-safe by construction. The hook returns list[dict[str, Any]]
    (id, score, payload, and optionally vector), so results land in XCom
    without any user-side workaround.
  • Uses query_points, not the deprecated search(). The search()
    API in qdrant-client is scheduled for removal in a future major;
    query_points is the modern surface (also supports named/sparse
    vectors, hybrid search, etc.). A regression test asserts we never
    fall back to the deprecated method.
  • **kwargs passthrough. Forwards any query_points parameter we
    don't enumerate (using, prefetch, lookup_from, ...) so the hook
    stays forward-compatible with hybrid search and named vectors without
    a follow-up PR.

What changes

  • providers/qdrant/src/airflow/providers/qdrant/hooks/qdrant.py
    • New QdrantHook.search(...) method wrapping query_points, returning
      list[dict] via ScoredPoint.model_dump().
  • providers/qdrant/src/airflow/providers/qdrant/operators/qdrant.py
    • New QdrantSearchOperator class alongside the existing
      QdrantIngestOperator. template_fields include collection_name,
      query, query_filter, limit so a RAG DAG can XCom-pull a query
      vector from an upstream embedding task.
  • providers/qdrant/tests/unit/qdrant/hooks/test_qdrant.py
    • Three tests: return type is list[dict] via model_dump; uses
      query_points (not deprecated search) with all named args
      forwarded; extra **kwargs also forwarded.
  • providers/qdrant/tests/unit/qdrant/operators/test_qdrant.py
    • Five tests: execute returns the hook result; defaults forward as
      expected; every optional arg reaches the hook; template_fields
      cover the runtime parameters; default conn_id matches the hook's.
  • providers/qdrant/tests/system/qdrant/example_dag_qdrant.py
    • Adds a QdrantSearchOperator task downstream of the existing
      ingest task with # [START/END] howto_operator_qdrant_search
      markers.
  • providers/qdrant/docs/operators/qdrant.rst
    • How-to section with the matching .. _howto/operator:QdrantSearchOperator:
      anchor and an .. exampleinclude:: pulling the DAG snippet.

No provider.yaml / get_provider_info.py changes needed: the registry
lists python-modules, not classes, so a new class in an existing module is
picked up automatically. No changelog edit either -- provider changelogs
are regenerated from git log by the release manager per AGENTS.md.

Testing

  • All 8 unit tests pass locally (3 hook + 5 operator), verified via
    a standalone harness that runs the real hook/operator code with mocked
    Qdrant client + a BaseHook/BaseOperator shim (full Airflow can't
    run on Windows).
  • API contract verified against qdrant-client 1.18.0: query_points
    accepts every one of the 9 named parameters we forward, and
    QueryResponse.points is a List[ScoredPoint] with the expected
    model_dump() shape (id, score, payload, vector, ...).
  • Regression check: QdrantIngestOperator still constructs and
    behaves identically -- we only added to the module, no existing code
    was touched.
  • Full-provider ruff check + ruff format --check: 26 files clean.
  • Self-reviewed against every rule in .github/instructions/code-review.instructions.md
    -- no red flags (no time.time, no assert in prod, no new
    AirflowException, no British spellings, no missing tests).

Was generative AI tooling used to co-author this PR?
  • Yes -- GitHub Copilot (Claude Opus 4.6)

Generated-by: GitHub Copilot (Claude Opus 4.6) following the guidelines

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants