API Reference

Classes

class darca_vector_db.BaseDBClient[source]

Bases: ABC

Abstract base class for vector database clients.

This class defines a standardized interface for all vector database clients. It enforces implementation of essential methods for connecting to a vector database, creating collections, inserting vectors, and performing vector searches.

connect() → None[source]

Establishes a connection to the vector database.

create_collection()[source]

(name: str, vector_size: int, distance_metric: str) -> None Creates a new collection in the vector database.

insert_vector(collection_name: str, vector_id: str, vector: List[float],

metadata: Optional[Dict[str, Any]]) -> None Inserts a vector into a specified collection.

search_vectors(collection_name: str, query_vector:

List[float], top_k: int) -> Any Searches for similar vectors within a collection.

abstractmethod connect() → None[source]

Establishes a connection to the vector database.

This method should be implemented by subclasses to establish a connection to the underlying vector database system.

Raises:

NotImplementedError – If the method is not implemented by the subclass.

abstractmethod create_collection(name: str, vector_size: int, distance_metric: str) → None[source]

Creates a new collection in the vector database.

This method defines the creation of a new collection within the vector database. A collection is a logical grouping of vectors with a specified size and distance metric.

Parameters:

  • name (str) – The name of the collection to create. Must be unique within the database.

  • vector_size (int) – The size (dimensionality) of the vectors to be stored in the collection.

  • distance_metric (str) –

    The distance metric to use for vector comparisons. Typical values include:

    • ’cosine’

    • ’euclidean’

    • ’dot’

Raises:

  • NotImplementedError – If the method is not implemented by the subclass.

  • ValueError – If the specified distance metric is not supported by the backend. Note: Validation for unsupported distance metrics must be implemented by subclasses.

abstractmethod insert_vector(collection_name: str, vector_id: str, vector: List[float], metadata: Dict[str, Any] | None = None) → None[source]

Inserts a vector into a specified collection.

This method adds a single vector, identified by a unique ID, to an existing collection. Optionally, metadata can be associated with the vector for additional information.

Parameters:

  • collection_name (str) – The name of the collection where the vector will be stored.

  • vector_id (str) – A unique identifier for the vector. It must be unique within the collection.

  • vector (List[float]) – The vector data to be inserted. The length of the list should match the collection’s vector size.

  • metadata (dict, optional) – A dictionary of metadata to associate with the vector. Defaults to None.

Raises:

  • NotImplementedError – If the method is not implemented by the subclass.

  • ValueError – If the vector size does not match the expected collection vector size.

abstractmethod search_vectors(collection_name: str, query_vector: List[float], top_k: int = 10) → Any[source]

Searches for similar vectors within a collection.

This method performs a similarity search against a specified collection, returning the most similar vectors to a given query vector.

Parameters:

  • collection_name (str) – The name of the collection to search within.

  • query_vector (List[float]) – The query vector used to perform the search. The length must match the collection’s vector size.

  • top_k (int, optional) – The number of most similar vectors to return. Defaults to 10.

Returns:

The search results as returned by the underlying vector database implementation. The format of the results may vary depending on the backend.

Return type:

Any

Raises:

  • NotImplementedError – If the method is not implemented by the subclass.

  • ValueError – If the query vector size does not match the expected collection vector size.

class darca_vector_db.QdrantDBClient(host: str = 'localhost', port: int = 6333, api_key: str | None = None)[source]

Bases: BaseDBClient

Implementation of the BaseDBClient for the Qdrant vector database.

Parameters:

  • host (str) – Host address of the Qdrant server.

  • port (int) – Port number for the Qdrant server.

  • api_key (str, optional) – API key for authentication.

connect() → None[source]

Establishes a connection to the Qdrant server.

create_collection(name: str, vector_size: int, distance_metric: str = 'cosine') → None[source]

Creates a collection in Qdrant.

insert_vector(collection_name: str, vector_id: int, vector: List[float], metadata: Dict[str, Any] | None = None) → None[source]

Inserts a vector into the Qdrant collection.

search_vectors(collection_name: str, query_vector: List[float], top_k: int = 10) → Any[source]

Searches for similar vectors within the Qdrant collection.

