Warning
V1 API Deprecation Notice: The V1 API will be removed in the upcoming v0.3.0 release.
Users currently using the V1 API (root package import) should migrate to the V2 API (github.com/amikos-tech/chroma-go/pkg/api/v2).
The V2 API offers feature parity with V1 plus additional capabilities.
For continued V1 support, please use v0.2.x releases.
A simple Chroma Vector Database client written in Go
Works with Chroma Version: v0.4.3 - v1.0.x
We invite users to visit the docs site for the library for more in-depth information: Chroma Go Docs
Note
v0.2.0 documentation is still being updated. Please consult the tests under pkg/api/v2 for more detailed usage
examples. We are working on updating the documentation with full usage examples (also feel free to contribute if you
have any examples you would like to share).
| Operation | V1 support | V2 support | 
|---|---|---|
| Create Tenant | ✅ | ✅ | 
| Get Tenant | ✅ | ✅ | 
| Create Database | ✅ | ✅ | 
| Get Database | ✅ | ✅ | 
| Delete Database | ❌ | ✅ | 
| Reset | ✅ | ✅ | 
| Heartbeat | ✅ | ✅ | 
| List Collections | ✅ | ✅ | 
| Count Collections | ✅ | ✅ | 
| Get Version | ✅ | ✅ | 
| Create Collection | ✅ | ✅ | 
| Delete Collection | ✅ | ✅ | 
| Collection Add | ✅ | ✅ | 
| Collection Get | ✅ | ✅ | 
| Collection Count | ✅ | ✅ | 
| Collection Query | ✅ | ✅ | 
| Collection Update | ✅ | ✅ | 
| Collection Upsert | ✅ | ✅ | 
| Collection Delete (delete documents) | ✅ | ✅ | 
| Modify Collection | ✅ | ⚒️ partial | 
Additional support features:
- ✅ Authentication (Basic, Token with Authorization header, Token with X-Chroma-Token header)
 - ✅ Private PKI and self-signed certificate support
 - ✅ Chroma Cloud support
 - 🔥✅ Structured Logging (V2 API only) - Injectable logger with Zap bridge for structured logging
 - ⚒️ Persistent Embedding Function support (coming soon) - automatically load embedding function from Chroma collection configuration
 - ⚒️ Persistent Client support (coming soon) - Run/embed full-featured Chroma in your go application without the need for Chroma server.
 
- 🔥✅ Default Embedding Support - Since 
0.2.0+, we also support the defaultall-MiniLM-L6-v2model 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
 
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
 - More coming soon...
 
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@maingo get github.com/amikos-tech/chroma-goImport v1:
import (
chroma "github.com/amikos-tech/chroma-go"
)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,minikubeandkubectlinstalled) 
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.Note
To delete the minikube cluster: minikube delete --profile chromago
- We create a new collection
 - Add documents using the default embedding function
 - Query the collection using the same embedding function
 - Delete documents from the collection
 
package main
import (
	"context"
	"fmt"
	"log"
	chroma "github.com/amikos-tech/chroma-go/pkg/api/v2"
)
func main() {
	// Create a new Chroma client
	client, err := chroma.NewHTTPClient()
	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
	col, err := client.GetOrCreateCollection(context.Background(), "col1",
		chroma.WithCollectionMetadataCreate(
			chroma.NewMetadata(
				chroma.NewStringAttribute("str", "hello"),
				chroma.NewIntAttribute("int", 1),
				chroma.NewFloatAttribute("float", 1.1),
			),
		),
	)
	if err != nil {
		log.Fatalf("Error creating collection: %s \n", err)
		return
	}
	err = col.Add(context.Background(),
		//chroma.WithIDGenerator(chroma.NewULIDGenerator()),
		chroma.WithIDs("1", "2"),
		chroma.WithTexts("hello world", "goodbye world"),
		chroma.WithMetadatas(
			chroma.NewDocumentMetadata(chroma.NewIntAttribute("int", 1)),
			chroma.NewDocumentMetadata(chroma.NewStringAttribute("str", "hello")),
		))
	if err != nil {
		log.Fatalf("Error adding collection: %s \n", err)
	}
	count, err := col.Count(context.Background())
	if err != nil {
		log.Fatalf("Error counting collection: %s \n", err)
		return
	}
	fmt.Printf("Count collection: %d\n", count)
	qr, err := col.Query(context.Background(), chroma.WithQueryTexts("say hello"))
	if err != nil {
		log.Fatalf("Error querying collection: %s \n", err)
		return
	}
	fmt.Printf("Query result: %v\n", qr.GetDocumentsGroups()[0][0])
	err = col.Delete(context.Background(), chroma.WithIDsDelete("1", "2"))
	if err != nil {
		log.Fatalf("Error deleting collection: %s \n", err)
		return
	}
}The V2 API client supports injectable loggers for structured logging. Here's a quick example using Zap:
package main
import (
	"context"
	"log"
	"go.uber.org/zap"
	chromalogger "github.com/amikos-tech/chroma-go/pkg/logger"
	chroma "github.com/amikos-tech/chroma-go/pkg/api/v2"
)
func main() {
	// Create a zap logger
	zapLogger, _ := zap.NewDevelopment()
	defer zapLogger.Sync()
	// Wrap it in the Chroma logger
	logger := chromalogger.NewZapLogger(zapLogger)
	// Create client with the logger
	client, err := chroma.NewHTTPClient(
		chroma.WithBaseURL("http://localhost:8000"),
		chroma.WithLogger(logger),
	)
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()
	// All client operations will now be logged with structured logging
	ctx := context.Background()
	collections, _ := client.ListCollections(ctx)
	// You can also log directly
	logger.Info("Retrieved collections",
		chromalogger.Int("count", len(collections)),
	)
	// For debug logging, use WithLogger with a debug-level logger
	// Note: WithDebug() is deprecated - use WithLogger instead
	devLogger, _ := chromalogger.NewDevelopmentZapLogger()
	debugClient, _ := chroma.NewHTTPClient(
		chroma.WithBaseURL("http://localhost:8000"),
		chroma.WithLogger(devLogger), // Use a logger with debug level enabled
	)
	defer debugClient.Close()
}See the logging documentation for more details.
make buildV1 API:
make testV2 API:
make test-v2make generate make lint-fixNote: Docker must be installed
make server- Official Chroma documentation
 - Chroma Helm chart for cloud-native deployments
 - Chroma Cookbook for examples and recipes