Implementation:Guardrails ai Guardrails VectorDBBase

Knowledge Sources	Guardrails
Domains	Vector Database, Embeddings
Last Updated	2026-02-14 00:00 GMT

Overview

Defines the abstract base class for vector database implementations used for similarity search in the Guardrails framework.

Description

The VectorDBBase class is an abstract base class (ABC) that provides a consistent interface for vector storage, retrieval, and similarity search operations. It wraps an EmbeddingBase instance for converting text to vectors and supports the following operations:

• add_vectors (abstract) -- Adds a list of raw float vectors to the store.
• add_texts -- Convenience method that embeds a list of text strings using the embedder and then adds the resulting vectors via add_vectors.
• similarity_search_vector (abstract) -- Searches for the k most similar vectors given a raw vector.
• similarity_search_vector_with_threshold (abstract) -- Searches for the k most similar vectors above a minimum similarity threshold.
• similarity_search -- Convenience method that embeds a text query and delegates to similarity_search_vector.
• similarity_search_with_threshold -- Convenience method that embeds a text query and delegates to similarity_search_vector_with_threshold.
• save (abstract) -- Persists the vector database to a given path.
• load (classmethod) -- Loads a vector database from a given path.
• last_index (abstract) -- Returns the total number of vectors in the database.

All search methods return lists of integer indices referring to positions in the vector store.

Usage

Use VectorDBBase as the interface when building or consuming vector database backends within Guardrails. Concrete implementations (such as Faiss) must implement all abstract methods. Use the text-based convenience methods (similarity_search, add_texts) for common workflows, and the vector-based methods for fine-grained control.

Code Reference

Source Location

• Repository: Guardrails
• File: guardrails/vectordb/base.py

Signature

class VectorDBBase(ABC):
    def __init__(
        self,
        embedder: EmbeddingBase,
        path: Optional[str] = None,
    ) -> None: ...

    @abstractmethod
    def add_vectors(self, vectors: List[List[float]]) -> None: ...

    @abstractmethod
    def similarity_search_vector(self, vector: List[float], k: int) -> List[int]: ...

    @abstractmethod
    def similarity_search_vector_with_threshold(
        self, vector: List[float], k: int, threshold: float
    ) -> List[int]: ...

    def similarity_search(self, text: str, k: int) -> List[int]: ...

    def similarity_search_with_threshold(
        self, text: str, k: int, threshold: float
    ) -> List[int]: ...

    def add_texts(
        self, texts: List[str], ids: Optional[List[Any]] = None
    ) -> None: ...

    @abstractmethod
    def save(self, path: Optional[str] = None): ...

    @classmethod
    def load(cls, path: str): ...

    @abstractmethod
    def last_index(self) -> int: ...

Import

from guardrails.vectordb.base import VectorDBBase

I/O Contract

__init__

Parameter	Type	Description
embedder	EmbeddingBase	An embedding model instance used to convert text to vectors
path	Optional[str]	Optional file path for persisting or loading the vector database

add_vectors

Parameter	Type	Description
vectors	List[List[float]]	A list of float vectors to add to the store

Returns: None

similarity_search_vector

Parameter	Type	Description
vector	List[float]	The query vector
k	int	Number of nearest neighbors to return

Returns: List[int] -- Indices of the k most similar vectors.

similarity_search_vector_with_threshold

Parameter	Type	Description
vector	List[float]	The query vector
k	int	Maximum number of results to return
threshold	float	Minimum similarity threshold

Returns: List[int] -- Indices of similar vectors meeting the threshold.

similarity_search

Parameter	Type	Description
text	str	The query text to search for
k	int	Number of nearest neighbors to return

Returns: List[int] -- Indices of the k most similar vectors.

add_texts

Parameter	Type	Description
texts	List[str]	List of text strings to embed and add
ids	Optional[List[Any]]	Optional list of IDs to associate with the texts

Returns: None

last_index

Returns: int -- The total number of vectors (last index) in the database.

Usage Examples

from guardrails.vectordb.base import VectorDBBase
from guardrails.embedding import EmbeddingBase

# VectorDBBase is abstract; use a concrete subclass like Faiss
# This example shows the interface pattern:

class MyVectorDB(VectorDBBase):
    def add_vectors(self, vectors):
        # Store vectors
        pass

    def similarity_search_vector(self, vector, k):
        # Return k nearest neighbor indices
        return [0, 1, 2][:k]

    def similarity_search_vector_with_threshold(self, vector, k, threshold):
        # Return indices above threshold
        return [0, 1][:k]

    def save(self, path=None):
        pass

    def last_index(self):
        return 0

# Usage with text-based convenience methods
embedder = ...  # an EmbeddingBase instance
db = MyVectorDB(embedder=embedder)
db.add_texts(["Hello world", "Guardrails AI", "Vector search"])
results = db.similarity_search("search query", k=2)
print(results)  # [index1, index2]

Related Pages

• Implementation:Guardrails_ai_Guardrails_Faiss -- Concrete implementation using Facebook's FAISS library
• Guardrails_ai_Guardrails_EmbeddingBase -- The embedding interface used by VectorDBBase