Skip to main content
Version: 2.29

ArcadeDB

haystack_integrations.components.retrievers.arcadedb.embedding_retriever​

ArcadeDBEmbeddingRetriever​

Retrieve documents from ArcadeDB using vector similarity (LSM_VECTOR / HNSW index).

Usage example:

python
from haystack import Document

# Requires: pip install sentence-transformers-haystack
from haystack_integrations.components.embedders.sentence_transformers import (
    SentenceTransformersTextEmbedder,
)
from haystack_integrations.components.retrievers.arcadedb import (
    ArcadeDBEmbeddingRetriever,
)
from haystack_integrations.document_stores.arcadedb import ArcadeDBDocumentStore

store = ArcadeDBDocumentStore(database="mydb")
retriever = ArcadeDBEmbeddingRetriever(document_store=store, top_k=5)

# Add documents to DocumentStore
documents = [
    Document(text="My name is Carla and I live in Berlin"),
    Document(text="My name is Paul and I live in New York"),
    Document(text="My name is Silvano and I live in Matera"),
    Document(text="My name is Usagi Tsukino and I live in Tokyo"),
]
document_store.write_documents(documents)

embedder = SentenceTransformersTextEmbedder()
query_embeddings = embedder.run("Who lives in Berlin?")["embedding"]

result = retriever.run(query=query_embeddings)
for doc in result["documents"]:
    print(doc.content)

init​

python
__init__(
    *,
    document_store: ArcadeDBDocumentStore,
    filters: dict[str, Any] | None = None,
    top_k: int = 10,
    filter_policy: FilterPolicy = FilterPolicy.REPLACE
) -> None

Create an ArcadeDBEmbeddingRetriever.

Parameters:

  • document_store (ArcadeDBDocumentStore) – An instance of ArcadeDBDocumentStore.
  • filters (dict[str, Any] | None) – Default filters applied to every retrieval call.
  • top_k (int) – Maximum number of documents to return.
  • filter_policy (FilterPolicy) – How runtime filters interact with default filters.

run​

python
run(
    query_embedding: list[float],
    filters: dict[str, Any] | None = None,
    top_k: int | None = None,
) -> dict[str, list[Document]]

Retrieve documents by vector similarity.

Parameters:

  • query_embedding (list[float]) – The embedding vector to search with.
  • filters (dict[str, Any] | None) – Optional filters to narrow results.
  • top_k (int | None) – Maximum number of documents to return.

Returns:

  • dict[str, list[Document]] – A dictionary with the following keys:
  • documents: List of Documents most similar to the given query_embedding

to_dict​

python
to_dict() -> dict[str, Any]

Serializes the component to a dictionary.

Returns:

  • dict[str, Any] – Dictionary with serialized data.

close​

python
close() -> None

Release the synchronous resources of the underlying Document Store.

from_dict​

python
from_dict(data: dict[str, Any]) -> ArcadeDBEmbeddingRetriever

Deserializes the component from a dictionary.

Parameters:

  • data (dict[str, Any]) – Dictionary to deserialize from.

Returns:

  • ArcadeDBEmbeddingRetriever – Deserialized component.

haystack_integrations.document_stores.arcadedb.document_store​

ArcadeDB DocumentStore for Haystack 2.x — document storage + vector search via HTTP/JSON API.

ArcadeDBDocumentStore​

An ArcadeDB-backed DocumentStore for Haystack 2.x.

Uses ArcadeDB's HTTP/JSON API for all operations — no special drivers required. Supports HNSW vector search (LSM_VECTOR) and SQL metadata filtering.

Usage example:

python
from haystack.dataclasses.document import Document
from haystack_integrations.document_stores.arcadedb import ArcadeDBDocumentStore

document_store = ArcadeDBDocumentStore(
    url="http://localhost:2480",
    database="haystack",
    embedding_dimension=768,
)
document_store.write_documents([
    Document(content="This is first", embedding=[0.0]*5),
    Document(content="This is second", embedding=[0.1, 0.2, 0.3, 0.4, 0.5])
])

init​

python
__init__(
    *,
    url: str = "http://localhost:2480",
    database: str = "haystack",
    username: Secret = Secret.from_env_var("ARCADEDB_USERNAME", strict=False),
    password: Secret = Secret.from_env_var("ARCADEDB_PASSWORD", strict=False),
    type_name: str = "Document",
    embedding_dimension: int = 768,
    similarity_function: str = "cosine",
    recreate_type: bool = False,
    create_database: bool = True
) -> None

Create an ArcadeDBDocumentStore instance.

Parameters:

  • url (str) – ArcadeDB HTTP endpoint.
  • database (str) – Database name.
  • username (Secret) – HTTP Basic Auth username (default: ARCADEDB_USERNAME env var).
  • password (Secret) – HTTP Basic Auth password (default: ARCADEDB_PASSWORD env var).
  • type_name (str) – Vertex type name for documents.
  • embedding_dimension (int) – Vector dimension for the HNSW index.
  • similarity_function (str) – Distance metric — "cosine", "euclidean", or "dot".
  • recreate_type (bool) – If True, drop and recreate the type on initialization.
  • create_database (bool) – If True, create the database if it doesn't exist.

