MariaDBEmbeddingRetriever

An embedding-based Retriever compatible with the MariaDB Document Store.

Most common position in a pipeline	1. After a Text Embedder and before a PromptBuilder in a RAG pipeline 2. The last component in a semantic search pipeline 3. After a Text Embedder and before a TransformersExtractiveReader in an extractive QA pipeline
Mandatory init variables	document_store: An instance of a MariaDBDocumentStore
Mandatory run variables	query_embedding: A vector representing the query (a list of floats)
Output variables	documents: A list of documents
API reference	MariaDB
GitHub link	https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mariadb

Overview

The MariaDBEmbeddingRetriever is an embedding-based Retriever compatible with the MariaDBDocumentStore. It compares the query and Document embeddings and fetches the Documents most relevant to the query using MariaDB's native MHNSW vector index.

When using the MariaDBEmbeddingRetriever in your Pipeline, make sure embeddings are available. Add a Document Embedder to your indexing Pipeline and a Text Embedder to your query Pipeline.

In addition to query_embedding, the Retriever accepts optional parameters including top_k (the maximum number of Documents to retrieve) and filters to narrow down the search space.

Vector index

For fast approximate nearest neighbor search, the MariaDBDocumentStore must be initialized with create_vector_index=True. This creates a MHNSW index at table creation time, but requires every document to have a non-null embedding. The embedding_dimension and distance parameters also only take effect at table creation (or with recreate_table=True).

Installation

To quickly set up a MariaDB 11.7 instance, you can use Docker:

shell

docker run -d -p 3306:3306 \
  -e MARIADB_ROOT_PASSWORD=secret \
  -e MARIADB_DATABASE=haystack \
  -e MARIADB_USER=haystack \
  -e MARIADB_PASSWORD=secret \
  mariadb:11.7

Install the system library and the integration:

shell

# Ubuntu / Debian
sudo apt-get install -y libmariadb-dev

pip install mariadb-haystack

The pipeline example below also uses the Sentence Transformers embedders:

shell

pip install sentence-transformers-haystack

Usage

On its own

python

import os
from haystack_integrations.document_stores.mariadb import MariaDBDocumentStore
from haystack_integrations.components.retrievers.mariadb import (
    MariaDBEmbeddingRetriever,
)

os.environ["MARIADB_USER"] = "haystack"
os.environ["MARIADB_PASSWORD"] = "secret"

document_store = MariaDBDocumentStore(embedding_dimension=768)
retriever = MariaDBEmbeddingRetriever(document_store=document_store)

# using a fake vector to keep the example simple
retriever.run(query_embedding=[0.1] * 768)

In a Pipeline

python

import os
from haystack import Document, Pipeline
from haystack_integrations.components.embedders.sentence_transformers import (
    SentenceTransformersTextEmbedder,
    SentenceTransformersDocumentEmbedder,
)
from haystack.document_stores.types import DuplicatePolicy

from haystack_integrations.document_stores.mariadb import MariaDBDocumentStore
from haystack_integrations.components.retrievers.mariadb import (
    MariaDBEmbeddingRetriever,
)

os.environ["MARIADB_USER"] = "haystack"
os.environ["MARIADB_PASSWORD"] = "secret"

document_store = MariaDBDocumentStore(
    embedding_dimension=768,
    distance="cosine",
)

documents = [
    Document(content="There are over 7,000 languages spoken around the world today."),
    Document(
        content="Elephants have been observed to recognize themselves in mirrors."
    ),
    Document(
        content="Bioluminescent waves can be seen in the Maldives and Puerto Rico."
    ),
]

document_embedder = SentenceTransformersDocumentEmbedder()
documents_with_embeddings = document_embedder.run(documents)

document_store.write_documents(
    documents_with_embeddings.get("documents"),
    policy=DuplicatePolicy.OVERWRITE,
)

query_pipeline = Pipeline()
query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder())
query_pipeline.add_component(
    "retriever",
    MariaDBEmbeddingRetriever(document_store=document_store),
)
query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")

result = query_pipeline.run(
    {"text_embedder": {"text": "How many languages are there?"}}
)
print(result["retriever"]["documents"][0])