ChromaClient
The main client for interacting with Chroma. Manages collections and provides access to the database.
Constructor
new ChromaClient(params?: ChromaClientParams)
Client configuration optionsShow ChromaClientParams properties
path
string
default:"http://localhost:8000"
The base URL for the Chroma API server
Additional fetch options for HTTP requests
Authentication configuration
tenant
string
default:"default_tenant"
The tenant to use
database
string
default:"default_database"
The database to use
const client = new ChromaClient({
path: "http://localhost:8000"
});
Collection Methods
createCollection
Creates a new collection with the specified properties.
await client.createCollection(params: CreateCollectionParams): Promise<Collection>
params
CreateCollectionParams
required
Show CreateCollectionParams properties
The name of the collection
Optional metadata associated with the collection
Custom embedding function for the collection. Defaults to DefaultEmbeddingFunction
configuration
CreateCollectionConfiguration
Collection configuration options
ChromaConnectionError - If unable to connect to the serverChromaServerError - If there is an issue creating the collection
Example:
const collection = await client.createCollection({
name: "my_collection",
metadata: {
"description": "My first collection"
}
});
getCollection
Gets an existing collection with the specified name.
await client.getCollection(params: GetCollectionParams): Promise<Collection>
params
GetCollectionParams
required
Show GetCollectionParams properties
The name of the collection
Optional custom embedding function for the collection
Error if the collection does not exist or there is an issue getting it
Example:
const collection = await client.getCollection({
name: "my_collection"
});
getOrCreateCollection
Gets or creates a collection with the specified properties.
await client.getOrCreateCollection(params: GetOrCreateCollectionParams): Promise<Collection>
params
GetOrCreateCollectionParams
required
Same as CreateCollectionParams
Error if there is an issue getting or creating the collection
Example:
const collection = await client.getOrCreateCollection({
name: "my_collection",
metadata: {
"description": "My first collection"
}
});
deleteCollection
Deletes a collection with the specified name.
await client.deleteCollection(params: DeleteCollectionParams): Promise<void>
params
DeleteCollectionParams
required
Show DeleteCollectionParams properties
The name of the collection to delete
Error if there is an issue deleting the collection
Example:
await client.deleteCollection({
name: "my_collection"
});
listCollections
Get all collection names.
await client.listCollections(params?: ListCollectionsParams): Promise<string[]>
Show ListCollectionsParams properties
Optional limit on the number of items to get
Optional offset on the items to get
const collections = await client.listCollections({
limit: 10,
offset: 0
});
await client.listCollectionsAndMetadata(params?: ListCollectionsParams): Promise<{
name: string;
id: string;
metadata?: CollectionMetadata;
}[]>
const collections = await client.listCollectionsAndMetadata({
limit: 10,
offset: 0
});
countCollections
Counts all collections.
await client.countCollections(): Promise<number>
const count = await client.countCollections();
Utility Methods
version
Returns the version of the Chroma API.
await client.version(): Promise<string>
ChromaConnectionError if unable to connect to the server
Example:
const version = await client.version();
heartbeat
Returns a heartbeat from the Chroma API.
await client.heartbeat(): Promise<number>
ChromaConnectionError if unable to connect to the server
Example:
const heartbeat = await client.heartbeat();
reset
Resets the state of the database.
await client.reset(): Promise<boolean>
ChromaConnectionError - If unable to connect to the serverChromaServerError - If the server experienced an error
Example:
CloudClient
A client for connecting to Chroma Cloud. Extends ChromaClient with cloud-specific configuration.
Constructor
new CloudClient(params: CloudClientParams)
params
CloudClientParams
required
Show CloudClientParams properties
Your Chroma Cloud API key. If not provided, uses the CHROMA_API_KEY environment variable
cloudHost
string
default:"https://api.trychroma.com"
The Chroma Cloud host URL
Error if no API key is provided and CHROMA_API_KEY environment variable is not set
Example:
const client = new CloudClient({
apiKey: "your-api-key",
database: "my_database"
});
CloudClient inherits all methods from ChromaClient. See the ChromaClient documentation above for available methods.
AdminClient
A client for administrative operations like managing tenants and databases.
Constructor
new AdminClient(params?: AdminClientParams)
Show AdminClientParams properties
path
string
default:"http://localhost:8000"
The base URL for the Chroma API server
Additional fetch options for HTTP requests
Authentication configuration
tenant
string
default:"default_tenant"
The tenant to use
database
string
default:"default_database"
The database to use
const adminClient = new AdminClient({
path: "http://localhost:8000"
});
Tenant Methods
createTenant
Creates a new tenant.
await adminClient.createTenant(params: { name: string }): Promise<Tenant>
The name of the tenant to create
Error if there is an issue creating the tenant
Example:
await adminClient.createTenant({
name: "my_tenant"
});
getTenant
Gets a tenant by name.
await adminClient.getTenant(params: { name: string }): Promise<Tenant>
The name of the tenant to get
Error if there is an issue getting the tenant
Example:
const tenant = await adminClient.getTenant({
name: "my_tenant"
});
setTenant
Sets the tenant and database for the client.
await adminClient.setTenant(params: { tenant: string; database?: string }): Promise<void>
Error if there is an issue
Example:
await adminClient.setTenant({
tenant: "my_tenant",
database: "my_database"
});
Database Methods
createDatabase
Creates a new database.
await adminClient.createDatabase(params: {
name: string;
tenantName: string;
}): Promise<{ name: string }>
The name of the database to create
Error if there is an issue creating the database
Example:
await adminClient.createDatabase({
name: "my_database",
tenantName: "my_tenant"
});
getDatabase
Gets a database by name.
await adminClient.getDatabase(params: {
name: string;
tenantName: string;
}): Promise<Database>
The name of the database to get
Error if there is an issue getting the database
Example:
const database = await adminClient.getDatabase({
name: "my_database",
tenantName: "my_tenant"
});
deleteDatabase
Deletes a database.
await adminClient.deleteDatabase(params: {
name: string;
tenantName: string;
}): Promise<void>
The name of the database to delete
Error if there is an issue deleting the database
Example:
await adminClient.deleteDatabase({
name: "my_database",
tenantName: "my_tenant"
});
listDatabases
Lists databases for a specific tenant.
await adminClient.listDatabases(params: {
tenantName: string;
limit?: number;
offset?: number;
}): Promise<Database[]>
The maximum number of databases to return
The number of databases to skip
Error if there is an issue listing the databases
Example:
const databases = await adminClient.listDatabases({
tenantName: "my_tenant",
limit: 10,
offset: 0
});
setDatabase
Sets the database for the client.
await adminClient.setDatabase(params: { database?: string }): Promise<void>
Error if there is an issue
Example:
await adminClient.setDatabase({
database: "my_database"
});