Python Client

EphemeralClient#

python

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

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".

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 {}.

Client#

python

Return a running chroma.API instance

Client 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

list_collections#

python

List all collections.

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.

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

get_collection#

python

Get a collection with the given name.

Arguments:

  • 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.

Returns:

  • Collection - The collection

Raises:

  • ValueError - If the collection does not exist

Examples:

python

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
  • embedding_function - Optional function to use to embed documents

Returns:

The collection

Examples:

python

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

count_collections#

python

Count the number of collections.

Returns:

  • int - The number of collections.

Examples:

python

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 the client.

Returns:

  • Settings - The settings used to initialize the client.