Usage Guide

This document explains in detail how to use the darca-vector-db library, including setup, configuration, and using the provided API to interact with vector databases.

Installation

The recommended way to install darca-vector-db is via Poetry.

1. Clone the repository: .. code-block:: bash

   git clone https://github.com/roelkist/darca-vector-db.git cd darca-vector-db

2. Create a virtual environment and install dependencies: .. code-block:: bash

   make venv make poetry make install

Basic Usage

The darca-vector-db library provides a simple interface to interact with a vector database. The backend currently supported is Qdrant.

Importing the Library

You can import the necessary components from the package as follows:

from darca_vector_db import DBClient, DBClientException

Creating a Client

To create a client for interacting with a Qdrant vector database:

client = DBClient(backend="qdrant", host="localhost", port=6333)
client.connect()

The DBClient class acts as a unified interface for interacting with different vector databases.

Creating a Collection

To create a collection in the Qdrant database, use the create_collection method:

client.create_collection(
    name="my_vectors",
    vector_size=128,
    distance_metric="cosine"
)

Parameters: - name: The name of the collection to create. - vector_size: The size of the vectors to be stored in the collection. - distance_metric: The distance metric to use for comparisons. Supported values: cosine, euclidean, dot.

Inserting Vectors

To insert a vector into a collection:

client.insert_vector(
    collection_name="my_vectors",
    vector_id=1,  # Must be an integer
    vector=[0.1] * 128,  # A valid vector of size 128
    metadata={"label": "example"}
)

Parameters: - collection_name: Name of the collection to insert the vector into. - vector_id: Unique identifier for the vector. Must be an integer. - vector: The actual vector data (list of floats) of size vector_size. - metadata: Optional dictionary of metadata associated with the vector.

Searching for Vectors

To search for similar vectors within a collection:

results = client.search_vectors(
    collection_name="my_vectors",
    query_vector=[0.1] * 128,  # A valid query vector of size 128
    top_k=5
)
print(results)

Parameters: - collection_name: Name of the collection to search within. - query_vector: The vector to search for. Must match the collection’s vector_size. - top_k: The number of most similar vectors to return.

Error Handling

All errors related to vector database operations are raised as subclasses of DBClientException.

Example:

try:
    client.connect()
except DBClientException as e:
    print(f"An error occurred: {e.message}")

Custom Exceptions Provided: - DBClientException: Base exception for all vector database errors. - DBConnectionError: Raised when the connection to the database fails. - CollectionCreationError: Raised when collection creation fails. - VectorInsertionError: Raised when vector insertion fails. - VectorSearchError: Raised when vector searching fails.