{"id":49273962,"url":"https://github.com/zvec-ai/zvec-go","last_synced_at":"2026-05-06T06:04:29.294Z","repository":{"id":352803456,"uuid":"1209050078","full_name":"zvec-ai/zvec-go","owner":"zvec-ai","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-21T06:42:24.000Z","size":102,"stargazers_count":0,"open_issues_count":6,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-21T08:35:36.901Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zvec-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"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":"2026-04-13T03:34:45.000Z","updated_at":"2026-04-21T06:41:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zvec-ai/zvec-go","commit_stats":null,"previous_names":["zvec-ai/zvec-go"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/zvec-ai/zvec-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zvec-ai%2Fzvec-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zvec-ai%2Fzvec-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zvec-ai%2Fzvec-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zvec-ai%2Fzvec-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zvec-ai","download_url":"https://codeload.github.com/zvec-ai/zvec-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zvec-ai%2Fzvec-go/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32266014,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T09:15:33.318Z","status":"ssl_error","status_checked_at":"2026-04-25T09:15:31.997Z","response_time":59,"last_error":"SSL_read: 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":[],"created_at":"2026-04-25T15:05:06.874Z","updated_at":"2026-05-06T06:04:29.282Z","avatar_url":"https://github.com/zvec-ai.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ZVec Go SDK\n\nEnglish | [中文](README_CN.md)\n\nGo bindings for the [zvec](https://github.com/alibaba/zvec) vector database, powered by cgo wrapping the zvec C-API.\n\n## Introduction\n\nzvec is a high-performance vector database supporting multiple index types (HNSW, IVF, Flat, Invert) and rich data types. zvec-go provides complete Go language bindings, allowing you to easily leverage zvec's powerful capabilities in your Go projects.\n\n## Prerequisites\n\n- **Go** ≥ 1.21\n- **C compiler** (gcc or clang) for cgo\n- **CMake** ≥ 3.20 and **Ninja** (for building the C-API library)\n\n## Quick Start\n\n```bash\n# Clone with submodules\ngit clone --recursive https://github.com/zvec-ai/zvec-go.git\ncd zvec-go\n\n# Build the C-API library using Makefile\nmake build-zvec\n\n# Run tests\nmake test\n```\n\nOr use the full build commands:\n\n```bash\n# Clone with submodules\ngit clone --recursive https://github.com/zvec-ai/zvec-go.git\ncd zvec-go\n\n# Build the C-API library from submodule\ncd zvec \u0026\u0026 mkdir -p build \u0026\u0026 cd build\ncmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_C_BINDINGS=ON -G Ninja\ncmake --build . -j$(nproc 2\u003e/dev/null || sysctl -n hw.ncpu) --target zvec_c_api\ncd ../..\n\n# Run tests\ngo test -tags integration -count=1 -v ./...\n```\n\n## Installation\n\nzvec-go provides **two build modes** to suit different users:\n\n### Mode 1: Vendor Mode (Default — Pre-built Libraries)\n\nPre-built libraries are distributed via GitHub Releases.\n\n**Recommended Usage:**\n\n```bash\n# 1. Clone the repository\ngit clone https://github.com/zvec-ai/zvec-go.git\ncd zvec-go\n\n# 2. Download pre-built library for your platform\n#    (downloads from GitHub Releases, extracts to lib/)\ngo run ./cmd/download-libs -version v0.3.1\n\n# Use in your project with replace directive\n# In your project's go.mod:\n#   require github.com/zvec-ai/zvec-go v0.3.1\n#   replace github.com/zvec-ai/zvec-go =\u003e /path/to/zvec-go\n\n# 3. Build (cgo is required)\nCGO_ENABLED=1 go build .\n```\n\n**Alternative: Using with go get (requires manual library download)**\n\n```bash\n# 1. Add the dependency\ngo get github.com/zvec-ai/zvec-go\n\n# 2. Download pre-built libraries manually from GitHub Releases:\n#    https://github.com/zvec-ai/zvec-go/releases/download/v0.3.1/zvec-libs-darwin-arm64.tar.gz\n#    Extract to your project's lib/ directory\n\n# 3. Build (cgo is required)\nCGO_CFLAGS=\"-I$(pwd)/lib/include\" \\\nCGO_LDFLAGS=\"-L$(pwd)/lib/darwin_arm64 -lzvec_c_api -Wl,-rpath,$(pwd)/lib/darwin_arm64\" \\\nCGO_ENABLED=1 go build .\n```\n\nSupported platforms: **Linux (x64, ARM64)**, **macOS (ARM64)**, **Windows (x64)**.\n\n### Mode 2: Source Mode (Build from Source)\n\nFor developers who want to use a custom zvec version, contribute to the project, or build for unsupported platforms:\n\n```bash\n# Clone with submodules\ngit clone --recursive https://github.com/zvec-ai/zvec-go.git\ncd zvec-go\n\n# Build the C-API library\nmake build-zvec\n\n# Use in your project with replace directive\n# In your project's go.mod:\n#   require github.com/zvec-ai/zvec-go v0.0.0\n#   replace github.com/zvec-ai/zvec-go =\u003e /path/to/zvec-go\n\n# Build with source tag\nCGO_ENABLED=1 go build -tags source ./...\n\n# Run tests\ngo test -tags \"source integration\" -v ./...\n```\n\n### Which Mode Should I Use?\n\n| Scenario | Mode | Build Tag |\n|----------|------|-----------|\n| Just want to use zvec-go in my project | **Vendor** (default) | _(none)_ |\n| Contributing to zvec-go development | **Source** | `-tags source` |\n| Need a custom/latest zvec version | **Source** | `-tags source` |\n| Building for an unsupported platform | **Source** | `-tags source` |\n| AI/LLM agent integrating zvec-go | **Vendor** (default) | _(none)_ |\n\n## Usage\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"log\"\n\n    zvec \"github.com/zvec-ai/zvec-go\"\n)\n\nfunc main() {\n    // Initialize zvec\n    if err := zvec.Initialize(nil); err != nil {\n        log.Fatal(err)\n    }\n    defer zvec.Shutdown()\n\n    // Create a collection schema\n    schema := zvec.NewCollectionSchema(\"example\")\n    defer schema.Destroy()\n\n    // Add an ID field (primary key, with invert index)\n    idField := zvec.NewFieldSchema(\"id\", zvec.DataTypeString, false, 0)\n    idField.SetIndexParams(zvec.NewInvertIndexParams(true, false))\n    schema.AddField(idField)\n\n    // Add a vector field (with HNSW index)\n    embField := zvec.NewFieldSchema(\"embedding\", zvec.DataTypeVectorFP32, false, 4)\n    embField.SetIndexParams(zvec.NewHNSWIndexParams(zvec.MetricTypeCosine, 16, 200))\n    schema.AddField(embField)\n\n    // Create and open a collection\n    collection, err := zvec.CreateAndOpen(\"./my_data\", schema, nil)\n    if err != nil {\n        log.Fatal(err)\n    }\n    defer collection.Close()\n\n    // Insert a document\n    doc := zvec.NewDoc()\n    doc.SetPK(\"doc1\")\n    doc.AddStringField(\"id\", \"doc1\")\n    doc.AddVectorFP32Field(\"embedding\", []float32{0.1, 0.2, 0.3, 0.4})\n    collection.Insert([]*zvec.Doc{doc})\n    doc.Destroy()\n\n    // Vector query\n    query := zvec.NewVectorQuery()\n    query.SetFieldName(\"embedding\")\n    query.SetQueryVector([]float32{0.4, 0.3, 0.3, 0.1})\n    query.SetTopK(10)\n\n    results, _ := collection.Query(query)\n    query.Destroy()\n    defer zvec.FreeDocs(results)\n\n    for _, r := range results {\n        fmt.Printf(\"PK=%s Score=%.4f\\n\", r.GetPK(), r.GetScore())\n    }\n}\n```\n\n## API Reference\n\n### Initialization \u0026 Configuration\n\n| API | Description |\n|-----|-------------|\n| `Initialize(config)` | Initialize the zvec library |\n| `Shutdown()` | Shut down the zvec library and release resources |\n| `IsInitialized()` | Check if the library is initialized |\n| `GetVersion()` | Get the version string |\n| `GetVersionMajor()` | Get the major version number |\n| `GetVersionMinor()` | Get the minor version number |\n| `GetVersionPatch()` | Get the patch version number |\n| `CheckVersion(major, minor, patch)` | Check if the version is compatible |\n\n### Schema \u0026 Index\n\n| API | Description |\n|-----|-------------|\n| `NewCollectionSchema(name)` | Create a collection schema |\n| `NewFieldSchema(name, dataType, nullable, dim)` | Create a field schema |\n| `NewHNSWIndexParams(metricType, M, efConstruction)` | Create HNSW index parameters |\n| `NewIVFIndexParams(metricType, nlist, nIters, useSoar)` | Create IVF index parameters |\n| `NewFlatIndexParams(metricType)` | Create Flat index parameters |\n| `NewInvertIndexParams(enable, wildcard)` | Create invert index parameters |\n| `SetIndexParams(params)` | Set field index parameters |\n\n### Collection Operations\n\n| API | Description |\n|-----|-------------|\n| `CreateAndOpen(path, schema, options)` | Create and open a collection |\n| `Open(path, options)` | Open an existing collection |\n| `Close()` | Close a collection |\n| `Destroy(path)` | Destroy a collection |\n| `Flush()` | Flush data to disk |\n| `Optimize()` | Optimize the collection |\n| `GetStats()` | Get collection statistics |\n| `GetSchema()` | Get the collection schema |\n| `GetOptions()` | Get collection options |\n| `AddColumn(field)` | Add a column |\n| `DropColumn(fieldName)` | Drop a column |\n| `AlterColumn(fieldName, field)` | Alter a column |\n| `CreateIndex(fieldName, params)` | Create an index |\n| `DropIndex(fieldName)` | Drop an index |\n\n### Document Operations\n\n| API | Description |\n|-----|-------------|\n| `NewDoc()` | Create a new document |\n| `Destroy()` | Destroy a document and release resources |\n| `SetPK(pk)` | Set the primary key |\n| `GetPK()` | Get the primary key |\n| `GetDocID()` | Get the document ID |\n| `AddStringField(name, value)` | Add a string field |\n| `AddBoolField(name, value)` | Add a boolean field |\n| `AddInt32Field(name, value)` | Add an Int32 field |\n| `AddInt64Field(name, value)` | Add an Int64 field |\n| `AddFloatField(name, value)` | Add a Float field |\n| `AddDoubleField(name, value)` | Add a Double field |\n| `AddVectorFP32Field(name, value)` | Add an FP32 vector field |\n| `SetFieldNull(name)` | Set a field to NULL |\n| `RemoveField(name)` | Remove a field |\n| `HasField(name)` | Check if a field exists |\n\n### Write Operations\n\n| API | Description |\n|-----|-------------|\n| `Insert(docs)` | Insert documents |\n| `Update(docs)` | Update documents |\n| `Upsert(docs)` | Insert or update documents |\n| `Delete(pks)` | Delete documents by primary keys |\n| `DeleteByFilter(filter)` | Delete documents by filter expression |\n\n### Query Operations\n\n| API | Description |\n|-----|-------------|\n| `NewVectorQuery()` | Create a vector query object |\n| `SetFieldName(name)` | Set the query field name |\n| `SetQueryVector(vector)` | Set the query vector |\n| `SetTopK(k)` | Set the number of results to return |\n| `SetFilter(filter)` | Set the filter expression |\n| `SetOutputFields(fields)` | Set the output fields |\n| `SetIncludeVector(include)` | Whether to include vector data |\n| `SetIncludeDocID(include)` | Whether to include document ID |\n| `Query(query)` | Execute a query |\n| `GroupByVectorQuery(query)` | Group-by vector query |\n| `Fetch(pks)` | Fetch documents by primary keys |\n| `FreeDocs(docs)` | Free query result memory |\n\n### Data Types\n\n| Type | Description |\n|------|-------------|\n| `DataTypeString` | String type |\n| `DataTypeBool` | Boolean type |\n| `DataTypeInt32` | 32-bit integer |\n| `DataTypeInt64` | 64-bit integer |\n| `DataTypeUint32` | 32-bit unsigned integer |\n| `DataTypeUint64` | 64-bit unsigned integer |\n| `DataTypeFloat` | Single-precision float |\n| `DataTypeDouble` | Double-precision float |\n| `DataTypeVectorFP32` | FP32 vector |\n| `DataTypeBinary` | Binary data |\n| `DataTypeArray` | Array type |\n| `DataTypeSparseVector` | Sparse vector |\n\n### Index Types \u0026 Metrics\n\n| Type | Description |\n|------|-------------|\n| `MetricTypeL2` | L2 distance |\n| `MetricTypeIP` | Inner product |\n| `MetricTypeCosine` | Cosine similarity |\n| `MetricTypeMIPSL2` | MIPSL2 distance |\n| `QuantizeTypeFP16` | FP16 quantization |\n| `QuantizeTypeInt8` | Int8 quantization |\n| `QuantizeTypeInt4` | Int4 quantization |\n\n### Error Handling\n\n| API | Description |\n|-----|-------------|\n| `Error.Code()` | Get the error code |\n| `Error.Message()` | Get the error message |\n| `IsNotFound(err)` | Check if it is a \"not found\" error |\n| `IsAlreadyExists(err)` | Check if it is an \"already exists\" error |\n| `IsInvalidArgument(err)` | Check if it is an \"invalid argument\" error |\n\n## Examples\n\nThe project provides rich example code to help you get started quickly:\n\n- **examples/basic** — Basic usage example, demonstrating initialization, schema definition, CRUD operations, and vector queries\n- **examples/schema_and_index** — Schema and index configuration, showing how to define different field and index types\n- **examples/crud_operations** — Complete CRUD operations, including insert, update, delete, and more\n- **examples/vector_query** — Vector query example, demonstrating various query parameters and filter expressions\n- **examples/collection_management** — Collection management, showing creation, opening, optimization, and more\n- **examples/error_handling** — Error handling example, showing how to properly handle various error scenarios\n- **examples/configuration** — Global configuration example, demonstrating memory limits, thread counts, and other options\n\nRun an example:\n\n```bash\ncd examples/basic\ngo run main.go\n```\n\n## Development Guide\n\nIf you want to contribute to zvec-go, please refer to [CONTRIBUTING.md](CONTRIBUTING.md) for the detailed contribution guide.\n\n## Syncing with zvec Core\n\nThis repository uses a **git submodule** to track the [zvec](https://github.com/alibaba/zvec) core library. To update:\n\n```bash\n# Update to latest main\n./scripts/sync-zvec.sh\n\n# Update to a specific tag\n./scripts/sync-zvec.sh v0.4.0\n```\n\n[Dependabot](https://docs.github.com/en/code-security/dependabot) is also configured to automatically create PRs when the zvec submodule has new commits.\n\n## Makefile Commands\n\nThe project provides convenient Makefile commands for managing build, test, and development tasks:\n\n| Command | Description |\n|---------|-------------|\n| `make build-zvec` | Build the zvec C-API library |\n| `make build` | Build the C-API library and verify Go compilation |\n| `make test` | Run all Go tests |\n| `make test-short` | Run tests in short mode (skip long-running tests) |\n| `make test-race` | Run tests with race detector |\n| `make test-cover` | Run tests and generate coverage report |\n| `make bench` | Run performance benchmarks |\n| `make fuzz` | Run fuzz tests (default 30s per target, set `FUZZ_TIME` to customize) |\n| `make lint` | Run all linter checks |\n| `make vet` | Run go vet checks |\n| `make fmt` | Format Go source files |\n| `make fmt-check` | Check Go file formatting (CI-friendly) |\n| `make sync-zvec` | Sync zvec submodule to latest main |\n| `make sync-zvec-build` | Sync zvec submodule + rebuild + test |\n| `make check-zvec` | Check for upstream C-API changes (no update) |\n| `make clean` | Clean build artifacts |\n| `make deps` | Download Go module dependencies |\n| `make install-tools` | Install development tools (golangci-lint, gofumpt) |\n| `make all` | Run full CI check (build, test, lint) |\n| `make help` | Show help message |\n\n## Supported Platforms\n\n- Linux (x86_64, ARM64)\n- macOS (ARM64)\n- Windows (x86_64)\n\n## License\n\nApache License 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzvec-ai%2Fzvec-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzvec-ai%2Fzvec-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzvec-ai%2Fzvec-go/lists"}