YAshhh29 opened a new pull request, #69673:
URL: https://github.com/apache/airflow/pull/69673
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?
- [X] Yes -- GitHub Copilot (Claude Opus 4.6)
Generated-by: GitHub Copilot (Claude Opus 4.6) following [the
guidelines](https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst#gen-ai-assisted-contributions)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
