ChromaDB Go Client

https://go-client.chromadb.dev
Admin
An experimental Go client for ChromaDB, providing functionalities for managing collections, adding,...
Tokens:15,682
Snippets:95
Trust Score:5.3
Update:10 months ago
Show doc for...
Tokens:
Raw
### Install Chroma Go Client

Source: https://go-client.chromadb.dev/index

Add the Chroma Go client library to your Go project using the go get command. This is the initial step to start using the client.

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

--------------------------------

### Go: Chroma Cloud Authentication

Source: https://go-client.chromadb.dev/auth

Shows how to authenticate with Chroma Cloud using an API key. This is the recommended method for cloud deployments. Requires the `context` package.

```go
package main

import (
    "context"
    "log"
    v2 "github.com/amikos-tech/chroma-go/pkg/api/v2"
)

func main() {
    client, err := v2.NewCloudClient(
        v2.WithCloudAPIKey("your-api-key"),
    )
    if err != nil {
        log.Fatal(err)
    }

    if err := client.Heartbeat(context.TODO()); err != nil {
        log.Fatal(err)
    }
}
```

--------------------------------

### Go: Basic Authentication for Chroma API v1 (Legacy)

Source: https://go-client.chromadb.dev/auth

Demonstrates basic authentication for Chroma's legacy API v1. This method uses a username and password. It requires the `chroma-go` library and `context`.

```go
package main

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

func main() {
    client, err := chroma.NewClient(
        chroma.WithBasePath("http://localhost:8000"),
        chroma.WithAuth(types.NewBasicAuthCredentialsProvider("admin", "password")),
    )
    if err != nil {
        log.Fatal(err)
    }

    if _, err := client.Heartbeat(context.TODO()); err != nil {
        log.Fatal(err)
    }
}
```

--------------------------------

### Add and Retrieve Documents from Chroma Collection

Source: https://go-client.chromadb.dev/index

Demonstrates adding documents with associated metadata and IDs to a ChromaDB collection, and then retrieving them. This example uses OpenAI embeddings and requires a running Chroma instance and an OpenAI API key.

```go
package main

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

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

func main() {
    ctx := context.Background()
    client, err := chroma.NewClient() //connects to localhost:8000
    if err !=nil{
        log.Fatalf("Failed to create client: %v", err)
    }

    openaiEf, err := openai.NewOpenAIEmbeddingFunction(os.Getenv("OPENAI_API_KEY"))
    if err != nil {
        log.Fatalf("Error creating OpenAI embedding function: %s \n", err)
    }
    // Get the collection we created earlier
    collection, err := client.GetCollection(ctx, "my-collection", openaiEf)
    if err != nil {
        log.Fatalf("Failed to create collection: %v", err)
        return
    }
    _, err = collection.Add(context.TODO(), nil, []map[string]interface{}{{"key1": "value1"}}, []string{"My name is John and I have three dogs."}, []string{"ID1"})
    if err != nil {
        log.Fatalf("Error adding documents: %v\n", err)
        return
    }
    data, err := collection.Get(context.TODO(), nil, nil, nil, nil)
    if err != nil {
        log.Fatalf("Error getting documents: %v\n", err)
        return
    }
    // see GetResults struct for more details
    fmt.Printf("Collection data: %v\n", data)
}
```

--------------------------------

### Migrate ChromaDB Go Client from WithDebug to WithLogger

Source: https://go-client.chromadb.dev/logging

Illustrates the migration from the deprecated `WithDebug()` option to the recommended `WithLogger()` option for enabling debug logging in the ChromaDB Go client. The 'Before' example shows the deprecated usage, while the 'After' example demonstrates how to obtain a development Zap logger and pass it to `WithLogger()` for equivalent functionality.

```go
// Before (DEPRECATED):
client, err := v2.NewHTTPClient(
    v2.WithBaseURL("http://localhost:8000"),
    v2.WithDebug(), // DEPRECATED - only prints a warning now
)


```

```go
// After (RECOMMENDED):
// Use WithLogger with a debug-level logger
logger, _ := chromalogger.NewDevelopmentZapLogger()
client, err := v2.NewHTTPClient(
    v2.WithBaseURL("http://localhost:8000"),
    v2.WithLogger(logger),
)
```

--------------------------------

### Go Jina AI Reranker Usage Example

Source: https://go-client.chromadb.dev/rerankers

Provides a practical example of using the Jina AI reranker with the Go ChromaDB client. It demonstrates how to instantiate the reranker, providing an API key obtained from Jina AI. The code then calls the Rerank method and prints the reranking scores and original indices for each document. Requires the JINA_API_KEY environment variable.

```go
package main

import (
    "context"
    "fmt"
    jina "github.com/amikos-tech/chroma-go/pkg/rerankings/jina"
    "os"
)

func main() {
    var query = "What is the capital of the United States?"
    var results = []string{
        "Carson City is the capital city of the American state of Nevada.",
        "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean that are a political division controlled by the United States. Its capital is Saipan.",
        "Charlotte Amalie is the capital and largest city of the United States Virgin Islands. It has about 20,000 people. The city is on the island of Saint Thomas.",
        "Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States.",
        "Capital punishment (the death penalty) has existed in the United States since before the United States was a country.",
    }

    rf, err := jina.NewJinaRerankingFunction(jina.WithAPIKey(os.Getenv("JINA_API_KEY")))
    if err != nil {
        fmt.Printf("Error creating Jina reranking function: %s \n", err)
    }

    res, err := rf.Rerank(context.Background(), query, results)
    if err != nil {
        fmt.Printf("Error reranking: %s \n", err)
    }

    for _, rs := range res[rf.ID()] {
        fmt.Printf("Rank: %f, Index: %d\n", rs.Rank, rs.Index)
    }
}

```

