ZVec Go SDK

June 10, 2026 · View on GitHub

English | 中文

Go bindings for the zvec vector database, powered by cgo wrapping the zvec C-API.

Introduction

zvec 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.

Prerequisites

Go ≥ 1.21
C compiler (gcc or clang) for cgo
CMake ≥ 3.20 and Ninja (for building the C-API library)

Quick Start

# Clone with submodules
git clone --recursive https://github.com/zvec-ai/zvec-go.git
cd zvec-go

# Build the C-API library using Makefile
make build-zvec

# Run tests
make test

Or use the full build commands:

# Clone with submodules
git clone --recursive https://github.com/zvec-ai/zvec-go.git
cd zvec-go

# Build the C-API library from submodule
cd zvec && mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_C_BINDINGS=ON -G Ninja
cmake --build . -j$(nproc 2>/dev/null || sysctl -n hw.ncpu) --target zvec_c_api
cd ../..

# Run tests
go test -tags integration -count=1 -v ./...

Installation

zvec-go provides two build modes to suit different users:

Mode 1: Vendor Mode (Default — Pre-built Libraries)

Pre-built libraries are distributed via GitHub Releases.

Recommended Usage:

# 1. Clone the repository
git clone https://github.com/zvec-ai/zvec-go.git
cd zvec-go

# 2. Download pre-built library for your platform
#    (downloads from GitHub Releases, extracts to lib/)
go run ./cmd/download-libs -version v0.5.0

# Use in your project with replace directive
# In your project's go.mod:
#   require github.com/zvec-ai/zvec-go v0.5.0
#   replace github.com/zvec-ai/zvec-go => /path/to/zvec-go

# 3. Build (cgo is required)
CGO_ENABLED=1 go build .

Alternative: Using with go get (requires manual library download)

# 1. Add the dependency
go get github.com/zvec-ai/zvec-go

# 2. Download pre-built libraries manually from GitHub Releases:
#    https://github.com/zvec-ai/zvec-go/releases/download/v0.5.0/zvec-libs-darwin-arm64.tar.gz
#    Extract to your project's lib/ directory

# 3. Build (cgo is required)
CGO_CFLAGS="-I$(pwd)/lib/include" \
CGO_LDFLAGS="-L$(pwd)/lib/darwin_arm64 -lzvec_c_api -Wl,-rpath,$(pwd)/lib/darwin_arm64" \
CGO_ENABLED=1 go build .

Supported platforms: Linux (x64, ARM64), macOS (ARM64), Windows (x64).

Mode 2: Source Mode (Build from Source)

For developers who want to use a custom zvec version, contribute to the project, or build for unsupported platforms:

# Clone with submodules
git clone --recursive https://github.com/zvec-ai/zvec-go.git
cd zvec-go

# Build the C-API library
make build-zvec

# Use in your project with replace directive
# In your project's go.mod:
#   require github.com/zvec-ai/zvec-go v0.0.0
#   replace github.com/zvec-ai/zvec-go => /path/to/zvec-go

# Build with source tag
CGO_ENABLED=1 go build -tags source ./...

# Run tests
go test -tags "source integration" -v ./...

Which Mode Should I Use?

Scenario	Mode	Build Tag
Just want to use zvec-go in my project	Vendor (default)	(none)
Contributing to zvec-go development	Source	`-tags source`
Need a custom/latest zvec version	Source	`-tags source`
Building for an unsupported platform	Source	`-tags source`
AI/LLM agent integrating zvec-go	Vendor (default)	(none)

Usage

package main

import (
    "fmt"
    "log"

    zvec "github.com/zvec-ai/zvec-go"
)

