chroma

README

---
title: "Chroma"
lang: "en-US"
draft: false
description: "Learn about how to set up a VDP Chroma component https://github.com/instill-ai/instill-core"
---

The Chroma component is a data component that allows users to build and search vector datasets.
It can carry out the following tasks:

- [Batch Upsert](#batch-upsert)
- [Upsert](#upsert)
- [Query](#query)
- [Delete](#delete)
- [Create Collection](#create-collection)
- [Delete Collection](#delete-collection)



## Release Stage

`Alpha`



## Configuration

The component configuration is defined and maintained [here](https://github.com/instill-ai/component/blob/main/data/chroma/v0/config/definition.json).




## Setup




In order to communicate with Chroma, the following connection details need to be
provided. You may specify them directly in a pipeline recipe as key-value pairs
withing the component's `setup` block, or you can create a **Connection** from
the [**Integration Settings**](https://www.instill.tech/docs/vdp/integration)
page and reference the whole `setup` as `setup:
${connection.<my-connection-id>}`.

| Field | Field ID | Type | Note |
| :--- | :--- | :--- | :--- |
| API Key (required) | `api-key` | string | Fill in your Chroma API key |
| Chroma URL Endpoint (required) | `url` | string | Fill in your Chroma hosted public URL endpoint with port, e.g http://1.2.3:8000 |




## Supported Tasks

### Batch Upsert

Upsert multiple vector items into a collection, existing items will be updated


| Input | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Task ID (required) | `task` | string | `TASK_BATCH_UPSERT` |
| Collection Name (required) | `collection-name` | string | The name of the collection to upsert the item into |
| Array ID (required) | `array-id` | array[string] | The array of id |
| Array Metadata (required) | `array-metadata` | array[object] | The array of vector metadata |
| Array Vector (required) | `array-vector` | array[array] | The array of vector values |
| Array Document | `array-document` | array[string] | The array of document string values |
| Array URI | `array-uri` | array[string] | The array of uri |



| Output | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Status | `status` | string | Batch add status |






### Upsert

Upsert a vector item into a collection, existing item will be updated


| Input | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Task ID (required) | `task` | string | `TASK_UPSERT` |
| Collection Name (required) | `collection-name` | string | The name of the collection to upsert the item into |
| ID (required) | `id` | string | The ID of the item |
| Metadata (required) | `metadata` | object | The vector metadata |
| Vector (required) | `vector` | array[number] | An array of dimensions for the vector value |
| Document | `document` | string | The document string value |
| URI | `uri` | string | The uri of the item |



| Output | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Status | `status` | string | Add status |






### Query

Perform a vector search on a collection


| Input | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Task ID (required) | `task` | string | `TASK_QUERY` |
| Collection Name (required) | `collection-name` | string | The name of the collection to perform vector similarity search on |
| Vector (required) | `vector` | array[number] | An array of dimensions for the vector query. |
| N Results (required) | `n-results` | integer | The N amount of items to return from the vector search operation |
| Filter | `filter` | object | The metadata filter to be applied to the data with Chroma where filter, please refer to [using-where-filters](https://docs.trychroma.com/guides#using-where-filters) |
| Filter Document | `filter-document` | string | The document content filter to be applied to the data, please refer to [filtering-by-document-contents](https://docs.trychroma.com/guides#filtering-by-document-contents) |
| Fields | `fields` | array[string] | The fields to be returned from the vector search operation |



| Output | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Result | `result` | object | Result of the vector search operation |
| Status | `status` | string | Vector search status |






### Delete

Delete vector items from a collection


| Input | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Task ID (required) | `task` | string | `TASK_DELETE` |
| Collection Name (required) | `collection-name` | string | The name of the collection to delete the object from |
| ID | `id` | string | The ID of the item |
| Filter | `filter` | object | The metadata filter to be applied to the data with Chroma where filter, please refer to [using-where-filters](https://docs.trychroma.com/guides#using-where-filters) |
| Filter Document | `filter-document` | string | The document content filter to be applied to the data, please refer to [filtering-by-document-contents](https://docs.trychroma.com/guides#filtering-by-document-contents) |



| Output | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Status | `status` | string | Delete status |






### Create Collection

Create a collection


| Input | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Task ID (required) | `task` | string | `TASK_CREATE_COLLECTION` |
| Collection Name (required) | `collection-name` | string | The name of the collection to create |
| Config | `metadata` | object | The metadata of the collection. Please refer to [creating-inspecting-and-deleting-collection](https://docs.trychroma.com/guides#creating,-inspecting,-and-deleting-collections) |
| Configuration | `configuration` | object | The configuration of the collection. Please refer to [creating-inspecting-and-deleting-collection](https://docs.trychroma.com/guides#creating,-inspecting,-and-deleting-collections) |
| Get or Create | `get-or-create` | boolean | If true, the collection will be created if it does not exist |



| Output | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Status | `status` | string | Create collection status |






### Delete Collection

Delete a collection


| Input | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Task ID (required) | `task` | string | `TASK_DELETE_COLLECTION` |
| Collection Name (required) | `collection-name` | string | The name of the collection to delete |



| Output | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Status | `status` | string | Delete collection status |

Documentation

Index

• Constants
• func Init(bc base.Component) *component
• type BatchUpsertInput
• type BatchUpsertOutput
• type CreateCollectionInput
• type CreateCollectionOutput
• type CreateCollectionReq
• type CreateCollectionResp
• type Data
• type DeleteCollectionInput
• type DeleteCollectionOutput
• type DeleteCollectionResp
• type DeleteInput
• type DeleteOutput
• type DeleteReq
• type GetCollectionResp
• type QueryInput
• type QueryOutput
• type QueryReq
• type QueryResp
• type Result
• type UpsertInput
• type UpsertOutput
• type UpsertReq
• type UpsertResp

Constants

const (
	TaskDelete           = "TASK_DELETE"
	TaskBatchUpsert      = "TASK_BATCH_UPSERT"
	TaskUpsert           = "TASK_UPSERT"
	TaskQuery            = "TASK_QUERY"
	TaskDeleteCollection = "TASK_DELETE_COLLECTION"
	TaskCreateCollection = "TASK_CREATE_COLLECTION"
)

Functions

func Init

func Init(bc base.Component) *component

Types

type BatchUpsertInput

type BatchUpsertInput struct {
	CollectionName string           `json:"collection-name"`
	ArrayID        []string         `json:"array-id"`
	ArrayVector    [][]float64      `json:"array-vector"`
	ArrayMetadata  []map[string]any `json:"array-metadata"`
	ArrayURI       []string         `json:"array-uri"`
	ArrayDocument  []string         `json:"array-document"`
}

type BatchUpsertOutput

type BatchUpsertOutput struct {
	Status string `json:"status"`
}

type CreateCollectionInput

type CreateCollectionInput struct {
	CollectionName string         `json:"collection-name"`
	Configuration  map[string]any `json:"configuration"`
	Metadata       map[string]any `json:"metadata"`
	GetOrCreate    bool           `json:"get-or-create"`
}

type CreateCollectionOutput

type CreateCollectionOutput struct {
	Status string `json:"status"`
}

type CreateCollectionReq

type CreateCollectionReq struct {
	Name          string         `json:"name"`
	Configuration map[string]any `json:"configuration"`
	Metadata      map[string]any `json:"metadata"`
	GetOrCreate   bool           `json:"get_or_create"`
}

type CreateCollectionResp

type CreateCollectionResp struct {
	Detail []map[string]any `json:"detail"`
}

type Data

type Data struct {
	UpsertCount int      `json:"upsertCount"`
	UpsertIDs   []string `json:"upsertIds"`
}

type DeleteCollectionInput

type DeleteCollectionInput struct {
	CollectionName string `json:"collection-name"`
}

type DeleteCollectionOutput

type DeleteCollectionOutput struct {
	Status string `json:"status"`
}

type DeleteCollectionResp

type DeleteCollectionResp struct {
	Detail []map[string]any `json:"detail"`
}

type DeleteInput

type DeleteInput struct {
	CollectionName string         `json:"collection-name"`
	ID             string         `json:"id"`
	Filter         map[string]any `json:"filter"`
	FilterDocument map[string]any `json:"filter-document"`
}

type DeleteOutput

type DeleteOutput struct {
	Status string `json:"status"`
}

type DeleteReq

type DeleteReq struct {
	IDs           []string       `json:"ids"`
	Where         map[string]any `json:"where"`
	WhereDocument map[string]any `json:"where_document"`
}

type GetCollectionResp

type GetCollectionResp struct {
	ID string `json:"id"`

	Detail []map[string]any `json:"detail"`
}

type QueryInput

type QueryInput struct {
	CollectionName string         `json:"collection-name"`
	Vector         []float64      `json:"vector"`
	Filter         map[string]any `json:"filter"`
	FilterDocument map[string]any `json:"filter-document"`
	NResults       int            `json:"n-results"`
	Fields         []string       `json:"fields"`
}

type QueryOutput

type QueryOutput struct {
	Status string `json:"status"`
	Result Result `json:"result"`
}

type QueryReq

type QueryReq struct {
	QueryEmbeddings [][]float64    `json:"query_embeddings"`
	Where           map[string]any `json:"where"`
	WhereDocument   map[string]any `json:"where_document"`
	NResults        int            `json:"n_results"`
	Include         []string       `json:"include"`
}

type QueryResp

type QueryResp struct {
	IDs        [][]string         `json:"ids"`
	Distances  [][]float64        `json:"distances"`
	Metadatas  [][]map[string]any `json:"metadatas"`
	Embeddings [][][]float64      `json:"embeddings"`
	Documents  [][]string         `json:"documents"`
	Uris       [][]string         `json:"uris"`

	Detail []map[string]any `json:"detail"`
}

type Result

type Result struct {
	Ids      []string         `json:"ids"`
	Items    []map[string]any `json:"items"`
	Vectors  [][]float64      `json:"vectors"`
	Metadata []map[string]any `json:"metadata"`
}

type UpsertInput

type UpsertInput struct {
	CollectionName string         `json:"collection-name"`
	ID             string         `json:"id"`
	Vector         []float64      `json:"vector"`
	Metadata       map[string]any `json:"metadata"`
	Document       string         `json:"document"`
	URI            string         `json:"uri"`
}

type UpsertOutput

type UpsertOutput struct {
	Status string `json:"status"`
}

type UpsertReq

type UpsertReq struct {
	Embeddings [][]float64      `json:"embeddings"`
	Metadatas  []map[string]any `json:"metadatas"`
	Documents  []string         `json:"documents"`
	IDs        []string         `json:"ids"`
	Uris       []string         `json:"uris"`
}

type UpsertResp

type UpsertResp struct {
	Error   string `json:"error"`
	Message string `json:"message"`
}