--------------------------------

### Go: Custom Headers Authentication for Chroma API v1 (Legacy)

Source: https://go-client.chromadb.dev/auth

Shows how to set custom headers for authentication with Chroma's legacy API v1. This allows for flexible authentication configurations. Requires `chroma-go` and `context`.

```go
package main

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

func main() {
    headers := map[string]string{
        "Authorization": "Bearer custom-token",
        "X-Custom-Header": "custom-value",
    }

    client, err := chroma.NewClient(
        chroma.WithBasePath("http://localhost:8000"),
        chroma.WithDefaultHeaders(headers),
    )
    if err != nil {
        log.Fatal(err)
    }

    if _, err := client.Heartbeat(context.TODO()); err != nil {
        log.Fatal(err)
    }
}
```

--------------------------------

### Go: Basic Authentication for Chroma API v2

Source: https://go-client.chromadb.dev/auth

Demonstrates how to authenticate with Chroma's API v2 using basic authentication. This method requires a username and password. It uses the `chroma-go` library and requires the `context` package for API calls.

```go
package main

import (
    "context"
    "log"
    v2 "github.com/amikos-tech/chroma-go/pkg/api/v2"
)

func main() {
    client, err := v2.NewHTTPClient(
        v2.WithBaseURL("http://localhost:8000"),
        v2.WithAuth(v2.NewBasicAuthCredentialsProvider("admin", "password")),
    )
    if err != nil {
        log.Fatal(err)
    }

    if err := client.Heartbeat(context.TODO()); err != nil {
        log.Fatal(err)
    }
}
```

--------------------------------

### Go: X-Chroma-Token Authentication for Chroma API v1 (Legacy)

Source: https://go-client.chromadb.dev/auth

Illustrates authentication with the `X-Chroma-Token` header for Chroma's legacy API v1. This method uses a specific token header. Requires `chroma-go`, `types`, and `context`.

```go
package main

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

func main() {
    client, err := chroma.NewClient(
        chroma.WithBasePath("http://localhost:8000"),
        chroma.WithAuth(types.NewTokenAuthCredentialsProvider("my-token", types.XChromaTokenHeader)),
    )
    if err != nil {
        log.Fatal(err)
    }

    if _, err := client.Heartbeat(context.TODO()); err != nil {
        log.Fatal(err)
    }
}
```

--------------------------------

### Go: Custom Headers Authentication for Chroma API v2

Source: https://go-client.chromadb.dev/auth

Demonstrates setting custom headers for authentication with Chroma's API v2. This is useful for non-standard authentication schemes or when passing additional metadata. Requires `context`.

```go
package main

import (
    "context"
    "log"
    v2 "github.com/amikos-tech/chroma-go/pkg/api/v2"
)

func main() {
    headers := map[string]string{
        "Authorization": "Bearer custom-token",
        "X-Custom-Header": "custom-value",
    }

    client, err := v2.NewHTTPClient(
        v2.WithBaseURL("http://localhost:8000"),
        v2.WithDefaultHeaders(headers),
    )
    if err != nil {
        log.Fatal(err)
    }

    if err := client.Heartbeat(context.TODO()); err != nil {
        log.Fatal(err)
    }
}
```

--------------------------------

### Run Local HFEI Reranker Server

Source: https://go-client.chromadb.dev/rerankers

This command starts a local Hugging Face Inference (HFEI) reranker server using Docker. It maps port 8080 on the host to port 80 in the container, mounts the local 'data' directory to '/data' inside the container, and specifies the model to use (BAAI/bge-reranker-base). Ensure Docker is installed and accessible.

```bash
docker run --rm -p 8080:80 -v $PWD/data:/data --platform linux/amd64 ghcr.io/huggingface/text-embeddings-inference:cpu-latest --model-id BAAI/bge-reranker-base

```

--------------------------------

### Go: X-Chroma-Token Authentication for Chroma API v2

Source: https://go-client.chromadb.dev/auth

Illustrates authentication with Chroma's API v2 using the `X-Chroma-Token` header. This is an alternative token-based authentication method. The `XChromaTokenHeader` constant defines the specific header. Requires `context`.

```go
package main

import (
    "context"
    "log"
    v2 "github.com/amikos-tech/chroma-go/pkg/api/v2"
)

func main() {
    client, err := v2.NewHTTPClient(
        v2.WithBaseURL("http://localhost:8000"),
        v2.WithAuth(v2.NewTokenAuthCredentialsProvider("my-token", v2.XChromaTokenHeader)),
    )
    if err != nil {
        log.Fatal(err)
    }

    if err := client.Heartbeat(context.TODO()); err != nil {
        log.Fatal(err)
    }
}
```

--------------------------------

### HuggingFace Inference API Go Example

Source: https://go-client.chromadb.dev/embeddings

