Collection

Collection Methods

conditional

Start a collection-scoped conditional transaction. Conditional transactions read from a stable snapshot, buffer writes locally, and commit those writes with optimistic conflict detection. Use txn.commit() for manual transactions, or txn.run(callback, max_retries=3) to rerun the whole callback after retryable optimistic-concurrency conflicts. Limitations:

Transactions cannot span collections.
Nested transaction guarantees are not provided.
txn.query(...) is not supported.
Predicate deletes are not supported; transactional deletes must provide explicit IDs.
Reading an ID after buffering a write for that ID is an explicit transaction error.
Only one write per ID can be buffered in a transaction.
Filter reads protect only returned IDs.

count

Return the number of records in the collection.

add

Add records to the collection.

Union[str, IDs]

required

Record IDs to add.

Optional[Embeddings]

Embeddings to add. If None, embeddings are computed.

Union[Optional[Metadatas], List[Optional[Metadatas]], None]

Optional metadata for each record.

Union[str, IDs, None]

Optional documents for each record.

Optional[Embeddings]

Optional images for each record.

Union[str, IDs, None]

Optional URIs for loading images.

Raises:

ValueError: If embeddings and documents are both missing.
ValueError: If embeddings and documents are both provided.
ValueError: If lengths of provided fields do not match.
ValueError: If an ID already exists.

get

Retrieve records from the collection. If no filters are provided, returns records up to limit starting at offset.

Union[str, IDs, None]

If provided, only return records with these IDs.

Optional[Dict[Union[str, Literal[$and], Literal[$or]], Where]]

A Where filter used to filter based on metadata values.

Optional[int]

Maximum number of results to return.

Optional[int]

Number of results to skip before returning.

Optional[Dict[Where, Union[str, List[Dict[Where, Union[str, List[WhereDocument]]]]]]]

A WhereDocument filter used to filter based on K.DOCUMENT.

List[Literal[documents, embeddings, metadatas, distances, uris, data]]

Fields to include in results. Can contain “embeddings”, “metadatas”, “documents”, “uris”. Defaults to “metadatas” and “documents”.

Returns: Retrieved records and requested fields as a GetResult object.

peek

Return the first limit records from the collection.

int

Maximum number of records to return.

Returns: Retrieved records and requested fields.

query

Query for the K nearest neighbor records in the collection. This is a batch query API. Multiple queries can be performed at once by providing multiple embeddings, texts, or images.

query_1 = [0.1, 0.2, 0.3]
query_2 = [0.4, 0.5, 0.6]
results = collection.query(
    query_embeddings=[query_1, query_2],
    n_results=10,
)

If query_texts, query_images, or query_uris are provided, the collection’s embedding function will be used to create embeddings before querying the API. The ids, where, where_document, and include parameters are applied to all queries.

Optional[Embeddings]

Raw embeddings to query for.

Union[str, IDs, None]

Documents to embed and query against.

Optional[Embeddings]

Images to embed and query against.

Union[str, IDs, None]

URIs to be loaded and embedded.

Union[str, IDs, None]

Optional subset of IDs to search within.

int

Number of neighbors to return per query.

Optional[Dict[Union[str, Literal[$and], Literal[$or]], Where]]

Metadata filter.

Optional[Dict[Where, Union[str, List[Dict[Where, Union[str, List[WhereDocument]]]]]]]

Document content filter.

List[Literal[documents, embeddings, metadatas, distances, uris, data]]

Fields to include in results. Can contain “embeddings”, “metadatas”, “documents”, “uris”, “distances”. Defaults to “metadatas”, “documents”, “distances”.

Returns: Nearest neighbor results. Raises:

ValueError: If no query input is provided.
ValueError: If multiple query input types are provided.

modify

Update collection name, metadata, or configuration.

Optional[str]

New collection name.

Optional[Dict[str, Any]]

New metadata for the collection.

Optional[UpdateCollectionConfiguration]

