Chroma DB

Chroma DB stores documents in a Chroma vector database and searches it by meaning. With nothing else configured, the database is kept in your NappAI account storage; it can also connect to your own Chroma server.

A vector database stores texts so they can be searched by meaning, not just by exact words. That way an agent can find the paragraph of a manual that answers a question even if it uses different words.

When to use it

Giving an agent the knowledge in your manuals, contracts or FAQs without hiring any outside service.
Building an internal document search by meaning.
Searching only among documents of one department or city using filters.

Configuration

The Operation field decides what the component does, and the fields and outputs change with your choice:

Add (default): stores in the database the documents it receives in Ingest Data.
Search: finds the documents closest to the text in Search Query.
Retriever: offers the database as a search engine for another component to use, for example an agent or a question-answering chain.

Field	What it does
Operation	What the component does: `Add`, `Search` or `Retriever`.
Ingest Data (required)	With `Add`. The documents to store, usually those coming out of a text splitter or a file loader.
Search Query	With `Search`. The text to search for. If left empty, nothing is returned.
Embedding (required)	The connector where you plug the component that turns texts into numbers to compare them by meaning, such as OpenAI Embeddings. Always use the same one to store and to search.
Collection Name (required)	Name of the collection inside the database. Use the same name to store and to search.
Persist Directory	Name of the storage folder where the database is kept. Empty, `default` is used.

Advanced options

Field	What it does
Number of Results	How many documents each search returns. Default: 4.
Server Host	Only if you use your own Chroma server: its address. Together with Server HTTP Port, Server GRPC Port, Server SSL Enabled and Server CORS Allow Origins, which whoever runs it will give you. Empty, NappAI storage is used. The documents are then stored in and searched on that server.
Allow Duplicates	Off (default), documents already in the database are not stored again.
Limit	With `Add`, how many stored documents are shown in the node summary.
Search Type	How to search: `Similarity`, `Similarity with score threshold`. `Similarity` returns the closest; with a threshold, only those above Search Score Threshold.
Search Score Threshold	Minimum similarity score, only with the threshold search. Default: 0.1.
Filter by Metadata	Searches only among the documents whose data meet some conditions, for example `brand` equal to `Vellani`. Works with `Search`, `Retriever` and in tool mode. See Filter by metadata.

The data is kept in your account’s storage, where you can view and download it.

Filter by metadata

Besides its text, each document keeps some data (its metadata): the brand, the document type, the month… The filter makes the search look only at the documents whose data meet some conditions. It applies the same way to Results, to Retriever and when an agent uses the component as a tool.

Turn on Filter by Metadata (in the advanced options) and choose Filter Mode:

Manual: you write the conditions on the node. In Number of Conditions you choose how many rows you want, and each row has:
- Field: the data to check, for example brand.
- Operator: Equal, NotEqual, GreaterThan, GreaterThanEqual, LessThan, LessThanEqual, In (one of a comma-separated list, such as Q90, S80), NotIn (none of the list) and Contains (the text or the list contains the value).
- Type: Text, Int (whole number), Number (with decimals) or Boolean (true or false).
- Value: the value to compare with. Left empty, that row does not filter.
Combine Conditions decides whether all of them must match (AND) or one is enough (OR).
Dynamic: the conditions arrive as JSON in Metadata Filter (JSON), from another component or written by an agent:
- {"brand": "Vellani"}: exact value.
- {"model": ["Q90", "S80"]}: any of the list.
- {"year": {">=": 2024}, "status": {"!=": "archived"}}: with the operators =, !=, >, >=, <, <=, in, not in and contains.
With several fields, all of them must match. Empty, it does not filter. A badly written JSON gives an error instead of searching without the filter.

Let the agent fill it in. With the component in tool mode, turn on tool mode for Value (with Field and Operator fixed, for example model and Equal) or for Metadata Filter (JSON). The agent writes the value when the question asks for it (“only the Q90 machine”) and leaves it empty when not. Tell it in the tool description which fields and values exist.

Lists. When a piece of data is a list, like the tags Metadata Tagger writes, Equal and In match when one of its items does, and Contains looks inside them.

In Chroma DB there is no Contains, and greater/less only compare numbers. Chroma cannot store lists: a list is stored as comma-separated text (“Q90, S80”), so Equal does not find a single item. To filter by lists, use FAISS, Qdrant, PGVector or Elasticsearch.

Example: only one brand’s manuals

When storing, each chunk carries its data, for example type: manual and brand: Vellani (set by the file loader or by Metadata Tagger).
On the node with Operation set to Search, turn on Filter by Metadata, leave Filter Mode on Manual and fill in the row: Field brand, Operator Equal, Type Text, Value Vellani.
Search for “what does error E07 mean”: only chunks from Vellani documents come back.

The same filter in Dynamic mode is {"brand": "Vellani"}. Nodes saved earlier keep their filters; the new field names appear when you update the node.

Output

The outputs depend on Operation:

Results: with Add and Search. With Search, the list of documents found, which you can pass to a prompt or an agent.
Vector Store: with Add. The database, to connect it to components that work with a vector database.
Retriever: with Retriever. The search engine, to connect it to components that ask for one.

In tool mode, an agent can use the component to search by itself. See Tool Mode.

Example

A consultancy wants its assistant to answer from its procedures guide.

Load the guide with a file component, pass it through a text splitter and connect it to Ingest Data of a Chroma DB with Operation set to Add and Collection Name procedures.
Connect an embeddings component to Embedding and run the flow once.
In the assistant’s flow, add another Chroma DB with the same collection, Operation set to Search and in tool mode, and connect it to the agent.

Good practices

Always store and search with the same embeddings component: if you change model, store the documents again.
You can download the whole database from storage and upload it in another environment.

FAISS: another vector database kept in your storage.
Recursive Character Text Splitter: cuts documents into pieces before storing them.
OpenAI Embeddings: converts texts so they can be searched by meaning.
FastEmbed Embeddings (Local): converts texts inside NappAI, with no key or cost per use.