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.

Constructor Options

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

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 .

upsert()

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>().

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>().

listIndexes()

Returns an array of index names as strings.

describeIndex()

Returns:

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

deleteIndex()

updateVector()

The update object can contain:

deleteVector()

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

Related

• Metadata Filters