ZerdaZerda

Quickstart

On this page

This walks through the smallest working example for each backend, using only APIs that exist in the source.

FAISS (fully local, no accounts)

Python · 21 lines
from zerda.embeddings import OpenAIEmbedder
from zerda.vector_database import FAISSVectorDatabase
from zerda.chunks import DocumentChunk  # wherever DocumentChunk lives in your project

embedder = OpenAIEmbedder()

db = FAISSVectorDatabase(
    embedder=embedder,
    index_type="flat",       # 'flat' | 'ivf' | 'hnsw'
    distance_metric="cosine" # 'cosine' | 'l2' | 'ip'
)

chunk = DocumentChunk(chunk_id="c1", doc_id="d1", text="Machine learning is fascinating")
db.add_chunk(chunk)

results = db.search("AI technology", top_k=5)
for chunk, score in results:
    print(f"{score:.3f}  {chunk.text[:60]}")

print(db.get_stats())
print(len(db))

Chroma (local or persistent, no accounts)

Python · 10 lines
from zerda.vector_database import ChromaVectorDatabase

db = ChromaVectorDatabase(
    embedder=embedder,
    collection_name="my_documents",
    persist_directory="./chroma_db",   # omit for in-memory only
)

db.add([chunk])                         # unified DocumentChunk-list style
results = db.search("AI technology", top_k=5)

[!NOTE] Two calling styles ChromaVectorDatabase.add() also accepts a legacy explicit-arguments style (ids=, documents=, metadatas=) for backward compatibility. See ChromaVectorDatabase.add — and the caveat about a bug in that code path in Troubleshooting.

Pinecone (managed cloud)

Python · 19 lines
import os
os.environ["PINECONE_API_KEY"] = "your-api-key"

from zerda.vector_database import PineconeVectorDatabase

db = PineconeVectorDatabase(
    embedder=embedder,
    index_name="my-index",
    environment="us-east-1",
    distance_metric="cosine",
)

db.add_chunk(chunk)

results = db.search(
    query="AI technology",
    top_k=5,
    filter_dict={"category": "tech"},
)

The common contract

All three classes implement the same five mandatory methods from VectorDatabaseBase, so code written against the base contract works unmodified across backends:

Python · 5 lines
def add(chunks, embeddings=None) -> None: ...
def search(query, top_k=5, score_threshold=None, **kwargs) -> list[tuple[DocumentChunk, float]]: ...
def remove_by_doc_id(doc_id) -> int: ...
def get_stats() -> dict: ...
def __len__() -> int: ...

Each backend also exposes extra, backend-specific methods (add_chunk, search_by_doc_id, delete_by_ids, namespaces, batching context managers, and so on) — see the per-class API reference pages for the full picture.

Next steps

Related pages