func main() {
    // Initialize zvec
    if err := zvec.Initialize(nil); err != nil {
        log.Fatal(err)
    }
    defer zvec.Shutdown()

    // Create a collection schema
    schema := zvec.NewCollectionSchema("example")
    defer schema.Destroy()

    // Add an ID field (primary key, with invert index)
    idField := zvec.NewFieldSchema("id", zvec.DataTypeString, false, 0)
    invertParams, _ := zvec.NewInvertIndexParams(true, false)
    idField.SetIndexParams(invertParams)
    schema.AddField(idField)

    // Add a vector field (with HNSW index)
    embField := zvec.NewFieldSchema("embedding", zvec.DataTypeVectorFP32, false, 4)
    hnswParams, _ := zvec.NewHNSWIndexParams(zvec.MetricTypeCosine, 16, 200)
    embField.SetIndexParams(hnswParams)
    schema.AddField(embField)

    // Create and open a collection
    collection, err := zvec.CreateAndOpen("./my_data", schema, nil)
    if err != nil {
        log.Fatal(err)
    }
    defer collection.Close()

    // Insert a document
    doc := zvec.NewDoc()
    doc.SetPK("doc1")
    doc.AddStringField("id", "doc1")
    doc.AddVectorFP32Field("embedding", []float32{0.1, 0.2, 0.3, 0.4})
    collection.Insert([]*zvec.Doc{doc})
    doc.Destroy()

    // Vector query
    query := zvec.NewSearchQuery()
    query.SetFieldName("embedding")
    query.SetQueryVector([]float32{0.4, 0.3, 0.3, 0.1})
    query.SetTopK(10)

    results, _ := collection.Query(query)
    query.Destroy()
    defer zvec.FreeDocs(results)

    for _, r := range results {
        fmt.Printf("PK=%s Score=%.4f\n", r.GetPK(), r.GetScore())
    }
}

API Reference

Initialization & Configuration

API	Description
`Initialize(config)`	Initialize the zvec library
`Shutdown()`	Shut down the zvec library and release resources
`IsInitialized()`	Check if the library is initialized
`GetVersion()`	Get the version string
`GetVersionMajor()`	Get the major version number
`GetVersionMinor()`	Get the minor version number
`GetVersionPatch()`	Get the patch version number
`CheckVersion(major, minor, patch)`	Check if the version is compatible

Schema & Index

API	Description
`NewCollectionSchema(name)`	Create a collection schema
`NewFieldSchema(name, dataType, nullable, dim)`	Create a field schema
`NewHNSWIndexParams(metricType, M, efConstruction)`	Create HNSW index parameters
`NewIVFIndexParams(metricType, nlist, nIters, useSoar)`	Create IVF index parameters
`NewFlatIndexParams(metricType)`	Create Flat index parameters
`NewInvertIndexParams(enable, wildcard)`	Create invert index parameters
`NewFTSIndexParams(tokenizer, filters, extra)`	Create FTS index parameters
`SetIndexParams(params)`	Set field index parameters

Collection Operations

API	Description
`CreateAndOpen(path, schema, options)`	Create and open a collection
`Open(path, options)`	Open an existing collection
`Close()`	Close a collection
`Destroy(path)`	Destroy a collection
`Flush()`	Flush data to disk
`Optimize()`	Optimize the collection
`GetStats()`	Get collection statistics
`GetSchema()`	Get the collection schema
`GetOptions()`	Get collection options
`AddColumn(field)`	Add a column
`DropColumn(fieldName)`	Drop a column
`AlterColumn(fieldName, field)`	Alter a column
`CreateIndex(fieldName, params)`	Create an index
`DropIndex(fieldName)`	Drop an index

Document Operations

API	Description
`NewDoc()`	Create a new document
`Destroy()`	Destroy a document and release resources
`SetPK(pk)`	Set the primary key
`GetPK()`	Get the primary key
`GetDocID()`	Get the document ID
`AddStringField(name, value)`	Add a string field
`AddBoolField(name, value)`	Add a boolean field
`AddInt32Field(name, value)`	Add an Int32 field
`AddInt64Field(name, value)`	Add an Int64 field
`AddFloatField(name, value)`	Add a Float field
`AddDoubleField(name, value)`	Add a Double field
`AddVectorFP32Field(name, value)`	Add an FP32 vector field
`SetFieldNull(name)`	Set a field to NULL
`RemoveField(name)`	Remove a field
`HasField(name)`	Check if a field exists

Write Operations

API	Description
`Insert(docs)`	Insert documents
`Update(docs)`	Update documents
`Upsert(docs)`	Insert or update documents
`Delete(pks)`	Delete documents by primary keys
`DeleteByFilter(filter)`	Delete documents by filter expression

Query Operations

API	Description
`NewSearchQuery()`	Create a search query object
`SetFieldName(name)`	Set the query field name
`SetQueryVector(vector)`	Set the query vector
`SetTopK(k)`	Set the number of results to return
`SetFilter(filter)`	Set the filter expression
`SetOutputFields(fields)`	Set the output fields
`SetIncludeVector(include)`	Whether to include vector data
`SetIncludeDocID(include)`	Whether to include document ID
`Query(query)`	Execute a query
`GroupBySearchQuery(query)`	Group-by search query
`Fetch(pks, opts)`	Fetch documents by primary keys
`MultiQuery(query)`	Execute a multi-query search
`FreeDocs(docs)`	Free query result memory

FTS (Full-Text Search)

