{"id":29468967,"url":"https://github.com/amikos-tech/chroma-go","last_synced_at":"2026-03-05T16:01:25.444Z","repository":{"id":185815400,"uuid":"674149041","full_name":"amikos-tech/chroma-go","owner":"amikos-tech","description":"The Go client for Chroma vector database","archived":false,"fork":false,"pushed_at":"2026-03-04T21:04:06.000Z","size":31252,"stargazers_count":194,"open_issues_count":23,"forks_count":35,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-04T21:14:43.769Z","etag":null,"topics":["chromadb","client","embeddings","vector-database"],"latest_commit_sha":null,"homepage":"https://go-client.chromadb.dev","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amikos-tech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-08-03T08:52:06.000Z","updated_at":"2026-03-04T15:58:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"07a035f5-a6e8-4249-b64e-cf4cf9a2c26b","html_url":"https://github.com/amikos-tech/chroma-go","commit_stats":null,"previous_names":["amikos-tech/chroma-go"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/amikos-tech/chroma-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amikos-tech%2Fchroma-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amikos-tech%2Fchroma-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amikos-tech%2Fchroma-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amikos-tech%2Fchroma-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amikos-tech","download_url":"https://codeload.github.com/amikos-tech/chroma-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amikos-tech%2Fchroma-go/sbom","scorecard":{"id":113171,"data":{"date":"2025-08-11","repo":{"name":"github.com/amikos-tech/chroma-go","commit":"63903596ce0539f35104ac74f5bc9abd6856a3da"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4.7,"checks":[{"name":"Maintained","score":10,"reason":"14 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Code-Review","score":1,"reason":"Found 3/28 approved changesets -- score normalized to 1","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: jobLevel 'checks' permission set to 'write': .github/workflows/lint.yaml:15","Info: jobLevel 'contents' permission set to 'read': .github/workflows/lint.yaml:11","Info: jobLevel 'pull-requests' permission set to 'read': .github/workflows/lint.yaml:13","Warn: no topLevel permission defined: .github/workflows/go.yml:1","Warn: no topLevel permission defined: .github/workflows/lint.yaml:1","Warn: no topLevel permission defined: .github/workflows/mkdocs.yml:1","Warn: no topLevel permission defined: .github/workflows/nightly.yml:1"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/go.yml:108: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/go.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/go.yml:110: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/go.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/go.yml:116: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/go.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/go.yml:129: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/go.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/go.yml:143: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/go.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/go.yml:145: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/go.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/go.yml:151: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/go.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/go.yml:172: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/go.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/go.yml:186: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/go.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/go.yml:188: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/go.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/go.yml:194: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/go.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/go.yml:216: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/go.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/go.yml:20: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/go.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/go.yml:54: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/go.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/go.yml:56: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/go.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/go.yml:60: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/go.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/go.yml:73: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/go.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/go.yml:75: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/go.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/go.yml:81: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/go.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/go.yml:91: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/go.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/lint.yaml:18: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/lint.yaml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/lint.yaml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/lint.yaml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/lint.yaml:26: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/lint.yaml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/mkdocs.yml:13: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/mkdocs.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/mkdocs.yml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/mkdocs.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/mkdocs.yml:32: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/mkdocs.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/nightly.yml:17: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/nightly.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/nightly.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/nightly.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/nightly.yml:25: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/nightly.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/nightly.yml:29: update your workflow using https://app.stepsecurity.io/secureworkflow/amikos-tech/chroma-go/nightly.yml/main?enable=pin","Warn: pipCommand not pinned by hash: .github/workflows/mkdocs.yml:22","Warn: pipCommand not pinned by hash: .github/workflows/mkdocs.yml:23","Info:   0 out of  20 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of  10 third-party GitHubAction dependencies pinned","Info:   0 out of   2 pipCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE.md:0","Info: FSF or OSI recognized license: MIT License: LICENSE.md:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":3,"reason":"branch protection is not maximal on development and all release branches","details":["Info: 'allow deletion' disabled on branch 'main'","Info: 'force pushes' disabled on branch 'main'","Warn: 'branch protection settings apply to administrators' is disabled on branch 'main'","Info: 'stale review dismissal' is required to merge on branch 'main'","Warn: branch 'main' does not require approvers","Info: codeowner review is required on branch 'main'","Warn: 'last push approval' is disabled on branch 'main'","Warn: no status checks found to merge onto branch 'main'","Info: PRs are required in order to make changes on branch 'main'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 30 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":9,"reason":"1 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GO-2025-3829"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-15T16:31:12.780Z","repository_id":185815400,"created_at":"2025-08-15T16:31:12.780Z","updated_at":"2025-08-15T16:31:12.780Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30134566,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T15:35:27.018Z","status":"ssl_error","status_checked_at":"2026-03-05T15:35:23.768Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chromadb","client","embeddings","vector-database"],"created_at":"2025-07-14T11:01:29.829Z","updated_at":"2026-03-05T16:01:25.437Z","avatar_url":"https://github.com/amikos-tech.png","language":"Go","funding_links":[],"categories":["Go","SDKs \u0026 Libraries"],"sub_categories":[],"readme":"# Chroma Go\n\nA simple Chroma Vector Database client written in Go.\nCurrent `chroma-go` release lines (`v0.3.x` and `v0.4.x`) are compatible with Chroma `v1.x`.\nFor older Chroma versions, use older `chroma-go` releases (for example `v0.2.x`). See [compatibility](#compatibility).\n\n\u003e [!WARNING]\n\u003e **V1 API Removed**: The V1 API is removed in `v0.3.x` and later releases.\n\u003e If you require V1 API compatibility, please use versions prior to `v0.3.0` (for example `v0.2.x`).\n\u003e ```bash\n\u003e go get github.com/amikos-tech/chroma-go@v0.2.4\n\u003e ```\n\nWe invite users to visit the docs site for the library for more in-depth\ninformation: [Chroma Go Docs](https://go-client.chromadb.dev/)\n\n## Compatibility\n\n- `chroma-go` `v0.3.x` and `v0.4.x` are compatible with Chroma `v1.x`.\n- For older Chroma versions, use older `chroma-go` release lines (for example `v0.2.x`).\n- Older client versions: [GitHub Releases](https://github.com/amikos-tech/chroma-go/releases)\n\n## Installation\n\n```bash\ngo get github.com/amikos-tech/chroma-go\n```\n\nImport:\n\n```go\nimport (\n\tchroma \"github.com/amikos-tech/chroma-go/pkg/api/v2\"\n)\n```\n\n## Quick Start\n\n### Persistent Client\n\nRun Chroma locally in-process (no external server) with `NewPersistentClient`.\nThe runtime auto-downloads the correct shim library on first use and caches it under `~/.cache/chroma/local_shim`.\nOverride with `CHROMA_LIB_PATH` or `WithPersistentLibraryPath(...)`.\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\n\tchroma \"github.com/amikos-tech/chroma-go/pkg/api/v2\"\n)\n\nfunc main() {\n\tclient, err := chroma.NewPersistentClient(\n\t\tchroma.WithPersistentPath(\"./chroma_data\"),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"Error creating client: %s\", err)\n\t}\n\tdefer client.Close()\n\n\tcol, err := client.GetOrCreateCollection(context.Background(), \"my_collection\")\n\tif err != nil {\n\t\tlog.Fatalf(\"Error creating collection: %s\", err)\n\t}\n\n\terr = col.Add(context.Background(),\n\t\tchroma.WithIDs(\"1\", \"2\"),\n\t\tchroma.WithTexts(\"hello world\", \"goodbye world\"),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"Error adding documents: %s\", err)\n\t}\n\n\tqr, err := col.Query(context.Background(),\n\t\tchroma.WithQueryTexts(\"say hello\"),\n\t\tchroma.WithNResults(1),\n\t\tchroma.WithInclude(chroma.IncludeDocuments),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"Error querying: %s\", err)\n\t}\n\tfmt.Printf(\"Result: %v\\n\", qr.GetDocumentsGroups()[0][0])\n}\n```\n\nFull runnable example: [`examples/v2/persistent_client`](https://github.com/amikos-tech/chroma-go/tree/main/examples/v2/persistent_client)\n\n### Self-Hosted (HTTP)\n\nConnect to a Chroma server running on `http://localhost:8000`:\n\n```bash\ndocker run -d --name chroma -p 8000:8000 -e ALLOW_RESET=TRUE chromadb/chroma:latest\n```\n\nThen create the client (default Chroma URL: `http://localhost:8000`):\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\n\tchroma \"github.com/amikos-tech/chroma-go/pkg/api/v2\"\n)\n\nfunc main() {\n\tclient, err := chroma.NewHTTPClient(\n\t\tchroma.WithBaseURL(\"http://localhost:8000\"),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"Error creating client: %s\", err)\n\t}\n\tdefer client.Close()\n\n\tcol, err := client.GetOrCreateCollection(context.Background(), \"my_collection\")\n\tif err != nil {\n\t\tlog.Fatalf(\"Error creating collection: %s\", err)\n\t}\n\n\terr = col.Add(context.Background(),\n\t\tchroma.WithIDs(\"1\", \"2\"),\n\t\tchroma.WithTexts(\"hello world\", \"goodbye world\"),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"Error adding documents: %s\", err)\n\t}\n\n\tqr, err := col.Query(context.Background(),\n\t\tchroma.WithQueryTexts(\"say hello\"),\n\t\tchroma.WithNResults(1),\n\t\tchroma.WithInclude(chroma.IncludeDocuments),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"Error querying: %s\", err)\n\t}\n\tfmt.Printf(\"Result: %v\\n\", qr.GetDocumentsGroups()[0][0])\n}\n```\n\nStop the local container when done: `docker stop chroma \u0026\u0026 docker rm chroma`.\nAlternative local startup helper: `make server` (requires Docker).\nSee the [official documentation](https://docs.trychroma.com/guides#running-chroma-in-client/server-mode) for other deployment options.\n\n### Chroma Cloud\n\nConnect to [Chroma Cloud](https://www.trychroma.com/) using your API key:\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\tchroma \"github.com/amikos-tech/chroma-go/pkg/api/v2\"\n)\n\nfunc main() {\n\tclient, err := chroma.NewCloudClient(\n\t\tchroma.WithCloudAPIKey(os.Getenv(\"CHROMA_API_KEY\")),\n\t\tchroma.WithDatabaseAndTenant(\n\t\t\tos.Getenv(\"CHROMA_DATABASE\"),\n\t\t\tos.Getenv(\"CHROMA_TENANT\"),\n\t\t),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"Error creating client: %s\", err)\n\t}\n\tdefer client.Close()\n\n\tcol, err := client.GetOrCreateCollection(context.Background(), \"my_collection\")\n\tif err != nil {\n\t\tlog.Fatalf(\"Error creating collection: %s\", err)\n\t}\n\n\tfmt.Printf(\"Collection: %s\\n\", col.Name())\n}\n```\n\nFull auth example: [`examples/v2/auth`](https://github.com/amikos-tech/chroma-go/tree/main/examples/v2/auth)\n\n## Examples\n\n| Example | Path | Entry | Focus |\n|---------|------|-------|-------|\n| Basic usage | [`examples/v2/basic`](./examples/v2/basic) | `main.go` | CRUD flow with `NewHTTPClient` |\n| Persistent client | [`examples/v2/persistent_client`](./examples/v2/persistent_client) | `main.go` | Local embedded runtime with `NewPersistentClient` |\n| Authentication | [`examples/v2/auth`](./examples/v2/auth) | `main.go` | Basic/token/cloud auth patterns |\n| Tenant and database | [`examples/v2/tenant_and_db`](./examples/v2/tenant_and_db) | `main.go` | Multi-tenant and database scoping |\n| Metadata filters | [`examples/v2/metadata_filters`](./examples/v2/metadata_filters) | `main.go` | `where` filters and query conditions |\n| Array metadata | [`examples/v2/array_metadata`](./examples/v2/array_metadata) | `main.go` | Array metadata and contains operators |\n| Schema | [`examples/v2/schema`](./examples/v2/schema) | `main.go` | Schema/index configuration |\n| Search API | [`examples/v2/search`](./examples/v2/search) | `main.go` | Ranking/filtering/pagination search flow |\n| Embedding functions | [`examples/v2/embedding_function_basic`](./examples/v2/embedding_function_basic) | `main.go` | Built-in embedding function setup |\n| Custom embedding function | [`examples/v2/custom_embedding_function`](./examples/v2/custom_embedding_function) | `README.md` | Custom embedder integration guide |\n| Reranking functions | [`examples/v2/reranking_function_basic`](./examples/v2/reranking_function_basic) | `README.md` | Reranker usage patterns |\n| Logging (Zap) | [`examples/v2/logging`](./examples/v2/logging) | `main.go` | Structured logging with Zap |\n| Logging (slog) | [`examples/v2/logging_slog`](./examples/v2/logging_slog) | `main.go` | Structured logging with `log/slog` |\n\n## Offline / Air-Gapped Environments\n\nThe default embedding function and persistent client runtime require native libraries that are normally downloaded on first use.\nFor offline or air-gapped environments, pre-download all runtime dependencies:\n\n```bash\n./scripts/fetch_runtime_deps.sh\n```\n\nThen run the offline smoke test to verify:\n\n```bash\nmake offline-smoke\n```\n\nSee [Offline Runtime Bundle](./docs/docs/offline-runtime-bundle.md) for full details and available flags.\n\n## Feature Parity with ChromaDB API\n\n| Operation                            | Support    |\n|--------------------------------------|------------|\n| Create Tenant                        | ✅          |\n| Get Tenant                           | ✅          |\n| Create Database                      | ✅          |\n| Get Database                         | ✅          |\n| Delete Database                      | ✅          |\n| Reset                                | ✅          |\n| Heartbeat                            | ✅          |\n| List Collections                     | ✅          |\n| Count Collections                    | ✅          |\n| Get Version                          | ✅          |\n| Create Collection                    | ✅          |\n| Delete Collection                    | ✅          |\n| Collection Add                       | ✅          |\n| Collection Get                       | ✅          |\n| Collection Count                     | ✅          |\n| Collection Query                     | ✅          |\n| Collection Update                    | ✅          |\n| Collection Upsert                    | ✅          |\n| Collection Delete (delete documents) | ✅          |\n| Modify Collection                    | ✅          |\n| Search API                           | ✅          |\n\nAdditional support features:\n\n- ✅ [Authentication](https://go-client.chromadb.dev/auth/) (Basic, Token with Authorization header, Token with\n  X-Chroma-Token header)\n- ✅ [Private PKI and self-signed certificate support](https://go-client.chromadb.dev/client/)\n- ✅ Chroma Cloud support\n- ✅ [Structured Logging](https://go-client.chromadb.dev/logging/) - Injectable logger with Zap bridge for structured\n  logging\n- ✅ Persistent Embedding Function support - automatically load embedding function from Chroma collection\n  configuration\n- ✅ Persistent Client support - Run/embed full-featured Chroma in your Go application without running an external\n  Chroma server process.\n- ✅ [Search API Support](https://go-client.chromadb.dev/search/)\n- ✅ Array Metadata support with `$contains`/`$not_contains` operators (Chroma \u003e= 1.5.0)\n\n## Embedding API and Models Support\n\n- ✅ [Default Embedding](https://go-client.chromadb.dev/embeddings/#default-embeddings) Support - the default\n  `all-MiniLM-L6-v2` model running on Onnx Runtime (ORT).\n- ✅ [Offline Runtime Setup Script](./docs/docs/offline-runtime-bundle.md) - download and cache default embedding runtime files locally before running smoke/offline workflows.\n- ✅ [OpenAI Embedding](https://go-client.chromadb.dev/embeddings/#openai) Support\n- ✅ [Cohere](https://go-client.chromadb.dev/embeddings/#cohere) (including Multi-language support)\n- ✅ [Sentence Transformers](https://go-client.chromadb.dev/embeddings/#huggingface-inference-api) (HuggingFace Inference\n  API and [HFEI local server](https://go-client.chromadb.dev/embeddings/#huggingface-embedding-inference-server))\n- ✅ [Google Gemini Embedding](https://go-client.chromadb.dev/embeddings/#google-gemini-ai) Support\n- ✅ [HuggingFace Embedding Inference Server Support](https://go-client.chromadb.dev/embeddings/#huggingface-embedding-inference-server)\n- ✅ [Ollama Embedding](https://go-client.chromadb.dev/embeddings/#ollama) Support\n- ✅ [Cloudflare Workers AI Embedding](https://go-client.chromadb.dev/embeddings/#cloudflare-workers-ai) Support\n- ✅ [Together AI Embedding](https://go-client.chromadb.dev/embeddings/#together-ai) Support\n- ✅ [Voyage AI Embedding](https://go-client.chromadb.dev/embeddings/#voyage-ai) Support\n- ✅ [Mistral AI API Embedding](https://go-client.chromadb.dev/embeddings/#mistral-ai) Support\n- ✅ [Nomic AI Embedding](https://go-client.chromadb.dev/embeddings/#nomic-ai) Support\n- ✅ [Jina AI Embedding](https://go-client.chromadb.dev/embeddings/#jina-ai) Support\n- ✅ [Roboflow CLIP Embedding](https://go-client.chromadb.dev/embeddings/#roboflow) Support (Multimodal: text + images)\n- ✅ [Amazon Bedrock Embedding](https://go-client.chromadb.dev/embeddings/#amazon-bedrock) Support (Titan models, bearer token + SDK auth)\n- ✅ [Baseten Embedding](https://go-client.chromadb.dev/embeddings/#baseten) Support\n- ✅ [Morph Embedding](https://go-client.chromadb.dev/embeddings/#morph) Support\n- ✅ [Perplexity Embedding](https://go-client.chromadb.dev/embeddings/#perplexity) Support\n\n**Sparse \u0026 Specialized Embedding Functions:**\n\n- ✅ [Chroma Cloud Embedding](https://go-client.chromadb.dev/embeddings/#chroma-cloud) Support\n- ✅ [Chroma Cloud Splade Embedding](https://go-client.chromadb.dev/embeddings/#chroma-cloud-splade) Support (sparse)\n- ✅ [BM25 Embedding](https://go-client.chromadb.dev/embeddings/#bm25) Support (sparse)\n\n## Reranking Functions\n\nThe Chroma Go client supports Reranking functions:\n\n- ✅ [Cohere](https://go-client.chromadb.dev/rerankers/#cohere-reranker)\n- ✅ [Jina AI](https://go-client.chromadb.dev/rerankers/#jina-ai-reranker)\n- ✅ [HuggingFace Embedding Inference Server Reranker](https://go-client.chromadb.dev/rerankers/#hfei-Reranker)\n- ✅ [Together AI](https://go-client.chromadb.dev/rerankers/#together-ai-reranker)\n\n## Schema Quickstart\n\n```go\n// NewSchemaWithDefaults (L2 + HNSW defaults)\nschema, err := chroma.NewSchemaWithDefaults()\nif err != nil {\n\tpanic(err)\n}\n```\n\n```go\n// Custom schema: vector + FTS + metadata indexes\nschema, err := chroma.NewSchema(\n\tchroma.WithDefaultVectorIndex(chroma.NewVectorIndexConfig(\n\t\tchroma.WithSpace(chroma.SpaceCosine),\n\t\tchroma.WithHnsw(chroma.NewHnswConfig(\n\t\t\tchroma.WithEfConstruction(200),\n\t\t\tchroma.WithMaxNeighbors(32),\n\t\t)),\n\t)),\n\tchroma.WithDefaultFtsIndex(\u0026chroma.FtsIndexConfig{}),\n\tchroma.WithStringIndex(\"category\"),\n\tchroma.WithIntIndex(\"year\"),\n\tchroma.WithFloatIndex(\"rating\"),\n)\nif err != nil {\n\tpanic(err)\n}\n```\n\n```go\n// Disable an index for one field\nschema, err := chroma.NewSchema(\n\tchroma.WithDefaultVectorIndex(chroma.NewVectorIndexConfig(chroma.WithSpace(chroma.SpaceL2))),\n\tchroma.DisableStringIndex(\"large_text_field\"),\n)\nif err != nil {\n\tpanic(err)\n}\n```\n\n```go\n// SPANN (Chroma Cloud)\nschema, err := chroma.NewSchema(\n\tchroma.WithDefaultVectorIndex(chroma.NewVectorIndexConfig(\n\t\tchroma.WithSpace(chroma.SpaceCosine),\n\t\tchroma.WithSpann(chroma.NewSpannConfig(\n\t\t\tchroma.WithSpannSearchNprobe(64),\n\t\t\tchroma.WithSpannEfConstruction(200),\n\t\t)),\n\t)),\n)\nif err != nil {\n\tpanic(err)\n}\n```\n\nRunnable schema example: [`examples/v2/schema`](https://github.com/amikos-tech/chroma-go/tree/main/examples/v2/schema)\n\n### Strict Metadata Map Validation\n\nWhen metadata comes from `map[string]interface{}`:\n\n- `NewMetadataFromMap` is best-effort and silently skips invalid `[]interface{}` values.\n- `NewMetadataFromMapStrict` returns an error for invalid or unsupported values.\n- `WithCollectionMetadataMapCreateStrict` applies strict conversion in create/get-or-create flows and returns a deferred option error before any HTTP request is sent.\n\n```go\n// Strict create/get-or-create metadata map conversion\ncol, err := client.GetOrCreateCollection(context.Background(), \"col1\",\n\tchroma.WithCollectionMetadataMapCreateStrict(map[string]interface{}{\n\t\t\"description\": \"validated metadata\",\n\t\t\"tags\":        []interface{}{\"a\", \"b\"},\n\t}),\n)\nif err != nil {\n\tlog.Fatalf(\"Error creating collection: %s\", err)\n}\n\n// Strict metadata map conversion before collection metadata update\nnewMetadata, err := chroma.NewMetadataFromMapStrict(map[string]interface{}{\n\t\"description\": \"updated description\",\n\t\"tags\":        []interface{}{\"x\", \"y\"},\n})\nif err != nil {\n\tlog.Fatalf(\"Invalid metadata map: %s\", err)\n}\nif err := col.ModifyMetadata(context.Background(), newMetadata); err != nil {\n\tlog.Fatalf(\"Error modifying metadata: %s\", err)\n}\n```\n\n### Unified Options API\n\nThe V2 API provides a unified options pattern where common options work across multiple operations:\n\n| Option              | Get | Query | Delete | Add | Update | Search |\n|---------------------|-----|-------|--------|-----|--------|--------|\n| `WithIDs`           | ✓   | ✓     | ✓      | ✓   | ✓      | ✓      |\n| `WithWhere`         | ✓   | ✓     | ✓      |     |        |        |\n| `WithWhereDocument` | ✓   | ✓     | ✓      |     |        |        |\n| `WithInclude`       | ✓   | ✓     |        |     |        |        |\n| `WithTexts`         |     |       |        | ✓   | ✓      |        |\n| `WithMetadatas`     |     |       |        | ✓   | ✓      |        |\n| `WithEmbeddings`    |     |       |        | ✓   | ✓      |        |\n\n```go\n// Get documents by ID or filter\nresults, _ := col.Get(ctx,\nchroma.WithIDs(\"id1\", \"id2\"),\nchroma.WithWhere(chroma.EqString(\"status\", \"active\")),\nchroma.WithInclude(chroma.IncludeDocuments, chroma.IncludeMetadatas),\n)\n\n// Query with semantic search\nresults, _ := col.Query(ctx,\nchroma.WithQueryTexts(\"machine learning\"),\nchroma.WithWhere(chroma.GtInt(\"year\", 2020)),\nchroma.WithNResults(10),\n)\n\n// Delete by filter\n_ = col.Delete(ctx, chroma.WithWhere(chroma.EqString(\"status\", \"archived\")))\n\n// Search API with ranking and pagination\nresults, _ := col.Search(ctx,\nchroma.NewSearchRequest(\nchroma.WithKnnRank(chroma.KnnQueryText(\"query\")),\nchroma.WithFilter(chroma.EqString(chroma.K(\"category\"), \"tech\")),\nchroma.NewPage(chroma.Limit(20)),\nchroma.WithSelect(chroma.KDocument, chroma.KScore),\n),\n)\n```\n\n### Structured Logging\n\nThe client supports injectable loggers for structured logging. Here's a quick example using Zap:\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"log\"\n\n\t\"go.uber.org/zap\"\n\tchromalogger \"github.com/amikos-tech/chroma-go/pkg/logger\"\n\tchroma \"github.com/amikos-tech/chroma-go/pkg/api/v2\"\n)\n\nfunc main() {\n\t// Create a zap logger\n\tzapLogger, _ := zap.NewDevelopment()\n\tdefer zapLogger.Sync()\n\n\t// Wrap it in the Chroma logger\n\tlogger := chromalogger.NewZapLogger(zapLogger)\n\n\t// Create client with the logger\n\tclient, err := chroma.NewHTTPClient(\n\t\tchroma.WithBaseURL(\"http://localhost:8000\"),\n\t\tchroma.WithLogger(logger),\n\t)\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tdefer client.Close()\n\n\t// All client operations will now be logged with structured logging\n\tctx := context.Background()\n\tcollections, _ := client.ListCollections(ctx)\n\n\t// You can also log directly\n\tlogger.Info(\"Retrieved collections\",\n\t\tchromalogger.Int(\"count\", len(collections)),\n\t)\n\n\t// For debug logging, use WithLogger with a debug-level logger\n\tdevLogger, _ := chromalogger.NewDevelopmentZapLogger()\n\tdebugClient, _ := chroma.NewHTTPClient(\n\t\tchroma.WithBaseURL(\"http://localhost:8000\"),\n\t\tchroma.WithLogger(devLogger),\n\t)\n\tdefer debugClient.Close()\n}\n```\n\nSee the [logging documentation](https://go-client.chromadb.dev/logging/) for more details.\n\n## Development\n\n### Build\n\n```bash\nmake build\n```\n\n### Test\n\n```bash\nmake test\n```\n\n### Performance Validation\n\nLocal/persistent runtime soak/load validation is available through a dedicated\nsoak-tagged test harness.\n\nSmoke profile (PR gate, hard-fail thresholds, \u003c=10m timeout target):\n\n```bash\nmake test-local-load-smoke\n```\n\nNightly soak profile (report-only thresholds, \u003c=70m timeout target):\n\n```bash\nmake test-local-soak-nightly\n```\n\nUseful environment variables:\n\n- `CHROMA_PERF_PROFILE` - `smoke` or `soak`.\n- `CHROMA_PERF_ENFORCE` - `true` to fail on threshold breaches, `false` for report-only.\n- `CHROMA_PERF_INCLUDE_DEFAULT_EF` - include `default_ef` scenarios (default: true for soak, false for smoke).\n- `CHROMA_PERF_REPORT_DIR` - output directory for `perf-summary-*.json` and `perf-summary-*.md`.\n- `CHROMA_PERF_ENABLE_DELETE_REINSERT` - enables delete+reinsert write operations (disabled by default due to current local runtime stability issues under delete-heavy load).\n\nSee `docs/docs/performance-testing.md` for profile definitions, thresholds, and report schema.\n\n### Lint\n\n```bash\nmake lint-fix\n```\n\n### Local Server\n\n\u003e Note: Docker must be installed\n\n```bash\nmake server\n```\n\n## References\n\n- [Official Chroma documentation](https://docs.trychroma.com/)\n- [Chroma Helm chart](https://github.com/amikos-tech/chromadb-chart) for cloud-native deployments\n- [Chroma Cookbook](https://cookbook.chromadb.dev) for examples and recipes\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famikos-tech%2Fchroma-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famikos-tech%2Fchroma-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famikos-tech%2Fchroma-go/lists"}