Embed documents into Chroma for RAG

Use this destination when you want the simplest possible RAG index, built and refreshed by a repeatable pipeline rather than a notebook. Ingest unstructured documents into Chroma, a lightweight, developer-friendly open-source vector database. The pipeline extracts text from the document, chunks it using a configurable strategy, generates vector embeddings, and upserts the chunks with metadata into a Chroma collection via its REST API. Chroma is the simplest vector database to set up — a single Docker container with no external dependencies.

Configuration

"source": {
    "fileAttributes": {
        "unstructuredAttributes": {
            "fileExtension": "pdf",
            "preserveFilename": true
        }
    }
},
"destination": {
    "chroma": {
        "collectionName": "financial_documents",
        "chunking": {
            "strategy": "recursive",
            "chunkSize": 500,
            "chunkOverlap": 50
        },
        "metadata": {
            "company": "Apple Inc",
            "documentType": "10-Q",
            "filingDate": "2026-01-30"
        },
        "chromaSecretName": "oss/chroma"
    }
}

Field	Type	Default	Description
`collectionName`	string	(required)	Chroma collection name. Auto-created with cosine distance if it doesn’t exist.
`chunking`	object	recursive, 500/50	Chunking strategy configuration (see below).
`metadata`	map	`{}`	Static key-value metadata stored on every chunk. Used for filtered search.
`embeddingSecretName`	string	server default	Embedding Vault secret name. Only consulted when the server-level `ai.embedding.secretName` is unset; with the default configuration (`oss/embedding`, seeded automatically) the server-level secret is always used and this field is ignored.
`chromaSecretName`	string	server default	Vault secret name for the Chroma connection. Only consulted when the server-level `secrets.chromaSecretName` is unset; with the default configuration (`oss/chroma`) the server-level secret is always used and this field is ignored.

Supported File Types

Format	Description
PDF (`.pdf`)	Text extracted via Apache PDFBox
Word (`.doc`)	Text extracted via Apache POI (legacy format)
Word (`.docx`)	Text extracted via Apache POI (modern format)
PowerPoint (`.ppt`)	Text extracted via Apache POI (legacy format)
PowerPoint (`.pptx`)	Text extracted via Apache POI (modern format)
Excel (`.xls`, `.xlsx`)	Cell values extracted via Apache POI
HTML (`.html`, `.htm`)	Text extracted via JSoup (tags stripped)
RTF (`.rtf`)	Text extracted via javax.swing RTF parser
Email (`.msg`)	Subject, from, to, and body extracted via Apache POI
Email (`.eml`)	Subject, from, and body extracted via Jakarta Mail
EPUB (`.epub`)	XHTML content extracted and parsed via JSoup
Plain text (`.txt`, `.md`, `.csv`, `.json`, `.xml`)	Content used directly

For structured data (CSV, JSON, XML), use database destinations (PostgreSQL, MongoDB) instead.

Vault Secrets

Chroma connection

vault kv put secret/oss/chroma \
  host="host.docker.internal" \
  port="8000"

Field	Description
`host`	Chroma server hostname. Use `host.docker.internal` for local Chroma.
`port`	REST API port (default 8000).

The loader reads only host and port from the secret and sends no authentication header, so Chroma auth tokens are not currently supported: the Chroma endpoint must be reachable without authentication (Chroma’s default). Chroma Cloud and token-protected instances are not supported.

Embedding API

The embedding secret is server-level (ai.embedding.secretName, default oss/embedding) and is seeded automatically by docker/vault-init.sh. You only need to write it manually if you want to point at a different embedding provider. See AI Configuration for the full picture.

vault kv put secret/oss/embedding \
  provider="openai" \
  endpoint="https://api.openai.com/v1/embeddings" \
  model="text-embedding-3-small" \
  apiKey="sk-..."

For Anthropic-only deployments, the bundled TEI sidecar serves bge-m3 (1024-dim) and vault-init.sh seeds the embedding secret to point at it — no OpenAI key required.

Chunking Strategies

Documents are split into chunks before embedding. Each chunk becomes a separate entry in the Chroma collection with the document’s metadata plus chunk_index, filename, and source_pipeline fields.

"chunking": {
    "strategy": "recursive",
    "chunkSize": 500,
    "chunkOverlap": 50
}