class darca_vector_db.DBClient(backend: str = 'qdrant', **kwargs)[source]

Bases: object

A unified client for interacting with vector databases.

Parameters:

  • backend (str) – The backend to use (default: ‘qdrant’).

  • kwargs (dict) – Additional parameters for backend initialization.

connect() → None[source]

Establishes a connection to the vector database.

create_collection(name: str, vector_size: int, distance_metric: str = 'cosine') → None[source]

Creates a new collection in the vector database.

Parameters:

  • name (str) – The name of the collection to create.

  • vector_size (int) – The size of the vectors to be stored in the collection.

  • distance_metric (str) – The distance metric to use for vector comparisons (default: ‘cosine’).

Raises:

  • ValueError – If the distance metric is not supported.

  • CollectionCreationError – If the collection creation fails.

insert_vector(collection_name: str, vector_id: str, vector: List[float], metadata: Dict[str, Any] | None = None) → None[source]

Inserts a vector into the specified collection. :param collection_name: The name of the collection to insert the vector into. :type collection_name: str :param vector_id: The unique ID for the vector. :type vector_id: str :param vector: The vector data to insert. :type vector: list[float] :param metadata: Additional metadata to associate with the vector. :type metadata: dict, optional :param Raises: :param VectorInsertionError: If the vector insertion fails.

search_vectors(collection_name: str, query_vector: List[float], top_k: int = 10) → Any[source]

Searches for similar vectors in the specified collection. :param collection_name: The name of the collection to search. :type collection_name: str :param query_vector: The vector to search for. :type query_vector: list[float] :param top_k: The number of similar vectors to return (default: 10). :type top_k: int

Returns:

  • Any – The search results.

  • Raises

  • VectorSearchError – If the vector search fails.

Exceptions

class darca_vector_db.DBClientException(message: str, error_code: str, metadata: Dict[str, Any] | None = None)[source]

Bases: DarcaException

Base exception class for all errors related to vector database operations.

Attributes:

message (str): Description of the error. error_code (str): A unique code representing the error type. metadata (dict): Additional information related to the error.

add_note()

Exception.add_note(note) – add a note to the exception

args
log_exception()

Logs the exception details using DarcaLogger. Always logs as an error because exceptions indicate failure.

to_dict()

Convert exception details to a dictionary.

Returns:

Dictionary representation of the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class darca_vector_db.DBConnectionError(message: str, error_code: str, metadata: Dict[str, Any] | None = None)[source]

Bases: DBClientException

Raised when a connection attempt to the vector database fails.

add_note()

Exception.add_note(note) – add a note to the exception

args
log_exception()

Logs the exception details using DarcaLogger. Always logs as an error because exceptions indicate failure.

to_dict()

Convert exception details to a dictionary.

Returns:

Dictionary representation of the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class darca_vector_db.CollectionCreationError(message: str, error_code: str, metadata: Dict[str, Any] | None = None)[source]

Bases: DBClientException

Raised when the creation of a collection in the vector database fails.

add_note()

Exception.add_note(note) – add a note to the exception

args
log_exception()

Logs the exception details using DarcaLogger. Always logs as an error because exceptions indicate failure.

to_dict()

Convert exception details to a dictionary.

Returns:

Dictionary representation of the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class darca_vector_db.VectorInsertionError(message: str, error_code: str, metadata: Dict[str, Any] | None = None)[source]

Bases: DBClientException

Raised when inserting a vector into a collection fails.

add_note()

Exception.add_note(note) – add a note to the exception

args
log_exception()

Logs the exception details using DarcaLogger. Always logs as an error because exceptions indicate failure.

to_dict()

Convert exception details to a dictionary.

Returns:

Dictionary representation of the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class darca_vector_db.VectorSearchError(message: str, error_code: str, metadata: Dict[str, Any] | None = None)[source]

Bases: DBClientException

Raised when searching for vectors within a collection fails.

add_note()

Exception.add_note(note) – add a note to the exception

args
log_exception()

Logs the exception details using DarcaLogger. Always logs as an error because exceptions indicate failure.

to_dict()

Convert exception details to a dictionary.

Returns:

Dictionary representation of the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.