ChromaDB is an embeddable vector database. It stores texts and their embeddings, and can search by semantic meaning. No separate server required.
Installation
uv add chromadb
# First install downloads ~500 MB (the embedding model)
PersistentClient โ Saving Data to Disk
import chromadb
# Data is saved to the ./chroma_db folder
client = chromadb.PersistentClient(path="./chroma_db")
# Create a collection or retrieve an existing one
collection = client.get_or_create_collection(name="documents")
chromadb.Client() โ stores data in RAM only; it is lost on restart.
add() โ Adding Documents
collection.add(
documents=["Python is an interpreted language.", "Django is a web framework."],
ids=["doc_0", "doc_1"],
metadatas=[{"source": "intro.txt"}, {"source": "frameworks.txt"}]
)
Three required fields:
- documents โ the texts
- ids โ unique strings (duplicates are not allowed)
- metadatas โ dictionaries with metadata (optional but useful)
ChromaDB automatically generates embeddings using its built-in model.
query() โ Semantic Search
results = collection.query(
query_texts=["How do I build a web application?"],
n_results=3,
include=["documents", "metadatas", "distances"]
)
for doc, meta, dist in zip(
results["documents"][0],
results["metadatas"][0],
results["distances"][0]
):
relevance = 1 - dist
print(f"[{relevance:.0%}] {meta['source']}: {doc[:80]}")
Interpreting Distance
distance is the cosine distance, ranging from 0 to 2:
| Distance | Relevance | Interpretation |
|---|---|---|
| 0.0โ0.3 | 70โ100% | Very similar |
| 0.3โ0.6 | 40โ70% | Moderately similar |
| > 0.6 | < 40% | Weak match |
# Filter by threshold
THRESHOLD = 0.5
relevant = [
(doc, meta) for doc, meta, dist
in zip(results["documents"][0], results["metadatas"][0], results["distances"][0])
if dist < THRESHOLD
]
Checking for Duplicates Before Adding
existing_ids = set(collection.get(include=[])["ids"])
new_docs, new_ids, new_metas = [], [], []
for doc, id_, meta in zip(documents, ids, metadatas):
if id_ not in existing_ids:
new_docs.append(doc)
new_ids.append(id_)
new_metas.append(meta)
if new_docs:
collection.add(documents=new_docs, ids=new_ids, metadatas=new_metas)
๐ฌ Comments (0)
No comments yet
Be the first to share your opinion about this article!