fastrag.vector_store.chroma#

ChromaVectorStore, via chromadb’s async HTTP client or an embedded store.

A VectorStore backed by Chroma. Chroma has no BM25 ranking (its document filters are substring/regex matches, not relevance scores), so this store does not implement LexicalStore: pair it with a separate lexical store for hybrid retrieval.

Every write and query passes vectors, so the collection’s default embedding function is never invoked (and its model never downloaded).

Chroma metadata values must be scalars, so a document’s (possibly nested) metadata is kept as one JSON string; source_id, source_uri and step_config_hash are stored as their own metadata keys so where filters can match them.

Module Attributes

DEFAULT_COLLECTION

Collection name used when the caller does not name one.

METRICS

Chroma's HNSW distance functions.

ID_PAGE_SIZE

Ids per get page in ChromaVectorStore.all_ids().

Classes

ChromaVectorStore(*[, url, path, ...])

Vectors in a Chroma server, or in an embedded on-disk Chroma database.
fastrag.vector_store.chroma.DEFAULT_COLLECTION = 'fastrag_documents'#

Collection name used when the caller does not name one.

fastrag.vector_store.chroma.METRICS = frozenset({'cosine', 'ip', 'l2'})#

Chroma’s HNSW distance functions.

fastrag.vector_store.chroma.ID_PAGE_SIZE = 10000#

Ids per get page in ChromaVectorStore.all_ids().

class fastrag.vector_store.chroma.ChromaVectorStore(*, url=None, path=None, collection='fastrag_documents', headers=None, tenant='default_tenant', database='default_database', metric_type='cosine', policy=None)[source]#

Bases: VectorStore

Vectors in a Chroma server, or in an embedded on-disk Chroma database.

Give url to talk to a Chroma server through its async HTTP client, or path to run Chroma in-process against a local directory (its client is synchronous, so calls run in a worker thread). Construction never touches the network or the disk — the client is built in __aenter__.

async with ChromaVectorStore(url="http://localhost:8000") as vector_store:
    async for document in vector_store.save(embedded_documents):
        ...

filter is a JSON-encoded Chroma where object, e.g. '{"source_uri": "https://example.org/docs"}'. score is Chroma’s own distance, so lower is better; results are still best first.

Parameters:

  • url (str | None) – Server endpoint, e.g. http://localhost:8000. Exclusive with path.

  • path (str | None) – Directory of an embedded persistent database. Exclusive with url.

  • collection (str) – Name of the Chroma collection. Created on demand.

  • headers (Mapping[str, str] | None) – Extra HTTP headers, e.g. an auth token, sent with url.

  • tenant (str) – Chroma tenant the collection lives in.

  • database (str) – Chroma database the collection lives in.

  • metric_type (str) – HNSW distance for a new collection: cosine, l2 or ip. An existing collection must already use it.

  • policy (Policy | None) – Execution policy for the terminal step save() returns.

async ensure_ready(dimension)[source]#

Create collection if absent, or validate its metric and width.

Chroma fixes a collection’s width on its first insert rather than at creation, so an existing collection is checked against one stored vector; an empty one accepts any width.

Parameters:

dimension (int)

Return type:

None

async upsert(documents)[source]#

Insert or replace documents by id, in one call.

Parameters:

documents (Sequence[Document])

Return type:

None

async existing_ids(ids)[source]#

Fetch the whole batch by id in one get, returning ids only.

Parameters:

ids (Sequence[str])

Return type:

set[str]

async all_ids()[source]#

Page through every id with get; empty if the collection does not exist.

Return type:

set[str]

async delete(ids)[source]#

Delete ids in one call; Chroma ignores ids it does not hold.

Parameters:

ids (Sequence[str])

Return type:

None

async search(embedding, *, k, filter=None)[source]#

Return at most k documents nearest embedding, best first.

score is Chroma’s distance for the collection’s metric, where lower means closer; rank is the position in Chroma’s already nearest-first order.

Parameters:
Return type:

list[Document]

save(upstream, *, skip_existing=False)#

Return a lazy terminal step that indexes upstream’s documents.

Constructing the returned step performs no I/O — evaluating it (async for document in vector_store.save(upstream): or .run()) is what upserts. Each document is queued into a batcher that checks existing_ids() and flushes to upsert() once self.policy.batch_size documents have queued, or after a short window; every document is yielded back once its batch is resolved, with cached set to whether the store already held it, and DocumentSaved emitted for it.

Parameters:

  • upstream (PipelineStep[Document]) – Final upstream step yielding embedded documents.

  • skip_existing (bool) – For an identity-preserving Embedder, check destination ids before embedding. Indexed items bypass vector retrieval and produce cached DocumentEmbedded and DocumentSaved events. Cached events and results may contain only identity/metadata with empty content and no vectors. Custom content filters disable header projection. Use a separate destination for each embedding configuration.

Return type:

PipelineStep[Document]

Either way, recreate_cache (on the store’s policy or the pipeline’s) skips the existence check and upserts every document.

sync(upstream, *, skip_existing=False)#

Like save(), then delete every stored document upstream did not yield.

After a clean run the store holds exactly the documents the run produced: documents whose source disappeared or changed (a changed chunk gets a new id) are removed. Deletion happens once the upstream is exhausted, so a run that raises or is stopped early deletes nothing. A run with any ItemFailed deletes nothing either: a failed item’s documents are missing from the run, not from the source. Either way a DocumentsPruned event reports the outcome.

The run must cover everything the store should keep — use one store (collection/index) per synced pipeline.

Parameters:
Return type:

PipelineStep[Document]