Client

ChromaClient

The main client for interacting with Chroma. Manages collections and provides access to the database.

Constructor

new ChromaClient(params?: ChromaClientParams)

Parameters:

ChromaClientParams

Client configuration options

Show ChromaClientParams properties

string

default:"http://localhost:8000"

The base URL for the Chroma API server

RequestInit

Additional fetch options for HTTP requests

AuthOptions

Authentication configuration

string

default:"default_tenant"

The tenant to use

string

default:"default_database"

The database to use

Example:

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>

Parameters:

CreateCollectionParams

required

Show CreateCollectionParams properties

string

required

The name of the collection

CollectionMetadata

Optional metadata associated with the collection

IEmbeddingFunction

Custom embedding function for the collection. Defaults to DefaultEmbeddingFunction

CreateCollectionConfiguration

Collection configuration options

Returns: Promise resolving to the created Collection instance Throws:

ChromaConnectionError - If unable to connect to the server
ChromaServerError - 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>

Parameters:

GetCollectionParams

required

Show GetCollectionParams properties

string

required

The name of the collection

IEmbeddingFunction

Optional custom embedding function for the collection

Returns: Promise resolving to the Collection instance Throws: 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>

Parameters:

GetOrCreateCollectionParams

required

Same as CreateCollectionParams

Returns: Promise resolving to the got or created Collection instance Throws: 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>

Parameters:

DeleteCollectionParams

required

Show DeleteCollectionParams properties

string

required

The name of the collection to delete

Returns: Promise that resolves when the collection is deleted Throws: 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[]>

Parameters:

ListCollectionsParams

Show ListCollectionsParams properties

number

Optional limit on the number of items to get

number

Optional offset on the items to get

Returns: Promise resolving to a list of collection names Example:

const collections = await client.listCollections({
  limit: 10,
  offset: 0
});

listCollectionsAndMetadata

List collection names, IDs, and metadata.

await client.listCollectionsAndMetadata(params?: ListCollectionsParams): Promise<{
  name: string;
  id: string;
  metadata?: CollectionMetadata;
}[]>

Parameters:

ListCollectionsParams

Same as listCollections

Returns: Promise resolving to a list of collection names, IDs, and metadata Example:

const collections = await client.listCollectionsAndMetadata({
  limit: 10,
  offset: 0
});

countCollections

Counts all collections.

await client.countCollections(): Promise<number>

Returns: Promise resolving to the number of collections Example:

const count = await client.countCollections();

Utility Methods

version

Returns the version of the Chroma API.

await client.version(): Promise<string>

Returns: Promise resolving to the version of the Chroma API Throws: 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>

Returns: Promise resolving to the heartbeat in nanoseconds Throws: 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>

Returns: Promise that resolves when the reset operation is complete Throws:

ChromaConnectionError - If unable to connect to the server
ChromaServerError - If the server experienced an error

Example:

await client.reset();

CloudClient

A client for connecting to Chroma Cloud. Extends ChromaClient with cloud-specific configuration.

Constructor

new CloudClient(params: CloudClientParams)

Parameters:

CloudClientParams

required

Show CloudClientParams properties

string

Your Chroma Cloud API key. If not provided, uses the CHROMA_API_KEY environment variable

string

The database to use

string

The tenant to use

string

default:"https://api.trychroma.com"

The Chroma Cloud host URL

string

default:"8000"

The Chroma Cloud port

Throws: 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)

Parameters:

object

Show AdminClientParams properties

string

default:"http://localhost:8000"

The base URL for the Chroma API server

RequestInit

Additional fetch options for HTTP requests

AuthOptions

Authentication configuration

string

default:"default_tenant"

The tenant to use

string

default:"default_database"

The database to use

Example:

const adminClient = new AdminClient({
  path: "http://localhost:8000"
});

Tenant Methods

createTenant

Creates a new tenant.

await adminClient.createTenant(params: { name: string }): Promise<Tenant>

Parameters:

string

required

The name of the tenant to create

Returns: Promise resolving to the created tenant Throws: 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>

Parameters:

string

required

The name of the tenant to get

Returns: Promise resolving to the tenant Throws: 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>

Parameters:

object

required

Show properties

string

required

The name of the tenant

string

The name of the database

Returns: Promise that resolves when complete Throws: 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 }>

Parameters:

object

required

Show properties

string

required

The name of the database to create

string

required

The name of the tenant

Returns: Promise resolving to the created database Throws: 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>

Parameters:

object

required

Show properties

string

required

The name of the database to get

string

required

The name of the tenant

Returns: Promise resolving to the database Throws: 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>

Parameters:

object

required

Show properties

string

required

The name of the database to delete

string

required

The name of the tenant

Returns: Promise that resolves when complete Throws: 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[]>

Parameters:

object

required

Show properties

string

required

The name of the tenant

number

The maximum number of databases to return

number

The number of databases to skip

Returns: Promise resolving to a list of databases Throws: 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>

Parameters:

string

The name of the database

Returns: Promise that resolves when complete Throws: Error if there is an issue Example:

await adminClient.setDatabase({
  database: "my_database"
});

Python Client

JavaScript Client

Go Client

CLI

ChromaClient

Constructor

Collection Methods

createCollection

getCollection

getOrCreateCollection

deleteCollection

listCollections

listCollectionsAndMetadata

countCollections

Utility Methods

version

heartbeat

reset

CloudClient

Constructor

AdminClient

Constructor

Tenant Methods

createTenant

getTenant

setTenant

Database Methods

createDatabase

getDatabase

deleteDatabase

listDatabases

setDatabase

​ChromaClient

​Constructor

​Collection Methods

​createCollection

​getCollection

​getOrCreateCollection

​deleteCollection

​listCollections

​listCollectionsAndMetadata

​countCollections

​Utility Methods

​version

​heartbeat

​reset

​CloudClient

​Constructor

​AdminClient

​Constructor

​Tenant Methods

​createTenant

​getTenant

​setTenant

​Database Methods

​createDatabase

​getDatabase

​deleteDatabase

​listDatabases

​setDatabase

ChromaClient

Constructor

Collection Methods

createCollection

getCollection

getOrCreateCollection

deleteCollection

listCollections

listCollectionsAndMetadata

countCollections

Utility Methods

version

heartbeat

reset

CloudClient

Constructor

AdminClient

Constructor

Tenant Methods

createTenant

getTenant

setTenant

Database Methods

createDatabase

getDatabase

deleteDatabase

listDatabases

setDatabase