PersistentClient and Collections

~18 min · chroma, setup

Level 0Scout

0 XP0/41 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

One client, many collections

A Chroma client points at a directory on disk. Inside the client you create collections — independent indexes that share the same on-disk store. A typical app has one collection per content type (docs, conversations, code) so each can have its own embedding model and metadata schema.

Pin your distance metric at creation

Chroma defaults to cosine, but you can opt into L2 or inner product. Choose at creation time — changing the metric on an existing collection means rebuilding it. For most text use cases, leave it on cosine.

Code

Create a persistent client and a collection·python

import chromadb
from chromadb.config import Settings

client = chromadb.PersistentClient(
    path='./chroma_store',
    settings=Settings(anonymized_telemetry=False),
)

docs = client.get_or_create_collection(
    name='handbook',
    metadata={'hnsw:space': 'cosine'},
)

print(client.list_collections())
print(docs.count())

Encapsulate connection setup·python

from functools import lru_cache

@lru_cache(maxsize=1)
def get_client():
    return chromadb.PersistentClient(path='./chroma_store',
                                     settings=Settings(anonymized_telemetry=False))

def get_collection(name: str):
    return get_client().get_or_create_collection(
        name=name, metadata={'hnsw:space': 'cosine'},
    )

External links

Exercise

Create two persistent clients in two directories. In each, create one collection. Add a few documents. Show that the directories are independent and that deleting one client's directory does not affect the other.

Progress

Progress is local-only — sign in to sync across devices.

← 🧩 Chunking and IngestionQuiz · 4 questions Next →Add, Query, and the Three Result Modes

Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)

No comments yet — be the first.