mariadb-haystack 0.0.1__py3-none-any.whl

haystack_integrations/components/retrievers/mariadb/__init__.py

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

haystack_integrations/components/retrievers/mariadb/embedding_retriever.py

@@ -0,0 +1,112 @@
+# 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.mariadb import MariaDBDocumentStore
+
+
+@component
+class MariaDBEmbeddingRetriever:
+    """
+    Retrieves documents from `MariaDBDocumentStore` using vector similarity search.
+
+    Uses MariaDB's native `VEC_DISTANCE_COSINE` or `VEC_DISTANCE_EUCLIDEAN` functions
+    with MHNSW indexing for efficient approximate nearest-neighbour search.
+
+    ### Usage example
+
+    ```python
+    from haystack_integrations.document_stores.mariadb import MariaDBDocumentStore
+    from haystack_integrations.components.retrievers.mariadb import MariaDBEmbeddingRetriever
+
+    store = MariaDBDocumentStore(host="localhost", database="haystack", embedding_dimension=768)
+    retriever = MariaDBEmbeddingRetriever(document_store=store, top_k=5)
+    result = retriever.run(query_embedding=[0.1] * 768)
+    documents = result["documents"]
+    ```
+    """
+
+    def __init__(
+        self,
+        *,
+        document_store: MariaDBDocumentStore,
+        filters: dict[str, Any] | None = None,
+        top_k: int = 10,
+        score_threshold: float | None = None,
+        filter_policy: str | FilterPolicy = FilterPolicy.REPLACE,
+    ) -> None:
+        """
+        Initialize the MariaDBEmbeddingRetriever.
+
+        :param document_store: A `MariaDBDocumentStore` instance.
+        :param filters: Default Haystack metadata filters applied to every query.
+        :param top_k: Maximum number of documents to return.
+        :param score_threshold: Minimum score to include a document. Documents below this score are excluded.
+        :param filter_policy: How runtime filters interact with init-time filters.
+        :raises ValueError: If `document_store` is not a `MariaDBDocumentStore`.
+        """
+        if not isinstance(document_store, MariaDBDocumentStore):
+            msg = "document_store must be an instance of MariaDBDocumentStore"
+            raise ValueError(msg)
+
+        self.document_store = document_store
+        self.filters = filters or {}
+        self.top_k = top_k
+        self.score_threshold = score_threshold
+        self.filter_policy = (
+            filter_policy if isinstance(filter_policy, FilterPolicy) else FilterPolicy.from_str(filter_policy)
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize the component to a dictionary."""
+        return default_to_dict(
+            self,
+            filters=self.filters,
+            top_k=self.top_k,
+            score_threshold=self.score_threshold,
+            filter_policy=self.filter_policy.value,
+            document_store=self.document_store.to_dict(),
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "MariaDBEmbeddingRetriever":
+        """Deserialize the component from a dictionary."""
+        doc_store_params = data["init_parameters"]["document_store"]
+        data["init_parameters"]["document_store"] = MariaDBDocumentStore.from_dict(doc_store_params)
+        if filter_policy := data["init_parameters"].get("filter_policy"):
+            data["init_parameters"]["filter_policy"] = FilterPolicy.from_str(filter_policy)
+        return default_from_dict(cls, data)
+
+    @component.output_types(documents=list[Document])
+    def run(
+        self,
+        query_embedding: list[float],
+        filters: dict[str, Any] | None = None,
+        top_k: int | None = None,
+        score_threshold: float | None = None,
+    ) -> dict[str, list[Document]]:
+        """
+        Retrieve documents similar to the query embedding.
+
+        :param query_embedding: The query vector.
+        :param filters: Runtime filters merged with init-time filters per `filter_policy`.
+        :param top_k: Override the retriever's `top_k`.
+        :param score_threshold: Override the retriever's `score_threshold`.
+        :returns: Dictionary with `"documents"` key containing the ranked results.
+        """
+        filters = apply_filter_policy(self.filter_policy, self.filters, filters)
+        return {
+            "documents": self.document_store._embedding_retrieval(
+                query_embedding=query_embedding,
+                filters=filters,
+                top_k=top_k or self.top_k,
+                score_threshold=score_threshold if score_threshold is not None else self.score_threshold,
+            )
+        }

haystack_integrations/components/retrievers/mariadb/keyword_retriever.py

@@ -0,0 +1,105 @@
+# 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.mariadb import MariaDBDocumentStore
+
+
+@component
+class MariaDBKeywordRetriever:
+    """
+    Retrieves documents from `MariaDBDocumentStore` using full-text keyword search.
+
+    Uses MariaDB's `MATCH ... AGAINST` full-text search in natural language mode,
+    backed by a FULLTEXT index on the `content` column.
+
+    ### Usage example
+
+    ```python
+    from haystack_integrations.document_stores.mariadb import MariaDBDocumentStore
+    from haystack_integrations.components.retrievers.mariadb import MariaDBKeywordRetriever
+
+    store = MariaDBDocumentStore(host="localhost", database="haystack", embedding_dimension=768)
+    retriever = MariaDBKeywordRetriever(document_store=store, top_k=5)
+    result = retriever.run(query="climate change")
+    documents = result["documents"]
+    ```
+    """
+
+    def __init__(
+        self,
+        *,
+        document_store: MariaDBDocumentStore,
+        filters: dict[str, Any] | None = None,
+        top_k: int = 10,
+        filter_policy: str | FilterPolicy = FilterPolicy.REPLACE,
+    ) -> None:
+        """
+        Initialize the MariaDBKeywordRetriever.
+
+        :param document_store: A `MariaDBDocumentStore` instance.
+        :param filters: Default Haystack metadata filters.
+        :param top_k: Maximum number of documents to return.
+        :param filter_policy: How runtime filters interact with init-time filters.
+        :raises ValueError: If `document_store` is not a `MariaDBDocumentStore`.
+        """
+        if not isinstance(document_store, MariaDBDocumentStore):
+            msg = "document_store must be an instance of MariaDBDocumentStore"
+            raise ValueError(msg)
+
+        self.document_store = document_store
+        self.filters = filters or {}
+        self.top_k = top_k
+        self.filter_policy = (
+            filter_policy if isinstance(filter_policy, FilterPolicy) else FilterPolicy.from_str(filter_policy)
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize the component to a dictionary."""
+        return default_to_dict(
+            self,
+            filters=self.filters,
+            top_k=self.top_k,
+            filter_policy=self.filter_policy.value,
+            document_store=self.document_store.to_dict(),
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "MariaDBKeywordRetriever":
+        """Deserialize the component from a dictionary."""
+        doc_store_params = data["init_parameters"]["document_store"]
+        data["init_parameters"]["document_store"] = MariaDBDocumentStore.from_dict(doc_store_params)
+        if filter_policy := data["init_parameters"].get("filter_policy"):
+            data["init_parameters"]["filter_policy"] = FilterPolicy.from_str(filter_policy)
+        return default_from_dict(cls, data)
+
+    @component.output_types(documents=list[Document])
+    def run(
+        self,
+        query: str,
+        filters: dict[str, Any] | None = None,
+        top_k: int | None = None,
+    ) -> dict[str, list[Document]]:
+        """
+        Retrieve documents matching the query via full-text search.
+
+        :param query: The keyword query string.
+        :param filters: Runtime filters merged with init-time filters per `filter_policy`.
+        :param top_k: Override the retriever's `top_k`.
+        :returns: Dictionary with `"documents"` key containing results ranked by relevance.
+        """
+        filters = apply_filter_policy(self.filter_policy, self.filters, filters)
+        return {
+            "documents": self.document_store._keyword_retrieval(
+                query=query,
+                filters=filters,
+                top_k=top_k or self.top_k,
+            )
+        }

haystack_integrations/document_stores/mariadb/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2023-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from haystack_integrations.document_stores.mariadb.document_store import MariaDBDocumentStore
+
+__all__ = ["MariaDBDocumentStore"]

haystack_integrations/document_stores/mariadb/document_store.py

@@ -0,0 +1,548 @@
+# SPDX-FileCopyrightText: 2023-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import json
+import re
+import struct
+from dataclasses import replace
+from typing import Any
+
+from haystack import default_from_dict, default_to_dict, logging
+from haystack.dataclasses import ByteStream, Document
+from haystack.document_stores.errors import DocumentStoreError, DuplicateDocumentError
+from haystack.document_stores.types import DuplicatePolicy
+from haystack.utils.auth import Secret, deserialize_secrets_inplace
+
+import mariadb
+
+from .filters import _convert_filters_to_where_clause_and_params, _validate_filters
+
+logger = logging.getLogger(__name__)
+
+_VALID_TABLE_NAME_RE = re.compile(r"^[A-Za-z0-9_]+$")
+
+_VALID_DISTANCES = ("cosine", "euclidean")
+
+_DISTANCE_TO_SQL = {
+    "cosine": "VEC_DISTANCE_COSINE",
+    "euclidean": "VEC_DISTANCE_EUCLIDEAN",
+}
+
+_CREATE_TABLE_STATEMENT = """
+CREATE TABLE IF NOT EXISTS `{table_name}` (
+    id VARCHAR(128) PRIMARY KEY,
+    embedding VECTOR({embedding_dimension}),
+    content LONGTEXT,
+    blob_data LONGBLOB,
+    blob_meta JSON,
+    blob_mime_type VARCHAR(255),
+    meta JSON,
+    FULLTEXT KEY content_ft_idx (content)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
+"""
+
+_CREATE_TABLE_WITH_VECTOR_INDEX_STATEMENT = """
+CREATE TABLE IF NOT EXISTS `{table_name}` (
+    id VARCHAR(128) PRIMARY KEY,
+    embedding VECTOR({embedding_dimension}) NOT NULL,
+    content LONGTEXT,
+    blob_data LONGBLOB,
+    blob_meta JSON,
+    blob_mime_type VARCHAR(255),
+    meta JSON,
+    FULLTEXT KEY content_ft_idx (content),
+    VECTOR INDEX (embedding) DISTANCE={distance}
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
+"""
+
+_INSERT_STATEMENT = """
+INSERT INTO `{table_name}`
+(id, embedding, content, blob_data, blob_meta, blob_mime_type, meta)
+VALUES (?, ?, ?, ?, ?, ?, ?)
+"""
+
+_INSERT_IGNORE_STATEMENT = """
+INSERT IGNORE INTO `{table_name}`
+(id, embedding, content, blob_data, blob_meta, blob_mime_type, meta)
+VALUES (?, ?, ?, ?, ?, ?, ?)
+"""
+
+_UPSERT_STATEMENT = """
+INSERT INTO `{table_name}`
+(id, embedding, content, blob_data, blob_meta, blob_mime_type, meta)
+VALUES (?, ?, ?, ?, ?, ?, ?)
+ON DUPLICATE KEY UPDATE
+    embedding = VALUES(embedding),
+    content = VALUES(content),
+    blob_data = VALUES(blob_data),
+    blob_meta = VALUES(blob_meta),
+    blob_mime_type = VALUES(blob_mime_type),
+    meta = VALUES(meta)
+"""
+
+_KEYWORD_QUERY = """
+SELECT *, MATCH(content) AGAINST(? IN NATURAL LANGUAGE MODE) AS score
+FROM `{table_name}`
+{where_clause}
+HAVING score > 0
+ORDER BY score DESC
+LIMIT ?
+"""
+
+_EMBEDDING_QUERY = """
+SELECT *, {vec_func}(embedding, ?) AS score
+FROM `{table_name}`
+WHERE embedding IS NOT NULL
+{extra_where}
+ORDER BY score ASC
+LIMIT ?
+"""
+
+
+class MariaDBDocumentStore:
+    """
+    A Document Store backed by MariaDB 11.7+ using native VECTOR support.
+
+    Uses MariaDB's `VECTOR` datatype with `MHNSW` indexing for approximate nearest-neighbour
+    vector search, and `MATCH ... AGAINST` for full-text keyword search.
+
+    ### Usage example
+
+    ```python
+    from haystack_integrations.document_stores.mariadb import MariaDBDocumentStore
+
+    store = MariaDBDocumentStore(
+        host="localhost",
+        port=3306,
+        database="haystack",
+        embedding_dimension=768,
+    )
+    store.write_documents(documents)
+    ```
+    """
+
+    def __init__(
+        self,
+        *,
+        host: str = "localhost",
+        port: int = 3306,
+        database: str = "haystack",
+        user: Secret = Secret.from_env_var("MARIADB_USER"),
+        password: Secret = Secret.from_env_var("MARIADB_PASSWORD"),
+        table_name: str = "haystack_documents",
+        recreate_table: bool = False,
+        embedding_dimension: int = 768,
+        distance: str = "cosine",
+        create_vector_index: bool = False,
+    ) -> None:
+        """
+        Initialize the MariaDBDocumentStore.
+
+        :param host: MariaDB host.
+        :param port: MariaDB port.
+        :param database: Database name.
+        :param user: Database user, read from the `MARIADB_USER` environment variable.
+        :param password: Database password, read from the `MARIADB_PASSWORD` environment variable.
+        :param table_name: Table used to store documents. Must contain only letters, digits, and underscores.
+        :param recreate_table: Drop and recreate the table on init. **Deletes all data.**
+        :param embedding_dimension: Dimension of embedding vectors. Applied only when the table is created;
+            ignored on an existing table.
+        :param distance: Distance function for vector similarity — `"cosine"` or `"euclidean"`. Applied only when
+            the table is created; ignored on an existing table.
+        :param create_vector_index: If `True`, creates an MHNSW vector index for fast ANN search. Requires every
+            document to have a non-null embedding. Applied only when the table is created; ignored on an existing
+            table.
+        """
+        self._connection: Any = None
+        self._cursor: Any = None
+        self._table_initialized = False
+
+        if not _VALID_TABLE_NAME_RE.match(table_name):
+            msg = f"table_name must contain only letters, digits, and underscores, got '{table_name}'"
+            raise ValueError(msg)
+        if distance not in _VALID_DISTANCES:
+            msg = f"distance must be one of {_VALID_DISTANCES}, got '{distance}'"
+            raise ValueError(msg)
+
+        self.host = host
+        self.port = port
+        self.database = database
+        self.user = user
+        self.password = password
+        self.table_name = table_name
+        self.embedding_dimension = embedding_dimension
+        self.distance = distance
+        self.recreate_table = recreate_table
+        self.create_vector_index = create_vector_index
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Serialize this document store to a dictionary.
+
+        :returns: Dictionary with serialized data.
+        """
+        return default_to_dict(
+            self,
+            host=self.host,
+            port=self.port,
+            database=self.database,
+            user=self.user.to_dict(),
+            password=self.password.to_dict(),
+            table_name=self.table_name,
+            embedding_dimension=self.embedding_dimension,
+            distance=self.distance,
+            recreate_table=self.recreate_table,
+            create_vector_index=self.create_vector_index,
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "MariaDBDocumentStore":
+        """
+        Deserialize this document store from a dictionary.
+
+        :param data: Dictionary to deserialize from.
+        :returns: Deserialized document store.
+        """
+        deserialize_secrets_inplace(data["init_parameters"], ["user", "password"])
+        return default_from_dict(cls, data)
+
+    def _ensure_connection(self) -> None:
+        """Lazily establish the DB connection and initialize the table."""
+        if self._connection is not None and self._cursor is not None:
+            try:
+                self._connection.ping()
+                return
+            except Exception:
+                self._close_connection()
+
+        try:
+            self._connection = mariadb.connect(
+                host=self.host,
+                port=self.port,
+                database=self.database,
+                user=self.user.resolve_value() or "",
+                password=self.password.resolve_value() or "",
+                autocommit=True,
+            )
+        except mariadb.Error as e:
+            msg = (
+                f"Failed to connect to MariaDB at {self.host}:{self.port}/{self.database}. "
+                "Ensure MariaDB 11.7+ is running and credentials are correct."
+            )
+            raise DocumentStoreError(msg) from e
+
+        self._cursor = self._connection.cursor(dictionary=True)
+
+        if not self._table_initialized:
+            self._initialize_table()
+
+    def _initialize_table(self) -> None:
+        if self.recreate_table:
+            self._drop_table()
+
+        if self.create_vector_index:
+            sql = _CREATE_TABLE_WITH_VECTOR_INDEX_STATEMENT.format(
+                table_name=self.table_name,
+                embedding_dimension=self.embedding_dimension,
+                distance=self.distance,
+            )
+        else:
+            sql = _CREATE_TABLE_STATEMENT.format(
+                table_name=self.table_name,
+                embedding_dimension=self.embedding_dimension,
+            )
+        try:
+            self._cursor.execute(sql)
+            self._table_initialized = True
+        except mariadb.Error as e:
+            msg = f"Could not create table '{self.table_name}'"
+            raise DocumentStoreError(msg) from e
+
+    def _drop_table(self) -> None:
+        try:
+            self._cursor.execute(f"DROP TABLE IF EXISTS `{self.table_name}`")
+            self._table_initialized = False
+        except mariadb.Error as e:
+            msg = f"Could not drop table '{self.table_name}'"
+            raise DocumentStoreError(msg) from e
+
+    def _close_connection(self) -> None:
+        if self._cursor is not None:
+            try:
+                self._cursor.close()
+            except Exception:  # noqa: S110
+                pass
+            self._cursor = None
+        if self._connection is not None:
+            try:
+                self._connection.close()
+            except Exception:  # noqa: S110
+                pass
+            self._connection = None
+        self._table_initialized = False
+
+    def close(self) -> None:
+        """
+        Release the associated synchronous resources.
+        """
+        self._close_connection()
+
+    def delete_table(self) -> None:
+        """Drop the documents table"""
+        self._ensure_connection()
+        self._drop_table()
+
+    def count_documents(self) -> int:
+        """
+        Return how many documents are present in the document store.
+
+        :returns: Number of documents in the document store.
+        """
+        self._ensure_connection()
+        self._cursor.execute(f"SELECT COUNT(*) AS cnt FROM `{self.table_name}`")  # noqa: S608
+        row = self._cursor.fetchone()
+        return row["cnt"] if row else 0
+
+    def filter_documents(self, filters: dict[str, Any] | None = None) -> list[Document]:
+        """
+        Return 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.
+        :raises TypeError: If `filters` is not a dictionary.
+        :raises ValueError: If `filters` syntax is invalid.
+        :returns: A list of Documents that match the given filters.
+        """
+        _validate_filters(filters)
+        self._ensure_connection()
+
+        sql = f"SELECT * FROM `{self.table_name}`"  # noqa: S608
+        params: list[Any] = []
+
+        if filters:
+            where_clause, params = _convert_filters_to_where_clause_and_params(filters)
+            sql += where_clause
+
+        self._cursor.execute(sql, params)
+        records = self._cursor.fetchall()
+        return _rows_to_documents(records)
+
+    def write_documents(self, documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE) -> int:
+        """
+        Write documents to the store.
+
+        :param documents: A list of Documents to write to the document store.
+        :param policy: The duplicate policy to use when writing documents.
+        :raises ValueError: If `documents` contains objects that are not of type `Document`.
+        :raises DuplicateDocumentError: If a document with the same id already exists in the document store
+             and the policy is set to `DuplicatePolicy.FAIL` (or not specified).
+        :raises DocumentStoreError: If the write operation fails for any other reason.
+        :returns: The number of documents written to the document store.
+        """
+        if not documents:
+            return 0
+        if not isinstance(documents[0], Document):
+            msg = "param 'documents' must be a list of Document objects"
+            raise ValueError(msg)
+
+        if policy == DuplicatePolicy.NONE:
+            policy = DuplicatePolicy.FAIL
+
+        self._ensure_connection()
+
+        if policy == DuplicatePolicy.OVERWRITE:
+            sql = _UPSERT_STATEMENT.format(table_name=self.table_name)
+        elif policy == DuplicatePolicy.SKIP:
+            sql = _INSERT_IGNORE_STATEMENT.format(table_name=self.table_name)
+        else:
+            sql = _INSERT_STATEMENT.format(table_name=self.table_name)
+
+        rows = [_document_to_row(doc) for doc in documents]
+        try:
+            self._connection.begin()
+            self._cursor.executemany(sql, rows)
+            # ON DUPLICATE KEY UPDATE counts updated rows as 2, inserted as 1 in MariaDB.
+            # For OVERWRITE all documents are written regardless, so return len(rows).
+            written = len(rows) if policy == DuplicatePolicy.OVERWRITE else self._cursor.rowcount
+            self._connection.commit()
+        except mariadb.IntegrityError as e:
+            self._connection.rollback()
+            msg = "Some documents already exist and policy is FAIL"
+            raise DuplicateDocumentError(msg) from e
+        except mariadb.Error as e:
+            self._connection.rollback()
+            msg = "Failed to write documents"
+            raise DocumentStoreError(msg) from e
+
+        return written
+
+    def delete_documents(self, document_ids: list[str]) -> None:
+        """
+        Delete documents that match the provided `document_ids` from the document store.
+
+        :param document_ids: The document ids to delete.
+        """
+        if not document_ids:
+            return
+        self._ensure_connection()
+        placeholders = ", ".join(["?"] * len(document_ids))
+        try:
+            self._cursor.execute(
+                f"DELETE FROM `{self.table_name}` WHERE id IN ({placeholders})",  # noqa: S608
+                tuple(document_ids),
+            )
+        except mariadb.Error as e:
+            msg = "Failed to delete documents"
+            raise DocumentStoreError(msg) from e
+
+    def _embedding_retrieval(
+        self,
+        query_embedding: list[float],
+        *,
+        filters: dict[str, Any] | None = None,
+        top_k: int = 10,
+        score_threshold: float | None = None,
+    ) -> list[Document]:
+        """
+        Retrieve documents by vector similarity.
+
+        :param query_embedding: Query vector.
+        :param filters: Optional Haystack filters.
+        :param top_k: Maximum results.
+        :param score_threshold: Minimum score to include a document. Documents below this score are excluded.
+        :returns: List of Documents ordered by similarity (most similar first).
+        """
+        if len(query_embedding) != self.embedding_dimension:
+            msg = (
+                f"query_embedding has {len(query_embedding)} dimensions but the store "
+                f"was configured with embedding_dimension={self.embedding_dimension}"
+            )
+            raise ValueError(msg)
+
+        _validate_filters(filters)
+        self._ensure_connection()
+
+        vec_func = _DISTANCE_TO_SQL[self.distance]
+        embedding_bytes = _embedding_to_bytes(query_embedding)
+
+        extra_where = ""
+        params: list[Any] = [embedding_bytes]
+
+        if filters:
+            where_clause, filter_params = _convert_filters_to_where_clause_and_params(filters, operator="AND")
+            extra_where = where_clause
+            params.extend(filter_params)
+
+        params.append(top_k)
+
+        sql = _EMBEDDING_QUERY.format(
+            vec_func=vec_func,
+            table_name=self.table_name,
+            extra_where=extra_where,
+        )
+
+        self._cursor.execute(sql, params)
+        records = self._cursor.fetchall()
+
+        docs = _rows_to_documents(records)
+        # VEC_DISTANCE_* returns distance (lower = more similar); convert to a positive score
+        docs = [
+            replace(doc, score=float(1.0 - record["score"]) if self.distance == "cosine" else float(-record["score"]))
+            if record.get("score") is not None
+            else doc
+            for doc, record in zip(docs, records, strict=True)
+        ]
+        if score_threshold is not None:
+            docs = [doc for doc in docs if doc.score is not None and doc.score >= score_threshold]
+        return docs
+
+    def _keyword_retrieval(
+        self,
+        query: str,
+        *,
+        filters: dict[str, Any] | None = None,
+        top_k: int = 10,
+    ) -> list[Document]:
+        """
+        Retrieve documents by full-text keyword search.
+
+        :param query: Search query string.
+        :param filters: Optional Haystack filters.
+        :param top_k: Maximum results.
+        :returns: List of Documents ordered by relevance.
+        """
+        _validate_filters(filters)
+        self._ensure_connection()
+
+        params: list[Any] = [query]
+        where_clause = ""
+
+        if filters:
+            where_clause, filter_params = _convert_filters_to_where_clause_and_params(filters)
+            params = [query, *filter_params]
+
+        params.append(top_k)
+
+        sql = _KEYWORD_QUERY.format(table_name=self.table_name, where_clause=where_clause)
+        self._cursor.execute(sql, params)
+        records = self._cursor.fetchall()
+
+        docs = _rows_to_documents(records)
+        docs = [
+            replace(doc, score=float(record.get("score") or 0.0)) for doc, record in zip(docs, records, strict=True)
+        ]
+        return docs
+
+
+def _embedding_to_bytes(embedding: list[float]) -> bytes:
+    return struct.pack(f"{len(embedding)}f", *embedding)
+
+
+def _bytes_to_embedding(data: bytes | bytearray) -> list[float]:
+    n = len(data) // 4
+    return list(struct.unpack(f"{n}f", data))
+
+
+def _document_to_row(doc: Document) -> tuple:
+    embedding_bytes = _embedding_to_bytes(doc.embedding) if doc.embedding is not None else None
+    blob_data = doc.blob.data if doc.blob else None
+    blob_meta = json.dumps(doc.blob.meta) if doc.blob and doc.blob.meta else None
+    blob_mime_type = doc.blob.mime_type if doc.blob else None
+    meta = json.dumps(doc.meta) if doc.meta else json.dumps({})
+    return (doc.id, embedding_bytes, doc.content, blob_data, blob_meta, blob_mime_type, meta)
+
+
+def _rows_to_documents(records: list[dict[str, Any]]) -> list[Document]:
+    docs = []
+    for record in records:
+        row = dict(record)
+        row.pop("score", None)
+
+        blob_data = row.pop("blob_data", None)
+        blob_meta_raw = row.pop("blob_meta", None)
+        blob_mime_type = row.pop("blob_mime_type", None)
+
+        if isinstance(row.get("meta"), str):
+            row["meta"] = json.loads(row["meta"])
+        elif row.get("meta") is None:
+            row.pop("meta", None)
+
+        emb = row.get("embedding")
+        if emb is not None:
+            if hasattr(emb, "tolist"):
+                row["embedding"] = emb.tolist()
+            elif isinstance(emb, (bytes, bytearray)):
+                row["embedding"] = _bytes_to_embedding(emb)
+
+        doc = Document.from_dict(row)
+
+        if blob_data:
+            if isinstance(blob_meta_raw, str):
+                blob_meta_raw = json.loads(blob_meta_raw)
+            doc = replace(doc, blob=ByteStream(data=blob_data, meta=blob_meta_raw or {}, mime_type=blob_mime_type))
+
+        docs.append(doc)
+    return docs

haystack_integrations/document_stores/mariadb/filters.py

@@ -0,0 +1,207 @@
+# SPDX-FileCopyrightText: 2023-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import re
+from datetime import datetime
+from typing import Any
+
+from haystack.errors import FilterError
+
+NO_VALUE = "no_value"
+
+
+def _validate_filters(filters: dict[str, Any] | None = None) -> None:
+    if filters:
+        if not isinstance(filters, dict):
+            msg = "Filters must be a dictionary"
+            raise TypeError(msg)
+        if "operator" not in filters and "conditions" not in filters:
+            msg = "Invalid filter syntax. See https://docs.haystack.deepset.ai/docs/metadata-filtering for details."
+            raise ValueError(msg)
+
+
+def _convert_filters_to_where_clause_and_params(
+    filters: dict[str, Any],
+    operator: str = "WHERE",
+) -> tuple[str, list[Any]]:
+    """Convert Haystack filters to a MariaDB WHERE clause string and parameter list."""
+    if "field" in filters:
+        clause, values = _parse_comparison_condition(filters)
+    else:
+        clause, values = _parse_logical_condition(filters)
+
+    params = [v for v in values if v != NO_VALUE]
+    return f" {operator} {clause}", params
+
+
+def _parse_logical_condition(condition: dict[str, Any]) -> tuple[str, list[Any]]:
+    if "operator" not in condition:
+        msg = f"'operator' key missing in {condition}"
+        raise FilterError(msg)
+    if "conditions" not in condition:
+        msg = f"'conditions' key missing in {condition}"
+        raise FilterError(msg)
+
+    operator = condition["operator"]
+    if operator not in ("AND", "OR", "NOT"):
+        msg = f"Unknown logical operator '{operator}'. Valid operators are: 'AND', 'OR', 'NOT'"
+        raise FilterError(msg)
+
+    parts, all_params = [], []
+    for c in condition["conditions"]:
+        if "field" in c:
+            clause, vals = _parse_comparison_condition(c)
+        else:
+            clause, vals = _parse_logical_condition(c)
+        parts.append(clause)
+        all_params.extend(vals)
+
+    if operator == "NOT":
+        inner = parts[0] if len(parts) == 1 else "(" + " AND ".join(parts) + ")"
+        return f"COALESCE(NOT {inner}, TRUE)", all_params
+
+    joined = f" {operator} ".join(parts)
+    return f"({joined})", all_params
+
+
+def _parse_comparison_condition(condition: dict[str, Any]) -> tuple[str, list[Any]]:
+    field: str = condition["field"]
+    if "operator" not in condition:
+        msg = f"'operator' key missing in {condition}"
+        raise FilterError(msg)
+    if "value" not in condition:
+        msg = f"'value' key missing in {condition}"
+        raise FilterError(msg)
+
+    operator: str = condition["operator"]
+    if operator not in COMPARISON_OPERATORS:
+        msg = f"Unknown comparison operator '{operator}'. Valid operators are: {list(COMPARISON_OPERATORS.keys())}"
+        raise FilterError(msg)
+
+    value: Any = condition["value"]
+    # MariaDB stores JSON booleans as the literals 'true'/'false'; convert before comparison.
+    if isinstance(value, bool):
+        value = "true" if value else "false"
+    sql_field = _build_field_expr(field, value)
+    clause, val = COMPARISON_OPERATORS[operator](sql_field, value)
+    # _in/_not_in return the value list directly; flatten it so params stay flat
+    if isinstance(val, list):
+        return clause, val
+    return clause, [val]
+
+
+_SAFE_FIELD_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_.]*$")
+
+
+def _build_field_expr(field: str, value: Any) -> str:
+    """Return a safe SQL expression for a document field or meta JSON path."""
+    if field.startswith("meta."):
+        field_name = field.split(".", 1)[1]
+        if not _SAFE_FIELD_RE.match(field_name):
+            msg = f"Invalid meta field name: '{field_name}'"
+            raise FilterError(msg)
+        # JSON_UNQUOTE(JSON_EXTRACT(meta, '$.field')) returns the value as a string.
+        # Cast to numeric types when the comparison value is numeric.
+        base = f"JSON_UNQUOTE(JSON_EXTRACT(meta, '$.{field_name}'))"
+        if isinstance(value, int):
+            return f"CAST({base} AS SIGNED)"
+        if isinstance(value, float):
+            return f"CAST({base} AS DECIMAL(65,30))"
+        if isinstance(value, list) and value:
+            first = value[0]
+            if isinstance(first, int) and not isinstance(first, bool):
+                return f"CAST({base} AS SIGNED)"
+            if isinstance(first, float):
+                return f"CAST({base} AS DECIMAL(65,30))"
+        return base
+    # Top-level document field (id, content, etc.) — backtick-quoted
+    return f"`{field}`"
+
+
+def _equal(field: str, value: Any) -> tuple[str, Any]:
+    if value is None:
+        return f"{field} IS NULL", NO_VALUE
+    return f"{field} = ?", value
+
+
+def _not_equal(field: str, value: Any) -> tuple[str, Any]:
+    if value is None:
+        return f"{field} IS NOT NULL", NO_VALUE
+    return f"({field} IS NULL OR {field} != ?)", value
+
+
+def _greater_than(field: str, value: Any) -> tuple[str, Any]:
+    _check_comparable(value, ">")
+    return f"{field} > ?", value
+
+
+def _greater_than_equal(field: str, value: Any) -> tuple[str, Any]:
+    _check_comparable(value, ">=")
+    return f"{field} >= ?", value
+
+
+def _less_than(field: str, value: Any) -> tuple[str, Any]:
+    _check_comparable(value, "<")
+    return f"{field} < ?", value
+
+
+def _less_than_equal(field: str, value: Any) -> tuple[str, Any]:
+    _check_comparable(value, "<=")
+    return f"{field} <= ?", value
+
+
+def _in(field: str, value: Any) -> tuple[str, list]:
+    if not isinstance(value, list):
+        msg = f"'in' operator requires a list value, got {type(value)}"
+        raise FilterError(msg)
+    placeholders = ", ".join(["?"] * len(value))
+    return f"{field} IN ({placeholders})", value
+
+
+def _not_in(field: str, value: Any) -> tuple[str, list]:
+    if not isinstance(value, list):
+        msg = f"'not in' operator requires a list value, got {type(value)}"
+        raise FilterError(msg)
+    placeholders = ", ".join(["?"] * len(value))
+    return f"({field} IS NULL OR {field} NOT IN ({placeholders}))", value
+
+
+def _like(field: str, value: Any) -> tuple[str, Any]:
+    if not isinstance(value, str):
+        msg = f"'like' operator requires a string value, got {type(value)}"
+        raise FilterError(msg)
+    return f"{field} LIKE ?", value
+
+
+def _not_like(field: str, value: Any) -> tuple[str, Any]:
+    if not isinstance(value, str):
+        msg = f"'not like' operator requires a string value, got {type(value)}"
+        raise FilterError(msg)
+    return f"{field} NOT LIKE ?", value
+
+
+def _check_comparable(value: Any, op: str) -> None:
+    if isinstance(value, str):
+        try:
+            datetime.fromisoformat(value)
+        except (ValueError, TypeError) as exc:
+            msg = f"Cannot compare strings with '{op}'. Strings are only comparable if they are ISO formatted dates."
+            raise FilterError(msg) from exc
+    if isinstance(value, list):
+        msg = f"Filter value cannot be a list when using '{op}'"
+        raise FilterError(msg)
+
+
+COMPARISON_OPERATORS = {
+    "==": _equal,
+    "!=": _not_equal,
+    ">": _greater_than,
+    ">=": _greater_than_equal,
+    "<": _less_than,
+    "<=": _less_than_equal,
+    "in": _in,
+    "not in": _not_in,
+    "like": _like,
+    "not like": _not_like,
+}

mariadb_haystack-0.0.1.dist-info/METADATA

@@ -0,0 +1,49 @@
+Metadata-Version: 2.5
+Name: mariadb-haystack
+Version: 0.0.1
+Summary: An integration of MariaDB 11.7+ (native VECTOR support) with Haystack
+Project-URL: Source, https://github.com/deepset-ai/haystack-core-integrations
+Project-URL: Documentation, https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/mariadb/README.md
+Project-URL: Issues, 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
+Classifier: Development Status :: 4 - Beta
+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 :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.10
+Requires-Dist: haystack-ai>=2.28.0
+Requires-Dist: mariadb>=1.1.6
+Description-Content-Type: text/markdown
+
+# mariadb-haystack
+
+[![PyPI - Version](https://img.shields.io/pypi/v/mariadb-haystack.svg)](https://pypi.org/project/mariadb-haystack)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mariadb-haystack.svg)](https://pypi.org/project/mariadb-haystack)
+
+- [Integration page](https://haystack.deepset.ai/integrations/mariadb-documentstore)
+- [Changelog](https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/mariadb/CHANGELOG.md)
+
+---
+
+## Contributing
+
+Refer to the general [Contribution Guidelines](https://github.com/deepset-ai/haystack-core-integrations/blob/main/CONTRIBUTING.md).
+
+The `mariadb` connector is a C extension built from source, so it needs the MariaDB Connector/C system library
+(`mariadb_config`): `sudo apt-get install -y libmariadb-dev` on Ubuntu, or `brew install mariadb-connector-c`
+on macOS.
+
+To run integration tests locally, you need a MariaDB 11.7+ instance running.
+You can start one using Docker:
+
+```console
+docker run -d --name mariadb-haystack -e MARIADB_ROOT_PASSWORD=password -e MARIADB_DATABASE=haystack -p 3306:3306 mariadb:11.7
+```

mariadb_haystack-0.0.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+haystack_integrations/components/retrievers/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+haystack_integrations/components/retrievers/mariadb/__init__.py,sha256=-2LFLFyCYQx1MPNLJbGCZkRRZchy6eL6yN-ylEE1RiA,395
+haystack_integrations/components/retrievers/mariadb/embedding_retriever.py,sha256=LrcQRJrefh5Skz8XqnRMJwkmMQVt3x7Ivf4wXxa1m_c,4644
+haystack_integrations/components/retrievers/mariadb/keyword_retriever.py,sha256=bT3yCOukh1sRBqYO-Mjecm6ynEqsXz8EuXT_0VxRn_0,4077
+haystack_integrations/document_stores/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+haystack_integrations/document_stores/mariadb/__init__.py,sha256=cWSChV85fsrz3lxqycd_tkYB3l81V0YA7CFcmccASCM,241
+haystack_integrations/document_stores/mariadb/document_store.py,sha256=YADg_PzTb9OELiDzMXXtD27nHv8HeegoFRteJYyYkh8,19439
+haystack_integrations/document_stores/mariadb/filters.py,sha256=7peSD0_CHQ9vgEdX4pJrbjuz5YjPfCtvAF7kUZghGz4,7227
+mariadb_haystack-0.0.1.dist-info/METADATA,sha256=bOf9eTRcOFFfdZeiFcyVc8Ruvqm5a9EDwe2vK7u4JqE,2313
+mariadb_haystack-0.0.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+mariadb_haystack-0.0.1.dist-info/licenses/LICENSE.txt,sha256=HutsHrNflRknTSqX9PFpbYgHFaF4cNSB-xYFWp65Zls,10280
+mariadb_haystack-0.0.1.dist-info/RECORD,,

mariadb_haystack-0.0.1.dist-info/WHEEL

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

mariadb_haystack-0.0.1.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,73 @@
+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 passes 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 [yyyy] [name of copyright owner]
+
+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.