Skip to main content

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.

info
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()​

Update a single vector by ID or by metadata filter. Either id or filter must be provided, but not both.

indexName:

string
Name of the index containing the vector to update

id?:

string
ID of the vector to update (mutually exclusive with filter)

filter?:

Record<string, any>
Metadata filter to identify vector(s) to update (mutually exclusive with id)

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

Example:

// Update by ID
await vectorStore.updateVector({
  indexName: 'docs',
  id: 'vec_123',
  update: { metadata: { status: 'reviewed' } }
});

// Update by filter
await vectorStore.updateVector({
  indexName: 'docs',
  filter: { source_id: 'manual.pdf' },
  update: { metadata: { version: 2 } }
});

deleteVector()​

indexName:

string
Name of the index containing the vector to delete

id:

string
ID of the vector to delete

deleteVectors()​

Delete multiple vectors by IDs or by metadata filter. This method enables bulk deletion and source-based vector management. Either ids or filter must be provided, but not both.

indexName:

string
Name of the index containing the vectors to delete

ids?:

string[]
Array of vector IDs to delete (mutually exclusive with filter)

filter?:

Record<string, any>
Metadata filter to identify vectors to delete (mutually exclusive with ids)

Example:

// Delete all chunks from a document
await vectorStore.deleteVectors({
  indexName: 'docs',
  filter: { source_id: 'manual.pdf' }
});

// Delete multiple vectors by ID
await vectorStore.deleteVectors({
  indexName: 'docs',
  ids: ['vec_1', 'vec_2', 'vec_3']
});

// Delete old temporary documents
await vectorStore.deleteVectors({
  indexName: 'docs',
  filter: {
    $and: [
      { bucket: 'temp' },
      { indexed_at: { $lt: '2025-01-01' } }
    ]
  }
});

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
  }
}