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 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.
Constructor OptionsDirect link to Constructor Options
host?:
port?:
ssl?:
apiKey?:
tenant?:
database?:
headers?:
fetchOptions?:
Running a Chroma ServerDirect link to 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.
MethodsDirect link to Methods
createIndex()Direct link to createIndex()
indexName:
dimension:
metric?:
forkIndex()Direct link to 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:
newIndexName:
upsert()Direct link to upsert()
indexName:
vectors:
metadata?:
ids?:
documents?:
query()Direct link to 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:
queryVector:
topK?:
filter?:
includeVector?:
documentFilter?:
get()Direct link to 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:
ids?:
filter?:
includeVector?:
documentFilter?:
limit?:
offset?:
listIndexes()Direct link to listIndexes()
Returns an array of index names as strings.
describeIndex()Direct link to describeIndex()
indexName:
Returns:
interface IndexStats {
dimension: number;
count: number;
metric: "cosine" | "euclidean" | "dotproduct";
}
deleteIndex()Direct link to deleteIndex()
indexName:
updateVector()Direct link to updateVector()
indexName:
id:
update:
The update object can contain:
vector?:
metadata?:
deleteVector()Direct link to deleteVector()
indexName:
id:
Response TypesDirect link to 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 HandlingDirect link to 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
}
}