qdrant-haystack 11.0.0__tar.gz → 12.0.0__tar.gz

{qdrant_haystack-11.0.0 → qdrant_haystack-12.0.0}/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [integrations/qdrant-v11.1.0] - 2026-10-01
+
+### 🐛 Bug Fixes
+
+- *(qdrant)* Respect falsy run() overrides in retrievers (#4007)
+
+### 📚 Documentation
+
+- Clarify score_threshold semantics for Qdrant hybrid retrieval (#4008)
+
+
+## [integrations/qdrant-v11.0.0] - 2026-09-25
+
+### 🚜 Refactor
+
+- [**breaking**] Qdrant - propagate errors on backend failures instead of empty responses (#3997)
+
+### ⚙️ CI
+
+- Improve changelog generation; fix existing changelogs (#3883)
+
+
 ## [integrations/qdrant-v10.6.0] - 2026-09-01
 
 ### 🐛 Bug Fixes

{qdrant_haystack-11.0.0 → qdrant_haystack-12.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: qdrant-haystack
-Version: 11.0.0
+Version: 12.0.0
 Summary: An integration of Qdrant ANN vector database backend with Haystack
 Project-URL: Source, https://github.com/deepset-ai/haystack-core-integrations
 Project-URL: Documentation, https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/qdrant/README.md

{qdrant_haystack-11.0.0 → qdrant_haystack-12.0.0}/src/haystack_integrations/components/retrievers/qdrant/retriever.py

@@ -188,9 +188,9 @@ class QdrantEmbeddingRetriever:
             query_embedding=query_embedding,
             filters=filters,
             top_k=top_k or self._top_k,
-            scale_score=scale_score or self._scale_score,
-            return_embedding=return_embedding or self._return_embedding,
-            score_threshold=score_threshold or self._score_threshold,
+            scale_score=scale_score if scale_score is not None else self._scale_score,
+            return_embedding=return_embedding if return_embedding is not None else self._return_embedding,
+            score_threshold=score_threshold if score_threshold is not None else self._score_threshold,
             group_by=group_by or self._group_by,
             group_size=group_size or self._group_size,
         )
@@ -243,9 +243,9 @@ class QdrantEmbeddingRetriever:
             query_embedding=query_embedding,
             filters=filters,
             top_k=top_k or self._top_k,
-            scale_score=scale_score or self._scale_score,
-            return_embedding=return_embedding or self._return_embedding,
-            score_threshold=score_threshold or self._score_threshold,
+            scale_score=scale_score if scale_score is not None else self._scale_score,
+            return_embedding=return_embedding if return_embedding is not None else self._return_embedding,
+            score_threshold=score_threshold if score_threshold is not None else self._score_threshold,
             group_by=group_by or self._group_by,
             group_size=group_size or self._group_size,
         )
@@ -433,9 +433,9 @@ class QdrantSparseEmbeddingRetriever:
             query_sparse_embedding=query_sparse_embedding,
             filters=filters,
             top_k=top_k or self._top_k,
-            scale_score=scale_score or self._scale_score,
-            return_embedding=return_embedding or self._return_embedding,
-            score_threshold=score_threshold or self._score_threshold,
+            scale_score=scale_score if scale_score is not None else self._scale_score,
+            return_embedding=return_embedding if return_embedding is not None else self._return_embedding,
+            score_threshold=score_threshold if score_threshold is not None else self._score_threshold,
             group_by=group_by or self._group_by,
             group_size=group_size or self._group_size,
         )
@@ -493,9 +493,9 @@ class QdrantSparseEmbeddingRetriever:
             query_sparse_embedding=query_sparse_embedding,
             filters=filters,
             top_k=top_k or self._top_k,
-            scale_score=scale_score or self._scale_score,
-            return_embedding=return_embedding or self._return_embedding,
-            score_threshold=score_threshold or self._score_threshold,
+            scale_score=scale_score if scale_score is not None else self._scale_score,
+            return_embedding=return_embedding if return_embedding is not None else self._return_embedding,
+            score_threshold=score_threshold if score_threshold is not None else self._score_threshold,
             group_by=group_by or self._group_by,
             group_size=group_size or self._group_size,
         )
@@ -560,9 +560,10 @@ class QdrantHybridRetriever:
         :param return_embedding: Whether to return the embeddings of the retrieved Documents.
         :param filter_policy: Policy to determine how filters are applied.
         :param score_threshold: A minimal score threshold for the result.
-            Score of the returned result might be higher or smaller than the threshold
-             depending on the Distance function used.
-            E.g. for cosine similarity only higher scores will be returned.
+            The threshold is applied to the fused Reciprocal Rank Fusion (RRF) scores, so only documents with a
+            higher fused score are returned. RRF scores are not comparable to dense or sparse similarity scores,
+            so thresholds tuned for those retrievers don't carry over. With `group_by`, groups with no surviving
+            hits are dropped.
         :param group_by: Payload field to group by, must be a string or number field. If the field contains more than 1
              value, all values will be used for grouping. One point can be in multiple groups.
         :param group_size: Maximum amount of points to return per group. Default is 3.
@@ -659,7 +660,7 @@ class QdrantHybridRetriever:
         rrf_weights: list[float] | None = None,
     ) -> dict[str, list[Document]]:
         """
-        Run the Sparse Embedding Retriever on the given input data.
+        Run the Hybrid Retriever on the given input data.
 
         :param query_embedding: Dense embedding of the query.
         :param query_sparse_embedding: Sparse embedding of the query.
@@ -670,9 +671,10 @@ class QdrantHybridRetriever:
              groups to return.
         :param return_embedding: Whether to return the embedding of the retrieved Documents.
         :param score_threshold: A minimal score threshold for the result.
-            Score of the returned result might be higher or smaller than the threshold
-             depending on the Distance function used.
-            E.g. for cosine similarity only higher scores will be returned.
+            The threshold is applied to the fused Reciprocal Rank Fusion (RRF) scores, so only documents with a
+            higher fused score are returned. RRF scores are not comparable to dense or sparse similarity scores,
+            so thresholds tuned for those retrievers don't carry over. With `group_by`, groups with no surviving
+            hits are dropped.
         :param group_by: Payload field to group by, must be a string or number field. If the field contains more than 1
              value, all values will be used for grouping. One point can be in multiple groups.
         :param group_size: Maximum amount of points to return per group. Default is 3.
@@ -704,8 +706,8 @@ class QdrantHybridRetriever:
             query_sparse_embedding=query_sparse_embedding,
             filters=filters,
             top_k=top_k or self._top_k,
-            return_embedding=return_embedding or self._return_embedding,
-            score_threshold=score_threshold or self._score_threshold,
+            return_embedding=return_embedding if return_embedding is not None else self._return_embedding,
+            score_threshold=score_threshold if score_threshold is not None else self._score_threshold,
             group_by=group_by or self._group_by,
             group_size=group_size or self._group_size,
             rrf_k=rrf_k if rrf_k is not None else self._rrf_k,
@@ -729,7 +731,7 @@ class QdrantHybridRetriever:
         rrf_weights: list[float] | None = None,
     ) -> dict[str, list[Document]]:
         """