New configuration for the collection.

update

Update existing records by ID. Records are provided in columnar format. If provided, the embeddings, metadatas, documents, and uris lists must be the same length. Entries in each list correspond to the same record.

ids = ["id1", "id2", "id3"]
embeddings = [[0.1, 0.2, 0.3], [0.4, 0.5, 0.6], [0.7, 0.8, 0.9]]
metadatas = [{"key": "value"}, {"key": "value"}, {"key": "value"}]
documents = ["document1", "document2", "document3"]
uris = ["uri1", "uri2", "uri3"]
collection.update(ids, embeddings, metadatas, documents, uris)

If embeddings are not provided, the embeddings will be computed based on documents using the collection’s embedding function.

Union[str, IDs]

required

Record IDs to update.

Optional[Embeddings]

Updated embeddings. If None, embeddings are computed.

Union[Optional[Metadatas], List[Optional[Metadatas]], None]

Updated metadata.

Union[str, IDs, None]

Updated documents.

Optional[Embeddings]

Updated images.

Union[str, IDs, None]

Updated URIs for loading images.

upsert

Create or update records by ID.

Union[str, IDs]

required

Record IDs to upsert.

Optional[Embeddings]

Embeddings to add or update. If None, embeddings are computed.

Union[Optional[Metadatas], List[Optional[Metadatas]], None]

Metadata to add or update.

Union[str, IDs, None]

Documents to add or update.

Optional[Embeddings]

Images to add or update.

Union[str, IDs, None]

URIs for loading images.

delete

Delete records by ID or filters. All documents that match the ids or where and where_document filters will be deleted.

Optional[IDs]

Record IDs to delete.

Optional[Dict[Union[str, Literal[$and], Literal[$or]], Where]]

Metadata filter.

Optional[Dict[Where, Union[str, List[Dict[Where, Union[str, List[WhereDocument]]]]]]]

Document content filter.

Raises:

ValueError: If no IDs or filters are provided.

Types

GetResult

Result payload for collection.get() operations. The returned records are in columnar form. Corresponding entries in each list correspond to the same record.

results = collection.get(ids=["id1", "id2", "id3"])
records = zip(results["ids"], results["documents"], results["metadatas"])
for id, document, metadata in records:
    print(id, document, metadata)

GetResult will only include ids and the fields specified in the include param when making the get() operation. Properties

IDs

Optional[Embeddings]

Optional[IDs]

Optional[Optional[Embeddings]]

Optional[List[Optional[Metadatas]]]

List[Literal[documents, embeddings, metadatas, distances, uris, data]]

QueryResult

Result payload for collection.query() operations. The returned records are batches of records in columnar form.

results = collection.query(query_embeddings=[batch_1, batch_2, ...])
batches = zip(results["ids"], results["documents"], results["metadatas"])

Each batch is a list of records in columnar form.

for batch in batches:
    records = zip(batch["ids"], batch["documents"], batch["metadatas"])
    for id, document, metadata in records:
        print(id, document, metadata)

QueryResult will only include ids and the fields specified in the include param when making the query() operation. Properties

List[IDs]

Optional[Embeddings]

Optional[List[IDs]]

Optional[List[Optional[Embeddings]]]

Optional[List[List[Optional[Metadatas]]]]

Optional[List[List[float]]]

List[Literal[documents, embeddings, metadatas, distances, uris, data]]

Self-Hosted Chroma

SDKs

Beta SDKs

APIs

Dictionary Syntax

Architecture

Collection Methods

conditional

count

add

get

peek

query

modify

update

upsert

delete

Types

GetResult

QueryResult

​Collection Methods

​conditional

​count

​add

​get

​peek

​query

​modify

​update

​upsert

​delete

​Types

​GetResult

​QueryResult

Collection Methods

conditional

count

add

get

peek

query

modify

update

upsert

delete

Types

GetResult

QueryResult