Collection
The Collection class represents a collection of embeddings in Chroma. It provides methods for adding, querying, updating, and deleting embeddings.
Properties
The name of the collection
The unique identifier of the collection
metadata
CollectionMetadata | undefined
Optional metadata associated with the collection
The embedding function used by this collection
configuration
CollectionConfiguration | undefined
The collection’s configuration
Methods
add
Add items to the collection.
await collection.add(params: AddRecordsParams): Promise<void>
Show AddRecordsParams properties
IDs of the items to add. Can be a single string or an array of strings
Optional embeddings of the items to add. Required if documents are not provided
Optional metadata of the items to add
Optional documents of the items to add. Required if embeddings are not provided
You must provide either embeddings or documents (which will be embedded automatically using the collection’s embedding function).
await collection.add({
ids: ["id1", "id2"],
embeddings: [[1, 2, 3], [4, 5, 6]],
metadatas: [{ "key": "value" }, { "key": "value" }],
documents: ["document1", "document2"]
});
query
Performs a query on the collection using the specified parameters.
await collection.query(params: QueryRecordsParams): Promise<MultiQueryResponse>
params
QueryRecordsParams
required
Show QueryRecordsParams properties
Optional query embeddings to use for the search
Optional query text(s) to search for in the collection
Number of results to return
Optional query condition to filter results based on metadata values
Optional query condition to filter results based on document content
Optional array of fields to include in the result (e.g., [“embeddings”, “metadatas”, “documents”, “distances”])
Optional IDs to filter on before querying
Error if neither queryEmbeddings nor queryTexts are provided
You must provide either queryEmbeddings or queryTexts.
const results = await collection.query({
queryTexts: "some text",
nResults: 10,
where: {"name": {"$eq": "John Doe"}},
include: ["metadatas", "documents"]
});
const results = await collection.query({
queryEmbeddings: [[0.1, 0.2, 0.3]],
nResults: 10,
where: {"name": {"$eq": "John Doe"}},
include: ["metadatas", "documents"]
});
get
Get items from the collection.
await collection.get(params?: BaseGetParams): Promise<GetResponse>
Show BaseGetParams properties
Optional IDs of the items to get
Optional where clause to filter items by
Optional limit on the number of items to get
Optional offset on the items to get
Optional list of items to include in the response
Optional where clause to filter items by document content
const response = await collection.get({
ids: ["id1", "id2"],
where: { "key": "value" },
limit: 10,
offset: 0,
include: ["embeddings", "metadatas", "documents"],
whereDocument: { "$contains": "value" }
});
update
Update items in the collection.
await collection.update(params: UpdateRecordsParams): Promise<void>
params
UpdateRecordsParams
required
Show UpdateRecordsParams properties
IDs of the items to update
Optional embeddings of the items to update
Optional metadata of the items to update
Optional documents of the items to update
await collection.update({
ids: ["id1", "id2"],
embeddings: [[1, 2, 3], [4, 5, 6]],
metadatas: [{ "key": "value" }, { "key": "value" }],
documents: ["document1", "document2"]
});
upsert
Upsert (insert or update) items to the collection.
await collection.upsert(params: UpsertRecordsParams): Promise<void>
params
UpsertRecordsParams
required
Same as AddRecordsParams
await collection.upsert({
ids: ["id1", "id2"],
embeddings: [[1, 2, 3], [4, 5, 6]],
metadatas: [{ "key": "value" }, { "key": "value" }],
documents: ["document1", "document2"]
});
delete
Deletes items from the collection.
await collection.delete(params?: DeleteParams): Promise<void>
Show DeleteParams properties
Optional ID or array of IDs of items to delete
Optional query condition to filter items to delete based on metadata values
Optional query condition to filter items to delete based on document content
Error if there is an issue deleting items
Example:
await collection.delete({
ids: "some_id",
where: {"name": {"$eq": "John Doe"}},
whereDocument: {"$contains": "search_string"}
});
count
Count the number of items in the collection.
await collection.count(): Promise<number>
const count = await collection.count();
console.log(`Collection has ${count} items`);
peek
Peek inside the collection to get a sample of items.
await collection.peek(params?: PeekParams): Promise<MultiGetResponse>
Show PeekParams properties
Number of results to return
Error if there is an issue executing the query
Example:
const results = await collection.peek({
limit: 10
});
modify
Modify the collection name or metadata.
await collection.modify(params: {
name?: string;
metadata?: CollectionMetadata;
configuration?: UpdateCollectionConfiguration;
}): Promise<CollectionParams>
Optional new name for the collection
Optional new metadata for the collection
configuration
UpdateCollectionConfiguration
Optional new configuration for the collection
await collection.modify({
name: "new_collection_name",
metadata: { "description": "Updated description" }
});
fork
Forks the collection into a new collection with a new name.
await collection.fork(params: ForkCollectionParams): Promise<Collection>
params
ForkCollectionParams
required
Show ForkCollectionParams properties
The name for the new forked collection
Error if there is an issue forking the collection
Example:
const newCollection = await collection.fork({
newName: "my_forked_collection"
});