-        Asynchronously run the Sparse Embedding Retriever on the given input data.
+        Asynchronously run the Hybrid Retriever on the given input data.
 
         :param query_embedding: Dense embedding of the query.
         :param query_sparse_embedding: Sparse embedding of the query.
@@ -740,9 +742,10 @@ class QdrantHybridRetriever:
              groups to return.
         :param return_embedding: Whether to return the embedding of the retrieved Documents.
         :param score_threshold: A minimal score threshold for the result.
-            Score of the returned result might be higher or smaller than the threshold
-             depending on the Distance function used.
-            E.g. for cosine similarity only higher scores will be returned.
+            The threshold is applied to the fused Reciprocal Rank Fusion (RRF) scores, so only documents with a
+            higher fused score are returned. RRF scores are not comparable to dense or sparse similarity scores,
+            so thresholds tuned for those retrievers don't carry over. With `group_by`, groups with no surviving
+            hits are dropped.
         :param group_by: Payload field to group by, must be a string or number field. If the field contains more than 1
              value, all values will be used for grouping. One point can be in multiple groups.
         :param group_size: Maximum amount of points to return per group. Default is 3.
@@ -774,8 +777,8 @@ class QdrantHybridRetriever:
             query_sparse_embedding=query_sparse_embedding,
             filters=filters,
             top_k=top_k or self._top_k,
