How to create a Chroma document store in Haystack

Local retrieval applications need storage that survives a Python process without requiring a separate database server. Chroma provides that middle ground by keeping Haystack documents and embeddings in a local collection on disk.

The chroma-haystack integration presents Chroma through Haystack's document-store interface. Setting persist_path selects local persistent storage, and collection_name identifies the collection that later application processes must reopen.

Fixed three-value embeddings keep the persistence test independent of model downloads and API credentials. Production indexing and retrieval must use embeddings from the same model with the same vector dimensions, but the storage boundary can be proven separately by reopening the collection and reading its records from another process.

1. Install the Chroma integration in the Python environment that runs Haystack.

   $ python -m pip install chroma-haystack

2. Create create_chroma_store.py with the Haystack imports and persistent Chroma collection.

   create_chroma_store.py

   from haystack import Document
   from haystack.document_stores.types import DuplicatePolicy
   from haystack_integrations.document_stores.chroma import ChromaDocumentStore
    
    
   document_store = ChromaDocumentStore(
       collection_name="support_articles",
       persist_path="support_chroma",
   )

   The relative support_chroma path is created under the directory where the script runs; an application-owned absolute path avoids changes caused by a different working directory.

3. Add three documents below the ChromaDocumentStore initialization.

   documents = [
       Document(
           id="account-reset",
           content="Reset passwords through the identity portal.",
           meta={"topic": "accounts"},
           embedding=[0.99, 0.03, 0.01],
       ),
       Document(
           id="search-restart",
           content="Restart the search service after changing the index.",
           meta={"topic": "operations"},
           embedding=[0.02, 0.98, 0.02],
       ),
       Document(
           id="invoice-archive",
           content="Archive paid invoices from the billing dashboard.",
           meta={"topic": "billing"},
           embedding=[0.01, 0.02, 0.99],
       ),
   ]

   The fixed vectors isolate local persistence from model configuration; real query vectors must match the indexed vectors' model and dimensions.

4. Complete create_chroma_store.py with the write-and-count block.

   written = document_store.write_documents(
       documents,
       policy=DuplicatePolicy.OVERWRITE,
   )
    
   print(f"documents written: {written}")
   print(f"documents stored: {document_store.count_documents()}")

   DuplicatePolicy.OVERWRITE replaces records with matching IDs when the script is rerun.

5. Run create_chroma_store.py from the directory that should contain support_chroma.

   $ python create_chroma_store.py
   documents written: 3
   documents stored: 3

6. Create check_chroma_store.py to reopen the collection from a separate process.

   check_chroma_store.py

   from haystack_integrations.document_stores.chroma import (
       ChromaDocumentStore,
   )
    
    
   document_store = ChromaDocumentStore(
       collection_name="support_articles",
       persist_path="support_chroma",
   )
    
   documents = document_store.filter_documents()
    
   print(f"stored documents: {len(documents)}")
   for document in sorted(documents, key=lambda item: item.id):
       print(f"{document.id}: {document.meta['topic']}")

7. Run the reopen check from the same working directory.

   $ python check_chroma_store.py
   stored documents: 3
   account-reset: accounts
   invoice-archive: billing
   search-restart: operations

   The three named records confirm that a new process reopened the support_articles collection from support_chroma.