Embeds documents using the HuggingFace Inference API. Requires the HUGGINGFACE_API_KEY environment variable. It takes a list of strings (documents) as input and returns their embeddings.

```go
package main

import (
    "context"
    "fmt"
    "os"

    huggingface "github.com/amikos-tech/chroma-go/pkg/embeddings/hf"
)

func main() {
    ef := huggingface.NewHuggingFaceEmbeddingFunction(os.Getenv("HUGGINGFACE_API_KEY"), "sentence-transformers/all-MiniLM-L6-v2")
    documents := []string{
        "Document 1 content here",
    }
    resp, reqErr := ef.EmbedDocuments(context.Background(), documents)
    if reqErr != nil {
        fmt.Printf("Error embedding documents: %s \n", reqErr)
    }
    fmt.Printf("Embedding response: %v \n", resp)
}
```

--------------------------------

### Cohere Embeddings with Go

Source: https://go-client.chromadb.dev/embeddings

Provides an example of using the Cohere embedding API with the ChromaDB Go client. It demonstrates initializing the Cohere embedding function using `cohere.NewCohereEmbeddingFunction` and requires the `COHERE_API_KEY` environment variable for authentication. The function then embeds a list of documents.

```go
package main

import (
    "context"
    "fmt"
    "os"

    cohere "github.com/amikos-tech/chroma-go/pkg/embeddings/cohere"
)

func main() {
    ef := cohere.NewCohereEmbeddingFunction(os.Getenv("COHERE_API_KEY"))
    documents := []string{
        "Document 1 content here",
    }
    resp, reqErr := ef.EmbedDocuments(context.Background(), documents)
    if reqErr != nil {
        fmt.Printf("Error embedding documents: %s \n", reqErr)
    }
    fmt.Printf("Embedding response: %v \n", resp)
}
```

--------------------------------

### Go: Bearer Token Authentication for Chroma API v2

Source: https://go-client.chromadb.dev/auth

Shows how to authenticate with Chroma's API v2 using a Bearer token. This is a common method for token-based authentication. The `AuthorizationTokenHeader` constant specifies the header to use. Requires `context`.

```go
package main

import (
    "context"
    "log"
    v2 "github.com/amikos-tech/chroma-go/pkg/api/v2"
)

func main() {
    client, err := v2.NewHTTPClient(
        v2.WithBaseURL("http://localhost:8000"),
        v2.WithAuth(v2.NewTokenAuthCredentialsProvider("my-token", v2.AuthorizationTokenHeader)),
    )
    if err != nil {
        log.Fatal(err)
    }

    if err := client.Heartbeat(context.TODO()); err != nil {
        log.Fatal(err)
    }
}
```

--------------------------------

### Ollama Embedding Go Example

Source: https://go-client.chromadb.dev/embeddings

Integrates with a local Ollama server for embeddings. Assumes Ollama is running at http://127.0.0.1:11434 and uses the 'nomic-embed-text' model by default. It accepts a list of documents and returns their embeddings.

```go
package main

import (
    "context"
    "fmt"
    ollama "github.com/amikos-tech/chroma-go/pkg/embeddings/ollama"
)

func main() {
    documents := []string{
        "Document 1 content here",
        "Document 2 content here",
    }
    // the `/api/embeddings` endpoint is automatically appended to the base URL
    ef, err := ollama.NewOllamaEmbeddingFunction(ollama.WithBaseURL("http://127.0.0.1:11434"), ollama.WithModel("nomic-embed-text"))
    if err != nil {
        fmt.Printf("Error creating Ollama embedding function: %s \n", err)
    }
    resp, err := ef.EmbedDocuments(context.Background(), documents)
    if err != nil {
        fmt.Printf("Error embedding documents: %s \n", err)
    }
    fmt.Printf("Embedding response: %v \n", resp)
}
```

--------------------------------

### HuggingFace Embedding Inference Server Go Example

Source: https://go-client.chromadb.dev/embeddings

