Client

configure#

python

Override Chroma's default settings, environment variables or .env files

EphemeralClient#

python

Creates an in-memory instance of Chroma. This is useful for testing and development, but not recommended for production use.

Arguments:

  • tenant - The tenant to use for this client. Defaults to the default tenant.
  • database - The database to use for this client. Defaults to the default database.

PersistentClient#

python

Creates a persistent instance of Chroma that saves to disk. This is useful for testing and development, but not recommended for production use.

Arguments:

  • path - The directory to save Chroma's data to. Defaults to "./chroma".
  • tenant - The tenant to use for this client. Defaults to the default tenant.
  • database - The database to use for this client. Defaults to the default database.

HttpClient#

python

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.

Arguments:

  • host - The hostname of the Chroma server. Defaults to "localhost".
  • port - The port of the Chroma server. Defaults to "8000".
  • ssl - Whether to use SSL to connect to the Chroma server. Defaults to False.
  • headers - A dictionary of headers to send to the Chroma server. Defaults to {}.
  • settings - A dictionary of settings to communicate with the chroma server.
  • tenant - The tenant to use for this client. Defaults to the default tenant.
  • database - The database to use for this client. Defaults to the default database.

AsyncHttpClient#

python

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.

Arguments:

  • host - The hostname of the Chroma server. Defaults to "localhost".
  • port - The port of the Chroma server. Defaults to "8000".
  • ssl - Whether to use SSL to connect to the Chroma server. Defaults to False.
  • headers - A dictionary of headers to send to the Chroma server. Defaults to {}.
  • settings - A dictionary of settings to communicate with the chroma server.
  • tenant - The tenant to use for this client. Defaults to the default tenant.
  • database - The database to use for this client. Defaults to the default database.

CloudClient#

python

Creates a client to connect to a tennant and database on the Chroma cloud.

Arguments:

  • tenant - The tenant to use for this client.
  • database - The database to use for this client.
  • api_key - The api key to use for this client.

Client#

python

Return a running chroma.API instance

tenant: The tenant to use for this client. Defaults to the default tenant. database: The database to use for this client. Defaults to the default database.

AdminClient#

python

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

BaseClient Methods#

python

heartbeat#

python

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

Returns:

  • int - The current time in nanoseconds since epoch

count_collections#

python

Count the number of collections.

Returns:

  • int - The number of collections.

Examples:

python client.count_collections() # 1

delete_collection#

python

Delete a collection with the given name.

Arguments:

  • name - The name of the collection to delete.

Raises:

  • ValueError - If the collection does not exist.

Examples:

python client.delete_collection("my_collection")

reset#

python

Resets the database. This will delete all collections and entries.

Returns:

  • bool - True if the database was reset successfully.

get_version#

python

Get the version of Chroma.

Returns:

  • str - The version of Chroma

get_settings#

python

Get the settings used to initialize.

Returns:

  • Settings - The settings used to initialize.

get_max_batch_size#

python

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

ClientClient Methods#

python

list_collections#

python

List all collections.

Arguments:

  • limit - The maximum number of entries to return. Defaults to None.
  • offset - The number of entries to skip before returning. Defaults to None.

Returns:

  • Sequence[Collection] - A list of collections

Examples:

python

create_collection#

python

Create a new collection with the given name and metadata.

Arguments:

  • name - The name of the collection to create.
  • metadata - Optional metadata to associate with the collection.
  • embedding_function - Optional function to use to embed documents. Uses the default embedding function if not provided.
  • get_or_create - If True, return the existing collection if it exists.
  • data_loader - Optional function to use to load records (documents, images, etc.)

Returns:

  • Collection - The newly created collection.

Raises:

  • ValueError - If the collection already exists and get_or_create is False.
  • ValueError - If the collection name is invalid.

Examples:

```python client.create_collection("my_collection") # collection(name="my_collection", metadata={})

client.create_collection("my_collection", metadata={"foo": "bar"}) # collection(name="my_collection", metadata={"foo": "bar"}) ```

get_collection#

python

Get a collection with the given name.

Arguments:

  • id - The UUID of the collection to get. Id and Name are simultaneously used for lookup if provided.
  • name - The name of the collection to get
  • embedding_function - Optional function to use to embed documents. Uses the default embedding function if not provided.
  • data_loader - Optional function to use to load records (documents, images, etc.)

Returns:

  • Collection - The collection

Raises:

  • ValueError - If the collection does not exist

Examples:

python client.get_collection("my_collection") # collection(name="my_collection", metadata={})

get_or_create_collection#

python

Get or create a collection with the given name and metadata.

Arguments:

  • name - The name of the collection to get or create
  • metadata - Optional metadata to associate with the collection. If the collection alredy exists, the metadata will be 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:

python client.get_or_create_collection("my_collection") # collection(name="my_collection", metadata={})

set_tenant#

python

Set the tenant and database for the client. Raises an error if the tenant or database does not exist.

Arguments:

  • tenant - The tenant to set.
  • database - The database to set.

set_database#

python

Set the database for the client. Raises an error if the database does not exist.

Arguments:

  • database - The database to set.

clear_system_cache#

python

Clear the system cache so that new systems can be created for an existing path. This should only be used for testing purposes.

AdminClient Methods#

python

create_database#

python

Create a new database. Raises an error if the database already exists.

Arguments:

  • database - The name of the database to create.

get_database#

python

Get a database. Raises an error if the database does not exist.

Arguments:

  • database - The name of the database to get.
  • tenant - The tenant of the database to get.

create_tenant#

python

Create a new tenant. Raises an error if the tenant already exists.

Arguments:

  • tenant - The name of the tenant to create.

get_tenant#

python

Get a tenant. Raises an error if the tenant does not exist.

Arguments:

  • tenant - The name of the tenant to get.

ServerClient Methods#

python

An API instance that extends the relevant Base API methods by passing in a tenant and database. This is the root component of the Chroma System

Edit this page on GitHub