ibm-db-haystack 0.3.0__tar.gz → 0.4.0__tar.gz

{ibm_db_haystack-0.3.0 → ibm_db_haystack-0.4.0}/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [integrations/ibm_db-v0.3.0] - 2026-09-01
+
+### 🐛 Bug Fixes
+
+- `IBMDB2DocumentStore` search_term + pagination (#3689)
+- IBMDB adding optional parameter `filters` to `get_metadata_field_unique_values()` (#3739)
+
+### 🧪 Testing
+
+- `IBMDBDocumentStore` removing duplicated tests already covered by haystack Mixin tests (#3779)
+
+### 🧹 Chores
+
+- Re-standardize READMEs (#3768)
+
+
 ## [integrations/ibm_db-v0.2.0] - 2026-07-27
 
 ### 🚀 Features

{ibm_db_haystack-0.3.0 → ibm_db_haystack-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ibm-db-haystack
-Version: 0.3.0
+Version: 0.4.0
 Summary: Haystack integration for IBM Db2
 Project-URL: Documentation, https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/ibm_db#readme
 Project-URL: Issues, https://github.com/deepset-ai/haystack-core-integrations/issues

{ibm_db_haystack-0.3.0 → ibm_db_haystack-0.4.0}/src/haystack_integrations/document_stores/ibm_db/document_store.py

@@ -5,14 +5,13 @@
 """IBM Db2 Document Store for Haystack."""
 
 import json
-import logging
 import threading
 from collections.abc import Iterator
 from contextlib import contextmanager, suppress
 from typing import Any, Literal
 
 import ibm_db_dbi  # type: ignore[import-untyped]
-from haystack import default_from_dict, default_to_dict
+from haystack import default_from_dict, default_to_dict, logging
 from haystack.dataclasses import Document
 from haystack.document_stores.errors import DocumentStoreError, DuplicateDocumentError
 from haystack.document_stores.types import DuplicatePolicy
@@ -22,6 +21,8 @@ from .filters import FilterTranslator
 
 logger = logging.getLogger(__name__)
 
+VALID_DISTANCE_METRICS = frozenset({"COSINE", "DOT", "EUCLIDEAN", "EUCLIDEAN_SQUARED", "HAMMING", "MANHATTAN"})
+
 
 def _parse_embedding(embedding: Any) -> list[float] | None:
     """
@@ -103,7 +104,14 @@ class IBMDb2DocumentStore:
         connection_options: dict[str, Any] | None = None,
         table_name: str = "haystack_documents",
         embedding_dim: int = 768,
-        distance_metric: Literal["EUCLIDEAN", "COSINE", "MANHATTAN"] = "COSINE",
+        distance_metric: Literal[
+            "COSINE",
+            "DOT",
+            "EUCLIDEAN",
+            "EUCLIDEAN_SQUARED",
+            "HAMMING",
+            "MANHATTAN",
+        ] = "COSINE",
         recreate_table: bool = False,
     ):
         """
@@ -121,7 +129,8 @@ class IBMDb2DocumentStore:
         :param connection_options: Additional connection options as dict (optional)
         :param table_name: Name of the table to store documents (default: "haystack_documents")
         :param embedding_dim: Dimension of embedding vectors (default: 768)
-        :param distance_metric: Distance metric for similarity search (default: "COSINE")
+        :param distance_metric: Distance metric for similarity search (default: "COSINE"). Supported metrics in Db2:
+            "COSINE", "DOT", "EUCLIDEAN", "EUCLIDEAN_SQUARED", "HAMMING", "MANHATTAN".
         :param recreate_table: If True, drop and recreate the table (default: False)
         """
         self.database = database
@@ -136,6 +145,9 @@ class IBMDb2DocumentStore:
         self.connection_options = connection_options
         self.table_name = table_name
         self.embedding_dim = embedding_dim
+        if distance_metric not in VALID_DISTANCE_METRICS:
+            msg = f"Invalid distance_metric '{distance_metric}'. Must be one of {sorted(VALID_DISTANCE_METRICS)}."
+            raise ValueError(msg)
         self.distance_metric = distance_metric
         self.recreate_table = recreate_table
 
@@ -269,7 +281,7 @@ class IBMDb2DocumentStore:
                 try:
                     cur.execute(create_sql)
                     conn.commit()
-                    logger.info(f"Created table {self.table_name}")
+                    logger.info("Created table {table_name}", table_name=self.table_name)
                 except Exception:
                     conn.rollback()
                     # If it still fails, raise the error

{ibm_db_haystack-0.3.0 → ibm_db_haystack-0.4.0}/tests/test_document_store.py

@@ -5,12 +5,14 @@
 """Integration tests for IBM DB2 Document Store using Haystack mixin tests."""
 
 import math
+import sys
 from datetime import datetime, timedelta, timezone
 from unittest.mock import MagicMock, Mock
 
 import pytest
 from haystack.dataclasses import Document
 from haystack.document_stores.errors import DocumentStoreError, DuplicateDocumentError
+from haystack.document_stores.types import DuplicatePolicy
 from haystack.testing.document_store import (
     CountDocumentsByFilterTest,
     CountDocumentsTest,
@@ -239,6 +241,120 @@ class TestDocumentStore(
         assert [doc.id for doc in results] == ["a", "c"]
         assert all(doc.score is not None for doc in results)
 
+    @pytest.mark.parametrize(
+        "metric",
+        ["COSINE", "DOT", "EUCLIDEAN", "EUCLIDEAN_SQUARED", "HAMMING", "MANHATTAN"],
+    )
+    def test_all_distance_metrics_return_ranked_results(self, metric: str, connection_config):
+        """
+        Verify that _embedding_retrieval works correctly for each of the 6 Db2
+        distance metrics: correct ranking, finite scores, top_k respected.
+
+        A fresh store with embedding_dim=4 is created for each metric so the
+        test is independent of the default `document_store` fixture.
+        All Db2 distance metrics return scores ordered ASC (smaller = more similar).
+        """
+        table_name = f"haystack_metric_{metric.lower()}_{sys.version_info.major}_{sys.version_info.minor}"
+        store = IBMDb2DocumentStore(
+            **connection_config,
+            table_name=table_name,
+            embedding_dim=4,
+            distance_metric=metric,
+            recreate_table=True,
+        )
+
+        try:
+            # Embeddings chosen so ranking is unambiguous for every metric:
+            #   most_similar  == query  → distance 0 (or near 0) for all metrics
+            #   second_best   is close  → small distance
+            #   least_similar is far    → large distance
+            query = [1.0, 1.0, 1.0, 1.0]
+            most_similar = [1.0, 1.0, 1.0, 1.0]
+            second_best = [1.0, 1.0, 0.5, 0.5]
+            least_similar = [0.0, 0.0, 0.0, 1.0]
+
+            docs = [
+                Document(content="most_similar", embedding=most_similar),
+                Document(content="second_best", embedding=second_best),
+                Document(content="least_similar", embedding=least_similar),
+            ]
+            store.write_documents(docs, policy=DuplicatePolicy.OVERWRITE)
+
+            results = store._embedding_retrieval(query_embedding=query, top_k=2)
+
+            # Exactly top_k documents returned
+            assert len(results) == 2, f"[{metric}] Expected 2 results, got {len(results)}"
+
+            # most_similar must be in the top-2; least_similar must be excluded
+            contents = [r.content for r in results]
+            assert "most_similar" in contents, f"[{metric}] 'most_similar' missing from top-2: {contents}"
+            assert "least_similar" not in contents, f"[{metric}] 'least_similar' appeared in top-2: {contents}"
+
+            # Scores must be finite floats and ordered ASC (ORDER BY score ASC)
+            for doc in results:
+                assert doc.score is not None, f"[{metric}] score is None"
+                assert math.isfinite(doc.score), f"[{metric}] non-finite score: {doc.score}"
+            assert results[0].content == "most_similar", (
+                f"[{metric}] Expected 'most_similar' at rank-1, got '{results[0].content}' "
+                f"(scores: {[r.score for r in results]})"
+            )
+            assert results[0].score <= results[1].score, (
+                f"[{metric}] Score ordering wrong: {results[0].score} > {results[1].score}"
+            )
+
+        finally:
+            try:
+                conn = store._get_connection()
+                with conn.cursor() as cur:
+                    cur.execute(f"DROP TABLE {store.table_name}")
+                    conn.commit()
+            except Exception:
+                pass
+            store.close()
+
+    @pytest.mark.parametrize(
+        "metric",
+        ["COSINE", "DOT", "EUCLIDEAN", "EUCLIDEAN_SQUARED", "HAMMING", "MANHATTAN"],
+    )
+    def test_all_distance_metrics_respect_filters(self, metric: str, connection_config):
+        """
+        Verify that metadata filters work correctly alongside each distance metric.
+        """
+        table_name = f"haystack_metric_flt_{metric.lower()}_{sys.version_info.major}_{sys.version_info.minor}"
+        store = IBMDb2DocumentStore(
+            **connection_config,
+            table_name=table_name,
+            embedding_dim=4,
+            distance_metric=metric,
+            recreate_table=True,
+        )
+
+        try:
+            query = [1.0, 1.0, 1.0, 1.0]
+            docs = [
+                Document(content="in_1", embedding=[1.0, 1.0, 1.0, 1.0], meta={"cat": "A"}),
+                Document(content="in_2", embedding=[0.9, 0.9, 0.9, 0.9], meta={"cat": "A"}),
+                Document(content="out", embedding=[1.0, 1.0, 1.0, 1.0], meta={"cat": "B"}),
+            ]
+            store.write_documents(docs, policy=DuplicatePolicy.OVERWRITE)
+
+            filters = {"field": "meta.cat", "operator": "==", "value": "A"}
+            results = store._embedding_retrieval(query_embedding=query, top_k=5, filters=filters)
+
+            assert len(results) == 2, f"[{metric}] Expected 2 filtered results, got {len(results)}"
+            for doc in results:
+                assert doc.meta.get("cat") == "A", f"[{metric}] Doc with wrong category returned: {doc.meta}"
+
+        finally:
+            try:
+                conn = store._get_connection()
+                with conn.cursor() as cur:
+                    cur.execute(f"DROP TABLE {store.table_name}")
+                    conn.commit()
+            except Exception:
+                pass
+            store.close()
+
     def test_get_metadata_field_unique_values_pagination(self, document_store: IBMDb2DocumentStore):
         docs = [
             Document(content=f"doc {i}", meta={"category": c}) for i, c in enumerate(["A", "B", "A", "C", "B", "A"])
@@ -541,6 +657,47 @@ class TestIBMDb2DocumentStoreUnit:
         assert isinstance(new_store.username, Secret)
         assert isinstance(new_store.password, Secret)
 
+    @pytest.mark.parametrize(
+        "metric",
+        [
+            "COSINE",
+            "DOT",
+            "EUCLIDEAN",
+            "EUCLIDEAN_SQUARED",
+            "HAMMING",
+            "MANHATTAN",
+        ],
+    )
+    def test_supported_distance_metrics(self, metric, monkeypatch):
+        """Test that all 6 supported Db2 distance metrics can be configured and serialized."""
+        monkeypatch.setenv("DB2_USERNAME", "db2inst1")
+        monkeypatch.setenv("DB2_PASSWORD", "Passw0rd123!")
+        store = IBMDb2DocumentStore(
+            database="testdb",
+            hostname="localhost",
+            username=Secret.from_env_var("DB2_USERNAME"),
+            password=Secret.from_env_var("DB2_PASSWORD"),
+            distance_metric=metric,
+        )
+        assert store.distance_metric == metric
+        data = store.to_dict()
+        assert data["init_parameters"]["distance_metric"] == metric
+        restored = IBMDb2DocumentStore.from_dict(data)
+        assert restored.distance_metric == metric
+
+    def test_invalid_distance_metric_raises(self, monkeypatch):
+        """Test that an invalid distance_metric raises ValueError at construction time."""
+        monkeypatch.setenv("DB2_USERNAME", "db2inst1")
+        monkeypatch.setenv("DB2_PASSWORD", "Passw0rd123!")
+        with pytest.raises(ValueError, match="Invalid distance_metric"):
+            IBMDb2DocumentStore(
+                database="testdb",
+                hostname="localhost",
+                username=Secret.from_env_var("DB2_USERNAME"),
+                password=Secret.from_env_var("DB2_PASSWORD"),
+                distance_metric="L2",  # type: ignore[arg-type]
+            )
+
     def test_to_row_with_none_metadata(self, unit_store):
         """Test _to_row with None metadata."""
         doc = Document(id="1", content="test", meta=None, embedding=[0.1] * 768)
@@ -638,6 +795,30 @@ class TestIBMDb2DocumentStoreUnit:
         executed_sql = cur.execute.call_args.args[0]
         assert "AND embedding IS NOT NULL" in executed_sql
 
+    @pytest.mark.parametrize(
+        "metric",
+        [
+            "COSINE",
+            "DOT",
+            "EUCLIDEAN",
+            "EUCLIDEAN_SQUARED",
+            "HAMMING",
+            "MANHATTAN",
+        ],
+    )
+    def test_embedding_retrieval_uses_configured_metric(self, mocked_store, metric):
+        store, _, cur = mocked_store
+        store.distance_metric = metric
+        cur.fetchall.return_value = []
+
+        store._embedding_retrieval([0.1, 0.2], top_k=5)
+
+        executed_sql = cur.execute.call_args.args[0]
+        expected_fragment = (
+            f"VECTOR_DISTANCE(embedding, VECTOR(CAST(? AS CLOB(100000)), {store.embedding_dim}, FLOAT32), {metric})"
+        )
+        assert expected_fragment in executed_sql
+
     @pytest.mark.parametrize(
         "fetch_error",
         [