Collection

The Collection class represents a collection of embeddings in Chroma. It provides methods for adding, querying, updating, and deleting embeddings.

Properties

string

The name of the collection

string

The unique identifier of the collection

CollectionMetadata | undefined

Optional metadata associated with the collection

IEmbeddingFunction

The embedding function used by this collection

CollectionConfiguration | undefined

The collection’s configuration

Methods

add

Add items to the collection.

await collection.add(params: AddRecordsParams): Promise<void>

Parameters:

AddRecordsParams

required

Show AddRecordsParams properties

ID | IDs

required

IDs of the items to add. Can be a single string or an array of strings

Embedding | Embeddings

Optional embeddings of the items to add. Required if documents are not provided

Metadata | Metadatas

Optional metadata of the items to add

Document | Documents

Optional documents of the items to add. Required if embeddings are not provided

Returns: Promise that resolves when items are added

You must provide either embeddings or documents (which will be embedded automatically using the collection’s embedding function).

Example:

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>

Parameters:

QueryRecordsParams

required

Show QueryRecordsParams properties

Embedding | Embeddings

Optional query embeddings to use for the search

string | string[]

Optional query text(s) to search for in the collection

number

default:10

Number of results to return

Where

Optional query condition to filter results based on metadata values

WhereDocument

Optional query condition to filter results based on document content

IncludeEnum[]

Optional array of fields to include in the result (e.g., [“embeddings”, “metadatas”, “documents”, “distances”])

IDs

Optional IDs to filter on before querying

Returns: Promise resolving to MultiQueryResponse Throws: Error if neither queryEmbeddings nor queryTexts are provided

You must provide either queryEmbeddings or queryTexts.

Example with query text:

const results = await collection.query({
  queryTexts: "some text",
  nResults: 10,
  where: {"name": {"$eq": "John Doe"}},
  include: ["metadatas", "documents"]
});

Example with query embeddings:

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>

Parameters:

BaseGetParams

Show BaseGetParams properties

ID | IDs

Optional IDs of the items to get

Where

Optional where clause to filter items by

number

Optional limit on the number of items to get

number

Optional offset on the items to get

IncludeEnum[]

Optional list of items to include in the response

WhereDocument

Optional where clause to filter items by document content

Returns: Promise resolving to GetResponse Example:

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>

Parameters:

UpdateRecordsParams

required

Show UpdateRecordsParams properties

ID | IDs

required

IDs of the items to update

Embedding | Embeddings

Optional embeddings of the items to update

Metadata | Metadatas

Optional metadata of the items to update

Document | Documents

Optional documents of the items to update

Returns: Promise that resolves when items are updated Example:

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>

Parameters:

UpsertRecordsParams

required

Same as AddRecordsParams

Returns: Promise that resolves when items are upserted Example:

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>

Parameters:

DeleteParams

Show DeleteParams properties

ID | IDs

Optional ID or array of IDs of items to delete

Where

Optional query condition to filter items to delete based on metadata values

WhereDocument

Optional query condition to filter items to delete based on document content

Returns: Promise that resolves when items are deleted Throws: 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>

Returns: Promise resolving to the number of items in the collection Example:

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>

Parameters:

PeekParams

Show PeekParams properties

number

default:10

Number of results to return

Returns: Promise resolving to the query results Throws: 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>

Parameters:

object

required

Show properties

string

Optional new name for the collection

CollectionMetadata

Optional new metadata for the collection

UpdateCollectionConfiguration

Optional new configuration for the collection

Returns: Promise resolving to the updated collection parameters Example:

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>

Parameters:

ForkCollectionParams

required

Show ForkCollectionParams properties

string

required

The name for the new forked collection

Returns: Promise resolving to the new forked Collection object Throws: Error if there is an issue forking the collection Example:

const newCollection = await collection.fork({
  newName: "my_forked_collection"
});

Python Client

JavaScript Client

Go Client

CLI

Collection

Collection

Properties

Methods

add

query

get

update

upsert

delete

count

peek

modify

fork

​Collection

​Properties

​Methods

​add

​query

​get

​update

​upsert

​delete

​count

​peek

​modify

​fork

Collection

Properties

Methods

add

query

get

update

upsert

delete

count

peek

modify

fork