to_dict​

python
to_dict() -> dict[str, Any]

Serializes the DocumentStore to a dictionary.

Returns:

  • dict[str, Any] – Dictionary with serialized data.

from_dict​

python
from_dict(data: dict[str, Any]) -> ArcadeDBDocumentStore

Deserializes the DocumentStore from a dictionary.

Parameters:

  • data (dict[str, Any]) – The dictionary to deserialize from.

Returns:

  • ArcadeDBDocumentStore – The deserialized DocumentStore.

close​

python
close() -> None

Release the associated synchronous resources.

count_documents​

python
count_documents() -> int

Returns how many documents are present in the document store.

Returns:

  • int – Number of documents in the document store.

filter_documents​

python
filter_documents(filters: dict[str, Any] | None = None) -> list[Document]

Return documents matching the given filters.

Parameters:

  • filters (dict[str, Any] | None) – Haystack filter dictionary.

Returns:

  • list[Document] – List of matching documents.

write_documents​

python
write_documents(
    documents: list[Document], policy: DuplicatePolicy = DuplicatePolicy.NONE
) -> int

Write documents to the store.

Parameters:

  • documents (list[Document]) – List of Haystack Documents to write.
  • policy (DuplicatePolicy) – How to handle duplicate document IDs.

Returns:

  • int – Number of documents written.

delete_documents​

python
delete_documents(document_ids: list[str]) -> None

Delete documents by their IDs.

Parameters:

  • document_ids (list[str]) – List of document IDs to delete.

delete_all_documents​

python
delete_all_documents() -> None

Deletes all documents in the document store.

delete_by_filter​

python
delete_by_filter(filters: dict[str, Any]) -> int

Deletes all documents that match the provided filters.

Parameters:

  • filters (dict[str, Any]) – The filters to apply to select documents for deletion. For filter syntax, see Haystack metadata filtering

Returns:

  • int – The number of documents deleted.

update_by_filter​

python
update_by_filter(filters: dict[str, Any], meta: dict[str, Any]) -> int

Updates the metadata of all documents that match the provided filters.

Parameters:

  • filters (dict[str, Any]) – The filters to apply to select documents for updating. For filter syntax, see Haystack metadata filtering
  • meta (dict[str, Any]) – The metadata fields to update.

Returns:

  • int – The number of documents updated.

count_documents_by_filter​

python
count_documents_by_filter(filters: dict[str, Any]) -> int

Counts the number of documents matching the provided filter

Parameters:

  • filters (dict[str, Any]) – The filters to apply to the documents

Returns:

  • int – The number of documents that match the filter

count_unique_metadata_by_filter​

python
count_unique_metadata_by_filter(
    filters: dict[str, Any], metadata_fields: list[str]
) -> dict[str, int]

Counts unique values for each metadata field in documents matching the provided filters.

Parameters:

  • filters (dict[str, Any]) – The filters to apply to the document list.
  • metadata_fields (list[str]) – Metadata fields for which to count unique values.

Returns:

  • dict[str, int] – A dictionary where keys are metadata field names and values are the counts of unique values for that field.

get_metadata_fields_info​

python
get_metadata_fields_info() -> dict[str, dict[str, str]]

Returns the metadata fields and their corresponding types based on sampled documents.

Returns:

  • dict[str, dict[str, str]] – A dictionary mapping field names to dictionaries with a type key.

get_metadata_field_min_max​

python
get_metadata_field_min_max(metadata_field: str) -> dict[str, Any]

For a given metadata field, finds its min and max values.

Parameters:

  • metadata_field (str) – The metadata field to inspect.

Returns:

  • dict[str, Any] – A dictionary with min and max keys and their corresponding values.

get_metadata_field_unique_values​

python
get_metadata_field_unique_values(
    metadata_field: str,
    search_term: str | None = None,
    from_: int = 0,
    size: int = 10,
    filters: dict[str, Any] | None = None,
) -> tuple[list[Any], int]

Retrieves unique values for a field matching a search term or all possible values if no search term is given.

Note: values of different types are kept distinct even when they compare equal in Python, so the int 1, the float 1.0, the bool True and the str "1" are returned as four separate values.

Parameters:

  • metadata_field (str) – The metadata field to inspect.
  • search_term (str | None) – Optional case-insensitive substring search term.
  • from_ (int) – The starting index for pagination.
  • size (int) – The number of values to return.
  • filters (dict[str, Any] | None) – Optional filters to restrict the documents considered.

Returns:

  • tuple[list[Any], int] – A tuple containing the paginated values (in their original type) and the total count.