oracle-haystack 0.1.0__py3-none-any.whl

haystack_integrations/components/retrievers/oracle/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2023-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from haystack_integrations.components.retrievers.oracle.embedding_retriever import OracleEmbeddingRetriever
+
+__all__ = ["OracleEmbeddingRetriever"]

haystack_integrations/components/retrievers/oracle/embedding_retriever.py

@@ -0,0 +1,119 @@
+# SPDX-FileCopyrightText: 2023-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Any
+
+from haystack import component, default_from_dict, default_to_dict
+from haystack.dataclasses import Document
+from haystack.document_stores.types import FilterPolicy
+from haystack.document_stores.types.filter_policy import apply_filter_policy
+
+from haystack_integrations.document_stores.oracle import OracleDocumentStore
+
+
+@component
+class OracleEmbeddingRetriever:
+    """
+    Retrieves documents from an OracleDocumentStore using vector similarity.
+
+    Use inside a Haystack pipeline after a text embedder::
+
+        pipeline.add_component("embedder", SentenceTransformersTextEmbedder())
+        pipeline.add_component("retriever", OracleEmbeddingRetriever(
+            document_store=store, top_k=5
+        ))
+        pipeline.connect("embedder.embedding", "retriever.query_embedding")
+    """
+
+    def __init__(
+        self,
+        *,
+        document_store: OracleDocumentStore,
+        filters: dict[str, Any] | None = None,
+        top_k: int = 10,
+        filter_policy: FilterPolicy = FilterPolicy.REPLACE,
+    ) -> None:
+        if not isinstance(document_store, OracleDocumentStore):
+            msg = "document_store must be an instance of OracleDocumentStore"
+            raise TypeError(msg)
+        self.document_store = document_store
+        self.filters = filters or {}
+        self.top_k = top_k
+        self.filter_policy = FilterPolicy.from_str(filter_policy) if isinstance(filter_policy, str) else filter_policy
+
+    @component.output_types(documents=list[Document])
+    def run(
+        self,
+        query_embedding: list[float],
+        filters: dict[str, Any] | None = None,
+        top_k: int | None = None,
+    ) -> dict[str, list[Document]]:
+        """
+        Retrieve documents by vector similarity.
+
+        Args:
+            query_embedding: Dense float vector from an embedder component.
+            filters: Runtime filters, merged with constructor filters according to filter_policy.
+            top_k: Override the constructor top_k for this call.
+
+        Returns:
+            ``{"documents": [Document, ...]}``
+        """
+        filters = apply_filter_policy(self.filter_policy, self.filters, filters)
+        docs = self.document_store._embedding_retrieval(
+            query_embedding,
+            filters=filters,
+            top_k=top_k if top_k is not None else self.top_k,
+        )
+        return {"documents": docs}
+
+    @component.output_types(documents=list[Document])
+    async def run_async(
+        self,
+        query_embedding: list[float],
+        filters: dict[str, Any] | None = None,
+        top_k: int | None = None,
+    ) -> dict[str, list[Document]]:
+        """Async variant of :meth:`run`."""
+        filters = apply_filter_policy(self.filter_policy, self.filters, filters)
+        docs = await self.document_store._embedding_retrieval_async(
+            query_embedding,
+            filters=filters,
+            top_k=top_k if top_k is not None else self.top_k,
+        )
+        return {"documents": docs}
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Serializes the component to a dictionary.
+
+        :returns:
+            Dictionary with serialized data.
+        """
+        return default_to_dict(
+            self,
+            document_store=self.document_store.to_dict(),
+            filters=self.filters,
+            top_k=self.top_k,
+            filter_policy=self.filter_policy.value,
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "OracleEmbeddingRetriever":
+        """
+        Deserializes the component from a dictionary.
+
+        :param data:
+            Dictionary to deserialize from.
+        :returns:
+            Deserialized component.
+        """
+        params = data.get("init_parameters", {})
+        if "document_store" in params:
+            params["document_store"] = OracleDocumentStore.from_dict(params["document_store"])
+        # Pipelines serialized with old versions of the component might not
+        # have the filter_policy field.
+        if filter_policy := params.get("filter_policy"):
+            params["filter_policy"] = FilterPolicy.from_str(filter_policy)
+        return default_from_dict(cls, data)

haystack_integrations/document_stores/oracle/__about__.py

@@ -0,0 +1,5 @@
+# SPDX-FileCopyrightText: 2023-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+__version__ = "0.1.0"

haystack_integrations/document_stores/oracle/__init__.py

@@ -0,0 +1,10 @@
+# SPDX-FileCopyrightText: 2023-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from haystack_integrations.document_stores.oracle.document_store import (
+    OracleConnectionConfig,
+    OracleDocumentStore,
+)
+
+__all__ = ["OracleConnectionConfig", "OracleDocumentStore"]

haystack_integrations/document_stores/oracle/document_store.py

@@ -0,0 +1,524 @@
+# SPDX-FileCopyrightText: 2023-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import array as _array
+import asyncio
+import json
+import logging
+import re
+import threading
+from dataclasses import dataclass
+from typing import Any, Literal
+
+import oracledb
+from haystack import default_from_dict, default_to_dict
+from haystack.dataclasses import Document
+from haystack.document_stores.errors import DuplicateDocumentError
+from haystack.document_stores.types import DuplicatePolicy
+from haystack.utils import Secret, deserialize_secrets_inplace
+
+from .filters import FilterTranslator
+
+logger = logging.getLogger(__name__)
+
+_SAFE_TABLE_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_$#]{0,127}$")
+
+
+@dataclass
+class OracleConnectionConfig:
+    """
+    Connection parameters for Oracle Database.
+
+    Supports both thin (direct TCP) and thick (wallet / ADB-S) modes.
+    Thin mode requires no Oracle Instant Client; thick mode is activated
+    automatically when *wallet_location* is provided.
+    """
+
+    user: Secret
+    password: Secret
+    dsn: Secret
+    wallet_location: str | None = None
+    wallet_password: Secret | None = None
+    min_connections: int = 1
+    max_connections: int = 5
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Serializes the component to a dictionary.
+
+        :returns:
+            Dictionary with serialized data.
+        """
+        return {
+            "user": self.user.to_dict(),
+            "password": self.password.to_dict(),
+            "dsn": self.dsn.to_dict(),
+            "wallet_location": self.wallet_location,
+            "wallet_password": self.wallet_password.to_dict() if self.wallet_password else None,
+            "min_connections": self.min_connections,
+            "max_connections": self.max_connections,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "OracleConnectionConfig":
+        """
+        Deserializes the component from a dictionary.
+
+        :param data:
+            Dictionary to deserialize from.
+        :returns:
+            Deserialized component.
+        """
+        deserialize_secrets_inplace(data, keys=["user", "password", "dsn", "wallet_password"])
+        return cls(**data)
+
+
+class OracleDocumentStore:
+    """
+    Haystack DocumentStore backed by Oracle AI Vector Search.
+
+    Requires Oracle Database 23ai or later (for VECTOR data type and
+    IF NOT EXISTS DDL support).
+
+    Usage::
+
+        from haystack.utils import Secret
+        from haystack_integrations.document_stores.oracle import (
+            OracleDocumentStore, OracleConnectionConfig,
+        )
+
+        store = OracleDocumentStore(
+            connection_config=OracleConnectionConfig(
+                user=Secret.from_env_var("ORACLE_USER"),
+                password=Secret.from_env_var("ORACLE_PASSWORD"),
+                dsn=Secret.from_env_var("ORACLE_DSN"),
+            ),
+            embedding_dim=1536,
+        )
+    """
+
+    def __init__(
+        self,
+        *,
+        connection_config: OracleConnectionConfig,
+        table_name: str = "haystack_documents",
+        embedding_dim: int,
+        distance_metric: Literal["COSINE", "EUCLIDEAN", "DOT"] = "COSINE",
+        create_table_if_not_exists: bool = True,
+        create_index: bool = False,
+        hnsw_neighbors: int = 32,
+        hnsw_ef_construction: int = 200,
+        hnsw_accuracy: int = 95,
+        hnsw_parallel: int = 4,
+    ) -> None:
+        if not _SAFE_TABLE_NAME.match(table_name):
+            msg = (
+                f"Invalid table_name {table_name!r}. Must be a valid Oracle identifier "
+                "(letters, digits, _, $, # — max 128 chars, cannot start with a digit)."
+            )
+            raise ValueError(msg)
+        if embedding_dim <= 0:
+            msg = f"embedding_dim must be a positive integer, got {embedding_dim}"
+            raise ValueError(msg)
+
+        self.connection_config = connection_config
+        self.table_name = table_name
+        self.embedding_dim = embedding_dim
+        self.distance_metric = distance_metric
+        self.create_table_if_not_exists = create_table_if_not_exists
+        self.create_index = create_index
+        self.hnsw_neighbors = hnsw_neighbors
+        self.hnsw_ef_construction = hnsw_ef_construction
+        self.hnsw_accuracy = hnsw_accuracy
+        self.hnsw_parallel = hnsw_parallel
+
+        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()
+
+    def _get_pool(self) -> oracledb.ConnectionPool:
+        if self._pool is not None:
+            return self._pool
+        with self._pool_lock:
+            if self._pool is not None:
+                return self._pool
+
+            cfg = self.connection_config
+            password = cfg.password.resolve_value()
+
+            connect_kwargs: dict[str, Any] = {
+                "user": cfg.user.resolve_value(),
+                "password": password,
+                "dsn": cfg.dsn.resolve_value(),
+                "min": cfg.min_connections,
+                "max": cfg.max_connections,
+                "increment": 1,
+            }
+            if cfg.wallet_location:
+                connect_kwargs["config_dir"] = cfg.wallet_location
+                connect_kwargs["wallet_location"] = cfg.wallet_location
+                connect_kwargs["wallet_password"] = (
+                    cfg.wallet_password.resolve_value() if cfg.wallet_password else password
+                )
+
+            self._pool = oracledb.create_pool(**connect_kwargs)
+        return self._pool
+
+    def _get_connection(self) -> oracledb.Connection:
+        return self._get_pool().acquire()
+
+    def __del__(self) -> None:
+        if self._pool is not None:
+            try:
+                self._pool.close()
+            except Exception:
+                logger.warning("Failed to close Oracle connection pool during cleanup.", exc_info=True)
+
+    def _ensure_table(self) -> None:
+        sql = f"""
+            CREATE TABLE IF NOT EXISTS {self.table_name} (
+                id        VARCHAR2(64) PRIMARY KEY,
+                text      CLOB,
+                metadata  JSON,
+                embedding VECTOR({self.embedding_dim}, FLOAT32)
+            )
+        """
+        with self._get_connection() as conn, conn.cursor() as cur:
+            cur.execute(sql)
+            conn.commit()
+
+    def create_hnsw_index(self) -> None:
+        """
+        Create an HNSW vector index on the embedding column.
+
+        Safe to call multiple times — uses IF NOT EXISTS.
+        """
+        sql = f"""
+            CREATE VECTOR INDEX IF NOT EXISTS {self.table_name}_vidx
+            ON {self.table_name}(embedding)
+            ORGANIZATION INMEMORY NEIGHBOR GRAPH
+            WITH TARGET ACCURACY {self.hnsw_accuracy}
+            DISTANCE {self.distance_metric}
+            PARAMETERS (type HNSW, neighbors {self.hnsw_neighbors},
+                        efConstruction {self.hnsw_ef_construction})
+            PARALLEL {self.hnsw_parallel}
+        """
+        with self._get_connection() as conn, conn.cursor() as cur:
+            cur.execute(sql)
+            conn.commit()
+
+    async def create_hnsw_index_async(self) -> None:
+        """Async variant of create_hnsw_index."""
+        await asyncio.to_thread(self.create_hnsw_index)
+
+    def write_documents(
+        self,
+        documents: list[Document],
+        policy: DuplicatePolicy = DuplicatePolicy.NONE,
+    ) -> int:
+        """
+        Writes documents to the document store.
+
+        :param documents: A list of Documents to write to the document store.
+        :param policy: The duplicate policy to use when writing documents.
+        :raises DuplicateDocumentError: If a document with the same id already exists in the document store
+            and the policy is set to `DuplicatePolicy.FAIL` or `DuplicatePolicy.NONE`.
+        :returns: The number of documents written to the document store.
+        """
+        if not isinstance(documents, list):
+            msg = "write_documents expects a list of Document objects."
+            raise ValueError(msg)
+        if documents and not isinstance(documents[0], Document):
+            msg = "write_documents expects a list of Document objects."
+            raise ValueError(msg)
+        if not documents:
+            return 0
+        if policy in (DuplicatePolicy.NONE, DuplicatePolicy.FAIL):
+            return self._insert_documents(documents)
+        if policy == DuplicatePolicy.SKIP:
+            return self._skip_duplicate_documents(documents)
+        if policy == DuplicatePolicy.OVERWRITE:
+            return self._upsert_documents(documents)
+        msg = f"Unknown DuplicatePolicy: {policy}"
+        raise ValueError(msg)
+
+    @staticmethod
+    def _to_row(doc: Document) -> tuple[str, str | None, str, _array.array | None]:
+        """
+        Convert a Document to (id, text, metadata_json, embedding_array).
+
+        Haystack IDs are stored verbatim in a VARCHAR2(64) column, so any
+        string ID (UUID, SHA-256 hash, or custom) is accepted without conversion.
+        """
+        doc_id = doc.id
+        text = doc.content
+        meta = json.dumps(doc.meta or {})
+        emb: _array.array | None = None
+        if doc.embedding is not None:
+            emb = _array.array("f", doc.embedding)
+        return doc_id, text, meta, emb
+
+    @staticmethod
+    def _to_named_row(doc: Document) -> dict[str, Any]:
+        doc_id, text, meta, emb = OracleDocumentStore._to_row(doc)
+        return {"doc_id": doc_id, "doc_text": text, "doc_meta": meta, "doc_emb": emb}
+
+    def _insert_documents(self, documents: list[Document]) -> int:
+        sql = f"""
+            INSERT INTO {self.table_name} (id, text, metadata, embedding)
+            VALUES (:doc_id, :doc_text, :doc_meta, :doc_emb)
+        """
+        rows = [OracleDocumentStore._to_named_row(d) for d in documents]
+        try:
+            with self._get_connection() as conn, conn.cursor() as cur:
+                cur.executemany(sql, rows)
+                conn.commit()
+        except oracledb.IntegrityError as exc:
+            msg = f"Document already exists. Use DuplicatePolicy.OVERWRITE or SKIP. Original error: {exc}"
+            raise DuplicateDocumentError(msg) from exc
+        return len(rows)
+
+    def _skip_duplicate_documents(self, documents: list[Document]) -> int:
+        # For a MERGE with WHEN NOT MATCHED only, Oracle reports 0 rows affected
+        # for existing documents and 1 for each new insert. oracledb sums these
+        # across executemany iterations, so cur.rowcount equals the number of
+        # newly written documents.
+        sql = f"""
+            MERGE INTO {self.table_name} t
+            USING (SELECT :doc_id AS id FROM dual) s ON (t.id = s.id)
+            WHEN NOT MATCHED THEN
+                INSERT (id, text, metadata, embedding)
+                VALUES (s.id, :doc_text, :doc_meta, :doc_emb)
+        """
+        rows = [OracleDocumentStore._to_named_row(d) for d in documents]
+        with self._get_connection() as conn, conn.cursor() as cur:
+            cur.executemany(sql, rows)
+            written = cur.rowcount
+            conn.commit()
+        return written
+
+    def _upsert_documents(self, documents: list[Document]) -> int:
+        sql = f"""
+            MERGE INTO {self.table_name} t
+            USING (SELECT :doc_id AS id FROM dual) s ON (t.id = s.id)
+            WHEN MATCHED THEN
+                UPDATE SET t.text = :doc_text, t.metadata = :doc_meta, t.embedding = :doc_emb
+            WHEN NOT MATCHED THEN
+                INSERT (id, text, metadata, embedding)
+                VALUES (s.id, :doc_text, :doc_meta, :doc_emb)
+        """
+        rows = [OracleDocumentStore._to_named_row(d) for d in documents]
+        with self._get_connection() as conn, conn.cursor() as cur:
+            cur.executemany(sql, rows)
+            written = cur.rowcount
+            conn.commit()
+        return written
+
+    async def write_documents_async(
+        self,
+        documents: list[Document],
+        policy: DuplicatePolicy = DuplicatePolicy.NONE,
+    ) -> int:
+        """
+        Asynchronously writes documents to the document store.
+
+        :param documents: A list of Documents to write to the document store.
+        :param policy: The duplicate policy to use when writing documents.
+        :raises DuplicateDocumentError: If a document with the same id already exists in the document store
+            and the policy is set to `DuplicatePolicy.FAIL` or `DuplicatePolicy.NONE`.
+        :returns: The number of documents written to the document store.
+        """
+        return await asyncio.to_thread(self.write_documents, documents, policy)
+
+    @staticmethod
+    def _build_where(filters: dict[str, Any] | None) -> tuple[str, dict[str, Any]]:
+        if not filters:
+            return "", {}
+        params: dict[str, Any] = {}
+        counter = [0]
+        fragment = FilterTranslator().translate(filters, params, counter)
+        return f"WHERE {fragment}", params
+
+    def filter_documents(self, filters: dict[str, Any] | None = None) -> list[Document]:
+        """
+        Returns the documents that match the filters provided.
+
+        For a detailed specification of the filters,
+        refer to the [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+        :param filters: The filters to apply to the document list.
+        :returns: A list of Documents that match the given filters.
+        """
+        where, params = OracleDocumentStore._build_where(filters)
+        sql = f"SELECT id, text, metadata FROM {self.table_name} {where}"
+        with self._get_connection() as conn, conn.cursor() as cur:
+            cur.execute(sql, params)
+            rows = cur.fetchall()
+        return [OracleDocumentStore._row_to_document(r) for r in rows]
+
+    async def filter_documents_async(self, filters: dict[str, Any] | None = None) -> list[Document]:
+        """
+        Asynchronously returns the documents that match the filters provided.
+
+        For a detailed specification of the filters,
+        refer to the [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering)
+
+        :param filters: The filters to apply to the document list.
+        :returns: A list of Documents that match the given filters.
+        """
+        return await asyncio.to_thread(self.filter_documents, filters)
+
+    def delete_documents(self, document_ids: list[str]) -> None:
+        """
+        Deletes documents that match the provided `document_ids` from the document store.
+
+        :param document_ids: the document ids to delete
+        """
+        if not document_ids:
+            return
+        placeholders = ", ".join(f":p{i}" for i in range(len(document_ids)))
+        sql = f"DELETE FROM {self.table_name} WHERE id IN ({placeholders})"
+        params = {f"p{i}": doc_id for i, doc_id in enumerate(document_ids)}
+        with self._get_connection() as conn, conn.cursor() as cur:
+            cur.execute(sql, params)
+            conn.commit()
+
+    async def delete_documents_async(self, document_ids: list[str]) -> None:
+        """
+        Asynchronously deletes documents that match the provided `document_ids` from the document store.
+
+        :param document_ids: the document ids to delete
+        """
+        await asyncio.to_thread(self.delete_documents, document_ids)
+
+    def count_documents(self) -> int:
+        """
+        Returns how many documents are present in the document store.
+
+        :returns:
+            Number of documents in the document store.
+        """
+        sql = f"SELECT COUNT(*) FROM {self.table_name}"
+        with self._get_connection() as conn, conn.cursor() as cur:
+            cur.execute(sql)
+            row = cur.fetchone()
+        return row[0] if row else 0
+
+    async def count_documents_async(self) -> int:
+        """
+        Asynchronously returns how many documents are present in the document store.
+
+        :returns:
+            Number of documents in the document store.
+        """
+        return await asyncio.to_thread(self.count_documents)
+
+    def _embedding_retrieval(
+        self,
+        query_embedding: list[float],
+        *,
+        filters: dict[str, Any] | None = None,
+        top_k: int = 10,
+    ) -> list[Document]:
+        # Oracle vector_distance() returns lower values for more similar vectors
+        # across all metrics (COSINE, EUCLIDEAN, DOT) → always sort ASC.
+        order = "ASC"
+        where, params = OracleDocumentStore._build_where(filters)
+        sql = f"""
+            SELECT id, text, metadata,
+                   vector_distance(embedding, :query_vec, {self.distance_metric}) AS score
+            FROM {self.table_name}
+            {where}
+            ORDER BY score {order}
+            FETCH APPROX FIRST :top_k ROWS ONLY
+        """
+        params["query_vec"] = _array.array("f", query_embedding)
+        params["top_k"] = top_k
+        with self._get_connection() as conn, conn.cursor() as cur:
+            cur.execute(sql, params)
+            rows = cur.fetchall()
+        return [OracleDocumentStore._row_to_document(r, with_score=True) for r in rows]
+
+    async def _embedding_retrieval_async(
+        self,
+        query_embedding: list[float],
+        *,
+        filters: dict[str, Any] | None = None,
+        top_k: int = 10,
+    ) -> list[Document]:
+        return await asyncio.to_thread(
+            self._embedding_retrieval,
+            query_embedding,
+            filters=filters,
+            top_k=top_k,
+        )
+
+    @staticmethod
+    def _row_to_document(row: tuple, *, with_score: bool = False) -> Document:
+        if with_score:
+            raw_id, text, metadata_raw, score = row
+        else:
+            raw_id, text, metadata_raw, score = *row, None
+
+        # oracledb returns CLOB/JSON as LOB objects — read them to strings
+        if hasattr(text, "read"):
+            text = text.read()
+        if hasattr(metadata_raw, "read"):
+            metadata_raw = metadata_raw.read()
+
+        if isinstance(metadata_raw, str):
+            meta = json.loads(metadata_raw)
+        elif isinstance(metadata_raw, dict):
+            meta = metadata_raw
+        else:
+            meta = {}
+
+        return Document(
+            id=raw_id,
+            content=text,
+            meta=meta,
+            score=float(score) if score is not None else None,
+            embedding=None,
+            blob=None,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Serializes the component to a dictionary.
+
+        :returns:
+            Dictionary with serialized data.
+        """
+        return default_to_dict(
+            self,
+            connection_config=self.connection_config.to_dict(),
+            table_name=self.table_name,
+            embedding_dim=self.embedding_dim,
+            distance_metric=self.distance_metric,
+            create_table_if_not_exists=self.create_table_if_not_exists,
+            create_index=self.create_index,
+            hnsw_neighbors=self.hnsw_neighbors,
+            hnsw_ef_construction=self.hnsw_ef_construction,
+            hnsw_accuracy=self.hnsw_accuracy,
+            hnsw_parallel=self.hnsw_parallel,
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "OracleDocumentStore":
+        """
+        Deserializes the component from a dictionary.
+
+        :param data:
+            Dictionary to deserialize from.
+        :returns:
+            Deserialized component.
+        """
+        params = data.get("init_parameters", {})
+        if "connection_config" in params:
+            params["connection_config"] = OracleConnectionConfig.from_dict(params["connection_config"])
+        return default_from_dict(cls, data)

haystack_integrations/document_stores/oracle/filters.py

@@ -0,0 +1,147 @@
+# SPDX-FileCopyrightText: 2023-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from datetime import datetime
+from typing import Any, ClassVar
+
+from haystack.errors import FilterError
+
+_RANGE_OPS = {">", ">=", "<", "<="}
+
+
+class FilterTranslator:
+    """
+    Translates Haystack 2.x filter dicts into Oracle SQL WHERE fragments.
+
+    Example input:
+        {"operator": "AND", "conditions": [
+            {"field": "meta.author", "operator": "==", "value": "Alice"},
+            {"field": "meta.year",   "operator": ">",  "value": 2020},
+        ]}
+
+    Example output SQL fragment:
+        (JSON_VALUE(metadata, '$.author') = :p0
+         AND TO_NUMBER(JSON_VALUE(metadata, '$.year')) > :p1)
+
+    Params dict is mutated in-place; caller passes an empty dict and uses it
+    for cursor.execute / cursor.executemany bindings.
+    """
+
+    _OP_MAP: ClassVar[dict[str, str]] = {
+        "==": "=",
+        "!=": "!=",
+        ">": ">",
+        ">=": ">=",
+        "<": "<",
+        "<=": "<=",
+    }
+
+    def translate(self, filters: dict[str, Any], params: dict[str, Any], counter: list[int]) -> str:
+        """
+        Translate the given filter dict into an SQL fragment, adding any necessary parameters to the params dict.
+        """
+        op = filters.get("operator")
+
+        # Logical nodes
+        if op in ("AND", "OR", "NOT"):
+            if "conditions" not in filters:
+                msg = f"'conditions' key missing in logical filter: {filters}"
+                raise FilterError(msg)
+            if op == "AND":
+                parts = [self.translate(c, params, counter) for c in filters["conditions"]]
+                return "(" + " AND ".join(parts) + ")"
+            if op == "OR":
+                parts = [self.translate(c, params, counter) for c in filters["conditions"]]
+                return "(" + " OR ".join(parts) + ")"
+            # NOT
+            inner = self.translate(filters["conditions"][0], params, counter)
+            return f"(NOT {inner})"
+
+        # Comparison leaf — validate required keys first
+        if "field" not in filters:
+            msg = f"'field' key missing in comparison filter: {filters}"
+            raise FilterError(msg)
+        if "operator" not in filters:
+            msg = f"'operator' key missing in comparison filter: {filters}"
+            raise FilterError(msg)
+        if "value" not in filters:
+            msg = f"'value' key missing in comparison filter: {filters}"
+            raise FilterError(msg)
+
+        if not isinstance(op, str) or op not in {*self._OP_MAP, "in", "not in"}:
+            msg = f"Unsupported filter operator: {op!r}"
+            raise FilterError(msg)
+
+        field: str = filters["field"]
+        value: Any = filters["value"]
+
+        if op in ("in", "not in"):
+            if not isinstance(value, list):
+                msg = f"'in' / 'not in' filter values must be a list, got {type(value).__name__!r}"
+                raise FilterError(msg)
+            col = FilterTranslator._field_to_sql(field, value[0] if value else value)
+            placeholders = []
+            for v in value:
+                pname = f"p{counter[0]}"
+                counter[0] += 1
+                params[pname] = v
+                placeholders.append(f":{pname}")
+            if op == "in":
+                return f"{col} IN ({', '.join(placeholders)})"
+            # NOT IN: include rows where the column is NULL, matching Python's
+            # `None not in [...]` == True semantics.
+            return f"({col} IS NULL OR {col} NOT IN ({', '.join(placeholders)}))"
+
+        if op in _RANGE_OPS and (isinstance(value, (str, list)) and not _is_iso_date(value)):
+            msg = f"Operator {op!r} requires a numeric or ISO-date value, got {type(value).__name__!r}: {value!r}"
+            raise FilterError(msg)
+
+        col = FilterTranslator._field_to_sql(field, value)
+
+        # NULL-safe equality / inequality
+        if op == "==" and value is None:
+            return f"{col} IS NULL"
+        if op == "!=" and value is None:
+            return f"{col} IS NOT NULL"
+
+        pname = f"p{counter[0]}"
+        counter[0] += 1
+        params[pname] = value
+
+        if op == "!=":
+            # Include rows where the column is NULL, matching Python's
+            # `None != x` == True semantics.
+            return f"({col} != :{pname} OR {col} IS NULL)"
+
+        sql_op = self._OP_MAP[op]
+        return f"{col} {sql_op} :{pname}"
+
+    @staticmethod
+    def _field_to_sql(field: str, value: Any) -> str:
+        if field == "id":
+            return "id"
+        if field == "content":
+            return "text"
+        if field.startswith("meta."):
+            key = field[len("meta.") :]
+            json_path = f"JSON_VALUE(metadata, '$.{key}')"
+            if isinstance(value, (int, float)) and not isinstance(value, bool):
+                return f"TO_NUMBER({json_path})"
+            return json_path
+        # Fallback: treat as top-level JSON key
+        json_path = f"JSON_VALUE(metadata, '$.{field}')"
+        if isinstance(value, (int, float)) and not isinstance(value, bool):
+            return f"TO_NUMBER({json_path})"
+        return json_path
+
+
+def _is_iso_date(value: Any) -> bool:
+    """Return True if *value* is a string that Python recognises as a valid ISO-8601 datetime."""
+    if not isinstance(value, str):
+        return False
+    try:
+        datetime.fromisoformat(value)
+        return True
+    except ValueError:
+        return False

oracle_haystack-0.1.0.dist-info/METADATA

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: oracle-haystack
+Version: 0.1.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
+Keywords: OCI,RAG,document store,haystack,oracle,vector search
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Python: >=3.10
+Requires-Dist: haystack-ai>=2.26.1
+Requires-Dist: oracledb<3.0.0,>=2.1.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.9.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# oracle-haystack
+
+[![PyPI - Version](https://img.shields.io/pypi/v/oracle-haystack.svg)](https://pypi.org/project/oracle-haystack)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/oracle-haystack.svg)](https://pypi.org/project/oracle-haystack)
+
+Haystack DocumentStore backed by [Oracle AI Vector Search](https://www.oracle.com/database/ai-vector-search/), available in Oracle Database 23ai and later.
+
+- [Changelog](https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/oracle/CHANGELOG.md)
+
+---
+
+## Installation
+
+```bash
+pip install oracle-haystack
+```
+
+Requires Python 3.10+ and Oracle Database 23ai (or later). No Oracle Instant Client is needed for direct TCP connections (thin mode).
+
+## Usage
+
+```python
+from haystack.utils import Secret
+from haystack_integrations.document_stores.oracle import OracleConnectionConfig, OracleDocumentStore
+from haystack_integrations.components.retrievers.oracle import OracleEmbeddingRetriever
+
+# Configure the connection
+config = OracleConnectionConfig(
+    user=Secret.from_env_var("ORACLE_USER"),
+    password=Secret.from_env_var("ORACLE_PASSWORD"),
+    dsn=Secret.from_env_var("ORACLE_DSN"),
+)
+
+# Create the document store
+store = OracleDocumentStore(
+    connection_config=config,
+    table_name="my_documents",
+    embedding_dim=768,
+    distance_metric="COSINE",
+    create_table_if_not_exists=True,
+)
+
+# Write documents
+from haystack.dataclasses import Document
+store.write_documents([
+    Document(content="Oracle 23ai supports native vector search."),
+])
+
+# Retrieve by embedding
+retriever = OracleEmbeddingRetriever(document_store=store, top_k=5)
+results = retriever.run(query_embedding=[0.1] * 768)
+print(results["documents"])
+```
+
+### Connecting to Oracle Autonomous Database (ADB-S / wallet)
+
+```python
+config = OracleConnectionConfig(
+    user=Secret.from_env_var("ORACLE_USER"),
+    password=Secret.from_env_var("ORACLE_PASSWORD"),
+    dsn=Secret.from_env_var("ORACLE_DSN"),
+    wallet_location="/path/to/wallet",
+    wallet_password=Secret.from_env_var("WALLET_PASSWORD"),
+)
+```
+
+### Optional HNSW index
+
+Pass `create_index=True` when constructing the store to build an HNSW vector index, which dramatically speeds up approximate nearest-neighbour search on large collections:
+
+```python
+store = OracleDocumentStore(
+    connection_config=config,
+    table_name="my_documents",
+    embedding_dim=768,
+    create_index=True,
+    hnsw_neighbors=32,
+    hnsw_ef_construction=200,
+    hnsw_accuracy=95,
+)
+```
+
+## Contributing
+
+Refer to the general [Contribution Guidelines](https://github.com/deepset-ai/haystack-core-integrations/blob/main/CONTRIBUTING.md).
+
+### Running tests
+
+#### Unit tests
+
+```bash
+PYTHONPATH=src hatch run test:unit -vvv
+```
+
+#### Integration tests against a live Oracle instance
+
+Set `ORACLE_USER`, `ORACLE_PASSWORD`, and `ORACLE_DSN` environment variables to point at your Oracle 23ai instance, then:
+
+```bash
+PYTHONPATH=src hatch run test:integration -vvv
+```
+
+#### Integration tests via Docker (local Oracle 23ai Free)
+
+A `docker-compose.yml` is provided that runs [`gvenzl/oracle-free:23-slim`](https://hub.docker.com/r/gvenzl/oracle-free) (Oracle Database 23ai Free edition).
+
+```bash
+docker compose up -d --wait
+```
+
+`--wait` blocks until the Oracle healthcheck passes (the first boot takes 2–4 minutes while Oracle initialises its data files).
+
+Run the full integration test suite:
+
+```bash
+PYTHONPATH=src hatch run test:integration -vvv
+```

oracle_haystack-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+haystack_integrations/components/retrievers/oracle/__init__.py,sha256=xTR2hHWAP0kL5BY3FAdDJwVquReJJwwTQL8jLoicceo,259
+haystack_integrations/components/retrievers/oracle/embedding_retriever.py,sha256=RiHEAs38O9isIyyTcbIjx9G_8ngnRG1aeREnviF2lnE,4292
+haystack_integrations/components/retrievers/oracle/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+haystack_integrations/document_stores/oracle/__about__.py,sha256=LvXvcqIsISI-Jl3STUWpFpoRFUa3MSjcbkaw4vC42Sc,133
+haystack_integrations/document_stores/oracle/__init__.py,sha256=CSjJlELEy6va2CaFrsbCj_Y9dMx841-NfFDhLlcN_UU,301
+haystack_integrations/document_stores/oracle/document_store.py,sha256=ysjSXucIHHMfsJt44y_o7m8TSmvEELeT7Kw84-QkrgE,19764
+haystack_integrations/document_stores/oracle/filters.py,sha256=Jmuvwf1puOd5Wej8eIzBCHrL9XIIVFFN5Al7f5-1qSI,5481
+haystack_integrations/document_stores/oracle/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+oracle_haystack-0.1.0.dist-info/METADATA,sha256=UyoJmZntP2YfETls1jtKfJvWP2ndOPzTBIiq6U9hiKc,4711
+oracle_haystack-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+oracle_haystack-0.1.0.dist-info/RECORD,,

oracle_haystack-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any