Skip to content

docs: Update ChromaDB configuration details for Chroma Cloud support #4008

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 6, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,9 @@ link:https://docs.trychroma.com/[Chroma] is the open-source embedding database.

== Prerequisites

1. Access to ChromeDB. The <<Run Chroma Locally, setup local ChromaDB>> appendix shows how to set up a DB locally with a Docker container.
1. Access to ChromaDB. Compatible with link:https://trychroma.com/signup[Chroma Cloud], or <<run Chroma Locally, setup local ChromaDB>> in the appendix shows how to set up a DB locally with a Docker container.
- For Chroma Cloud: You'll need your API key, tenant name, and database name from your Chroma Cloud dashboard.
- For local ChromaDB: No additional configuration required beyond starting the container.

2. `EmbeddingModel` instance to compute the document embeddings. Several options are available:
- If required, an API key for the xref:api/embeddings.adoc#available-implementations[EmbeddingModel] to generate the embeddings stored by the `ChromaVectorStore`.
Expand Down Expand Up @@ -72,12 +74,16 @@ A simple configuration can either be provided via Spring Boot's _application.pro
[source,properties]
----
# Chroma Vector Store connection properties
spring.ai.vectorstore.chroma.client.host=<your Chroma instance host>
spring.ai.vectorstore.chroma.client.port=<your Chroma instance port>
spring.ai.vectorstore.chroma.client.key-token=<your access token (if configure)>
spring.ai.vectorstore.chroma.client.host=<your Chroma instance host> // for Chroma Cloud: api.trychroma.com
spring.ai.vectorstore.chroma.client.port=<your Chroma instance port> // for Chroma Cloud: 443
spring.ai.vectorstore.chroma.client.key-token=<your access token (if configure)> // for Chroma Cloud: use the API key
spring.ai.vectorstore.chroma.client.username=<your username (if configure)>
spring.ai.vectorstore.chroma.client.password=<your password (if configure)>

# Chroma Vector Store tenant and database properties (required for Chroma Cloud)
spring.ai.vectorstore.chroma.tenant-name=<your tenant name> // default: SpringAiTenant
spring.ai.vectorstore.chroma.database-name=<your database name> // default: SpringAiDatabase

# Chroma Vector Store collection properties
spring.ai.vectorstore.chroma.initialize-schema=<true or false>
spring.ai.vectorstore.chroma.collection-name=<your collection name>
Expand Down Expand Up @@ -123,8 +129,10 @@ You can use the following properties in your Spring Boot configuration to custom
|`spring.ai.vectorstore.chroma.client.key-token`| Access token (if configured) | -
|`spring.ai.vectorstore.chroma.client.username`| Access username (if configured) | -
|`spring.ai.vectorstore.chroma.client.password`| Access password (if configured) | -
|`spring.ai.vectorstore.chroma.tenant-name`| Tenant (required for Chroma Cloud) | `SpringAiTenant`
|`spring.ai.vectorstore.chroma.database-name`| Database name (required for Chroma Cloud) | `SpringAiDatabase`
|`spring.ai.vectorstore.chroma.collection-name`| Collection name | `SpringAiCollection`
|`spring.ai.vectorstore.chroma.initialize-schema`| Whether to initialize the required schema | `false`
|`spring.ai.vectorstore.chroma.initialize-schema`| Whether to initialize the required schema (creates tenant/database/collection if they don't exist) | `false`
|===

[NOTE]
Expand All @@ -134,6 +142,36 @@ For ChromaDB secured with link:https://docs.trychroma.com/usage-guide#static-api
For ChromaDB secured with link:https://docs.trychroma.com/usage-guide#basic-authentication[Basic Authentication] use the `ChromaApi#withBasicAuth(<your user>, <your password>)` method to set your credentials. Check the `BasicAuthChromaWhereIT` for an example.
====

=== Chroma Cloud Configuration

For Chroma Cloud, you need to provide the tenant and database names from your Chroma Cloud instance. Here's an example configuration:

[source,properties]
----
# Chroma Cloud connection
spring.ai.vectorstore.chroma.client.host=api.trychroma.com
spring.ai.vectorstore.chroma.client.port=443
spring.ai.vectorstore.chroma.client.key-token=<your-chroma-cloud-api-key>

# Chroma Cloud tenant and database (required)
spring.ai.vectorstore.chroma.tenant-name=<your-tenant-id>
spring.ai.vectorstore.chroma.database-name=<your-database-name>

# Collection configuration
spring.ai.vectorstore.chroma.collection-name=my-collection
spring.ai.vectorstore.chroma.initialize-schema=true
----

[NOTE]
====
For Chroma Cloud:
- The host should be `api.trychroma.com`
- The port should be `443` (HTTPS)
- You must provide your API key via `key-token`
- The tenant and database names must match your Chroma Cloud configuration
- Set `initialize-schema=true` to automatically create the collection if it doesn't exist (it won't recreate existing tenant/database)
====

== Metadata filtering

You can leverage the generic, portable link:https://docs.spring.io/spring-ai/reference/api/vectordbs.html#_metadata_filters[metadata filters] with ChromaVector store as well.
Expand Down Expand Up @@ -238,6 +276,8 @@ Integrate with OpenAI's embeddings by adding the Spring Boot OpenAI starter to y
@Bean
public VectorStore chromaVectorStore(EmbeddingModel embeddingModel, ChromaApi chromaApi) {
return ChromaVectorStore.builder(chromaApi, embeddingModel)
.tenantName("your-tenant-name") // default: SpringAiTenant
.databaseName("your-database-name") // default: SpringAiDatabase
.collectionName("TestCollection")
.initializeSchema(true)
.build();
Expand Down