VittoriaDB Python SDK

Python client for VittoriaDB — an embedded vector database shipped as a single Go binary. The SDK talks to the server over HTTP: collections, vectors, semantic search, server-side embeddings, document upload, and RAG-friendly content storage. Optional auto-start downloads a matching release binary (when available) and manages the process lifecycle.

Documentation

Features

Backup and restore are not HTTP APIs: use the vittoriadb CLI (backup / restore). Stop the server before restore.

Installation

pip install vittoriadb

On install, the package tries to download a platform binary from GitHub Releases at tag v<sdk-version> (e.g. v0.7.0). If that asset is missing, you’ll see a warning — install the binary manually or put vittoriadb on your PATH.

Quick start

Connect

import vittoriadb

# Managed local server (downloads binary when release exists)
db = vittoriadb.connect()

# Existing server
db = vittoriadb.connect(url="http://localhost:8080", auto_start=False)

db.close()

Vectors and similarity search

collection = db.create_collection(
    name="docs",
    dimensions=384,
    metric="cosine",
)

collection.insert(
    "doc1",
    vector=[0.1] * 384,
    metadata={"title": "Hello", "category": "demo"},
)

results = collection.search(
    vector=[0.1] * 384,
    limit=5,
    filter={"category": "demo"},
    include_metadata=True,
)

# Structured / nested filters: POST search
results = collection.search(
    vector=[0.1] * 384,
    limit=5,
    use_post=True,
    filter={
        "and": [
            {"field": "category", "operator": "eq", "value": "demo"},
        ]
    },
)

Server-side embeddings

from vittoriadb.configure import Configure

collection = db.create_collection(
    name="smart",
    dimensions=384,
    vectorizer_config=Configure.Vectors.auto_embeddings(),
)

collection.insert_text(
    "a1",
    "Your text here.",
    metadata={"source": "wiki"},
)

hits = collection.search_text("your query", limit=5)

Observability

h = db.health()           # HealthStatus
s = db.stats()            # DatabaseStats: queries_total, avg_query_latency, queries_per_sec, …
text = db.prometheus_metrics()  # Prometheus exposition from GET /metrics

IVF index (prototype)

from vittoriadb import IndexType
from vittoriadb.configure import Configure

collection = db.create_collection(
    name="ivf_demo",
    dimensions=64,
    index_type=IndexType.IVF,
    config=Configure.Index.ivf_flat(nlist=16, nprobe=2),
)

RAG and content storage

Enable ContentStorageConfig on create_collection to persist chunk text for retrieval (include_content=True on search_text). See docs/content-storage.md.

from vittoriadb import ContentStorageConfig

collection = db.create_collection(
    name="rag",
    dimensions=384,
    vectorizer_config=Configure.Vectors.auto_embeddings(),
    content_storage=ContentStorageConfig(enabled=True, field_name="_content"),
)

collection.insert_text("id1", "Long passage …", metadata={"title": "Doc"})

for r in collection.search_text("query", limit=3, include_content=True):
    if r.has_content():
        print(r.content)

Vectorizer presets (Configure.Vectors)

Details: docs/embeddings.md.

Index tuning

HNSW — pass index_type="hnsw" or IndexType.HNSW and config keys such as m, ef_construction, ef_search (see API / server defaults).

IVF — index_type=IndexType.IVF and config=Configure.Index.ivf_flat(nlist=16, nprobe=2) (prototype index on server).

Configuration inspection

info = db.config()   # dict: unified config + metadata from GET /config

API overview

VittoriaDB

Collection

Exported types include Vector, SearchResult, CollectionInfo, HealthStatus, DatabaseStats, DistanceMetric, IndexType, VectorizerConfig, ContentStorageConfig, and configuration/error types listed in vittoriadb.__all__.

Contributing & license

• Issues: GitHub Issues
• Dev setup: DEVELOPMENT.md
• License: MIT

Changelog (high level)

• 0.7.0 — Aligned with VittoriaDB v0.7.0 GitHub release assets; same feature set as 0.6.x (filters, use_post, prometheus_metrics, Configure.Index.ivf_flat, HealthStatus / DatabaseStats); documentation table and API overview updated.
• 0.6.x — Metadata filters, observability helpers, IVF config in client; README refresh.
• 0.5.x — Unified server configuration; config(); performance-related server features.

Full release notes: GitHub Releases.