Initiating a persistent Chroma client#
You can configure Chroma to save and load the database from your local machine. Data will be persisted automatically and loaded on start (if it exists).
The path is where Chroma will store its database files on disk, and load them on start.
The client object has a few useful convenience methods.
Running Chroma in client/server mode#
Chroma can also be configured to run in client/server mode. In this mode, the Chroma client connects to a Chroma server running in a separate process.
To start the Chroma server, run the following command:
Then use the Chroma HTTP client to connect to the server:
That's it! Chroma's API will run in client-server mode with just this change.
Chroma also provides an async HTTP client. The behaviors and method signatures are identical to the synchronous client, but all methods that would block are now async. To use it, call AsyncHttpClient instead:
Using the Python HTTP-only client#
If you are running Chroma in client-server mode, you may not need the full Chroma library. Instead, you can use the lightweight client-only library. In this case, you can install the chromadb-client package. This package is a lightweight HTTP client for the server with a minimal dependency footprint.
Note that the chromadb-client package is a subset of the full Chroma library and does not include all the dependencies. If you want to use the full Chroma library, you can install the chromadb package instead. Most importantly, there is no default embedding function. If you add() documents without embeddings, you must have manually specified an embedding function and installed the dependencies for it.
Using collections#
Chroma lets you manage collections of embeddings, using the collection primitive.
Creating, inspecting, and deleting Collections#
Chroma uses collection names in the url, so there are a few restrictions on naming them:
- The length of the name must be between 3 and 63 characters.
- The name must start and end with a lowercase letter or a digit, and it can contain dots, dashes, and underscores in between.
- The name must not contain two consecutive dots.
- The name must not be a valid IP address.
Chroma collections are created with a name and an optional embedding function. If you supply an embedding function, you must supply it every time you get the collection.
If you later wish to get_collection, you MUST do so with the embedding function you supplied while creating the collection
The embedding function takes text as input, and performs tokenization and embedding. If no embedding function is supplied, Chroma will use sentence transformer as a default.
You can learn more about 🧬 embedding functions, and how to create your own.
Existing collections can be retrieved by name with .get_collection, and deleted with .delete_collection. You can also use .get_or_create_collection to get a collection if it exists, or create it if it doesn't.
Collections have a few useful convenience methods.
Changing the distance function#
create_collection also takes an optional metadata argument which can be used to customize the distance method of the embedding space by setting the value of hnsw:space.
Valid options for hnsw:space are "l2", "ip, "or "cosine". The default is "l2" which is the squared L2 norm.
| Distance | parameter | Equation |
|---|---|---|
| Squared L2 | l2 | |
| Inner product | ip | |
| Cosine similarity | cosine |
Adding data to a Collection#
Add data to Chroma with .add.
Raw documents:
If Chroma is passed a list of documents, it will automatically tokenize and embed them with the collection's embedding function (the default will be used if none was supplied at collection creation). Chroma will also store the documents themselves. If the documents are too large to embed using the chosen embedding function, an exception will be raised.
Each document must have a unique associated id. Trying to .add the same ID twice will result in only the initial value being stored. An optional list of metadata dictionaries can be supplied for each document, to store additional information and enable filtering.
Alternatively, you can supply a list of document-associated embeddings directly, and Chroma will store the associated documents without embedding them itself.
If the supplied embeddings are not the same dimension as the collection, an exception will be raised.
You can also store documents elsewhere, and just supply a list of embeddings and metadata to Chroma. You can use the ids to associate the embeddings with your documents stored elsewhere.
Querying a Collection#
Chroma collections can be queried in a variety of ways, using the .query method.
You can query by a set of query_embeddings.
The query will return the n_results closest matches to each query_embedding, in order. An optional where filter dictionary can be supplied to filter by the metadata associated with each document. Additionally, an optional where_document filter dictionary can be supplied to filter by contents of the document.
If the supplied query_embeddings are not the same dimension as the collection, an exception will be raised.
You can also query by a set of query_texts. Chroma will first embed each query_text with the collection's embedding function, and then perform the query with the generated embedding.
You can also retrieve items from a collection by id using .get.
.get also supports the where and where_document filters. If no ids are supplied, it will return all items in the collection that match the where and where_document filters.
Choosing which data is returned#
When using get or query you can use the include parameter to specify which data you want returned - any of embeddings, documents, metadatas, and for query, distances. By default, Chroma will return the documents, metadatas and in the case of query, the distances of the results. embeddings are excluded by default for performance and the ids are always returned. You can specify which of these you want returned by passing an array of included field names to the includes parameter of the query or get method.
Using Where filters#
Chroma supports filtering queries by metadata and document contents. The where filter is used to filter by metadata, and the where_document filter is used to filter by document contents.
Filtering by metadata#
In order to filter on metadata, you must supply a where filter dictionary to the query. The dictionary must have the following structure:
Filtering metadata supports the following operators:
$eq- equal to (string, int, float)$ne- not equal to (string, int, float)$gt- greater than (int, float)$gte- greater than or equal to (int, float)$lt- less than (int, float)$lte- less than or equal to (int, float)
Using the $eq operator is equivalent to using the where filter.
Where filters only search embeddings where the key exists. If you search collection.get(where={"version": {"$ne": 1}}). Metadata that does not have the key version will not be returned.
Filtering by document contents#
In order to filter on document contents, you must supply a where_document filter dictionary to the query. We support two filtering keys: $contains and $not_contains. The dictionary must have the following structure:
Using logical operators#
You can also use the logical operators $and and $or to combine multiple filters.
An $and operator will return results that match all of the filters in the list.
An $or operator will return results that match any of the filters in the list.
Using inclusion operators ($in and $nin)#
The following inclusion operators are supported:
$in- a value is in predefined list (string, int, float, bool)$nin- a value is not in predefined list (string, int, float, bool)
An $in operator will return results where the metadata attribute is part of a provided list:
An $nin operator will return results where the metadata attribute is not part of a provided list:
Practical examples
For additional examples and a demo how to use the inclusion operators, please see provided notebook here
If an id is not found in the collection, an error will be logged and the update will be ignored. If documents are supplied without corresponding embeddings, the embeddings will be recomputed with the collection's embedding function.
If the supplied embeddings are not the same dimension as the collection, an exception will be raised.
Chroma also supports an upsert operation, which updates existing items, or adds them if they don't yet exist.
If an id is not present in the collection, the corresponding items will be created as per add. Items with existing ids will be updated as per update.
Deleting data from a collection#
Chroma supports deleting items from a collection by id using .delete. The embeddings, documents, and metadata associated with each item will be deleted. ⚠️ Naturally, this is a destructive operation, and cannot be undone.
.delete also supports the where filter. If no ids are supplied, it will delete all items in the collection that match the where filter.