chromadb-zerodb

Chroma-compatible API backed by ZeroDB cloud. No Docker, no server, instant vector DB.

Drop-in replacement for chromadb — same Collection API, but vectors are stored in ZeroDB cloud. Auto-provisions on first use. Free tier included.

Why?

Install

pip install chromadb-zerodb

Quick Start

import chromadb_zerodb as chromadb

# Auto-provisions a free project on first use
client = chromadb.Client()

# Create a collection
collection = client.create_collection("my_docs")

# Add documents (auto-embedded with free BGE models)
collection.add(
    documents=[
        "Python is a great programming language",
        "JavaScript powers the web",
        "Rust is fast and memory-safe",
    ],
    ids=["doc1", "doc2", "doc3"],
    metadatas=[
        {"topic": "python"},
        {"topic": "javascript"},
        {"topic": "rust"},
    ],
)

# Query by text
results = collection.query(
    query_texts=["best language for beginners"],
    n_results=2,
)

print(results["documents"])  # [["Python is a great...", "JavaScript powers..."]]
print(results["distances"])  # [[0.05, 0.12]]

Migration from chromadb

Change one import:

# Before
import chromadb
client = chromadb.Client()

# After
import chromadb_zerodb as chromadb
client = chromadb.Client()

Everything else stays the same.

Authentication

Three ways to authenticate (checked in order):

1. Constructor arguments:

   client = chromadb.Client(api_key="zdb_...", project_id="proj_...")
   

2. Environment variables:

   export ZERODB_API_KEY=zdb_...
   export ZERODB_PROJECT_ID=proj_...
   

3. Auto-provision: If neither is set, a free project is created automatically. Credentials are cached in ~/.zerodb/credentials.json.

API Reference

Client

client = chromadb.Client(api_key=None, project_id=None, base_url=None)

client.create_collection(name, metadata=None)    # -> Collection
client.get_collection(name)                       # -> Collection
client.get_or_create_collection(name, metadata=None)  # -> Collection
client.list_collections()                         # -> List[str]
client.delete_collection(name)                    # -> None
client.heartbeat()                                # -> int (nanosecond timestamp)

Collection

collection.add(
    ids=None,           # auto-generated if omitted
    documents=None,     # auto-embedded if provided
    embeddings=None,    # or pass pre-computed vectors
    metadatas=None,
)

collection.query(
    query_texts=None,
    query_embeddings=None,
    n_results=10,
    where=None,         # metadata filter
)
# Returns: {"ids": [[...]], "documents": [[...]], "metadatas": [[...]], "distances": [[...]]}

collection.get(ids=None, where=None)
# Returns: {"ids": [...], "documents": [...], "metadatas": [...]}

collection.update(ids, documents=None, embeddings=None, metadatas=None)
collection.upsert(ids, documents=None, embeddings=None, metadatas=None)
collection.delete(ids=None, where=None)
collection.count()  # -> int

Bring Your Own Embeddings

collection.add(
    ids=["id1"],
    embeddings=[[0.1, 0.2, 0.3, ...]],  # your vectors
    documents=["the original text"],
    metadatas=[{"source": "my_model"}],
)

collection.query(
    query_embeddings=[[0.1, 0.2, 0.3, ...]],
    n_results=5,
)

Metadata Filtering

results = collection.query(
    query_texts=["search term"],
    where={"topic": "python"},
    n_results=5,
)

How It Works

• Collections are namespaced via ID prefixes (collection_name::doc_id)
• Auto-embedding uses ZeroDB's free BAAI BGE-M3 model
• Storage is ZeroDB's managed vector database (same infra as ZeroDB MCP)
• Credentials are cached at ~/.zerodb/credentials.json

Links

• ZeroDB Documentation
• ZeroDB MCP Server
• AINative Studio

License

MIT