Chroma Go

A simple Chroma Vector Database client written in Go

Works with Chroma Version: v0.4.3 - v0.5.x

We invite users to visit the docs site for the library for more in-depth information: Chroma Go Docs

Feature Parity with ChromaDB API

✅ Create Tenant
✅ Get Tenant
✅ Create Database
✅ Get Database
✅ Reset
✅ Heartbeat
✅ List Collections
✅ Count Collections
✅ Get Version
✅ Create Collection
✅ Delete Collection
✅ Collection Add
✅ Collection Get (partial without additional parameters)
✅ Collection Count
✅ Collection Query
✅ Collection Modify Embeddings
✅ Collection Update
✅ Collection Upsert
✅ Collection Delete - delete documents in collection
✅ Authentication (Basic, Token with Authorization header, Token with X-Chroma-Token header)
✅ Private PKI and self-signed certificate support

Embedding API and Models Support

🔥✅ Default Embedding Support - Since 0.2.0+, we also support the default all-MiniLM-L6-v2 model running on Onnx Runtime (ORT).
✅ OpenAI Embedding Support
✅ Cohere (including Multi-language support)
✅ Sentence Transformers (HuggingFace Inference API and [HFEI local server]())
✅ Google Gemini Embedding Support
🚫 Custom Embedding Function
✅ HuggingFace Embedding Inference Server Support
✅ Ollama Embedding Support
✅ Cloudflare Workers AI Embedding Support
✅ Together AI Embedding Support
✅ Voyage AI Embedding Support
✅ Mistral AI API Embedding Support
✅ Nomic AI Embedding Support
✅ Jina AI Embedding Support

Reranking Functions

From release 0.2.0 the Chroma Go client also supports Reranking functions. The following are supported:

✅ Cohere
✅ Jina AI
✅ HuggingFace Embedding Inference Server Reranker

Installation

[!IMPORTANT]
There are many new changes leading up to v0.2.0, as documented below. If you'd like to use them please install the latest version of the client.
go get github.com/amikos-tech/chroma-go@main

go get github.com/amikos-tech/chroma-go

Import:

import (
chroma "github.com/amikos-tech/chroma-go"
)

Usage

Ensure you have a running instance of Chroma running. We recommend one of the two following options:

Official documentation
If you are a fan of Kubernetes, you can use the Helm chart (Note: You will need Docker, minikube and kubectl installed)

The Setup (Cloud-native):

minikube start --profile chromago
minikube profile chromago
helm repo add chroma https://amikos-tech.github.io/chromadb-chart/
helm repo update
helm install chroma chroma/chromadb --set chromadb.allowReset=true,chromadb.apiVersion=0.4.5

|Note: To delete the minikube cluster: minikube delete --profile chromago

Getting Started

Consider the following example where:

We create a new collection
Add documents using the default embedding function
Query the collection using the same embedding function

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    chroma "github.com/amikos-tech/chroma-go"
    "github.com/amikos-tech/chroma-go/collection"
    openai "github.com/amikos-tech/chroma-go/pkg/embeddings/openai"
    "github.com/amikos-tech/chroma-go/types"
)

func main() {
    // Create a new Chroma client
    client,err := chroma.NewClient(chroma.WithBasePath("http://localhost:8000"))
    if err != nil {
        log.Fatalf("Error creating client: %s \n", err)
        return
    }
    // Close the client to release any resources such as local embedding functions
    defer func() {
        err = client.Close()
        if err != nil {
            log.Fatalf("Error closing client: %s \n", err)
        }
    }()

    // Create a new collection with options. We don't provide an embedding function here, so the default embedding function will be used
    newCollection, err := client.NewCollection(
        context.TODO(),
        "test-collection",
        collection.WithMetadata("key1", "value1"),
        collection.WithHNSWDistanceFunction(types.L2),
    )
    if err != nil {
        log.Fatalf("Error creating collection: %s \n", err)
    }

    // Create a new record set with to hold the records to insert
    rs, err := types.NewRecordSet(
        types.WithEmbeddingFunction(newCollection.EmbeddingFunction), // we pass the embedding function from the collection
        types.WithIDGenerator(types.NewULIDGenerator()),
    )
    if err != nil {
        log.Fatalf("Error creating record set: %s \n", err)
    }
    // Add a few records to the record set
    rs.WithRecord(types.WithDocument("My name is John. And I have two dogs."), types.WithMetadata("key1", "value1"))
    rs.WithRecord(types.WithDocument("My name is Jane. I am a data scientist."), types.WithMetadata("key2", "value2"))

    // Build and validate the record set (this will create embeddings if not already present)
    _, err = rs.BuildAndValidate(context.TODO())
    if err != nil {
        log.Fatalf("Error validating record set: %s \n", err)
    }

    // Add the records to the collection
    _, err = newCollection.AddRecords(context.Background(), rs)
    if err != nil {
        log.Fatalf("Error adding documents: %s \n", err)
    }

    // Count the number of documents in the collection
    countDocs, qrerr := newCollection.Count(context.TODO())
    if qrerr != nil {
        log.Fatalf("Error counting documents: %s \n", qrerr)
    }

    // Query the collection
    fmt.Printf("countDocs: %v\n", countDocs) //this should result in 2
    qr, qrerr := newCollection.Query(context.TODO(), []string{"I love dogs"}, 5, nil, nil, nil)
    if qrerr != nil {
        log.Fatalf("Error querying documents: %s \n", qrerr)
    }
    fmt.Printf("qr: %v\n", qr.Documents[0][0]) //this should result in the document about dogs
}

Development

Build

make build

Test

make test

Generate ChromaDB API Client

make generate

Lint

make lint-fix

Local Server

Note: Docker must be installed

make server

References

Official Chroma documentation
Chroma Helm chart for cloud-native deployments
Chroma Cookbook for examples and recipes

amikos-tech / chroma-go

readme