Skip to main content

​
Clients

​
EphemeralClient

Creates an in-memory instance of Chroma. This is useful for testing and development, but not recommended for production use.
​
settings
Optional[Settings]
​
tenant
str
The tenant to use for this client. Defaults to the default tenant.
​
database
str
The database to use for this client. Defaults to the default database.

​
PersistentClient

Creates a persistent instance of Chroma that saves to disk. This is useful for testing and development, but not recommended for production use.
​
path
Union[str, Path]
The directory to save Chroma’s data to. Defaults to ”./chroma”.
​
settings
Optional[Settings]
​
tenant
str
The tenant to use for this client. Defaults to the default tenant.
​
database
str
The database to use for this client. Defaults to the default database.

​
HttpClient

Creates a client that connects to a remote Chroma server. This supports many clients connecting to the same server, and is the recommended way to use Chroma in production.
​
host
str
The hostname of the Chroma server. Defaults to “localhost”.
​
port
int
The port of the Chroma server. Defaults to 8000.
​
ssl
bool
Whether to use SSL to connect to the Chroma server. Defaults to False.
​
headers
Optional[Dict[str, str]]
A dictionary of headers to send to the Chroma server. Defaults to {}.
​
settings
Optional[Settings]
A dictionary of settings to communicate with the chroma server.
​
tenant
str
The tenant to use for this client. Defaults to the default tenant.
​
database
str
The database to use for this client. Defaults to the default database.

​
AsyncHttpClient

Creates an async client that connects to a remote Chroma server. This supports many clients connecting to the same server, and is the recommended way to use Chroma in production.
​
host
str
The hostname of the Chroma server. Defaults to “localhost”.
​
port
int
The port of the Chroma server. Defaults to 8000.
​
ssl
bool
Whether to use SSL to connect to the Chroma server. Defaults to False.
​
headers
Optional[Dict[str, str]]
A dictionary of headers to send to the Chroma server. Defaults to {}.
​
settings
Optional[Settings]
A dictionary of settings to communicate with the chroma server.
​
tenant
str
The tenant to use for this client. Defaults to the default tenant.
​
database
str
The database to use for this client. Defaults to the default database.

​
CloudClient

Creates a client to connect to a tenant and database on Chroma cloud.
​
tenant
Optional[str]
The tenant to use for this client. Optional. If not provided, it will be inferred from the API key if the key is scoped to a single tenant. If provided, it will be validated against the API key’s scope.
​
database
Optional[str]
The database to use for this client. Optional. If not provided, it will be inferred from the API key if the key is scoped to a single database. If provided, it will be validated against the API key’s scope.
​
api_key
Optional[str]
The api key to use for this client.
​
settings
Optional[Settings]
​
cloud_host
str
​
cloud_port
int
​
enable_ssl
bool

​
AdminClient

Creates an admin client that can be used to create tenants and databases.
​
settings
Settings

​
Client Methods

​
heartbeat

Get the current time in nanoseconds since epoch. Used to check if the server is alive. Returns: The current time in nanoseconds since epoch

​
list_collections

List all collections.
​
limit
Optional[int]
The maximum number of entries to return. Defaults to None.
​
offset
Optional[int]
The number of entries to skip before returning. Defaults to None.
Returns: A list of collections

​
count_collections

Count the number of collections. Returns: The number of collections.

​
create_collection

Create a new collection with the given name and metadata.
​
name
str
required
The name of the collection to create.
​
schema
Optional[Schema]
​
configuration
Optional[CreateCollectionConfiguration]
​
metadata
Optional[Dict[str, Any]]
Optional metadata to associate with the collection.
​
embedding_function
Optional[EmbeddingFunction[Optional[Embeddings]]]
Optional function to use to embed documents. Uses the default embedding function if not provided.
​
data_loader
Optional[DataLoader[Optional[Embeddings]]]
Optional function to use to load records (documents, images, etc.)
​
get_or_create
bool
If True, return the existing collection if it exists.
Returns: The newly created collection. Raises:
  • ValueError: If the collection already exists and get_or_create is False.
  • ValueError: If the collection name is invalid.

​
get_collection

Get a collection with the given name.
​
name
str
required
The name of the collection to get
​
embedding_function
Optional[EmbeddingFunction[Optional[Embeddings]]]
Optional function to use to embed documents. Uses the default embedding function if not provided.
​
data_loader
Optional[DataLoader[Optional[Embeddings]]]
Optional function to use to load records (documents, images, etc.)
Returns: The collection Raises:
  • ValueError: If the collection does not exist

​
get_or_create_collection

Get or create a collection with the given name and metadata. Args: name: The name of the collection to get or create metadata: Optional metadata to associate with the collection. If the collection already exists, the metadata provided is ignored. If the collection does not exist, the new collection will be created with the provided metadata. embedding_function: Optional function to use to embed documents data_loader: Optional function to use to load records (documents, images, etc.) Returns: The collection Examples: 
client.get_or_create_collection("my_collection")
# collection(name="my_collection", metadata=\{\})
​
name
str
required
​
schema
Optional[Schema]
​
configuration
Optional[CreateCollectionConfiguration]
​
metadata
Optional[Dict[str, Any]]
​
embedding_function
Optional[EmbeddingFunction[Optional[Embeddings]]]
​
data_loader
Optional[DataLoader[Optional[Embeddings]]]

​
delete_collection

Delete a collection with the given name.
​
name
str
required
The name of the collection to delete.
Raises:
  • ValueError: If the collection does not exist.

​
reset

Resets the database. This will delete all collections and entries. Returns: True if the database was reset successfully.

​
get_version

Get the version of Chroma. Returns: The version of Chroma

​
get_settings

Get the settings used to initialize. Returns: The settings used to initialize.

​
get_max_batch_size

Return the maximum number of records that can be created or mutated in a single call.

​
Admin Client Methods

​
create_tenant

Create a new tenant. Raises an error if the tenant already exists.
​
name
str
required

​
get_tenant

Get a tenant. Raises an error if the tenant does not exist.
​
name
str
required

​
create_database

Create a new database. Raises an error if the database already exists.
​
name
str
required
​
tenant
str

​
get_database

Get a database. Raises an error if the database does not exist.
​
name
str
required
​
tenant
str
The tenant of the database to get.

​
delete_database

Delete a database. Raises an error if the database does not exist.
​
name
str
required
​
tenant
str
The tenant of the database to delete.

​
list_databases

List all databases for a tenant. Raises an error if the tenant does not exist.
​
limit
Optional[int]
​
offset
Optional[int]
​
tenant
str
The tenant to list databases for.