Strategy	Description
`none`	No chunking — one embedding per document. Only for very short documents.
`fixed`	Split by character count. Fast but may cut mid-sentence.
`sentence`	Split on sentence boundaries (`.` `!` `?`). Preserves semantic units.
`paragraph`	Split on double newlines. Ideal for structured documents with clear sections.
`recursive`	Try `\n\n`, then `\n`, then `.`, then space — best general-purpose default.

chunkSize (default 500): maximum characters per chunk
chunkOverlap (default 50): characters of overlap between consecutive chunks

Metadata

Static metadata is stored on every chunk in the Chroma collection:

"metadata": {
    "company": "Apple Inc",
    "documentType": "10-Q",
    "filingDate": "2026-01-30"
}

This allows filtered queries combining similarity with metadata predicates using Chroma’s where clause. Every entry automatically includes:

text — the chunk text (stored as Chroma document)
chunk_index — position of the chunk in the document
filename — original uploaded filename
source_pipeline — pipeline name

How It Works

Upload — an unstructured file is uploaded via POST /api/v1/pipeline/upload
Extract — text is extracted from the document
Chunk — text is split into chunks using the configured strategy
Embed — each chunk is sent to the embedding API to generate a vector
Upsert — vectors are upserted into the Chroma collection via REST API with metadata
Notify — a pipeline notification is published on completion

The collection is auto-created on first upsert with cosine distance. No Java client library is needed — the loader communicates with Chroma’s REST API directly via HTTP.

Running Chroma

Chroma ships as a bundled opt-in Compose service. Enable it with one line in .env:

COMPOSE_PROFILES=chroma

Then start the stack:

docker compose up -d

Combine profiles with commas (e.g., COMPOSE_PROFILES=chroma,kafka). The install.sh installer can also enable Chroma at install time — it writes the profile and seeds the oss/chroma secret for you. For the bundled container, use the compose service name as the host in the secret (host="chroma", port 8000). To use an existing external instance instead, skip the profile and point the oss/chroma secret’s host/port at it — the secret fields are the same either way. You can also run Chroma standalone:

docker run -d --name chroma -p 8000:8000 chromadb/chroma:latest

Either way there are no external dependencies like etcd or MinIO — Chroma is the simplest vector database to run.

Searching from Datris

The Assistant (and any MCP client) can search this store semantically without leaving Datris: the server embeds the query with the configured embedding provider and returns the closest chunks with scores.

Tool	Purpose
`search_chroma`	Semantic search (`query`, optional `collection`, `top_k`, default 5)
`list_chroma_collections`	Discover available collections before searching

The REST endpoint is POST /api/v1/search/chroma (Search API); a key needs the search:vector capability (included in the read-only, reporting and rag-builder templates). The CLI equivalent is datris search "question" --store chroma --collection financial_documents --top-k 5.

curl -X POST http://localhost:8080/api/v1/search/chroma \
  -H "x-api-key: $DATRIS_API_KEY" -H "Content-Type: application/json" \
  -d '{"query": "quarterly revenue growth", "collection": "financial_documents", "topK": 5}'

Verifying

# Check Chroma is running
curl http://localhost:8000/api/v2/heartbeat

# List collections
curl http://localhost:8000/api/v2/tenants/default_tenant/databases/default_database/collections

# Get collection details
curl http://localhost:8000/api/v2/tenants/default_tenant/databases/default_database/collections/financial_documents

# Count entries in collection (replace COLLECTION_ID with the actual UUID)
curl http://localhost:8000/api/v2/tenants/default_tenant/databases/default_database/collections/COLLECTION_ID/count

Getting Started

Connect your agent

Assistant

Catalog

Taps

Ingestion

Destinations

Data Quality

Transformation

AI Features

Configuration

Governance & Security

Production

Integrations

Recipes

Examples

Embed documents into Chroma for RAG

Configuration

Supported File Types

Vault Secrets

Chroma connection

Embedding API

Chunking Strategies

Metadata

How It Works

Running Chroma

Searching from Datris

Verifying

​Configuration

​Supported File Types

​Vault Secrets

​Chroma connection

​Embedding API

​Chunking Strategies

​Metadata

​How It Works

​Running Chroma

​Searching from Datris

​Verifying

Configuration

Supported File Types

Vault Secrets

Chroma connection

Embedding API

Chunking Strategies

Metadata

How It Works

Running Chroma

Searching from Datris

Verifying