Skip to Content
ReferenceRAGChromaVector

Chroma Vector Store

The ChromaVector class provides vector search using Chroma , an open-source embedding database. It offers efficient vector search with metadata filtering and hybrid search capabilities.

Chroma Cloud

Chroma Cloud powers serverless vector and full-text search. It’s extremely fast, cost-effective, scalable and painless. Create a DB and try it out in under 30 seconds with $5 of free credits.

Get started with Chroma Cloud 

Constructor Options

host?:

string
The host address of the Chroma server. Defaults to 'localhost'

port?:

number
The port number of the Chroma server. Defaults to 8000

ssl?:

boolean
Whether to use SSL/HTTPS for connections. Defaults to false

apiKey?:

string
A Chroma Cloud API key

tenant?:

string
The tenant name in the Chroma server to connect to. Defaults to 'default_tenant' for single-node Chroma. Auto-resolved for Chroma Cloud users based on the provided API key

database?:

string
The database name to connect to. Defaults to 'default_database' for single-node Chroma. Auto-resolved for Chroma Cloud users based on the provided API key

headers?:

Record<string, any>
Additional HTTP headers to send with requests

fetchOptions?:

RequestInit
Additional fetch options for HTTP requests

Running a Chroma Server

If you are a Chroma Cloud user, simply provide the ChromaVector constructor your API key, tenant, and database name.

When you install the @mastra/chroma package, you get access to the Chroma CLI , which can set these as environment variables for you: chroma db connect [DB-NAME] --env-file.

Otherwise, you have several options for setting up your single-node Chroma server:

  • Run one locally using the Chroma CLI: chroma run. You can find more configuration options on the Chroma docs .
  • Run on Docker  using the official Chroma image.
  • Deploy your own Chroma server on your provider of choice. Chroma offers example templates for AWS , Azure , and GCP .

Methods

createIndex()

indexName:

string
Name of the index to create

dimension:

number
Vector dimension (must match your embedding model)

metric?:

'cosine' | 'euclidean' | 'dotproduct'
= cosine
Distance metric for similarity search

forkIndex()

Note: Forking is only supported on Chroma Cloud, or if you deploy your own OSS distributed Chroma.

forkIndex lets you fork an existing Chroma index instantly. Operations on the forked index do not affect the original one. Learn more on the Chroma docs .

indexName:

string
Name of the index to fork

newIndexName:

string
The name of the forked index

upsert()

indexName:

string
Name of the index to upsert into

vectors:

number[][]
Array of embedding vectors

metadata?:

Record<string, any>[]
Metadata for each vector

ids?:

string[]
Optional vector IDs (auto-generated if not provided)

documents?:

string[]
Chroma-specific: Original text documents associated with the vectors

query()

Query an index using a queryVector. Returns an array of semantically similar records in order of distance from the queryVector. Each record has the shape:

{ id: string; score: number; document?: string; metadata?: Record<string, string | number | boolean>; embedding?: number[] }

You can also provide the shape of your metadata to a query call for type inference: query<T>().

indexName:

string
Name of the index to query

queryVector:

number[]
Query vector to find similar vectors

topK?:

number
= 10
Number of results to return

filter?:

Record<string, any>
Metadata filters for the query

includeVector?:

boolean
= false
Whether to include vectors in the results

documentFilter?:

Record<string, any>
Chroma-specific: Filter to apply on the document content

get()

Get records from your Chroma index by IDs, metadata, and document filters. It returns an array of records of the shape:

{ id: string; document?: string; metadata?: Record<string, string | number | boolean>; embedding?: number[] }

You can also provide the shape of your metadata to a get call for type inference: get<T>().

indexName:

string
Name of the index to query

ids?:

string[]
A list of record IDs to return. If not provided, all records are returned.

filter?:

Record<string, any>
Metadata filters.

includeVector?:

boolean
= false
Whether to include vectors in the results

documentFilter?:

Record<string, any>
Chroma-specific: Filter to apply on the document content

limit?:

number
= 100
The maximum number of records to return

offset?:

number
0
Offset for returning records. Use with `limit` to paginate results.

listIndexes()

Returns an array of index names as strings.

describeIndex()

indexName:

string
Name of the index to describe

Returns:

interface IndexStats { dimension: number; count: number; metric: "cosine" | "euclidean" | "dotproduct"; }

deleteIndex()

indexName:

string
Name of the index to delete

updateVector()

indexName:

string
Name of the index containing the vector to update

id:

string
ID of the vector to update

update:

object
Update parameters

The update object can contain:

vector?:

number[]
New vector to replace the existing one

metadata?:

Record<string, any>
New metadata to replace the existing metadata

deleteVector()

indexName:

string
Name of the index containing the vector to delete

id:

string
ID of the vector to delete

Response Types

Query results are returned in this format:

interface QueryResult { id: string; score: number; metadata: Record<string, any>; document?: string; // Chroma-specific: Original document if it was stored vector?: number[]; // Only included if includeVector is true }

Error Handling

The store throws typed errors that can be caught:

try { await store.query({ indexName: "index_name", queryVector: queryVector, }); } catch (error) { if (error instanceof VectorStoreError) { console.log(error.code); // 'connection_failed' | 'invalid_dimension' | etc console.log(error.details); // Additional error context } }