-            return_embedding=return_embedding or self._return_embedding,
-            score_threshold=score_threshold or self._score_threshold,
+            return_embedding=return_embedding if return_embedding is not None else self._return_embedding,
+            score_threshold=score_threshold if score_threshold is not None else self._score_threshold,
             group_by=group_by or self._group_by,
             group_size=group_size or self._group_size,
             rrf_k=rrf_k if rrf_k is not None else self._rrf_k,

{qdrant_haystack-11.0.0 → qdrant_haystack-12.0.0}/src/haystack_integrations/document_stores/qdrant/document_store.py

@@ -11,7 +11,7 @@ from haystack.dataclasses import Document
 from haystack.dataclasses.sparse_embedding import SparseEmbedding
 from haystack.document_stores.errors import DocumentStoreError, DuplicateDocumentError
 from haystack.document_stores.types import DuplicatePolicy
-from haystack.utils import Secret, deserialize_secrets_inplace
+from haystack.utils import Secret
 from haystack.utils.misc import _normalize_metadata_field_name
 from numpy import exp
 from qdrant_client.http import models as rest
@@ -1432,7 +1432,6 @@ class QdrantDocumentStore:
         :returns:
             The deserialized component.
         """
-        deserialize_secrets_inplace(data["init_parameters"], keys=["api_key"])
         return default_from_dict(cls, data)
 
     def to_dict(self) -> dict[str, Any]:
@@ -1757,9 +1756,10 @@ class QdrantDocumentStore:
              groups to return.
         :param return_embedding: Whether to return the embeddings of the retrieved documents.
         :param score_threshold: A minimal score threshold for the result.
-            Score of the returned result might be higher or smaller than the threshold
-             depending on the Distance function used.
-            E.g. for cosine similarity only higher scores will be returned.
+            The threshold is applied to the fused Reciprocal Rank Fusion (RRF) scores, so only documents with a
+            higher fused score are returned. RRF scores are not comparable to dense or sparse similarity scores,
+            so thresholds tuned for those retrievers don't carry over. With `group_by`, groups with no surviving
+            hits are dropped.
         :param group_by: Payload field to group by, must be a string or number field. If the field contains more than 1
              value, all values will be used for grouping. One point can be in multiple groups.
         :param group_size: Maximum amount of points to return per group. Default is 3.
@@ -2020,9 +2020,10 @@ class QdrantDocumentStore:
              groups to return.
         :param return_embedding: Whether to return the embeddings of the retrieved documents.
         :param score_threshold: A minimal score threshold for the result.
-            Score of the returned result might be higher or smaller than the threshold
-             depending on the Distance function used.
-            E.g. for cosine similarity only higher scores will be returned.
+            The threshold is applied to the fused Reciprocal Rank Fusion (RRF) scores, so only documents with a
+            higher fused score are returned. RRF scores are not comparable to dense or sparse similarity scores,
+            so thresholds tuned for those retrievers don't carry over. With `group_by`, groups with no surviving
+            hits are dropped.
         :param group_by: Payload field to group by, must be a string or number field. If the field contains more than 1
              value, all values will be used for grouping. One point can be in multiple groups.
         :param group_size: Maximum amount of points to return per group. Default is 3.

{qdrant_haystack-11.0.0 → qdrant_haystack-12.0.0}/src/haystack_integrations/document_stores/qdrant/filters.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2023-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from collections.abc import Callable
 from datetime import datetime
 from typing import Any
@@ -131,8 +135,6 @@ def _build_comparison_condition(operator: str, key: str, value: Any) -> models.C
 
 
 def _build_eq_condition(key: str, value: models.ValueVariants) -> models.Condition:
-    if isinstance(value, str) and " " in value:
-        return models.FieldCondition(key=key, match=models.MatchText(text=value))
     return models.FieldCondition(key=key, match=models.MatchValue(value=value))
 
 
@@ -140,44 +142,18 @@ def _build_in_condition(key: str, value: list[models.ValueVariants]) -> models.C
     if not isinstance(value, list):
         msg = f"Value {value} is not a list"
         raise FilterError(msg)
-    return models.Filter(
-        should=[
-            (
-                models.FieldCondition(key=key, match=models.MatchText(text=item))
-                if isinstance(item, str) and " " not in item
-                else models.FieldCondition(key=key, match=models.MatchValue(value=item))
-            )
-            for item in value
-        ]
-    )
+    return models.Filter(should=[_build_eq_condition(key, item) for item in value])
 
 
 def _build_ne_condition(key: str, value: models.ValueVariants) -> models.Condition:
-    return models.Filter(
-        must_not=[
-            (
-                models.FieldCondition(key=key, match=models.MatchText(text=value))
-                if isinstance(value, str) and " " not in value
-                else models.FieldCondition(key=key, match=models.MatchValue(value=value))
-            )
-        ]
-    )
+    return models.Filter(must_not=[_build_eq_condition(key, value)])
 
 
 def _build_nin_condition(key: str, value: list[models.ValueVariants]) -> models.Condition:
     if not isinstance(value, list):
         msg = f"Value {value} is not a list"
         raise FilterError(msg)
-    return models.Filter(
-        must_not=[
-            (
-                models.FieldCondition(key=key, match=models.MatchText(text=item))
-                if isinstance(item, str) and " " in item
-                else models.FieldCondition(key=key, match=models.MatchValue(value=item))
-            )
-            for item in value
-        ]
-    )
+    return models.Filter(must_not=[_build_eq_condition(key, item) for item in value])
 
 
 def _build_lt_condition(key: str, value: str | float | int) -> models.Condition:

{qdrant_haystack-11.0.0 → qdrant_haystack-12.0.0}/tests/test_embedding_retriever.py

@@ -200,6 +200,37 @@ class TestQdrantRetriever:
         mock_store._query_by_embedding_async.assert_awaited_once()
         assert res["documents"][0].content == "doc"
 
+    def test_run_falsy_runtime_values_override_init(self):
+        mock_store = Mock(spec=QdrantDocumentStore)
+        mock_store._query_by_embedding.return_value = []
+
+        retriever = QdrantEmbeddingRetriever(
+            document_store=mock_store, scale_score=True, return_embedding=True, score_threshold=0.5
+        )
+        retriever.run(query_embedding=[0.5, 0.7], scale_score=False, return_embedding=False, score_threshold=0.0)
+
+        call_kwargs = mock_store._query_by_embedding.call_args.kwargs
+        assert call_kwargs["scale_score"] is False
+        assert call_kwargs["return_embedding"] is False
+        assert call_kwargs["score_threshold"] == 0.0
+
+    @pytest.mark.asyncio
+    async def test_run_async_falsy_runtime_values_override_init(self):
+        mock_store = Mock(spec=QdrantDocumentStore)
+        mock_store._query_by_embedding_async = AsyncMock(return_value=[])
+
+        retriever = QdrantEmbeddingRetriever(
+            document_store=mock_store, scale_score=True, return_embedding=True, score_threshold=0.5
+        )
+        await retriever.run_async(
+            query_embedding=[0.5, 0.7], scale_score=False, return_embedding=False, score_threshold=0.0
+        )
+
+        call_kwargs = mock_store._query_by_embedding_async.call_args.kwargs
+        assert call_kwargs["scale_score"] is False
+        assert call_kwargs["return_embedding"] is False
+        assert call_kwargs["score_threshold"] == 0.0
+
     def test_run_raises_when_merge_with_native_init_filter(self):
         document_store = QdrantDocumentStore(location=":memory:", index="test")
         retriever = QdrantEmbeddingRetriever(

{qdrant_haystack-11.0.0 → qdrant_haystack-12.0.0}/tests/test_filters.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2023-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
 import pytest
 from haystack import Document
 from haystack.testing.document_store import FilterDocumentsTest
@@ -49,16 +53,6 @@ class TestConvertFiltersToQdrantUnit:
         )
         assert isinstance(qdrant_filter, models.Filter)
 
-    def test_eq_with_spaces_uses_text_match(self):
-        qdrant_filter = convert_filters_to_qdrant({"operator": "==", "field": "meta.title", "value": "hello world"})
-        condition = qdrant_filter.must[0]
-        assert isinstance(condition.match, models.MatchText)
-
-    def test_eq_without_spaces_uses_value_match(self):
-        qdrant_filter = convert_filters_to_qdrant({"operator": "==", "field": "meta.name", "value": "name_0"})
-        condition = qdrant_filter.must[0]
-        assert isinstance(condition.match, models.MatchValue)
-
     def test_single_logical_condition_unwrapped(self):
         qdrant_filter = convert_filters_to_qdrant(
             {
@@ -96,6 +90,54 @@ class TestQdrantFilters(FilterDocumentsTest):
             wait_result_from_api=True,
         )
 
+    @pytest.mark.parametrize(("value", "longer_value"), [("news", "newsletter"), ("New York", "New York City")])
+    def test_eq_matches_exact_string(self, document_store, value, longer_value):
+        exact_document = Document(content=value, meta={"name": value})
+        other_document = Document(content=longer_value, meta={"name": longer_value})
+        document_store.write_documents([exact_document, other_document])
+
+        result = document_store.filter_documents(filters={"field": "meta.name", "operator": "==", "value": value})
+
+        self.assert_documents_are_equal(result, [exact_document])
+
+    @pytest.mark.parametrize(("value", "longer_value"), [("news", "newsletter"), ("New York", "New York City")])
+    def test_ne_excludes_exact_string(self, document_store, value, longer_value):
+        exact_document = Document(content=value, meta={"name": value})
+        other_document = Document(content=longer_value, meta={"name": longer_value})
+        document_store.write_documents([exact_document, other_document])
+
+        result = document_store.filter_documents(filters={"field": "meta.name", "operator": "!=", "value": value})
+
+        self.assert_documents_are_equal(result, [other_document])
+
+    def test_in_matches_exact_strings(self, document_store):
+        document_store.write_documents(
+            [
+                Document(content=name, meta={"name": name})
+                for name in ["news", "newsletter", "New York", "New York City"]
+            ]
+        )
+
+        result = document_store.filter_documents(
+            filters={"field": "meta.name", "operator": "in", "value": ["news", "New York"]}
+        )
+
+        assert sorted(doc.meta["name"] for doc in result) == ["New York", "news"]
+
+    def test_not_in_excludes_exact_strings(self, document_store):
+        document_store.write_documents(
+            [
+                Document(content=name, meta={"name": name})
+                for name in ["news", "newsletter", "New York", "New York City"]
+            ]
+        )
+
+        result = document_store.filter_documents(
+            filters={"field": "meta.name", "operator": "not in", "value": ["news", "New York"]}
+        )
+
+        assert sorted(doc.meta["name"] for doc in result) == ["New York City", "newsletter"]
+
     def test_filter_documents_with_qdrant_filters(self, document_store, filterable_docs):
         document_store.write_documents(filterable_docs)
         result = document_store.filter_documents(

{qdrant_haystack-11.0.0 → qdrant_haystack-12.0.0}/tests/test_hybrid_retriever.py

@@ -229,6 +229,39 @@ class TestQdrantHybridRetriever:
         assert call_args[1]["rrf_k"] == 100
         assert call_args[1]["rrf_weights"] == [3.0, 1.0]
 
+    def test_run_falsy_runtime_values_override_init(self):
+        mock_store = Mock(spec=QdrantDocumentStore)
+        mock_store._query_hybrid.return_value = []
+
+        retriever = QdrantHybridRetriever(document_store=mock_store, return_embedding=True, score_threshold=0.5)
+        retriever.run(
+            query_embedding=[0.5, 0.7],
+            query_sparse_embedding=SparseEmbedding(indices=[0, 5], values=[0.1, 0.7]),
+            return_embedding=False,
+            score_threshold=0.0,
+        )
+
+        call_args = mock_store._query_hybrid.call_args
+        assert call_args[1]["return_embedding"] is False
+        assert call_args[1]["score_threshold"] == 0.0
+
+    @pytest.mark.asyncio
+    async def test_run_async_falsy_runtime_values_override_init(self):
+        mock_store = Mock(spec=QdrantDocumentStore)
+        mock_store._query_hybrid_async = AsyncMock(return_value=[])
+
+        retriever = QdrantHybridRetriever(document_store=mock_store, return_embedding=True, score_threshold=0.5)
+        await retriever.run_async(
+            query_embedding=[0.5, 0.7],
+            query_sparse_embedding=SparseEmbedding(indices=[0, 5], values=[0.1, 0.7]),
+            return_embedding=False,
+            score_threshold=0.0,
+        )
+
+        call_args = mock_store._query_hybrid_async.call_args
+        assert call_args[1]["return_embedding"] is False
+        assert call_args[1]["score_threshold"] == 0.0
+
     def test_run_with_group_by(self):
         mock_store = Mock(spec=QdrantDocumentStore)
         sparse_embedding = SparseEmbedding(indices=[0, 1, 2, 3], values=[0.1, 0.8, 0.05, 0.33])

{qdrant_haystack-11.0.0 → qdrant_haystack-12.0.0}/tests/test_sparse_embedding_retriever.py

@@ -199,6 +199,39 @@ class TestQdrantSparseEmbeddingRetriever:
         mock_store._query_by_sparse_async.assert_awaited_once()
         assert res["documents"][0].content == "doc"
 
+    def test_run_falsy_runtime_values_override_init(self):
+        mock_store = Mock(spec=QdrantDocumentStore)
+        mock_store._query_by_sparse.return_value = []
+        sparse = SparseEmbedding(indices=[0, 5], values=[0.1, 0.7])
+
+        retriever = QdrantSparseEmbeddingRetriever(
+            document_store=mock_store, scale_score=True, return_embedding=True, score_threshold=0.5
+        )
+        retriever.run(query_sparse_embedding=sparse, scale_score=False, return_embedding=False, score_threshold=0.0)
+
+        call_kwargs = mock_store._query_by_sparse.call_args.kwargs
+        assert call_kwargs["scale_score"] is False
+        assert call_kwargs["return_embedding"] is False
+        assert call_kwargs["score_threshold"] == 0.0
+
+    @pytest.mark.asyncio
+    async def test_run_async_falsy_runtime_values_override_init(self):
+        mock_store = Mock(spec=QdrantDocumentStore)
+        mock_store._query_by_sparse_async = AsyncMock(return_value=[])
+        sparse = SparseEmbedding(indices=[0, 5], values=[0.1, 0.7])
+
+        retriever = QdrantSparseEmbeddingRetriever(
+            document_store=mock_store, scale_score=True, return_embedding=True, score_threshold=0.5
+        )
+        await retriever.run_async(
+            query_sparse_embedding=sparse, scale_score=False, return_embedding=False, score_threshold=0.0
+        )
+
+        call_kwargs = mock_store._query_by_sparse_async.call_args.kwargs
+        assert call_kwargs["scale_score"] is False
+        assert call_kwargs["return_embedding"] is False
+        assert call_kwargs["score_threshold"] == 0.0
+
     def test_run_raises_when_merge_with_native_filter(self):
         document_store = QdrantDocumentStore(location=":memory:", index="test")
         retriever = QdrantSparseEmbeddingRetriever(