oracle-haystack 0.3.0__tar.gz → 0.5.0__tar.gz

oracle_haystack-0.5.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## [integrations/oracle-v0.4.0] - 2026-07-27
+
+### 🚀 Features
+
+- Oracle - make connection lazy, add closing methods and refactor tests (#3665)
+
+### 🐛 Bug Fixes
+
+- `Oracle` match `search_term` against metadata field value only, drop content match (#3645)
+- Fix new issues raised by ruff 0.16.0 (#3670)
+
+### 🧹 Chores
+
+- Improve consistency of integrations folder structure (#3430)
+
+### 🌀 Miscellaneous
+
+- Validating meta fields to prevent SQL injection (#3511)
+
+## [integrations/oracle-v0.2.0] - 2026-04-23
+
+### 🚀 Features
+
+- Complete `OracleDocumentStore` operations (#3179)
+
+
+## [integrations/oracle-v0.1.0] - 2026-04-16
+
+### 🚀 Features
+
+- Add Oracle AI Vector Search DocumentStore (oracle-haystack) (#3096)
+
+<!-- generated by git-cliff -->

oracle_haystack-0.5.0/LICENSE.txt

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2023-present deepset GmbH
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

{oracle_haystack-0.3.0 → oracle_haystack-0.5.0}/PKG-INFO

@@ -1,11 +1,12 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: oracle-haystack
-Version: 0.3.0
+Version: 0.5.0
 Summary: Oracle AI Vector Search DocumentStore integration for Haystack
 Project-URL: Source Code, https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/oracle
 Project-URL: Bug Tracker, https://github.com/deepset-ai/haystack-core-integrations/issues
 Author-email: deepset GmbH <info@deepset.ai>
 License-Expression: Apache-2.0
+License-File: LICENSE.txt
 Keywords: OCI,RAG,document store,haystack,oracle,vector search
 Classifier: Development Status :: 3 - Alpha
 Classifier: License :: OSI Approved :: Apache Software License
@@ -32,6 +33,7 @@ Description-Content-Type: text/markdown
 
 Haystack DocumentStore backed by [Oracle AI Vector Search](https://www.oracle.com/database/ai-vector-search/), available in Oracle Database 23ai and later.
 
+- [Integration page](https://haystack.deepset.ai/integrations/oracle)
 - [Changelog](https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/oracle/CHANGELOG.md)
 
 ---
@@ -39,3 +41,6 @@ Haystack DocumentStore backed by [Oracle AI Vector Search](https://www.oracle.co
 ## Contributing
 
 Refer to the general [Contribution Guidelines](https://github.com/deepset-ai/haystack-core-integrations/blob/main/CONTRIBUTING.md).
+
+To run integration tests locally, you need a Docker container running Oracle Database.
+Use the provided `docker-compose.yml` file to start the container: `docker compose up -d`.

{oracle_haystack-0.3.0 → oracle_haystack-0.5.0}/README.md

@@ -5,6 +5,7 @@
 
 Haystack DocumentStore backed by [Oracle AI Vector Search](https://www.oracle.com/database/ai-vector-search/), available in Oracle Database 23ai and later.
 
+- [Integration page](https://haystack.deepset.ai/integrations/oracle)
 - [Changelog](https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/oracle/CHANGELOG.md)
 
 ---
@@ -12,3 +13,6 @@ Haystack DocumentStore backed by [Oracle AI Vector Search](https://www.oracle.co
 ## Contributing
 
 Refer to the general [Contribution Guidelines](https://github.com/deepset-ai/haystack-core-integrations/blob/main/CONTRIBUTING.md).
+
+To run integration tests locally, you need a Docker container running Oracle Database.
+Use the provided `docker-compose.yml` file to start the container: `docker compose up -d`.

{oracle_haystack-0.3.0 → oracle_haystack-0.5.0}/pyproject.toml

@@ -138,6 +138,7 @@ ignore = [
   "PLR0912",
   "PLR0913",
   "PLR0915",
+  "PLR0917",
   # Allow `Any` - used legitimately for dynamic types and SDK boundaries
   "ANN401",
   # SQL is built from developer-supplied, regex-validated identifiers (table_name,

{oracle_haystack-0.3.0 → oracle_haystack-0.5.0}/src/haystack_integrations/components/retrievers/oracle/embedding_retriever.py

@@ -84,6 +84,12 @@ class OracleEmbeddingRetriever:
         )
         return {"documents": docs}
 
+    def close(self) -> None:
+        """
+        Release the synchronous resources of the underlying Document Store.
+        """
+        self.document_store.close()
+
     def to_dict(self) -> dict[str, Any]:
         """
         Serializes the component to a dictionary.

{oracle_haystack-0.3.0 → oracle_haystack-0.5.0}/src/haystack_integrations/components/retrievers/oracle/keyword_retriever.py

@@ -82,6 +82,12 @@ class OracleKeywordRetriever:
         )
         return {"documents": docs}
 
+    def close(self) -> None:
+        """
+        Release the synchronous resources of the underlying Document Store.
+        """
+        self.document_store.close()
+
     def to_dict(self) -> dict[str, Any]:
         """
         Serializes the component to a dictionary.

{oracle_haystack-0.3.0 → oracle_haystack-0.5.0}/src/haystack_integrations/document_stores/oracle/document_store.py

@@ -4,10 +4,12 @@
 
 import array as _array
 import asyncio
+import decimal
 import json
 import logging
 import re
 import threading
+from contextlib import suppress
 from dataclasses import dataclass
 from typing import Any, Literal
 
@@ -177,11 +179,7 @@ class OracleDocumentStore:
 
         self._pool: oracledb.ConnectionPool | None = None
         self._pool_lock = threading.Lock()
-
-        if create_table_if_not_exists:
-            self._ensure_table()
-        if create_index:
-            self.create_hnsw_index()
+        self._setup_done = False
 
     def _get_pool(self) -> oracledb.ConnectionPool:
         if self._pool is not None:
@@ -212,14 +210,33 @@ class OracleDocumentStore:
         return self._pool
 
     def _get_connection(self) -> oracledb.Connection:
+        self._ensure_setup()
         return self._get_pool().acquire()
 
-    def __del__(self) -> None:
+    def _ensure_setup(self) -> None:
+        """
+        Create the backing table and optional HNSW index once, on first use if needed.
+        """
+        if self._setup_done:
+            return
+        self._setup_done = True
+        try:
+            if self.create_table_if_not_exists:
+                self._ensure_table()
+            if self.create_index:
+                self.create_hnsw_index()
+        except Exception:
+            self._setup_done = False
+            raise
+
+    def close(self) -> None:
+        """
+        Release the associated synchronous resources.
+        """
         if self._pool is not None:
-            try:
+            with suppress(Exception):
                 self._pool.close()
-            except Exception:
-                logger.warning("Failed to close Oracle connection pool during cleanup.", exc_info=True)
+            self._pool = None
 
     def _ensure_table(self) -> None:
         sql = f"""
@@ -766,35 +783,58 @@ class OracleDocumentStore:
             return {"min": _try_parse_number(row[0]), "max": _try_parse_number(row[1])}
 
     def get_metadata_field_unique_values(
-        self, metadata_field: str, search_term: str | None = None, from_: int = 0, size: int | None = None
-    ) -> tuple[list[str], int]:
+        self,
+        metadata_field: str,
+        search_term: str | None = None,
+        from_: int = 0,
+        size: int | None = 10,
+        filters: dict[str, Any] | None = None,
+    ) -> tuple[list[Any], int]:
         """
         Return a paginated list of distinct values for a metadata field, plus the total distinct count.
 
+        **Note**: values of different JSON type categories are kept distinct - a string, a number and a
+        boolean never collapse into each other, even when they share a textual form (e.g. the string
+        `"1"` and the number `1`). One exception: the ``metadata`` column is Oracle's native ``JSON``
+        type, which canonicalizes numeric storage, so a whole-number float (`1.0`) and a numerically
+        equal int (`1`) collapse into the same value. Floats with a fractional part (e.g. `1.5`) are
+        unaffected.
+
         :param metadata_field: Metadata field name. May be prefixed with ``"meta."``
             (e.g. ``"meta.lang"`` or ``"lang"``).
-        :param search_term: Optional substring filter applied to both the document text and the field value.
+        :param search_term: Optional case-insensitive substring filter applied to the metadata field's own value.
         :param from_: Zero-based offset for pagination. Defaults to ``0``.
-        :param size: Maximum number of values to return. When ``None`` all values from ``from_`` onward
-            are returned.
+        :param size: Maximum number of values to return. Defaults to ``10``. When ``None`` all values
+            from ``from_`` onward are returned.
+        :param filters: Optional filters to restrict the documents considered.
         :returns: A tuple ``(values, total)`` where ``values`` is the paginated list of distinct field
-            values as strings and ``total`` is the overall distinct count (before pagination).
+            values in their original type and ``total`` is the overall distinct count (before pagination).
         :raises ValueError: If ``metadata_field`` contains characters outside ``[A-Za-z0-9_.]``.
         """
         field_path = metadata_field[5:] if metadata_field.startswith("meta.") else metadata_field
         _validate_field_path(field_path)
-        base_sql = f"FROM {self.table_name} WHERE JSON_VALUE(metadata, '$.{field_path}') IS NOT NULL"
+        # JSON_VALUE dequotes strings and stringifies numbers/booleans, so a JSON string "1" and the
+        # number 1 both become the identical SQL text '1' - merging distinct values and, once re-parsed,
+        # corrupting a numeric-looking string into a number. JSON_QUERY on our native JSON column keeps
+        # the driver's own decoded Python value instead (str stays str, bool stays bool, numbers come
+        # back as Decimal - converted to int/float below), so a string is never confused with a number.
+        json_extract = f"JSON_QUERY(metadata, '$.{field_path}')"
+        base_sql = f"FROM {self.table_name} WHERE {json_extract} IS NOT NULL"
         params: dict[str, Any] = {}
+        if filters:
+            counter = [0]
+            filters_fragment = FilterTranslator().translate(filters, params, counter)
+            base_sql += f" AND {filters_fragment}"
         if search_term:
-            base_sql += f" AND (text LIKE :search OR JSON_VALUE(metadata, '$.{field_path}') LIKE :search)"
+            base_sql += f" AND UPPER({json_extract}) LIKE UPPER(:search)"
             params["search"] = f"%{search_term}%"
 
-        sql_count = f"SELECT COUNT(DISTINCT JSON_VALUE(metadata, '$.{field_path}')) {base_sql}"
+        sql_count = f"SELECT COUNT(DISTINCT {json_extract}) {base_sql}"
         with self._get_connection() as conn, conn.cursor() as cur:
             cur.execute(sql_count, params)
             total = cur.fetchone()[0] or 0
 
-            sql_vals = f"SELECT DISTINCT JSON_VALUE(metadata, '$.{field_path}') {base_sql} ORDER BY 1"
+            sql_vals = f"SELECT DISTINCT {json_extract} {base_sql} ORDER BY 1"
             if size is not None:
                 sql_vals += " OFFSET :row_offset ROWS FETCH NEXT :row_limit ROWS ONLY"
                 params["row_offset"] = from_
@@ -804,7 +844,11 @@ class OracleDocumentStore:
                 params["row_offset"] = from_
             cur.execute(sql_vals, params)
             rows = cur.fetchall()
-            return [str(r[0]) for r in rows], total
+            # oracledb decodes a JSON_QUERY result from our native JSON column into a Python value
+            # directly (str/bool stay as-is); JSON numbers decode as Decimal, so pick int vs float to
+            # match what write_documents() was originally given.
+            values: list[Any] = [_try_parse_number(r[0]) if isinstance(r[0], decimal.Decimal) else r[0] for r in rows]
+            return values, total
 
     async def get_metadata_fields_info_async(self) -> dict[str, dict[str, str]]:
         """
@@ -834,22 +878,30 @@ class OracleDocumentStore:
         return await asyncio.to_thread(self.get_metadata_field_min_max, metadata_field)
 
     async def get_metadata_field_unique_values_async(
-        self, metadata_field: str, search_term: str | None = None, from_: int = 0, size: int | None = None
-    ) -> tuple[list[str], int]:
+        self,
+        metadata_field: str,
+        search_term: str | None = None,
+        from_: int = 0,
+        size: int | None = 10,
+        filters: dict[str, Any] | None = None,
+    ) -> tuple[list[Any], int]:
         """
         Asynchronously returns a paginated list of distinct values for a metadata field, plus the total count.
 
         :param metadata_field: Metadata field name. May be prefixed with ``"meta."``
             (e.g. ``"meta.lang"`` or ``"lang"``).
-        :param search_term: Optional substring filter applied to both the document text and the field value.
+        :param search_term: Optional case-insensitive substring filter applied to the metadata field's own value.
         :param from_: Zero-based offset for pagination. Defaults to ``0``.
-        :param size: Maximum number of values to return. When ``None`` all values from ``from_`` onward
-            are returned.
+        :param size: Maximum number of values to return. Defaults to ``10``. When ``None`` all values
+            from ``from_`` onward are returned.
+        :param filters: Optional filters to restrict the documents considered.
         :returns: A tuple ``(values, total)`` where ``values`` is the paginated list of distinct field
-            values as strings and ``total`` is the overall distinct count (before pagination).
+            values in their original type and ``total`` is the overall distinct count (before pagination).
         :raises ValueError: If ``metadata_field`` contains characters outside ``[A-Za-z0-9_.]``.
         """
-        return await asyncio.to_thread(self.get_metadata_field_unique_values, metadata_field, search_term, from_, size)
+        return await asyncio.to_thread(
+            self.get_metadata_field_unique_values, metadata_field, search_term, from_, size, filters
+        )
 
     def _embedding_retrieval(
         self,

{oracle_haystack-0.3.0 → oracle_haystack-0.5.0}/tests/conftest.py

@@ -16,25 +16,30 @@ _PASSWORD = "haystack"
 _DSN = "localhost:1521/freepdb1"
 
 
-def _make_store(table: str, embedding_dim: int) -> OracleDocumentStore:
-    return OracleDocumentStore(
-        connection_config=OracleConnectionConfig(
-            user=Secret.from_token(_USER),
-            password=Secret.from_token(_PASSWORD),
-            dsn=Secret.from_token(_DSN),
-        ),
-        table_name=table,
-        embedding_dim=embedding_dim,
-        distance_metric="COSINE",
-        create_table_if_not_exists=True,
-    )
+@pytest.fixture
+def make_store():
+    """Factory for a real OracleDocumentStore. Uses token secrets, so instances are not serialization-safe."""
+
+    def _make(table: str, embedding_dim: int = 4, *, create_table_if_not_exists: bool = True) -> OracleDocumentStore:
+        return OracleDocumentStore(
+            connection_config=OracleConnectionConfig(
+                user=Secret.from_token(_USER),
+                password=Secret.from_token(_PASSWORD),
+                dsn=Secret.from_token(_DSN),
+            ),
+            table_name=table,
+            embedding_dim=embedding_dim,
+            create_table_if_not_exists=create_table_if_not_exists,
+        )
+
+    return _make
 
 
 @pytest.fixture
-def document_store():
+def document_store(make_store):
     """768-dim store required by the mixin's filterable_docs fixture."""
     table = f"hs_sync_{uuid.uuid4().hex[:8]}"
-    s = _make_store(table, embedding_dim=768)
+    s = make_store(table, 768)
     yield s
     with s._get_connection() as conn, conn.cursor() as cur:
         cur.execute(f"DROP TABLE {table} PURGE")
@@ -42,10 +47,10 @@ def document_store():
 
 
 @pytest.fixture
-def embedding_store():
+def embedding_store(make_store):
     """4-dim store for embedding-retrieval, HNSW, and async tests."""
     table = f"hs_emb_{uuid.uuid4().hex[:8]}"
-    s = _make_store(table, embedding_dim=4)
+    s = make_store(table)
     yield s
     with s._get_connection() as conn, conn.cursor() as cur:
         cur.execute(f"DROP TABLE {table} PURGE")

{oracle_haystack-0.3.0 → oracle_haystack-0.5.0}/tests/test_document_store.py

@@ -2,12 +2,14 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+import decimal
 import uuid
+from unittest.mock import MagicMock
 
 import oracledb as _oracledb
 import pytest
 from haystack.dataclasses import Document
-from haystack.document_stores.errors import DuplicateDocumentError
+from haystack.document_stores.errors import DocumentStoreError, DuplicateDocumentError
 from haystack.document_stores.types import DuplicatePolicy
 from haystack.testing.document_store import (
     CountDocumentsByFilterTest,
@@ -25,15 +27,11 @@ from haystack.testing.document_store_async import (
     CountDocumentsByFilterAsyncTest,
     CountUniqueMetadataByFilterAsyncTest,
     FilterableDocsFixtureMixin,
+    GetMetadataFieldUniqueValuesAsyncTest,
     UpdateByFilterAsyncTest,
 )
-from haystack.utils import Secret
 
-from haystack_integrations.document_stores.oracle import OracleConnectionConfig, OracleDocumentStore
-
-_USER = "haystack"
-_PASSWORD = "haystack"
-_DSN = "localhost:1521/freepdb1"
+from haystack_integrations.document_stores.oracle import OracleDocumentStore
 
 
 def _doc(doc_id: str, content: str = "hello", meta: dict | None = None, embedding: list[float] | None = None):
@@ -47,72 +45,54 @@ def _uid(suffix: str = "") -> str:
     return f"{base}{suffix.upper():>4}"[:32]
 
 
-@pytest.mark.integration
-class TestOracleDocumentStore(
-    DocumentStoreBaseTests,
-    CountDocumentsByFilterTest,
-    CountUniqueMetadataByFilterTest,
-    DeleteAllTest,
-    DeleteByFilterTest,
-    DeleteDocumentsTest,
-    GetMetadataFieldMinMaxTest,
-    GetMetadataFieldsInfoTest,
-    GetMetadataFieldUniqueValuesTest,
-    UpdateByFilterTest,
-):
+def _lob(value: str) -> MagicMock:
+    """Mock for an oracledb Large Object (LOB)"""
+    lob = MagicMock()
+    lob.read.return_value = value
+    return lob
+
+
+class TestOracleDocumentStoreUnit:
     @staticmethod
     def _mock_doc(content="hello", embedding=None, doc_id="AABB" * 8):
         """Lightweight document builder for mock-based tests."""
         return Document(id=doc_id, content=content, meta={"k": "v"}, embedding=embedding)
 
-    @pytest.fixture
-    def document_store(self):
-        """768-dim store — overrides the mixin's NotImplementedError stub."""
-        table = f"hs_sync_{uuid.uuid4().hex[:8]}"
-        s = OracleDocumentStore(
-            connection_config=OracleConnectionConfig(
-                user=Secret.from_token(_USER),
-                password=Secret.from_token(_PASSWORD),
-                dsn=Secret.from_token(_DSN),
-            ),
-            table_name=table,
-            embedding_dim=768,
-            distance_metric="COSINE",
-            create_table_if_not_exists=True,
-        )
-        yield s
-        with s._get_connection() as conn, conn.cursor() as cur:
-            cur.execute(f"DROP TABLE {table} PURGE")
-            conn.commit()
-
-    # Mixin override
-    def assert_documents_are_equal(self, received: list[Document], expected: list[Document]) -> None:
-        # filter_documents does not SELECT the embedding column — ignore it when comparing
-        assert len(received) == len(expected)
-        received_sorted = sorted(received, key=lambda d: d.id)
-        expected_sorted = sorted(expected, key=lambda d: d.id)
-        for r, e in zip(received_sorted, expected_sorted, strict=True):
-            assert r.id == e.id
-            assert r.content == e.content
-            assert r.meta == e.meta
-
-    # Mixin override
-    def test_write_documents(self, document_store: OracleDocumentStore) -> None:
-        # Default policy is NONE — a second write of the same doc raises DuplicateDocumentError
-        doc = Document(content="test doc")
-        assert document_store.write_documents([doc]) == 1
-        with pytest.raises(DuplicateDocumentError):
-            document_store.write_documents([doc])
-        self.assert_documents_are_equal(document_store.filter_documents(), [doc])
-
-    # test_comparison_equal_with_none     → IS NULL
-    # test_comparison_not_equal_with_none → IS NOT NULL
-    # test_comparison_not_equal           → col != x OR IS NULL
-    # test_comparison_not_in              → IS NULL OR NOT IN
-    @pytest.mark.skip(
-        reason="Oracle NULL propagation in NOT(...) cannot match Python 'not (None == x) is True' semantics"
+    @pytest.mark.parametrize(
+        ("table_name", "embedding_dim", "match"),
+        [
+            pytest.param("1invalid", 4, "Invalid table_name", id="table_name_starts_with_digit"),
+            pytest.param("bad-name", 4, "Invalid table_name", id="table_name_illegal_char"),
+            pytest.param("valid", 0, "embedding_dim must be a positive integer", id="embedding_dim_zero"),
+            pytest.param("valid", -1, "embedding_dim must be a positive integer", id="embedding_dim_negative"),
+        ],
     )
-    def test_not_operator(self, document_store, filterable_docs): ...
+    def test_init_rejects_invalid_arguments(self, make_store, table_name, embedding_dim, match):
+        with pytest.raises(ValueError, match=match):
+            make_store(table_name, embedding_dim)
+
+    def test_init_opens_no_connection(self, make_store, mock_pool):  # noqa: ARG002
+        store = make_store("lazy_docs")
+        assert store._pool is None
+        assert store._setup_done is False
+
+    def test_setup_is_deferred_and_runs_once(self, make_store, mock_pool):
+        store = make_store("lazy_docs")
+        store.count_documents()
+        store.count_documents()
+        assert store._pool is not None
+        assert store._setup_done is True
+        _, _, cursor = mock_pool
+        create_calls = [c for c in cursor.execute.call_args_list if "CREATE TABLE IF NOT EXISTS" in c[0][0]]
+        assert len(create_calls) == 1
+
+    def test_setup_failure_resets_flag(self, make_store, mock_pool):
+        _, _, cursor = mock_pool
+        cursor.execute.side_effect = RuntimeError("boom")
+        store = make_store("lazy_docs")
+        with pytest.raises(RuntimeError):
+            store.count_documents()
+        assert store._setup_done is False
 
     def test_write_documents_none_policy_calls_insert(self, patched_store, mock_pool):
         _, _, cursor = mock_pool
@@ -207,6 +187,92 @@ class TestOracleDocumentStore(
         cursor.fetchone.return_value = (42,)
         assert patched_store.count_documents() == 42
 
+    def test_get_metadata_field_unique_values_search_term_filters_value_only(self, patched_store, mock_pool):
+        """search_term must filter on the metadata field's own JSON value, not on document text."""
+        _, _, cursor = mock_pool
+        cursor.fetchone.return_value = (1,)
+        cursor.fetchall.return_value = [("bar",)]
+
+        patched_store.get_metadata_field_unique_values("category", search_term="bar")
+
+        count_sql, count_params = cursor.execute.call_args_list[0][0]
+        vals_sql, vals_params = cursor.execute.call_args_list[1][0]
+
+        for sql in (count_sql, vals_sql):
+            assert "UPPER(JSON_QUERY(metadata, '$.category')) LIKE UPPER(:search)" in sql
+
+        assert count_params["search"] == "%bar%"
+        assert vals_params["search"] == "%bar%"
+
+    def test_get_metadata_field_unique_values_parses_json_scalar_types(self, patched_store, mock_pool):
+        """oracledb decodes a JSON_QUERY result from our native JSON column directly into a Python
+        value - str and bool need no conversion, but a JSON number decodes as Decimal and must be
+        converted to int or float to match what write_documents() was originally given."""
+        _, _, cursor = mock_pool
+        cursor.fetchone.return_value = (3,)
+        cursor.fetchall.return_value = [(decimal.Decimal(1),), (True,), ("bar",)]
+
+        values, total = patched_store.get_metadata_field_unique_values("priority")
+
+        assert values == [1, True, "bar"]
+        assert all(type(v) in (int, bool, str) for v in values)
+        assert total == 3
+
+    def test_delete_table_executes_drop_and_index_sql(self, patched_store, mock_pool):
+        _, _, cursor = mock_pool
+        patched_store.delete_table()
+        executed = [c[0][0] for c in cursor.execute.call_args_list]
+        assert any("DROP TABLE" in sql and "PURGE" in sql for sql in executed)
+        assert any("DBMS_SEARCH.DROP_INDEX" in sql for sql in executed)
+
+    def test_keyword_retrieval_builds_contains_query(self, patched_store, mock_pool):
+        _, _, cursor = mock_pool
+        cursor.fetchall.return_value = [("AABB" * 8, "hello", '{"k": "v"}', 1.5)]
+        docs = patched_store._keyword_retrieval("hello world", top_k=5)
+        sql, params = cursor.execute.call_args[0]
+        assert "CONTAINS(DATA, :query, 1)" in sql
+        assert "SCORE(1)" in sql
+        assert params["query"] == "hello world"
+        assert params["top_k"] == 5
+        assert docs[0].score == 1.5
+
+    @pytest.mark.parametrize(
+        "operation",
+        [
+            pytest.param(lambda s: s._embedding_retrieval([0.1, 0.2, 0.3, 0.4]), id="embedding_retrieval"),
+            pytest.param(lambda s: s._keyword_retrieval("query"), id="keyword_retrieval"),
+            pytest.param(lambda s: s.delete_table(), id="delete_table"),
+        ],
+    )
+    def test_query_methods_wrap_database_errors(self, patched_store, mock_pool, operation):
+        _, _, cursor = mock_pool
+        cursor.execute.side_effect = _oracledb.DatabaseError("ORA-00942")
+        with pytest.raises(DocumentStoreError):
+            operation(patched_store)
+
+    @pytest.mark.parametrize(
+        ("text_raw", "metadata_raw", "expected_content", "expected_meta"),
+        [
+            pytest.param("plain", '{"k": "v"}', "plain", {"k": "v"}, id="str_text_and_json_metadata"),
+            pytest.param(_lob("from_lob"), _lob('{"k": "v"}'), "from_lob", {"k": "v"}, id="lob_text_and_metadata"),
+            pytest.param("plain", {"k": "v"}, "plain", {"k": "v"}, id="dict_metadata"),
+            pytest.param("plain", None, "plain", {}, id="unsupported_metadata_type"),
+        ],
+    )
+    def test_row_to_document_reads_lob_and_maps_metadata(self, text_raw, metadata_raw, expected_content, expected_meta):
+        doc = OracleDocumentStore._row_to_document(("id1", text_raw, metadata_raw))
+        assert doc.content == expected_content
+        assert doc.meta == expected_meta
+
+    def test_create_hnsw_index_sql(self, patched_store, mock_pool):
+        _, _, cursor = mock_pool
+        patched_store.create_hnsw_index()
+        sql = cursor.execute.call_args[0][0]
+        assert "CREATE VECTOR INDEX" in sql
+        assert "HNSW" in sql
+        assert str(patched_store.hnsw_neighbors) in sql
+        assert str(patched_store.hnsw_ef_construction) in sql
+
     def test_to_dict_does_not_expose_plain_password(self, patched_store):
         d = patched_store.to_dict()
         pw = d["init_parameters"]["connection_config"]["password"]
@@ -220,17 +286,109 @@ class TestOracleDocumentStore(
         assert restored.embedding_dim == patched_store.embedding_dim
         assert restored.distance_metric == patched_store.distance_metric
 
-    def test_create_hnsw_index_sql(self, patched_store, mock_pool):
-        _, _, cursor = mock_pool
-        patched_store.create_hnsw_index()
-        sql = cursor.execute.call_args[0][0]
-        assert "CREATE VECTOR INDEX" in sql
-        assert "HNSW" in sql
-        assert str(patched_store.hnsw_neighbors) in sql
-        assert str(patched_store.hnsw_ef_construction) in sql
+    def test_close(self, patched_store):
+        pool = MagicMock()
+        patched_store._pool = pool
+        patched_store.close()
+        pool.close.assert_called_once()
+        assert patched_store._pool is None
+        patched_store.close()
+        pool.close.assert_called_once()
+
+    def test_close_is_exception_safe(self, patched_store):
+        pool = MagicMock()
+        pool.close.side_effect = RuntimeError("boom")
+        patched_store._pool = pool
+        patched_store.close()
+        assert patched_store._pool is None
 
-    def test_write_documents_empty_list_returns_zero(self, document_store):
-        assert document_store.write_documents([]) == 0
+
+@pytest.mark.integration
+class TestOracleDocumentStore(
+    DocumentStoreBaseTests,
+    CountDocumentsByFilterTest,
+    CountUniqueMetadataByFilterTest,
+    DeleteAllTest,
+    DeleteByFilterTest,
+    DeleteDocumentsTest,
+    GetMetadataFieldMinMaxTest,
+    GetMetadataFieldsInfoTest,
+    GetMetadataFieldUniqueValuesTest,
+    UpdateByFilterTest,
+):
+    @pytest.fixture
+    def document_store(self, make_store):
+        """768-dim store — overrides the mixin's NotImplementedError stub."""
+        table = f"hs_sync_{uuid.uuid4().hex[:8]}"
+        s = make_store(table, 768)
+        yield s
+        with s._get_connection() as conn, conn.cursor() as cur:
+            cur.execute(f"DROP TABLE {table} PURGE")
+            conn.commit()
+
+    # Mixin override
+    def assert_documents_are_equal(self, received: list[Document], expected: list[Document]) -> None:
+        # filter_documents does not SELECT the embedding column — ignore it when comparing
+        assert len(received) == len(expected)
+        received_sorted = sorted(received, key=lambda d: d.id)
+        expected_sorted = sorted(expected, key=lambda d: d.id)
+        for r, e in zip(received_sorted, expected_sorted, strict=True):
+            assert r.id == e.id
+            assert r.content == e.content
+            assert r.meta == e.meta
+
+    # Mixin override
+    def test_write_documents(self, document_store: OracleDocumentStore) -> None:
+        # Default policy is NONE — a second write of the same doc raises DuplicateDocumentError
+        doc = Document(content="test doc")
+        assert document_store.write_documents([doc]) == 1
+        with pytest.raises(DuplicateDocumentError):
+            document_store.write_documents([doc])
+        self.assert_documents_are_equal(document_store.filter_documents(), [doc])
+
+    def test_get_metadata_field_unique_values_distinct_types(self, document_store: OracleDocumentStore):
+        """
+        Override: the base mixin test stores int, float, str and bool under the *same* metadata field
+        name and expects all four back as distinct values. The ``metadata`` column is Oracle's native
+        ``JSON`` type, which canonicalizes numeric storage, so a whole-number float (e.g. 1.0) and a
+        numerically equal int (1) collapse into the same value regardless of which other values share
+        that field.
+
+        This adapts the same intent - int, float, str and bool must come back as distinct, unmangled
+        types via get_metadata_field_unique_values() - using one field per type instead of one shared
+        field, which is what Oracle can actually support.
+
+        The float value is a non-whole number (1.5, not 1.0): a whole-number float would still collapse
+        with an int under Oracle's numeric canonicalization even in its own field, so a fractional value
+        is used to sidestep that ambiguity entirely.
+        """
+        docs = [
+            Document(content="Doc 1", meta={"priority_int": 1}),
+            Document(content="Doc 2", meta={"priority_str": "1"}),
+            Document(content="Doc 3", meta={"priority_float": 1.5}),
+            Document(content="Doc 4", meta={"priority_bool": True}),
+        ]
+        document_store.write_documents(docs)
+
+        int_values, int_count = document_store.get_metadata_field_unique_values(metadata_field="priority_int")
+        str_values, str_count = document_store.get_metadata_field_unique_values(metadata_field="priority_str")
+        float_values, float_count = document_store.get_metadata_field_unique_values(metadata_field="priority_float")
+        bool_values, bool_count = document_store.get_metadata_field_unique_values(metadata_field="priority_bool")
+
+        assert (int_count, str_count, float_count, bool_count) == (1, 1, 1, 1)
+        assert int_values == [1] and type(int_values[0]) is int
+        assert str_values == ["1"] and type(str_values[0]) is str
+        assert float_values == [1.5] and type(float_values[0]) is float
+        assert bool_values == [True] and type(bool_values[0]) is bool
+
+    # test_comparison_equal_with_none     → IS NULL
+    # test_comparison_not_equal_with_none → IS NOT NULL
+    # test_comparison_not_equal           → col != x OR IS NULL
+    # test_comparison_not_in              → IS NULL OR NOT IN
+    @pytest.mark.skip(
+        reason="Oracle NULL propagation in NOT(...) cannot match Python 'not (None == x) is True' semantics"
+    )
+    def test_not_operator(self, document_store, filterable_docs): ...
 
     def test_filter_documents_not_operator(self, document_store):
         # Scoped to two fresh docs — no NULL-valued rows, so NOT works correctly.
@@ -311,16 +469,69 @@ class TestOracleDocumentStore(
         """Calling _ensure_table() a second time must not raise."""
         document_store._ensure_table()
 
+    def test_close_and_reopen(self, document_store):
+        document_store.count_documents()
+        assert document_store._pool is not None
+        document_store.close()
+        assert document_store._pool is None
+        assert document_store.count_documents() == 0
+        assert document_store._pool is not None
+
 
 @pytest.mark.integration
 class TestOracleDocumentStoreAsync(
     FilterableDocsFixtureMixin,
     CountDocumentsByFilterAsyncTest,
     CountUniqueMetadataByFilterAsyncTest,
+    GetMetadataFieldUniqueValuesAsyncTest,
     UpdateByFilterAsyncTest,
 ):
     """Async API surface tests."""
 
+    @pytest.mark.asyncio
+    async def test_get_metadata_field_unique_values_distinct_types_async(self, document_store: OracleDocumentStore):
+        """
+        Override: the base mixin test stores int, float, str and bool under the *same* metadata field
+        name and expects all four back as distinct values. The ``metadata`` column is Oracle's native
+        ``JSON`` type, which canonicalizes numeric storage, so a whole-number float (e.g. 1.0) and a
+        numerically equal int (1) collapse into the same value regardless of which other values share
+        that field.
+
+        This adapts the same intent - int, float, str and bool must come back as distinct, unmangled
+        types via get_metadata_field_unique_values_async() - using one field per type instead of one
+        shared field, which is what Oracle can actually support.
+
+        The float value is a non-whole number (1.5, not 1.0): a whole-number float would still collapse
+        with an int under Oracle's numeric canonicalization even in its own field, so a fractional value
+        is used to sidestep that ambiguity entirely.
+        """
+        docs = [
+            Document(content="Doc 1", meta={"priority_int": 1}),
+            Document(content="Doc 2", meta={"priority_str": "1"}),
+            Document(content="Doc 3", meta={"priority_float": 1.5}),
+            Document(content="Doc 4", meta={"priority_bool": True}),
+        ]
+        await document_store.write_documents_async(docs)
+
+        int_values, int_count = await document_store.get_metadata_field_unique_values_async(
+            metadata_field="priority_int"
+        )
+        str_values, str_count = await document_store.get_metadata_field_unique_values_async(
+            metadata_field="priority_str"
+        )
+        float_values, float_count = await document_store.get_metadata_field_unique_values_async(
+            metadata_field="priority_float"
+        )
+        bool_values, bool_count = await document_store.get_metadata_field_unique_values_async(
+            metadata_field="priority_bool"
+        )
+
+        assert (int_count, str_count, float_count, bool_count) == (1, 1, 1, 1)
+        assert int_values == [1] and type(int_values[0]) is int
+        assert str_values == ["1"] and type(str_values[0]) is str
+        assert float_values == [1.5] and type(float_values[0]) is float
+        assert bool_values == [True] and type(bool_values[0]) is bool
+
     @pytest.mark.asyncio
     async def test_async_write_and_count(self, embedding_store):
         doc = _doc(_uid("M001"))

{oracle_haystack-0.3.0 → oracle_haystack-0.5.0}/tests/test_embedding_retriever.py

@@ -67,6 +67,13 @@ def test_to_dict_from_dict_roundtrip(mock_store):
     assert restored.document_store.embedding_dim == 4
 
 
+def test_close(mock_store):
+    retriever = OracleEmbeddingRetriever(document_store=mock_store)
+    retriever.close()
+    mock_store.close.assert_called_once()
+    assert retriever.document_store is mock_store
+
+
 def test_invalid_document_store_raises_type_error():
     with pytest.raises(TypeError, match="must be an instance of OracleDocumentStore"):
         OracleEmbeddingRetriever(document_store="not_a_store")

{oracle_haystack-0.3.0 → oracle_haystack-0.5.0}/tests/test_keyword_retriever.py

@@ -67,6 +67,13 @@ def test_to_dict_from_dict_roundtrip(mock_store):
     assert restored.document_store.embedding_dim == 4
 
 
+def test_close(mock_store):
+    retriever = OracleKeywordRetriever(document_store=mock_store)
+    retriever.close()
+    mock_store.close.assert_called_once()
+    assert retriever.document_store is mock_store
+
+
 def test_invalid_document_store_raises_type_error():
     with pytest.raises(TypeError, match="must be an instance of OracleDocumentStore"):
         OracleKeywordRetriever(document_store="not_a_store")

oracle_haystack-0.3.0/CHANGELOG.md

@@ -1,16 +0,0 @@
-# Changelog
-
-## [integrations/oracle-v0.2.0] - 2026-04-23
-
-### 🚀 Features
-
-- Complete `OracleDocumentStore` operations (#3179)
-
-
-## [integrations/oracle-v0.1.0] - 2026-04-16
-
-### 🚀 Features
-
-- Add Oracle AI Vector Search DocumentStore (oracle-haystack) (#3096)
-
-<!-- generated by git-cliff -->