Connects to a locally running HuggingFace Embedding Inference Server to embed documents. Requires the server to be accessible at the specified URL (defaulting to http://localhost:8001/embed). Takes a list of strings (documents) and returns their embeddings.

```go
package main

import (
    "context"
    "fmt"

    huggingface "github.com/amikos-tech/chroma-go/hf"
)

func main() {
    ef, err := huggingface.NewHuggingFaceEmbeddingInferenceFunction("http://localhost:8001/embed") //set this to the URL of the HuggingFace Embedding Inference Server
    if err != nil {
        fmt.Printf("Error creating HuggingFace embedding function: %s \n", err)
    }
    documents := []string{
        "Document 1 content here",
    }
    resp, reqErr := ef.EmbedDocuments(context.Background(), documents)
    if reqErr != nil {
        fmt.Printf("Error embedding documents: %s \n", reqErr)
    }
    fmt.Printf("Embedding response: %v \n", resp)
}
```

--------------------------------

### Together AI Embedding Go Example

Source: https://go-client.chromadb.dev/embeddings

Embeds documents using Together AI. Requires a Together AI account and API key set in the TOGETHER_API_KEY environment variable. Uses 'togethercomputer/m2-bert-80M-2k-retrieval' as the default model. Accepts documents and returns their embeddings.

```go
package main

import (
    "context"
    "fmt"
    t "github.com/amikos-tech/chroma-go/pkg/embeddings/together"
)

func main() {
    documents := []string{
        "Document 1 content here",
        "Document 2 content here",
    }
    // Make sure that you have the `TOGETHER_API_KEY` set in your environment
    ef, err := t.NewTogetherEmbeddingFunction(t.WithEnvAPIKey(), t.WithDefaultModel("togethercomputer/m2-bert-80M-2k-retrieval"))
    if err != nil {
        fmt.Printf("Error creating Together embedding function: %s \n", err)
    }
    resp, err := ef.EmbedDocuments(context.Background(), documents)
    if err != nil {
        fmt.Printf("Error embedding documents: %s \n", err)
    }
    fmt.Printf("Embedding response: %v \n", resp)
}
```

--------------------------------

### Go: Bearer Token Authentication for Chroma API v1 (Legacy)

Source: https://go-client.chromadb.dev/auth

Shows Bearer token authentication for Chroma's legacy API v1. This uses the `AuthorizationTokenHeader` for token transmission. Requires `chroma-go`, `types`, and `context`.

```go
package main

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

func main() {
    client, err := chroma.NewClient(
        chroma.WithBasePath("http://localhost:8000"),
        chroma.WithAuth(types.NewTokenAuthCredentialsProvider("my-token", types.AuthorizationTokenHeader)),
    )
    if err != nil {
        log.Fatal(err)
    }

    if _, err := client.Heartbeat(context.TODO()); err != nil {
        log.Fatal(err)
    }
}
```

--------------------------------

### Go Cohere Reranker Usage Example

Source: https://go-client.chromadb.dev/rerankers

Demonstrates how to initialize and use the Cohere reranker with the Go ChromaDB client. It shows setting up the reranker with an API key and calling the Rerank method with a query and a list of results. The output displays the reranked results with their scores and original indices. Requires the COHERE_API_KEY environment variable.

```go
package main

import (
    "context"
    "fmt"
    cohere "github.com/amikos-tech/chroma-go/pkg/rerankings/cohere"
    "os"
)

func main() {
    var query = "What is the capital of the United States?"
    var results = []string{
        "Carson City is the capital city of the American state of Nevada.",
        "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean that are a political division controlled by the United States. Its capital is Saipan.",
        "Charlotte Amalie is the capital and largest city of the United States Virgin Islands. It has about 20,000 people. The city is on the island of Saint Thomas.",
        "Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States.",
        "Capital punishment (the death penalty) has existed in the United States since before the United States was a country.",
    }

    rf, err := cohere.NewCohereRerankingFunction(cohere.WithAPIKey(os.Getenv("COHERE_API_KEY")))
    if err != nil {
        fmt.Printf("Error creating Cohere reranking function: %s \n", err)
    }

    res, err := rf.Rerank(context.Background(), query, results)
    if err != nil {
        fmt.Printf("Error reranking: %s \n", err)
    }

    for _, rs := range res[rf.ID()] {
        fmt.Printf("Rank: %f, Index: %d\n", rs.Rank, rs.Index)
    }
}

```

--------------------------------

### CRUD Operations for Chroma Collections

Source: https://go-client.chromadb.dev/index

Perform Create, Read, Update, and Delete operations on ChromaDB collections using the Go client. This example demonstrates creating a collection with OpenAI embeddings, retrieving it, updating its name, and then deleting it. It requires an OpenAI API key and a running Chroma instance.

```go
package main

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

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

func main() {
    ctx := context.Background()
    client,err := chroma.NewClient() //connects to localhost:8000
    if err != nil {
        fmt.Printf("Failed to create client: %v", err)
    }

    openaiEf, err := openai.NewOpenAIEmbeddingFunction(os.Getenv("OPENAI_API_KEY"))
    if err != nil {
        log.Fatalf("Error creating OpenAI embedding function: %s \n", err)
    }

    // Create a new collection with OpenAI embedding function, L2 distance function and metadata
    _, err = client.CreateCollection(ctx, "my-collection", map[string]interface{}{"key1": "value1"}, true, openaiEf, types.L2)
    if err != nil {
        log.Fatalf("Failed to create collection: %v", err)
    }

    // Get collection
    collection, err := client.GetCollection(ctx, "my-collection", openaiEf)
    if err != nil {
        log.Fatalf("Failed to get collection: %v", err)
    }

    // Modify collection
    _, err = collection.Update(ctx, "new-collection",nil)
    if err != nil {
        log.Fatalf("Failed to update collection: %v", err)
    }

    // Delete collection
    _, err = client.DeleteCollection(ctx, "new-collection")
    if err != nil {
        log.Fatalf("Failed to delete collection: %v", err)
    }
}
```

--------------------------------

### OpenAI Embeddings with Go

Source: https://go-client.chromadb.dev/embeddings

Shows how to integrate OpenAI's embedding API using the ChromaDB Go client. This example highlights the use of `openai.NewOpenAIEmbeddingFunction` with options like `WithModel` to specify the embedding model (e.g., `TextEmbedding3Large`) and `WithBaseURL` for custom API endpoints. It requires setting the `OPENAI_API_KEY` environment variable for authentication.

```go
package main

import (
    "context"
    "fmt"
    "os"

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

func main() {
    ef, efErr := openai.NewOpenAIEmbeddingFunction(os.Getenv("OPENAI_API_KEY"), openai.WithModel(openai.TextEmbedding3Large))
    if efErr != nil {
        fmt.Printf("Error creating OpenAI embedding function: %s \n", efErr)
    }
    documents := []string{
        "Document 1 content here",
    }
    resp, reqErr := ef.EmbedDocuments(context.Background(), documents)
    if reqErr != nil {
        fmt.Printf("Error embedding documents: %s \n", reqErr)
    }
    fmt.Printf("Embedding response: %v \n", resp)
}
```

--------------------------------

### Safe Production Logging Configuration for ChromaDB

Source: https://go-client.chromadb.dev/logging

Provides examples of secure logging configurations for ChromaDB in production environments. It includes using `NoopLogger` to disable logging entirely or configuring a Zap logger with an `InfoLevel` or higher to avoid debug logs, which may contain sensitive information.

```go
// Production: Use NoopLogger to disable all logging
logger := chromalogger.NewNoopLogger()

// Or use a production logger with INFO level or higher
zapConfig := zap.NewProductionConfig()
zapConfig.Level = zap.NewAtomicLevelAt(zapcore.InfoLevel) // No debug logs
zapLogger, _ := zapConfig.Build()
logger := chromalogger.NewZapLogger(zapLogger)

client, err := v2.NewCloudClient(
    v2.WithLogger(logger),
    v2.WithCloudAPIKey("your-api-key"),
    v2.WithDatabaseAndTenant("database", "tenant"),
)

```

--------------------------------

### Cloudflare Workers AI Embedding Go Example

Source: https://go-client.chromadb.dev/embeddings

Utilizes Cloudflare Workers AI for document embeddings. Requires Cloudflare account, API Token, and Account ID set as environment variables (CF_API_TOKEN, CF_ACCOUNT_ID). Uses '@cf/baai/bge-small-en-v1.5' as the default model. Accepts documents and returns embeddings.

```go
package main

import (
    "context"
    "fmt"
    cf "github.com/amikos-tech/chroma-go/pkg/embeddings/cloudflare"
)

func main() {
    documents := []string{
        "Document 1 content here",
        "Document 2 content here",
    }
    // Make sure that you have the `CF_API_TOKEN` and `CF_ACCOUNT_ID` set in your environment
    ef, err := cf.NewCloudflareEmbeddingFunction(cf.WithEnvAPIToken(), cf.WithEnvAccountID(), cf.WithDefaultModel("@cf/baai/bge-small-en-v1.5"))
    if err != nil {
        fmt.Printf("Error creating Cloudflare embedding function: %s \n", err)
    }
    resp, err := ef.EmbedDocuments(context.Background(), documents)
    if err != nil {
        fmt.Printf("Error embedding documents: %s \n", err)
    }
    fmt.Printf("Embedding response: %v \n", resp)
}
```

--------------------------------

### Create Go ChromaDB Client with Options

Source: https://go-client.chromadb.dev/client

Demonstrates how to create a new ChromaDB client instance using various configuration options. Supports setting base path, tenant, database, default headers, and SSL certificates. Requires the `chroma-go` library.

```go
package main

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

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

func main() {
    client, err := chroma.NewClient(
        chroma.WithBasePath("http://localhost:8000"),
        chroma.WithTenant("my_tenant"),
        chroma.WithDatabase("my_db"),
        // chroma.WithDebug(true) is deprecated - use WithLogger instead for debug output
        chroma.WithDefaultHeaders(map[string]string{"Authorization": "Bearer my token"}),
        chroma.WithSSLCert("path/to/cert.pem"),
    )
    if err != nil {
        fmt.Printf("Failed to create client: %v", err)
    }
    // do something with client

    // Close the client to release any resources such as local embedding functions
    err = client.Close()
    if err != nil {
        fmt.Printf("Failed to close client: %v", err)
    }
}
```

--------------------------------

### Create Chroma Cloud Client in Go

Source: https://go-client.chromadb.dev/client

Demonstrates creating an instance of the Chroma Cloud Client. It shows how to configure authentication using an API key and specify the database and tenant. Error handling for client creation and version retrieval is included.

```Go
package main

import (
    "context"
    "fmt"
    chroma "github.com/amikos-tech/chroma-go/pkg/api/v2"
    "log"
)

func main() {
    c, err := chroma.NewHTTPClient(
        chroma.WithCloudAPIKey("my-api-key"),
        chroma.WithDatabaseAndTenant("team-uuid", "my-database"),
        // chroma.WithDebug() is deprecated - use WithLogger instead for debug output
    )
    if err != nil {
        log.Fatalf("Error creating client: %s \n", err)
    }
    v, err := c.GetVersion(context.Background())
    if err != nil {
        log.Fatalf("Error getting version: %s \n", err)
    }
    fmt.Printf("Chroma API Version: %s \n", v)
}
```

--------------------------------

### Create Chroma Local Client in Go

Source: https://go-client.chromadb.dev/client

Illustrates the creation of a Chroma Client for a local ChromaDB instance. It covers setting the base API URL, specifying the database and tenant, and adding custom default headers. Error handling for client instantiation and version fetching is provided.

```Go
package main

import (
    "context"
    "fmt"
    chroma "github.com/amikos-tech/chroma-go/pkg/api/v2"
    "log"
)

func main() {
    c, err := chroma.NewHTTPClient(
        chroma.WithBaseURL("http://localhost:8000"),
        chroma.WithDatabaseAndTenant("default_database", "default_tenant"),
        chroma.WithDefaultHeaders(map[string]string{"X-Custom-Header": "header-value"}),
        // chroma.WithDebug() is deprecated - use WithLogger instead for debug output
    )
    if err != nil {
        log.Fatalf("Error creating client: %s \n", err)
    }
    v, err := c.GetVersion(context.Background())
    if err != nil {
        log.Fatalf("Error getting version: %s \n", err)
    }
    fmt.Printf("Chroma API Version: %s \n", v)
}
```

--------------------------------

### Create New Chroma Client Instance

Source: https://go-client.chromadb.dev/index

Instantiate a new Chroma client, optionally configuring the base path to connect to a ChromaDB instance. Error handling is included for failed client creation.

```go
package main

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

func main() {
    client,err := chroma.NewClient(chroma.WithBasePath("http://localhost:8000"))
    if err != nil {
        fmt.Printf("Failed to create client: %v", err)
    }
    // do something with client
}
```

--------------------------------

### Configure ChromaDB Go Client with Zap Logging

Source: https://go-client.chromadb.dev/logging

Demonstrates how to set up a complete logging configuration for the ChromaDB Go client using the Zap logger. This includes configuring Zap's production settings, setting the log level to debug, defining output paths, and integrating with the ChromaDB client using `WithLogger`. It also shows how to add request-specific fields and handle potential errors during client creation and collection listing.

```go
package main

import (
    "context"
    "log"

    "go.uber.org/zap"
    "go.uber.org/zap/zapcore"

    chromalogger "github.com/amikos-tech/chroma-go/pkg/logger"
    v2 "github.com/amikos-tech/chroma-go/pkg/api/v2"
)

func main() {
    // Configure zap logger
    config := zap.NewProductionConfig()
    config.Level = zap.NewAtomicLevelAt(zapcore.DebugLevel)
    config.OutputPaths = []string{"stdout", "/var/log/chroma-client.log"}

    zapLogger, err := config.Build()
    if err != nil {
        log.Fatal(err)
    }
    defer zapLogger.Sync()

    // Create chroma logger
    logger := chromalogger.NewZapLogger(zapLogger)

    // Add request-specific fields
    requestLogger := logger.With(
        chromalogger.String("service", "my-app"),
        chromalogger.String("version", "1.0.0"),
    )

    // Create client with logger
    client, err := v2.NewHTTPClient(
        v2.WithBaseURL("http://localhost:8000"),
        v2.WithLogger(requestLogger),
    )
    if err != nil {
        log.Fatal(err)
    }

    // Use the client - all operations will be logged
    ctx := context.Background()
    collections, err := client.ListCollections(ctx)
    if err != nil {
        requestLogger.Error("Failed to list collections",
            chromalogger.ErrorField("error", err),
        )
        return
    }

    requestLogger.Info("Listed collections successfully",
        chromalogger.Int("count", len(collections)),
    )
}
```

--------------------------------

### Import Chroma Go Client Packages

Source: https://go-client.chromadb.dev/index

Import necessary packages from the chroma-go library to begin interacting with ChromaDB. This includes the main client, collection, and types packages.

```go
package main

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

--------------------------------

### Go: Create and Use a RecordSet for Adding Records in ChromaDB

Source: https://go-client.chromadb.dev/records

Demonstrates how to create a 'RecordSet' in Go using custom embedding functions and ID generators. It shows how to add multiple records with documents and metadata, and then build and validate them for insertion into ChromaDB.

```go
rs, rerr := types.NewRecordSet(
            types.WithEmbeddingFunction(types.NewConsistentHashEmbeddingFunction()),
            types.WithIDGenerator(types.NewULIDGenerator()),
        )
if err != nil {
    log.Fatalf("Error creating record set: %s", err)
}
// you can loop here to add multiple records
rs.WithRecord(types.WithDocument("Document 1 content"), types.WithMetadata("key1", "value1"))
rs.WithRecord(types.WithDocument("Document 2 content"), types.WithMetadata("key2", "value2"))
records, err = rs.BuildAndValidate(context.Background())

```

--------------------------------

### Configure ChromaDB Cloud Client with Zap Logger

Source: https://go-client.chromadb.dev/logging

Shows how to configure the ChromaDB Cloud client with a development Zap logger. This involves creating a Zap logger instance and passing it to the `NewCloudClient` function along with other necessary configurations like API key, database, and tenant.

```go
logger := chromalogger.NewDevelopmentZapLogger()

client, err := v2.NewCloudClient(
    v2.WithLogger(logger),
    v2.WithCloudAPIKey("your-api-key"),
    v2.WithDatabaseAndTenant("database", "tenant"),
)

```

--------------------------------

### Use Chroma-go WithLogger for Debugging (Recommended)

Source: https://go-client.chromadb.dev/logging

Demonstrates the recommended approach for enabling debug logging by using `WithLogger` with a development-level logger, replacing the deprecated `WithDebug()` method.

```go
// RECOMMENDED - Use WithLogger instead
logger, _ := chromalogger.NewDevelopmentZapLogger()
client, err := v2.NewHTTPClient(
    v2.WithBaseURL("http://localhost:8000"),
    v2.WithLogger(logger), // Provides debug-level logging
)
```

--------------------------------

### Chroma-go Context-Aware Logging

Source: https://go-client.chromadb.dev/logging

Demonstrates context-aware logging for distributed tracing and request correlation. Log messages can include context extracted from a `context.Context` object.

```go
ctx := context.WithValue(context.Background(), "trace-id", "abc123")

// The logger implementation can extract values from context
logger.InfoWithContext(ctx, "Processing request",
    chromalogger.String("operation", "query"),
)
```

--------------------------------

### Initialize Chroma-go NoopLogger

Source: https://go-client.chromadb.dev/logging

Creates a NoopLogger that discards all log messages. This is ideal for production environments where logging should be disabled to reduce overhead.

```go
logger := chromalogger.NewNoopLogger()

client, err := v2.NewHTTPClient(
    v2.WithBaseURL("http://localhost:8000"),
    v2.WithLogger(logger),
)
```

--------------------------------

### Chroma-go Structured Logging with Fields

Source: https://go-client.chromadb.dev/logging

Shows how to create a logger with persistent fields for structured logging. The `With` method allows attaching context like `request_id` and `user_id` to subsequent log messages.

```go
logger := chromalogger.NewDevelopmentZapLogger()

// Create a logger with persistent fields
requestLogger := logger.With(
    chromalogger.String("request_id", "123"),
    chromalogger.String("user_id", "user-456"),
)

client, err := v2.NewHTTPClient(
    v2.WithBaseURL("http://localhost:8000"),
    v2.WithLogger(requestLogger),
)
```

--------------------------------

### Query Documents in ChromaDB Collection using Go

Source: https://go-client.chromadb.dev/index

This Go code snippet demonstrates how to query documents within a ChromaDB collection. It requires the 'chroma-go' library and an OpenAI API key for embedding. The function takes a context, a list of query sentences, a 'where' filter, a 'where_document' filter, and 'include' options as input, returning the query results.

```go
package main

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

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

func main() {
    ctx := context.Background()
    client,err := chroma.NewClient() //connects to localhost:8000

    if err != nil {
        fmt.Printf("Failed to create client: %v", err)
    }

    openaiEf, err := openai.NewOpenAIEmbeddingFunction(os.Getenv("OPENAI_API_KEY"))
    if err != nil {
        log.Fatalf("Error creating OpenAI embedding function: %s \n", err)
    }
    // Get the collection we created earlier
    collection, err := client.GetCollection(ctx, "my-collection", openaiEf)
    if err != nil {
        log.Fatalf("Failed to create collection: %v", err)
        return
    }
    data, err := collection.Query(context.TODO(), []string{"I love dogs"}, 5, nil, nil, nil)
    if err != nil {
        log.Fatalf("Error querying documents: %v\n", err)
        return
    }
    // see QueryResults struct for more details
    fmt.Printf("Collection data: %v\n", data)
}

```

--------------------------------

### Default Embeddings with Go

Source: https://go-client.chromadb.dev/embeddings

Demonstrates how to initialize and use the default embedding function in ChromaDB Go client, which utilizes the 'all-MiniLM-L6-v2' model on ONNX Runtime. It includes necessary steps for resource cleanup using a defer function to close the embedding function, preventing memory leaks. Ensure ONNX Runtime is correctly configured, either by setting environment variables for path or version, or by relying on the default download.

```go
package main

import (
    "context"
    "fmt"

    defaultef "github.com/amikos-tech/chroma-go/pkg/embeddings/default_ef"
)

func main() {
    ef, closeef, efErr := defaultef.NewDefaultEmbeddingFunction()

    // make sure to call this to ensure proper resource release
    defer func() {
        err := closeef()
        if err != nil {
            fmt.Printf("Error closing default embedding function: %s \n", err)
        }
    }()
    if efErr != nil {
        fmt.Printf("Error creating OpenAI embedding function: %s \n", efErr)
    }
    documents := []string{
        "Document 1 content here",
    }
    resp, reqErr := ef.EmbedDocuments(context.Background(), documents)
    if reqErr != nil {
        fmt.Printf("Error embedding documents: %s \n", reqErr)
    }
    fmt.Printf("Embedding response: %v \n", resp)
}
```

--------------------------------

### Create Chroma-go Development ZapLogger

Source: https://go-client.chromadb.dev/logging

Provides a pre-configured development-level ZapLogger for use with the Chroma-go client. This simplifies setting up logging during development.

```go
logger, _ := chromalogger.NewDevelopmentZapLogger()

client, err := v2.NewHTTPClient(
    v2.WithBaseURL("http://localhost:8000"),
    v2.WithLogger(logger),
)
```

--------------------------------

### Implement Custom Logger for ChromaDB HTTP Client

Source: https://go-client.chromadb.dev/logging

Demonstrates how to implement the `Logger` interface to create a custom logger for the ChromaDB HTTP client. This allows for tailored logging behavior by defining methods like `Debug`, `Info`, etc., and passing an instance of the custom logger to the `NewHTTPClient` function.

```go
type MyCustomLogger struct {
    // your logger implementation
}

func (l *MyCustomLogger) Debug(msg string, fields ...chromalogger.Field) {
    // implement debug logging
}

func (l *MyCustomLogger) Info(msg string, fields ...chromalogger.Field) {
    // implement info logging
}

// ... implement other required methods

// Use your custom logger
client, err := v2.NewHTTPClient(
    v2.WithBaseURL("http://localhost:8000"),
    v2.WithLogger(&MyCustomLogger{}),
)

```

--------------------------------

### Implement Chroma-go ZapLogger with uber-go/zap

Source: https://go-client.chromadb.dev/logging

This snippet demonstrates how to wrap a high-performance uber-go/zap logger to be used with the Chroma-go client. It requires importing the zap and chromalogger packages.

```go
import (
    "go.uber.org/zap"
    chromalogger "github.com/amikos-tech/chroma-go/pkg/logger"
    v2 "github.com/amikos-tech/chroma-go/pkg/api/v2"
)

// Create a zap logger
zapLogger, _ := zap.NewProduction()

// Wrap it in ChromaLogger
logger := chromalogger.NewZapLogger(zapLogger)

// Use it with the client
client, err := v2.NewHTTPClient(
    v2.WithBaseURL("http://localhost:8000"),
    v2.WithLogger(logger),
)
```

--------------------------------

### Together AI Reranker with Go

Source: https://go-client.chromadb.dev/rerankers

This Go program shows how to integrate Together AI for reranking using the chroma-go client. It requires a TOGETHER_API_KEY environment variable to be set. The program initializes the reranker, specifies the model (defaulting to Salesforce/Llama-Rank-V1), and then performs reranking on a query and results. The ranked output includes the rank and original index.

```go
package main

import (
    "context"
    "fmt"
    together "github.com/amikos-tech/chroma-go/pkg/rerankings/together"
    "os"
)

func main() {
    var query = "What is the capital of the United States?"
    var results = []string{
        "Carson City is the capital city of the American state of Nevada.",
        "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean that are a political division controlled by the United States. Its capital is Saipan.",
        "Charlotte Amalie is the capital and largest city of the United States Virgin Islands. It has about 20,000 people. The city is on the island of Saint Thomas.",
        "Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States.",
        "Capital punishment (the death penalty) has existed in the United States since before the United States was a country.",
    }

    rf, err := together.NewTogetherRerankingFunction(together.WithAPIKey(os.Getenv("TOGETHER_API_KEY")))
    if err != nil {
        fmt.Printf("Error creating Together reranking function: %s \n", err)
    }

    res, err := rf.Rerank(context.Background(), query, results)
    if err != nil {
        fmt.Printf("Error reranking: %s \n", err)
    }

    for _, rs := range res[rf.ID()] {
        fmt.Printf("Rank: %f, Index: %d\n", rs.Rank, rs.Index)
    }
}

```

--------------------------------

### Embed Documents with Jina AI in Go

Source: https://go-client.chromadb.dev/embeddings

This Go code snippet demonstrates integrating Jina AI embeddings with chroma-go. It requires a JINA_API_KEY obtained from Jina AI and uses default model configurations. The function takes documents as input and outputs their corresponding embeddings.

```go
package main

import (
    "context"
    "fmt"
    jina "github.com/amikos-tech/chroma-go/pkg/embeddings/jina"
)

func main() {
    documents := []string{
        "Document 1 content here",
        "Document 2 content here",
    }
    // Make sure that you have the `JINA_API_KEY` set in your environment
    ef, err := jina.NewJinaEmbeddingFunction(jina.WithEnvAPIKey())
    if err != nil {
        fmt.Printf("Error creating Jina embedding function: %s \n", err)
    }
    resp, err := ef.EmbedDocuments(context.Background(), documents)
    if err != nil {
        fmt.Printf("Error embedding documents: %s \n", err)
    }
    fmt.Printf("Embedding response: %v \n", resp)
}

```

--------------------------------

### Hugging Face Inference Reranker with Go

Source: https://go-client.chromadb.dev/rerankers

This Go program demonstrates how to use the Hugging Face Inference reranker with the chroma-go client. It initializes the reranker function with the local HFEI endpoint and then uses it to rerank a given query against a list of results. The output displays the rank and original index of each result.

```go
package main

import (
    "context"
    "fmt"
    hf "github.com/amikos-tech/chroma-go/pkg/rerankings/hf"
    "os"
)

func main() {
    var query = "What is the capital of the United States?"
    var results = []string{
        "Carson City is the capital city of the American state of Nevada.",
        "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean that are a political division controlled by the United States. Its capital is Saipan.",
        "Charlotte Amalie is the capital and largest city of the United States Virgin Islands. It has about 20,000 people. The city is on the island of Saint Thomas.",
        "Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States.",
        "Capital punishment (the death penalty) has existed in the United States since before the United States was a country.",
    }

    rf, err := hf.NewHFRerankingFunction(hf.WithRerankingEndpoint("http://127.0.0.1:8080/rerank"))
    if err != nil {
        fmt.Printf("Error creating HFEI reranking function: %s \n", err)
    }

    res, err := rf.Rerank(context.Background(), query, results)
    if err != nil {
        fmt.Printf("Error reranking: %s \n", err)
    }

    for _, rs := range res[rf.ID()] {
        fmt.Printf("Rank: %f, Index: %d\n", rs.Rank, rs.Index)
    }
}

```
Tokens:
Raw