gvdb

Python client for GVDB distributed vector database.

Install

pip install gvdb

# With bulk import extras (Parquet, NumPy, Pandas, progress bar)
pip install gvdb[import]

# All optional dependencies
pip install gvdb[import-all]

Quick Start

from gvdb import GVDBClient

client = GVDBClient("localhost:50051", api_key="your-key")  # api_key is optional

# Create a collection
client.create_collection("my_vectors", dimension=768)

# Insert vectors
vectors = [[0.1, 0.2, ...], [0.3, 0.4, ...]]  # list of float lists
ids = [1, 2]
client.insert("my_vectors", ids, vectors)

# Search
results = client.search("my_vectors", query_vector=[0.1, 0.2, ...], top_k=10)
for r in results:
    print(f"ID: {r.id}, distance: {r.distance}")

# Hybrid search (BM25 + vector)
results = client.hybrid_search(
    "my_vectors",
    query_vector=[0.1, 0.2, ...],
    text_query="running shoes",
    top_k=10,
    text_field="description",   # metadata field to search
    return_metadata=True,
)

# Clean up
client.drop_collection("my_vectors")
client.close()

Bulk Import

Import vectors from common ML formats. Auto-creates collections, supports resume via upsert idempotency, and shows progress bars (with tqdm).

import numpy as np

# From NumPy array
vectors = np.random.rand(100_000, 768).astype(np.float32)
result = client.import_numpy(vectors, "embeddings")
print(result)  # ImportResult(total=100000, batches=10, elapsed=12.3s, ...)

# From Parquet (GVDB schema: id + vector + metadata columns)
result = client.import_parquet("vectors.parquet", "embeddings")

# From Pandas DataFrame
result = client.import_dataframe(df, "embeddings", vector_column="embedding")

# From CSV (JSON-encoded or dimension-prefixed vector columns)
result = client.import_csv("data.csv", "embeddings")

# From AnnData h5ad (scRNA-seq embeddings)
result = client.import_h5ad("adata.h5ad", "cells", embedding_key="X_pca")

All importers accept mode="upsert" (default, idempotent) or mode="stream_insert" (faster, no resume). See ImportResult for batch counts, timing, and failure tracking.

Optional dependency extras

Extra	Dependencies	For
`gvdb[parquet]`	pyarrow	`import_parquet`
`gvdb[numpy]`	numpy	`import_numpy`
`gvdb[pandas]`	pandas, pyarrow	`import_dataframe`, `import_csv`
`gvdb[h5ad]`	anndata, numpy	`import_h5ad`
`gvdb[progress]`	tqdm	Progress bars
`gvdb[import]`	All above except anndata	Common ML workflows
`gvdb[import-all]`	Everything + polars	All formats

Metadata

Release files for gvdb 0.38.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gvdb 0.38.0
File	Size	Uploaded
gvdb-0.38.0.tar.gz	120.9 kB	Jul 5, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for gvdb 0.38.0
File	Interpreter	ABI	Platform	Reset
gvdb-0.38.0-py3-none-any.whl 18.6 kB Jul 5, 2026	Python 3	none	any	Details

Total release size: 139.6 kB

Release files / gvdb-0.38.0.tar.gz

Download URL	gvdb-0.38.0.tar.gz
Size	120.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`997f656ff44d11114c2d928285acc56b742f29394c98f1c981bf5cf0e3e37be6`
BLAKE2b-256 checksum How to use checksums	`4657e572a6ed5fec4e817b89eb8b7a401e76b697f2171fcb1c4156cf75db31fc`
Upload date	Jul 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/JonathanBerhe/gvdb
Publishing commit: github.com/JonathanBerhe/gvdb/tree/b9eb3f085e95e85c7154e7494a40c9848930160a

Workflow

Publishing configuration: github.com/JonathanBerhe/gvdb/blob/b9eb3f085e95e85c7154e7494a40c9848930160a/.github/workflows/release-please.yml
Publishing logs: github.com/JonathanBerhe/gvdb/actions/runs/28739403316/attempts/1

Artifact

Subject: gvdb-0.38.0.tar.gz
SHA-256 checksum: 997f656ff44d11114c2d928285acc56b742f29394c98f1c981bf5cf0e3e37be6 Verifying attestations

Release files / gvdb-0.38.0-py3-none-any.whl

Download URL	gvdb-0.38.0-py3-none-any.whl
Size	18.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`ca0010299f5bab743d07368d2c871d8a8995ae4e067c53a74a30ea0a025a4099`
BLAKE2b-256 checksum How to use checksums	`1948365380f0522c4d46f8ee56a17746d9b84351096eaa37a87baa5affa6a35a`
Upload date	Jul 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/JonathanBerhe/gvdb
Publishing commit: github.com/JonathanBerhe/gvdb/tree/b9eb3f085e95e85c7154e7494a40c9848930160a

Workflow

Publishing configuration: github.com/JonathanBerhe/gvdb/blob/b9eb3f085e95e85c7154e7494a40c9848930160a/.github/workflows/release-please.yml
Publishing logs: github.com/JonathanBerhe/gvdb/actions/runs/28739403316/attempts/1

Artifact

Subject: gvdb-0.38.0-py3-none-any.whl
SHA-256 checksum: ca0010299f5bab743d07368d2c871d8a8995ae4e067c53a74a30ea0a025a4099 Verifying attestations