Skip to main content
Version: 3.2

IBM Db2

haystack_integrations.components.retrievers.ibm_db.embedding_retriever​

IBMDb2EmbeddingRetriever​

Retrieves documents from a IBMDb2DocumentStore using vector similarity.

Use inside a Haystack pipeline after a text embedder:

python
pipeline.add_component("embedder", SentenceTransformersTextEmbedder())
pipeline.add_component("retriever", IBMDb2EmbeddingRetriever(
    document_store=store, top_k=5
))
pipeline.connect("embedder.embedding", "retriever.query_embedding")

init​

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

Initialize the IBMDb2EmbeddingRetriever.

Parameters:

  • document_store (IBMDb2DocumentStore) – An instance of IBMDb2DocumentStore.
  • filters (dict[str, Any] | None) – Filters applied to the retrieved Documents.
  • top_k (int) – Maximum number of Documents to return.
  • filter_policy (FilterPolicy) – Policy to determine how filters are applied.

Raises:

  • TypeError – If document_store is not an instance of IBMDb2DocumentStore.

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]) – Dense float vector from an embedder component.
  • filters (dict[str, Any] | None) – Runtime filters, merged with constructor filters according to filter_policy.
  • top_k (int | None) – Override the constructor top_k for this call.

Returns:

  • dict[str, list[Document]] – A dictionary with key documents containing a list of matching :class:Document objects.

close​

python
close() -> None

Release the synchronous resources of the underlying Document Store.

to_dict​

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

Serializes the component to a dictionary.

Returns:

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

from_dict​

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

Deserializes the component from a dictionary.

Parameters:

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

Returns:

  • IBMDb2EmbeddingRetriever – Deserialized component.

haystack_integrations.document_stores.ibm_db.document_store​

IBM Db2 Document Store for Haystack.

IBMDb2DocumentStore​

IBM Db2 Document Store for Haystack using vector search capabilities.

This document store uses IBM Db2's native vector search functionality to store and retrieve documents with embeddings.

init​

python
__init__(
    *,
    database: str,
    hostname: str,
    username: Secret = Secret.from_env_var("DB2_USERNAME"),
    password: Secret = Secret.from_env_var("DB2_PASSWORD"),
    port: int = 50000,
    protocol: str = "TCPIP",
    schema: str | None = None,
    use_ssl: bool = False,
    ssl_certificate: str | None = None,
    connection_options: dict[str, Any] | None = None,
    table_name: str = "haystack_documents",
    embedding_dim: int = 768,
    distance_metric: Literal["EUCLIDEAN", "COSINE", "MANHATTAN"] = "COSINE",
    recreate_table: bool = False
)

Initialize the IBM Db2 Document Store.

Parameters:

  • database (str) – Database name
  • hostname (str) – Database server hostname
  • username (Secret) – Database username as a Secret, e.g. Secret.from_env_var("DB2_USERNAME").
  • password (Secret) – Database password as a Secret, e.g. Secret.from_env_var("DB2_PASSWORD").
  • port (int) – Database server port (default: 50000)
  • protocol (str) – Connection protocol (default: "TCPIP")
  • schema (str | None) – Database schema (optional)
  • use_ssl (bool) – Enable SSL/TLS connection (default: False)
  • ssl_certificate (str | None) – Path to SSL certificate file (optional, required if use_ssl is True)
  • connection_options (dict[str, Any] | None) – Additional connection options as dict (optional)
  • table_name (str) – Name of the table to store documents (default: "haystack_documents")
  • embedding_dim (int) – Dimension of embedding vectors (default: 768)
  • distance_metric (Literal['EUCLIDEAN', 'COSINE', 'MANHATTAN']) – Distance metric for similarity search (default: "COSINE")
  • recreate_table (bool) – If True, drop and recreate the table (default: False)

close​

python
close() -> None

Release the associated synchronous resources.

count_documents​

python
count_documents() -> int

Count all documents in the store.

Returns:

  • int – Number of documents

count_documents_by_filter​

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

Count documents that match the provided filters.

Parameters:

  • filters (dict[str, Any] | None) – Filters to apply. See Haystack documentation for filter syntax.

Returns:

  • int – Number of documents matching the filters

write_documents​

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

Write documents to the store.

Parameters:

  • documents (list[Document]) – List of documents to write
  • policy (DuplicatePolicy) – Policy for handling duplicate documents

Returns:

  • int – Number of documents written

Raises:

  • ValueError – If documents is not a list of Document objects or has invalid embeddings
  • TypeError – If embeddings have invalid types
  • DuplicateDocumentError – If a document with the same id already exists and policy is FAIL or NONE

filter_documents​

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

Filter documents using SQL-based metadata and field conditions.

Parameters:

  • filters (dict[str, Any] | None) – Optional filter dictionary to constrain the returned documents.

Returns:

  • list[Document] – List of matching documents.

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_by_filter​

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

Delete documents that match the provided filters.

Parameters:

  • filters (dict[str, Any] | None) – Filters to apply. See Haystack documentation for filter syntax.

Returns:

  • int – Number of documents deleted

delete_all_documents​

python
delete_all_documents(recreate_index: bool = False) -> int

Delete all documents from the document store.

Parameters:

  • recreate_index (bool) – If True, recreate the table after deletion

Returns:

  • int – Number of documents deleted

update_by_filter​

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

Update documents that match the provided filters.

Parameters:

  • filters (dict[str, Any] | None) – Filters to apply. See Haystack documentation for filter syntax.
  • meta (dict[str, Any] | None) – Dictionary of metadata fields to update

Returns:

  • int – Number of documents updated

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]

Get unique values for a given metadata field, optionally filtered by a search term.

Note: values of different types are kept distinct even when they compare equal in Python or share a textual form (e.g. the int 1, the bool True and the str "1" are returned as three separate values, and a whole-number float like 1.0 stays distinct from the int 1).

Parameters:

  • metadata_field (str) – The metadata field name (can include or omit the 'meta.' prefix).
  • search_term (str | None) – Optional term to filter the returned values by, matching as a case-insensitive substring of the metadata field's own value (not the document content). If None, all values are considered.
  • from_ (int) – The offset for pagination (0-based).
  • size (int) – The number of unique values to return.
  • filters (dict[str, Any] | None) – Optional filters to restrict the documents considered.

Returns:

  • tuple[list[Any], int] – A tuple containing (list of unique values in their original JSON type, total count of unique values matching search_term).

get_metadata_field_min_max​

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

Get the minimum and maximum values for a numeric metadata field.

Parameters:

  • field (str) – The metadata field name (can include 'meta.' prefix)

Returns:

  • dict[str, Any] – Dictionary with 'min' and 'max' keys

get_metadata_fields_info​

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

Get information about all metadata fields including their types.

Returns:

  • dict[str, dict[str, Any]] – Dictionary mapping field names to their type information

count_unique_metadata_by_filter​

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

Count unique values for specified metadata fields, optionally filtered.

Parameters:

  • filters (dict[str, Any] | None) – Optional filters to apply before counting
  • metadata_fields (list[str] | None) – List of metadata field names to count unique values for

Returns:

  • dict[str, int] – Dictionary mapping field names to their unique value counts

to_dict​

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

Serialize the document store to a dictionary.

Returns:

  • dict[str, Any] – Dictionary representation

from_dict​

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

Deserialize the document store from a dictionary.

Parameters:

  • data (dict[str, Any]) – Dictionary representation

Returns:

  • IBMDb2DocumentStore – IBMDb2DocumentStore instance