API	Description
`NewFTS()`	Create an FTS query payload
`SetQueryString(query)`	Set FTS boolean/advanced query expression
`SetMatchString(match)`	Set FTS natural-language match string
`NewFTSQueryParams(op)`	Create FTS query parameters
`SearchQuery.SetFTS(fts)`	Attach FTS payload to a search query
`SearchQuery.SetFTSParams(params)`	Set FTS query parameters

Multi-Query & Reranking

API	Description
`NewMultiQuery()`	Create a multi-query combining sub-queries
`AddSubQuery(sub)`	Add a sub-query (copied)
`SetRerankRRF(rankConstant)`	Set RRF rerank strategy on multi-query
`SetRerankWeighted(weights)`	Set weighted rerank strategy on multi-query
`NewSubQuery()`	Create a sub-query

Data Types

Type	Description
`DataTypeString`	String type
`DataTypeBool`	Boolean type
`DataTypeInt32`	32-bit integer
`DataTypeInt64`	64-bit integer
`DataTypeUint32`	32-bit unsigned integer
`DataTypeUint64`	64-bit unsigned integer
`DataTypeFloat`	Single-precision float
`DataTypeDouble`	Double-precision float
`DataTypeVectorFP32`	FP32 vector
`DataTypeBinary`	Binary data
`DataTypeArray`	Array type
`DataTypeSparseVector`	Sparse vector

Index Types & Metrics

Type	Description
`MetricTypeL2`	L2 distance
`MetricTypeIP`	Inner product
`MetricTypeCosine`	Cosine similarity
`MetricTypeMIPSL2`	MIPSL2 distance
`QuantizeTypeFP16`	FP16 quantization
`QuantizeTypeInt8`	Int8 quantization
`QuantizeTypeInt4`	Int4 quantization

Error Handling

API	Description
`Error.Code()`	Get the error code
`Error.Message()`	Get the error message
`IsNotFound(err)`	Check if it is a "not found" error
`IsAlreadyExists(err)`	Check if it is an "already exists" error
`IsInvalidArgument(err)`	Check if it is an "invalid argument" error

Examples

The project provides rich example code to help you get started quickly:

examples/basic — Basic usage example, demonstrating initialization, schema definition, CRUD operations, and vector queries
examples/schema_and_index — Schema and index configuration, showing how to define different field and index types
examples/crud_operations — Complete CRUD operations, including insert, update, delete, and more
examples/vector_query — Vector query example, demonstrating various query parameters and filter expressions
examples/collection_management — Collection management, showing creation, opening, optimization, and more
examples/error_handling — Error handling example, showing how to properly handle various error scenarios
examples/configuration — Global configuration example, demonstrating memory limits, thread counts, and other options
examples/fts_query — Full-Text Search example, demonstrating FTS index creation, text insertion, and FTS queries

Run an example:

cd examples/basic
go run main.go

Development Guide

If you want to contribute to zvec-go, please refer to CONTRIBUTING.md for the detailed contribution guide.

Syncing with zvec Core

This repository uses a git submodule to track the zvec core library. To update:

# Update to latest main
./scripts/sync-zvec.sh

# Update to a specific tag
./scripts/sync-zvec.sh v0.5.0

Dependabot is also configured to automatically create PRs when the zvec submodule has new commits.

Makefile Commands

The project provides convenient Makefile commands for managing build, test, and development tasks:

Command	Description
`make build-zvec`	Build the zvec C-API library
`make build`	Build the C-API library and verify Go compilation
`make test`	Run all Go tests
`make test-short`	Run tests in short mode (skip long-running tests)
`make test-race`	Run tests with race detector
`make test-cover`	Run tests and generate coverage report
`make bench`	Run performance benchmarks
`make fuzz`	Run fuzz tests (default 30s per target, set `FUZZ_TIME` to customize)
`make lint`	Run all linter checks
`make vet`	Run go vet checks
`make fmt`	Format Go source files
`make fmt-check`	Check Go file formatting (CI-friendly)
`make sync-zvec`	Sync zvec submodule to latest main
`make sync-zvec-build`	Sync zvec submodule + rebuild + test
`make check-zvec`	Check for upstream C-API changes (no update)
`make clean`	Clean build artifacts
`make deps`	Download Go module dependencies
`make install-tools`	Install development tools (golangci-lint, gofumpt)
`make all`	Run full CI check (build, test, lint)
`make help`	Show help message

Supported Platforms

Linux (x86_64, ARM64)
macOS (ARM64)
Windows (x86_64)

License

Apache License 2.0