Documentation Index
Fetch the complete documentation index at: https://docs.trychroma.com/llms.txt
Use this file to discover all available pages before exploring further.
There are several ways you can instantiate clients to connect to your Chroma database.
Cloud Client
You can use the CloudClient to create a client connecting to Chroma Cloud.
import chromadb
client = chromadb.CloudClient(
tenant='Tenant ID',
database='Database name',
api_key='Chroma Cloud API key'
)
CloudClient can be instantiated just with the API key argument. In which case, we will resolve the tenant and DB from Chroma Cloud. Note our auto-resolution will work only if the provided API key is scoped to a single DB.
If you set the CHROMA_API_KEY, CHROMA_TENANT, and the CHROMA_DATABASE environment variables, you can simply instantiate a CloudClient with no arguments:
client = chromadb.CloudClient()
Connecting to a non-default region
By default, CloudClient connects to api.trychroma.com (AWS us-east-1). To target a database in another region — for example, our GCP europe-west1 region — point the client at that region’s hostname. See Regions for the list of available endpoints.
import chromadb
client = chromadb.CloudClient(
cloud_host='europe-west1.gcp.trychroma.com',
cloud_port=443,
api_key='Chroma Cloud API key',
tenant='Tenant ID',
database='Database name',
)
.env block. For databases outside aws-us-east-1, the snippet sets CHROMA_HOST to the region-specific host:
CHROMA_HOST=europe-west1.gcp.trychroma.com
CHROMA_API_KEY=...
CHROMA_TENANT=...
CHROMA_DATABASE=...
In-Memory Client
In Python, you can run a Chroma server in-memory and connect to it with the ephemeral client:
import chromadb
client = chromadb.Client()
Client() method starts a Chroma server in-memory and also returns a client with which you can connect to it.
This is a great tool for experimenting with different embedding functions and retrieval techniques in a Python notebook, for example. If you don’t need data persistence, the ephemeral client is a good choice for getting up and running with Chroma.
Persistent Client
You can configure Chroma to save and load the database from your local machine, using the PersistentClient.Data will be persisted automatically and loaded on start (if it exists).import chromadb
client = chromadb.PersistentClient(path="/path/to/save/to")
path is where Chroma will store its database files on disk, and load them on start. If you don’t provide a path, the default is .chromaThe client object has a few useful convenience methods.
heartbeat() - returns a nanosecond heartbeat. Useful for making sure the client remains connected.reset() - empties and completely resets the database. WARNING: This is destructive and not reversible.
client.heartbeat()
client.reset()
To connect with the JS/TS client, you must connect to a Chroma server.To run a Chroma server locally that will persist your data, install Chroma from npm using any npm compatible client.And run the server using our CLI:npx chroma run --path ./getting-started
path is where Chroma will store its database files on disk, and load them on start. The default is .chroma.Alternatively, you can also use our official Docker image:docker pull chromadb/chroma
docker run -p 8000:8000 chromadb/chroma
ChromaClient:import { ChromaClient } from "chromadb";
const client = new ChromaClient();
ChromaClient is wired to connect to a Chroma server at http://localhost:8000, with default_tenant and default_database. If you have different settings you can provide them to the ChromaClient constructor:const client = new ChromaClient({
ssl: false,
host: "localhost",
port: 9000, // non-standard port based on your server config
database: "my-db",
headers: {},
});
heartbeat() - returns a nanosecond heartbeat. Useful for making sure the client remains connected.reset() - empties and completely resets the database. WARNING: This is destructive and not reversible.
await client.heartbeat();
await client.reset();
The Rust client connects to a running Chroma server. For local persistence, run the server with a data path and connect over HTTP.chroma run --path /db_path
use chroma::{ChromaHttpClient, ChromaHttpClientOptions};
let mut options = ChromaHttpClientOptions::default();
options.endpoint = "http://localhost:8000".parse()?;
let client = ChromaHttpClient::new(options);
client.heartbeat().await?;
