Installation
Clients
EphemeralClient
Creates an in-memory instance of Chroma. This is useful for testing and development, but not recommended for production use.The tenant to use for this client. Defaults to the default tenant.
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.The directory to save Chroma’s data to. Defaults to ”./chroma”.
The tenant to use for this client. Defaults to the default tenant.
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.The hostname of the Chroma server. Defaults to “localhost”.
The port of the Chroma server. Defaults to 8000.
Whether to use SSL to connect to the Chroma server. Defaults to False.
A dictionary of headers to send to the Chroma server. Defaults to .
A dictionary of settings to communicate with the chroma server.
The tenant to use for this client. Defaults to the default tenant.
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.The hostname of the Chroma server. Defaults to “localhost”.
The port of the Chroma server. Defaults to 8000.
Whether to use SSL to connect to the Chroma server. Defaults to False.
A dictionary of headers to send to the Chroma server. Defaults to .
A dictionary of settings to communicate with the chroma server.
The tenant to use for this client. Defaults to the default tenant.
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.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.
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.
The api key to use for this client.
AdminClient
Creates an admin client that can be used to create tenants and databases.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 epochlist_collections
List all collections.The maximum number of entries to return. Defaults to None.
The number of entries to skip before returning. Defaults to None.
count_collections
Count the number of collections. Returns: The number of collections.create_collection
Create a new collection with the given name and metadata.The name of the collection to create.
Optional metadata to associate with the collection.
Optional function to use to embed documents.
Uses the default embedding function if not provided.
Optional function to use to load records (documents, images, etc.)
If True, return the existing collection if it exists.
- 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.The name of the collection to get
Optional function to use to embed documents.
Uses the default embedding function if not provided.
Optional function to use to load records (documents, images, etc.)
- 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:delete_collection
Delete a collection with the given name.The name of the collection to delete.
- 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 Chromaget_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.get_tenant
Get a tenant. Raises an error if the tenant does not exist.create_database
Create a new database. Raises an error if the database already exists.get_database
Get a database. Raises an error if the database does not exist.The tenant of the database to get.
delete_database
Delete a database. Raises an error if the database does not exist.The tenant of the database to delete.
list_databases
List all databases for a tenant. Raises an error if the tenant does not exist.The tenant to list databases for.
Collection Methods
count
The total number of embeddings added to the database Returns: The total number of embeddings added to the databaseadd
Add embeddings to the data store.The ids of the embeddings you wish to add
The embeddings to add. If None, embeddings will be computed based on the documents or images using the embedding_function set for the Collection. Optional.
The metadata to associate with the embeddings. When querying, you can filter on this metadata. Optional.
The documents to associate with the embeddings. Optional.
The images to associate with the embeddings. Optional.
The uris of the images to associate with the embeddings. Optional.
- ValueError: If you don’t provide either embeddings or documents
- ValueError: If the length of ids, embeddings, metadatas, or documents don’t match
- ValueError: If you don’t provide an embedding function and don’t provide embeddings
- ValueError: If you provide both embeddings and documents
- ValueError: If you provide an id that already exists
get
Get embeddings and their associate data from the data store. If no ids or where filter is provided returns all embeddings up to limit starting at offset.The ids of the embeddings to get. Optional.
A Where type dict used to filter results by. E.g.
{"$and": [{"color" : "red"}, {"price": {"$gte": 4.20}}]}. Optional.The number of documents to return. Optional.
The offset to start returning results from. Useful for paging results with limit. Optional.
where_document
Optional[Dict[Where, Union[str, List[Dict[Where, Union[str, List[WhereDocument]]]]]]]
A WhereDocument type dict used to filter by the documents. E.g.
{"$contains": "hello"}. Optional.A list of what to include in the results. Can contain
"embeddings", "metadatas", "documents". Ids are always included. Defaults to ["metadatas", "documents"]. Optional.peek
Get the first few results in the database up to limitThe number of results to return.
query
Get the n_results nearest neighbor embeddings for provided query_embeddings or query_texts.The embeddings to get the closes neighbors of. Optional.
The document texts to get the closes neighbors of. Optional.
The images to get the closes neighbors of. Optional.
The URIs to be used with data loader. Optional.
A subset of ids to search within. Optional.
The number of neighbors to return for each query_embedding or query_texts. Optional.
A Where type dict used to filter results by. E.g.
{"$and": [{"color" : "red"}, {"price": {"$gte": 4.20}}]}. Optional.where_document
Optional[Dict[Where, Union[str, List[Dict[Where, Union[str, List[WhereDocument]]]]]]]
A WhereDocument type dict used to filter by the documents. E.g.
{"$contains": "hello"}. Optional.A list of what to include in the results. Can contain
"embeddings", "metadatas", "documents", "distances". Ids are always included. Defaults to ["metadatas", "documents", "distances"]. Optional.- ValueError: If you don’t provide either query_embeddings, query_texts, or query_images
- ValueError: If you provide both query_embeddings and query_texts
- ValueError: If you provide both query_embeddings and query_images
- ValueError: If you provide both query_texts and query_images
modify
Modify the collection name or metadataThe updated name for the collection. Optional.
The updated metadata for the collection. Optional.
update
Update the embeddings, metadatas or documents for provided ids.The ids of the embeddings to update
The embeddings to update. If None, embeddings will be computed based on the documents or images using the embedding_function set for the Collection. Optional.
The metadata to associate with the embeddings. When querying, you can filter on this metadata. Optional.
The documents to associate with the embeddings. Optional.
The images to associate with the embeddings. Optional.
upsert
Update the embeddings, metadatas or documents for provided ids, or create them if they don’t exist.The ids of the embeddings to update
The embeddings to add. If None, embeddings will be computed based on the documents using the embedding_function set for the Collection. Optional.
The metadata to associate with the embeddings. When querying, you can filter on this metadata. Optional.
The documents to associate with the embeddings. Optional.
delete
Delete the embeddings based on ids and/or a where filterThe ids of the embeddings to delete
A Where type dict used to filter the delection by. E.g.
{"$and": [{"color" : "red"}, {"price": {"$gte": 4.20}]}}. Optional.where_document
Optional[Dict[Where, Union[str, List[Dict[Where, Union[str, List[WhereDocument]]]]]]]
A WhereDocument type dict used to filter the deletion by the document content. E.g.
{"$contains": "hello"}. Optional.- ValueError: If you don’t provide either ids, where, or where_document
Embedding Functions
EmbeddingFunction
A protocol for embedding functions. To implement a new embedding function, Methods__init__(), build_from_config(), default_space(), embed_query(), embed_with_retries(), get_config(), is_legacy(), name(), supported_spaces(), validate_config(), validate_config_update()
SparseEmbeddingFunction
A protocol for sparse vector functions. To implement a new sparse vector function, Methods__init__(), build_from_config(), embed_query(), embed_with_retries(), get_config(), name(), validate_config(), validate_config_update()
Types
Embedding
Embedding[Tuple[Any, Ellipsis], dtype[Union[int32, float32]]]
SparseVector
Represents a sparse vector using parallel arrays for indices and values. Properties__init__(), from_dict(), to_dict()
Schema
Collection schema for configuring indexes and encryption. Properties__init__(), create_index(), delete_index(), deserialize_from_json(), serialize_to_json(), set_cmek()
Search
Payload for hybrid search operations. Methods__init__(), group_by(), limit(), rank(), select(), select_all(), to_dict(), where()
Select
Selection configuration for search results. Properties__init__(), from_dict(), to_dict()
Knn
KNN-based ranking Properties__init__(), abs(), exp(), from_dict(), log(), max(), min(), to_dict()
Rrf
Reciprocal Rank Fusion for combining multiple ranking strategies. Properties__init__(), abs(), exp(), from_dict(), log(), max(), min(), to_dict()
GetResult
PropertiesQueryResult
PropertiesSearchResult
Column-major response from the search API with conversion methods. Propertiesrows()