zvec

package module
v0.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 25, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

README

ZVec Go SDK

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 — go get + go generate)

Pre-built libraries are distributed via GitHub Releases. Use go get to fetch the code, then go generate to download the pre-built library for your platform:

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

# 2. Download pre-built library for your platform
#    (downloads from GitHub Releases, extracts to lib/)
go generate github.com/zvec-ai/zvec-go

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

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

You can also specify a version explicitly:

go run github.com/zvec-ai/zvec-go/cmd/download-libs@latest -version v0.3.1
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)
    idField.SetIndexParams(zvec.NewInvertIndexParams(true, false))
    schema.AddField(idField)

    // Add a vector field (with HNSW index)
    embField := zvec.NewFieldSchema("embedding", zvec.DataTypeVectorFP32, false, 4)
    embField.SetIndexParams(zvec.NewHNSWIndexParams(zvec.MetricTypeCosine, 16, 200))
    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.NewVectorQuery()
    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
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
NewVectorQuery() Create a vector 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
GroupByVectorQuery(query) Group-by vector query
Fetch(pks) Fetch documents by primary keys
FreeDocs(docs) Free query result memory
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

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

Documentation

Overview

Download pre-built C libraries for the current platform:

Package zvec provides Go bindings for the zvec vector database library.

Zvec is an open-source, in-process vector database — lightweight, lightning-fast, and designed to embed directly into applications. This Go SDK wraps the zvec C-API using cgo to provide idiomatic Go access to all zvec functionality.

Basic usage: 

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

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

// Add fields
idField := zvec.NewFieldSchema("id", zvec.DataTypeString, false, 0)
idField.SetIndexParams(zvec.NewInvertIndexParams(true, false))
schema.AddField(idField)

embeddingField := zvec.NewFieldSchema("embedding", zvec.DataTypeVectorFP32, false, 128)
hnswParams := zvec.NewHNSWIndexParams(zvec.MetricTypeCosine, 16, 200)
embeddingField.SetIndexParams(hnswParams)
schema.AddField(embeddingField)

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

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrNotFoundError           = &Error{Code: ErrNotFound, Message: "resource not found"}
	ErrAlreadyExistsError      = &Error{Code: ErrAlreadyExists, Message: "resource already exists"}
	ErrInvalidArgumentError    = &Error{Code: ErrInvalidArgument, Message: "invalid argument"}
	ErrPermissionDeniedError   = &Error{Code: ErrPermissionDenied, Message: "permission denied"}
	ErrFailedPreconditionError = &Error{Code: ErrFailedPrecondition, Message: "failed precondition"}
	ErrResourceExhaustedError  = &Error{Code: ErrResourceExhausted, Message: "resource exhausted"}
	ErrUnavailableError        = &Error{Code: ErrUnavailable, Message: "unavailable"}
	ErrInternalErrorError      = &Error{Code: ErrInternalError, Message: "internal error"}
	ErrNotSupportedError       = &Error{Code: ErrNotSupported, Message: "not supported"}
	ErrUnknownError            = &Error{Code: ErrUnknown, Message: "unknown error"}
)

Sentinel errors for common error codes.

Functions

func CheckVersion 

func CheckVersion(major, minor, patch int) bool

CheckVersion checks if the current library version meets the minimum requirements.

func ClearError 

func ClearError()

ClearError clears the last error status.

func FreeDocs 

func FreeDocs(docs []*Doc)

FreeDocs is a convenience function to destroy multiple documents at once.

func GetVersion 

func GetVersion() string

GetVersion returns the library version string.

func GetVersionMajor 

func GetVersionMajor() int

GetVersionMajor returns the major version number.

func GetVersionMinor 

func GetVersionMinor() int

GetVersionMinor returns the minor version number.

func GetVersionPatch 

func GetVersionPatch() int

GetVersionPatch returns the patch version number.

func Initialize 

func Initialize(config *ConfigData) error

Initialize initializes the zvec library with optional configuration. Pass nil to use default configuration. Must be called before any other zvec operations.

func IsAlreadyExists 

func IsAlreadyExists(err error) bool

IsAlreadyExists checks if the error is an already exists error.

func IsInitialized 

func IsInitialized() bool

IsInitialized checks if the library has been initialized.

func IsInvalidArgument 

func IsInvalidArgument(err error) bool

IsInvalidArgument checks if the error is an invalid argument error.

func IsNotFound 

func IsNotFound(err error) bool

IsNotFound checks if the error is a not found error.

func Shutdown 

func Shutdown() error

Shutdown cleans up zvec library resources. Should be called when the library is no longer needed.

Types

type Collection 

type Collection struct {
	// contains filtered or unexported fields
}

Collection represents a zvec collection.

func CreateAndOpen 

func CreateAndOpen(path string, schema *CollectionSchema, options *CollectionOptions) (*Collection, error)

CreateAndOpen creates a new collection and opens it. The caller is responsible for calling Close() when done.

func Open 

func Open(path string, options *CollectionOptions) (*Collection, error)

Open opens an existing collection. The caller is responsible for calling Close() when done.

func (*Collection) AddColumn 

func (c *Collection) AddColumn(fieldSchema *FieldSchema, defaultExpr string) error

AddColumn adds a new column to the collection.

func (*Collection) AlterColumn 

func (c *Collection) AlterColumn(columnName, newName string, newSchema *FieldSchema) error

AlterColumn alters a column in the collection. Pass empty string for newName to skip renaming. Pass nil for newSchema to skip schema modification.

func (*Collection) Close 

func (c *Collection) Close() error

Close closes the collection and releases the handle. The collection data on disk is preserved and can be reopened with Open().

func (*Collection) CreateIndex 

func (c *Collection) CreateIndex(fieldName string, params *IndexParams) error

CreateIndex creates an index for a collection field.

func (*Collection) Delete 

func (c *Collection) Delete(pks []string) (*WriteResult, error)

Delete deletes documents by primary keys.

func (*Collection) DeleteByFilter 

func (c *Collection) DeleteByFilter(filter string) error

DeleteByFilter deletes documents matching the filter expression.

func (*Collection) Destroy 

func (c *Collection) Destroy() error

Destroy destroys the collection data on disk and releases the handle. After calling Destroy, the collection data is permanently deleted. Note: zvec_collection_destroy deletes data but does not free the handle; zvec_collection_close frees the handle (deletes the shared_ptr).

func (*Collection) DropColumn 

func (c *Collection) DropColumn(columnName string) error

DropColumn drops a column from the collection.

func (*Collection) DropIndex 

func (c *Collection) DropIndex(fieldName string) error

DropIndex drops an index from a collection field.

func (*Collection) Fetch 

func (c *Collection) Fetch(primaryKeys []string) ([]*Doc, error)

Fetch retrieves documents by primary keys. The caller is responsible for calling Destroy() on each returned Doc, or using FreeDocs() to free all at once.

func (*Collection) Flush 

func (c *Collection) Flush() error

Flush flushes collection data to disk.

func (*Collection) GetOptions 

func (c *Collection) GetOptions() (*CollectionOptions, error)

GetOptions returns the collection options. The caller is responsible for calling Destroy() on the returned options.

func (*Collection) GetSchema 

func (c *Collection) GetSchema() (*CollectionSchema, error)

GetSchema returns the collection schema. The caller is responsible for calling Destroy() on the returned schema.

func (*Collection) GetStats 

func (c *Collection) GetStats() (*CollectionStats, error)

GetStats returns collection statistics.

func (*Collection) Insert 

func (c *Collection) Insert(docs []*Doc) (*WriteResult, error)

Insert inserts documents into the collection.

func (*Collection) Optimize 

func (c *Collection) Optimize() error

Optimize optimizes the collection (rebuild indexes, merge segments, etc.).

func (*Collection) Query 

func (c *Collection) Query(query *VectorQuery) ([]*Doc, error)

Query performs a vector similarity search. The caller is responsible for calling Destroy() on each returned Doc, or using FreeDocs() to free all at once.

func (*Collection) Update 

func (c *Collection) Update(docs []*Doc) (*WriteResult, error)

Update updates documents in the collection.

func (*Collection) Upsert 

func (c *Collection) Upsert(docs []*Doc) (*WriteResult, error)

Upsert inserts or updates documents in the collection.

type CollectionOptions 

type CollectionOptions struct {
	// contains filtered or unexported fields
}

CollectionOptions represents options for creating or opening a collection.

func NewCollectionOptions 

func NewCollectionOptions() *CollectionOptions

NewCollectionOptions creates a new collection options instance.

func (*CollectionOptions) Destroy 

func (o *CollectionOptions) Destroy()

Destroy releases the collection options resources.

func (*CollectionOptions) GetEnableMmap 

func (o *CollectionOptions) GetEnableMmap() bool

GetEnableMmap returns whether memory mapping is enabled.

func (*CollectionOptions) GetMaxBufferSize 

func (o *CollectionOptions) GetMaxBufferSize() uint64

GetMaxBufferSize returns the maximum buffer size in bytes.

func (*CollectionOptions) GetReadOnly 

func (o *CollectionOptions) GetReadOnly() bool

GetReadOnly returns whether the collection is read-only.

func (*CollectionOptions) SetEnableMmap 

func (o *CollectionOptions) SetEnableMmap(enable bool) error

SetEnableMmap sets whether to enable memory mapping.

func (*CollectionOptions) SetMaxBufferSize 

func (o *CollectionOptions) SetMaxBufferSize(size uint64) error

SetMaxBufferSize sets the maximum buffer size in bytes.

func (*CollectionOptions) SetReadOnly 

func (o *CollectionOptions) SetReadOnly(readOnly bool) error

SetReadOnly sets whether the collection is read-only.

type CollectionSchema 

type CollectionSchema struct {
	// contains filtered or unexported fields
}

CollectionSchema wraps zvec_collection_schema_t (opaque pointer).

func NewCollectionSchema 

func NewCollectionSchema(name string) *CollectionSchema

NewCollectionSchema creates a new collection schema with the specified name.

func (*CollectionSchema) AddField 

func (s *CollectionSchema) AddField(field *FieldSchema) error

AddField adds a field to the collection schema.

func (*CollectionSchema) AddIndex 

func (s *CollectionSchema) AddIndex(fieldName string, params *IndexParams) error

AddIndex adds an index to a field.

func (*CollectionSchema) Destroy 

func (s *CollectionSchema) Destroy()

Destroy releases the collection schema resources.

func (*CollectionSchema) DropField 

func (s *CollectionSchema) DropField(name string) error

DropField drops a field from the collection schema.

func (*CollectionSchema) DropIndex 

func (s *CollectionSchema) DropIndex(fieldName string) error

DropIndex drops an index from a field.

func (*CollectionSchema) GetField 

func (s *CollectionSchema) GetField(name string) *FieldSchema

GetField returns the field with the specified name (non-owning).

func (*CollectionSchema) GetMaxDocCountPerSegment 

func (s *CollectionSchema) GetMaxDocCountPerSegment() uint64

GetMaxDocCountPerSegment returns the maximum document count per segment.

func (*CollectionSchema) GetName 

func (s *CollectionSchema) GetName() string

GetName returns the collection name.

func (*CollectionSchema) HasField 

func (s *CollectionSchema) HasField(name string) bool

HasField returns whether the collection has a field with the specified name.

func (*CollectionSchema) HasIndex 

func (s *CollectionSchema) HasIndex(fieldName string) bool

HasIndex returns whether a field has an index.

func (*CollectionSchema) SetMaxDocCountPerSegment 

func (s *CollectionSchema) SetMaxDocCountPerSegment(count uint64) error

SetMaxDocCountPerSegment sets the maximum document count per segment.

func (*CollectionSchema) SetName 

func (s *CollectionSchema) SetName(name string) error

SetName sets the collection name.

type CollectionStats 

type CollectionStats struct {
	DocCount          uint64
	IndexCount        int
	IndexNames        []string
	IndexCompleteness []float32
}

CollectionStats holds statistics about a collection.

type ConfigData 

type ConfigData struct {
	// contains filtered or unexported fields
}

ConfigData represents the global configuration for the zvec library.

func NewConfigData 

func NewConfigData() *ConfigData

NewConfigData creates a new configuration data instance.

func (*ConfigData) Destroy 

func (c *ConfigData) Destroy()

Destroy releases the configuration data resources.

func (*ConfigData) GetMemoryLimit 

func (c *ConfigData) GetMemoryLimit() uint64

GetMemoryLimit returns the memory limit in bytes.

func (*ConfigData) GetOptimizeThreadCount 

func (c *ConfigData) GetOptimizeThreadCount() uint32

GetOptimizeThreadCount returns the number of optimize threads.

func (*ConfigData) GetQueryThreadCount 

func (c *ConfigData) GetQueryThreadCount() uint32

GetQueryThreadCount returns the number of query threads.

func (*ConfigData) SetConsoleLog 

func (c *ConfigData) SetConsoleLog(level LogLevel) error

SetConsoleLog configures console logging with the specified level.

func (*ConfigData) SetFileLog 

func (c *ConfigData) SetFileLog(level LogLevel, dir, basename string, fileSizeMB, overdueDays uint32) error

SetFileLog configures file logging.

func (*ConfigData) SetMemoryLimit 

func (c *ConfigData) SetMemoryLimit(bytes uint64) error

SetMemoryLimit sets the memory limit in bytes.

func (*ConfigData) SetOptimizeThreadCount 

func (c *ConfigData) SetOptimizeThreadCount(count uint32) error

SetOptimizeThreadCount sets the number of optimize threads.

func (*ConfigData) SetQueryThreadCount 

func (c *ConfigData) SetQueryThreadCount(count uint32) error

SetQueryThreadCount sets the number of query threads.

type DataType 

type DataType uint32

DataType represents the data type of a field. 

const (
	DataTypeUndefined        DataType = 0
	DataTypeBinary           DataType = 1
	DataTypeString           DataType = 2
	DataTypeBool             DataType = 3
	DataTypeInt32            DataType = 4
	DataTypeInt64            DataType = 5
	DataTypeUint32           DataType = 6
	DataTypeUint64           DataType = 7
	DataTypeFloat            DataType = 8
	DataTypeDouble           DataType = 9
	DataTypeVectorBinary32   DataType = 20
	DataTypeVectorBinary64   DataType = 21
	DataTypeVectorFP16       DataType = 22
	DataTypeVectorFP32       DataType = 23
	DataTypeVectorFP64       DataType = 24
	DataTypeVectorInt4       DataType = 25
	DataTypeVectorInt8       DataType = 26
	DataTypeVectorInt16      DataType = 27
	DataTypeSparseVectorFP16 DataType = 30
	DataTypeSparseVectorFP32 DataType = 31
	DataTypeArrayBinary      DataType = 40
	DataTypeArrayString      DataType = 41
	DataTypeArrayBool        DataType = 42
	DataTypeArrayInt32       DataType = 43
	DataTypeArrayInt64       DataType = 44
	DataTypeArrayUint32      DataType = 45
	DataTypeArrayUint64      DataType = 46
	DataTypeArrayFloat       DataType = 47
	DataTypeArrayDouble      DataType = 48
)

type Doc 

type Doc struct {
	// contains filtered or unexported fields
}

Doc represents a document in the zvec vector database. It wraps the C zvec_doc_t handle and manages ownership.

func NewDoc 

func NewDoc() *Doc

NewDoc creates a new document with owned=true. The caller is responsible for calling Destroy() when done.

func (*Doc) AddBinaryField 

func (d *Doc) AddBinaryField(name string, data []byte) error

AddBinaryField adds a binary field to the document. The data must not be empty; use SetFieldNull for null values.

func (*Doc) AddBoolField 

func (d *Doc) AddBoolField(name string, value bool) error

AddBoolField adds a boolean field to the document.

func (*Doc) AddDoubleField 

func (d *Doc) AddDoubleField(name string, value float64) error

AddDoubleField adds a float64 field to the document.

func (*Doc) AddFloatField 

func (d *Doc) AddFloatField(name string, value float32) error

AddFloatField adds a float32 field to the document.

func (*Doc) AddInt32Field 

func (d *Doc) AddInt32Field(name string, value int32) error

AddInt32Field adds an int32 field to the document.

func (*Doc) AddInt64Field 

func (d *Doc) AddInt64Field(name string, value int64) error

AddInt64Field adds an int64 field to the document.

func (*Doc) AddStringField 

func (d *Doc) AddStringField(name, value string) error

AddStringField adds a string field to the document.

func (*Doc) AddUint32Field 

func (d *Doc) AddUint32Field(name string, value uint32) error

AddUint32Field adds a uint32 field to the document.

func (*Doc) AddUint64Field 

func (d *Doc) AddUint64Field(name string, value uint64) error

AddUint64Field adds a uint64 field to the document.

func (*Doc) AddVectorFP32Field 

func (d *Doc) AddVectorFP32Field(name string, vector []float32) error

AddVectorFP32Field adds a float32 vector field to the document.

func (*Doc) Clear 

func (d *Doc) Clear()

Clear clears all fields and metadata from the document.

func (*Doc) Destroy 

func (d *Doc) Destroy()

Destroy releases the document resources. Only effective when owned=true.

func (*Doc) GetBoolField 

func (d *Doc) GetBoolField(name string) (bool, error)

GetBoolField returns the boolean value of a field.

func (*Doc) GetDocID 

func (d *Doc) GetDocID() uint64

GetDocID returns the document ID.

func (*Doc) GetDoubleField 

func (d *Doc) GetDoubleField(name string) (float64, error)

GetDoubleField returns the float64 value of a field.

func (*Doc) GetFieldCount 

func (d *Doc) GetFieldCount() int

GetFieldCount returns the number of fields in the document.

func (*Doc) GetFieldNames 

func (d *Doc) GetFieldNames() ([]string, error)

GetFieldNames returns a list of all field names in the document.

func (*Doc) GetFloatField 

func (d *Doc) GetFloatField(name string) (float32, error)

GetFloatField returns the float32 value of a field.

func (*Doc) GetInt32Field 

func (d *Doc) GetInt32Field(name string) (int32, error)

GetInt32Field returns the int32 value of a field.

func (*Doc) GetInt64Field 

func (d *Doc) GetInt64Field(name string) (int64, error)

GetInt64Field returns the int64 value of a field.

func (*Doc) GetOperator 

func (d *Doc) GetOperator() DocOperator

GetOperator returns the document operator.

func (*Doc) GetPK 

func (d *Doc) GetPK() string

GetPK returns the primary key of the document.

func (*Doc) GetScore 

func (d *Doc) GetScore() float32

GetScore returns the document score.

func (*Doc) GetStringField 

func (d *Doc) GetStringField(name string) (string, error)

GetStringField returns the string value of a field.

func (*Doc) GetUint32Field 

func (d *Doc) GetUint32Field(name string) (uint32, error)

GetUint32Field returns the uint32 value of a field.

func (*Doc) GetUint64Field 

func (d *Doc) GetUint64Field(name string) (uint64, error)

GetUint64Field returns the uint64 value of a field.

func (*Doc) GetVectorFP32Field 

func (d *Doc) GetVectorFP32Field(name string) ([]float32, error)

GetVectorFP32Field returns the float32 vector value of a field.

func (*Doc) HasField 

func (d *Doc) HasField(name string) bool

HasField returns true if the document has a field with the given name.

func (*Doc) HasFieldValue 

func (d *Doc) HasFieldValue(name string) bool

HasFieldValue returns true if the document has a field with the given name and a non-null value.

func (*Doc) IsEmpty 

func (d *Doc) IsEmpty() bool

IsEmpty returns true if the document has no fields.

func (*Doc) IsFieldNull 

func (d *Doc) IsFieldNull(name string) bool

IsFieldNull returns true if the field with the given name is null.

func (*Doc) RemoveField 

func (d *Doc) RemoveField(name string) error

RemoveField removes a field from the document.

func (*Doc) SetDocID 

func (d *Doc) SetDocID(docID uint64)

SetDocID sets the document ID.

func (*Doc) SetFieldNull 

func (d *Doc) SetFieldNull(name string) error

SetFieldNull sets a field to null.

func (*Doc) SetOperator 

func (d *Doc) SetOperator(op DocOperator)

SetOperator sets the document operator.

func (*Doc) SetPK 

func (d *Doc) SetPK(pk string)

SetPK sets the primary key of the document.

func (*Doc) SetScore 

func (d *Doc) SetScore(score float32)

SetScore sets the document score.

type DocOperator 

type DocOperator int

DocOperator represents the document operation type. 

const (
	DocOpInsert DocOperator = 0
	DocOpUpdate DocOperator = 1
	DocOpUpsert DocOperator = 2
	DocOpDelete DocOperator = 3
)

type Error 

type Error struct {
	Code    ErrorCode
	Message string
}

Error represents a zvec error with code and message.

func (*Error) Error 

func (e *Error) Error() string

type ErrorCode 

type ErrorCode int

ErrorCode represents a zvec error code. 

const (
	ErrOK                 ErrorCode = 0
	ErrNotFound           ErrorCode = 1
	ErrAlreadyExists      ErrorCode = 2
	ErrInvalidArgument    ErrorCode = 3
	ErrPermissionDenied   ErrorCode = 4
	ErrFailedPrecondition ErrorCode = 5
	ErrResourceExhausted  ErrorCode = 6
	ErrUnavailable        ErrorCode = 7
	ErrInternalError      ErrorCode = 8
	ErrNotSupported       ErrorCode = 9
	ErrUnknown            ErrorCode = 10
)

type FieldSchema 

type FieldSchema struct {
	// contains filtered or unexported fields
}

FieldSchema wraps zvec_field_schema_t (opaque pointer).

func NewFieldSchema 

func NewFieldSchema(name string, dataType DataType, nullable bool, dimension uint32) *FieldSchema

NewFieldSchema creates a new field schema with the specified parameters.

func (*FieldSchema) Destroy 

func (f *FieldSchema) Destroy()

Destroy releases the field schema resources if owned.

func (*FieldSchema) GetDataType 

func (f *FieldSchema) GetDataType() DataType

GetDataType returns the field data type.

func (*FieldSchema) GetDimension 

func (f *FieldSchema) GetDimension() uint32

GetDimension returns the field dimension (for vector fields).

func (*FieldSchema) GetIndexType 

func (f *FieldSchema) GetIndexType() IndexType

GetIndexType returns the index type of the field.

func (*FieldSchema) GetName 

func (f *FieldSchema) GetName() string

GetName returns the field name.

func (*FieldSchema) HasIndex 

func (f *FieldSchema) HasIndex() bool

HasIndex returns whether the field has an index.

func (*FieldSchema) IsDenseVector 

func (f *FieldSchema) IsDenseVector() bool

IsDenseVector returns whether the field is a dense vector field.

func (*FieldSchema) IsNullable 

func (f *FieldSchema) IsNullable() bool

IsNullable returns whether the field is nullable.

func (*FieldSchema) IsSparseVector 

func (f *FieldSchema) IsSparseVector() bool

IsSparseVector returns whether the field is a sparse vector field.

func (*FieldSchema) IsVectorField 

func (f *FieldSchema) IsVectorField() bool

IsVectorField returns whether the field is a vector field (dense or sparse).

func (*FieldSchema) SetDataType 

func (f *FieldSchema) SetDataType(dataType DataType) error

SetDataType sets the field data type.

func (*FieldSchema) SetDimension 

func (f *FieldSchema) SetDimension(dimension uint32) error

SetDimension sets the field dimension (for vector fields).

func (*FieldSchema) SetIndexParams 

func (f *FieldSchema) SetIndexParams(params *IndexParams) error

SetIndexParams sets the index parameters for the field.

func (*FieldSchema) SetName 

func (f *FieldSchema) SetName(name string) error

SetName sets the field name.

func (*FieldSchema) SetNullable 

func (f *FieldSchema) SetNullable(nullable bool) error

SetNullable sets whether the field is nullable.

type FlatQueryParams 

type FlatQueryParams struct {
	// contains filtered or unexported fields
}

FlatQueryParams represents query parameters for Flat index.

func NewFlatQueryParams 

func NewFlatQueryParams(isUsingRefiner bool, scaleFactor float32) *FlatQueryParams

NewFlatQueryParams creates a new Flat query parameters instance.

func (*FlatQueryParams) Destroy 

func (p *FlatQueryParams) Destroy()

Destroy releases the Flat query parameters resources.

type GroupByVectorQuery 

type GroupByVectorQuery struct {
	// contains filtered or unexported fields
}

GroupByVectorQuery represents a group-by vector query operation.

func NewGroupByVectorQuery 

func NewGroupByVectorQuery() *GroupByVectorQuery

NewGroupByVectorQuery creates a new group-by vector query instance.

func (*GroupByVectorQuery) Destroy 

func (q *GroupByVectorQuery) Destroy()

Destroy releases the group-by vector query resources.

func (*GroupByVectorQuery) SetFieldName 

func (q *GroupByVectorQuery) SetFieldName(name string) error

SetFieldName sets the field name for the vector query.

func (*GroupByVectorQuery) SetFilter 

func (q *GroupByVectorQuery) SetFilter(filter string) error

SetFilter sets the filter expression for the query.

func (*GroupByVectorQuery) SetFlatParams 

func (q *GroupByVectorQuery) SetFlatParams(params *FlatQueryParams) error

SetFlatParams sets the Flat query parameters.

func (*GroupByVectorQuery) SetGroupByFieldName 

func (q *GroupByVectorQuery) SetGroupByFieldName(name string) error

SetGroupByFieldName sets the group-by field name.

func (*GroupByVectorQuery) SetGroupCount 

func (q *GroupByVectorQuery) SetGroupCount(count uint32) error

SetGroupCount sets the group count parameter.

func (*GroupByVectorQuery) SetGroupTopK 

func (q *GroupByVectorQuery) SetGroupTopK(topk uint32) error

SetGroupTopK sets the group top-k parameter.

func (*GroupByVectorQuery) SetHNSWParams 

func (q *GroupByVectorQuery) SetHNSWParams(params *HNSWQueryParams) error

SetHNSWParams sets the HNSW query parameters.

func (*GroupByVectorQuery) SetIVFParams 

func (q *GroupByVectorQuery) SetIVFParams(params *IVFQueryParams) error

SetIVFParams sets the IVF query parameters.

func (*GroupByVectorQuery) SetIncludeVector 

func (q *GroupByVectorQuery) SetIncludeVector(include bool) error

SetIncludeVector sets whether to include vector data in results.

func (*GroupByVectorQuery) SetOutputFields 

func (q *GroupByVectorQuery) SetOutputFields(fields []string) error

SetOutputFields sets the output fields for the query.

func (*GroupByVectorQuery) SetQueryVector 

func (q *GroupByVectorQuery) SetQueryVector(data []float32) error

SetQueryVector sets the query vector data.

type HNSWQueryParams 

type HNSWQueryParams struct {
	// contains filtered or unexported fields
}

HNSWQueryParams represents query parameters for HNSW index.

func NewHNSWQueryParams 

func NewHNSWQueryParams(ef int, radius float32, isLinear, isUsingRefiner bool) *HNSWQueryParams

NewHNSWQueryParams creates a new HNSW query parameters instance.

func (*HNSWQueryParams) Destroy 

func (p *HNSWQueryParams) Destroy()

Destroy releases the HNSW query parameters resources.

func (*HNSWQueryParams) GetEf 

func (p *HNSWQueryParams) GetEf() int

GetEf returns the ef parameter.

func (*HNSWQueryParams) SetEf 

func (p *HNSWQueryParams) SetEf(ef int) error

SetEf sets the ef parameter for HNSW query.

type IVFQueryParams 

type IVFQueryParams struct {
	// contains filtered or unexported fields
}

IVFQueryParams represents query parameters for IVF index.

func NewIVFQueryParams 

func NewIVFQueryParams(nprobe int, isUsingRefiner bool, scaleFactor float32) *IVFQueryParams

NewIVFQueryParams creates a new IVF query parameters instance.

func (*IVFQueryParams) Destroy 

func (p *IVFQueryParams) Destroy()

Destroy releases the IVF query parameters resources.

func (*IVFQueryParams) SetNprobe 

func (p *IVFQueryParams) SetNprobe(nprobe int) error

SetNprobe sets the nprobe parameter for IVF query.

type IndexParams 

type IndexParams struct {
	// contains filtered or unexported fields
}

IndexParams wraps zvec_index_params_t (opaque pointer).

func NewFlatIndexParams 

func NewFlatIndexParams(metric MetricType) *IndexParams

NewFlatIndexParams creates Flat index parameters with the specified metric type.

func NewHNSWIndexParams 

func NewHNSWIndexParams(metric MetricType, m, efConstruction int) *IndexParams

NewHNSWIndexParams creates HNSW index parameters with the specified metric type and parameters.

func NewIVFIndexParams 

func NewIVFIndexParams(metric MetricType, nList, nIters int, useSoar bool) *IndexParams

NewIVFIndexParams creates IVF index parameters with the specified metric type and parameters.

func NewIndexParams 

func NewIndexParams(indexType IndexType) *IndexParams

NewIndexParams creates index parameters with the specified index type.

func NewInvertIndexParams 

func NewInvertIndexParams(enableRangeOpt, enableWildcard bool) *IndexParams

NewInvertIndexParams creates invert index parameters with the specified options.

func (*IndexParams) Destroy 

func (p *IndexParams) Destroy()

Destroy releases the index parameters resources.

func (*IndexParams) GetHNSWEfConstruction 

func (p *IndexParams) GetHNSWEfConstruction() int

GetHNSWEfConstruction returns the HNSW ef_construction parameter.

func (*IndexParams) GetHNSWM 

func (p *IndexParams) GetHNSWM() int

GetHNSWM returns the HNSW m parameter.

func (*IndexParams) GetMetricType 

func (p *IndexParams) GetMetricType() MetricType

GetMetricType returns the metric type.

func (*IndexParams) GetQuantizeType 

func (p *IndexParams) GetQuantizeType() QuantizeType

GetQuantizeType returns the quantize type.

func (*IndexParams) GetType 

func (p *IndexParams) GetType() IndexType

GetType returns the index type.

func (*IndexParams) SetHNSWParams 

func (p *IndexParams) SetHNSWParams(m, efConstruction int) error

SetHNSWParams sets HNSW specific parameters.

func (*IndexParams) SetIVFParams 

func (p *IndexParams) SetIVFParams(nList, nIters int, useSoar bool) error

SetIVFParams sets IVF specific parameters.

func (*IndexParams) SetInvertParams 

func (p *IndexParams) SetInvertParams(enableRangeOpt, enableWildcard bool) error

SetInvertParams sets invert index specific parameters.

func (*IndexParams) SetMetricType 

func (p *IndexParams) SetMetricType(metric MetricType) error

SetMetricType sets the metric type for vector indexes.

func (*IndexParams) SetQuantizeType 

func (p *IndexParams) SetQuantizeType(quantize QuantizeType) error

SetQuantizeType sets the quantize type for vector indexes.

type IndexType 

type IndexType uint32

IndexType represents the type of index. 

const (
	IndexTypeUndefined IndexType = 0
	IndexTypeHNSW      IndexType = 1
	IndexTypeIVF       IndexType = 2
	IndexTypeFlat      IndexType = 3
	IndexTypeInvert    IndexType = 10
)

type LogLevel 

type LogLevel int

LogLevel represents the log level. 

const (
	LogLevelDebug LogLevel = 0
	LogLevelInfo  LogLevel = 1
	LogLevelWarn  LogLevel = 2
	LogLevelError LogLevel = 3
	LogLevelFatal LogLevel = 4
)

type MetricType 

type MetricType uint32

MetricType represents the distance metric type. 

const (
	MetricTypeUndefined MetricType = 0
	MetricTypeL2        MetricType = 1
	MetricTypeIP        MetricType = 2
	MetricTypeCosine    MetricType = 3
	MetricTypeMIPSL2    MetricType = 4
)

type QuantizeType 

type QuantizeType uint32

QuantizeType represents the quantization type. 

const (
	QuantizeTypeUndefined QuantizeType = 0
	QuantizeTypeFP16      QuantizeType = 1
	QuantizeTypeInt8      QuantizeType = 2
	QuantizeTypeInt4      QuantizeType = 3
)

type VectorQuery 

type VectorQuery struct {
	// contains filtered or unexported fields
}

VectorQuery represents a vector query operation.

func NewVectorQuery 

func NewVectorQuery() *VectorQuery

NewVectorQuery creates a new vector query instance.

func (*VectorQuery) Destroy 

func (q *VectorQuery) Destroy()

Destroy releases the vector query resources.

func (*VectorQuery) GetFieldName 

func (q *VectorQuery) GetFieldName() string

GetFieldName returns the field name.

func (*VectorQuery) GetFilter 

func (q *VectorQuery) GetFilter() string

GetFilter returns the filter expression.

func (*VectorQuery) GetIncludeDocID 

func (q *VectorQuery) GetIncludeDocID() bool

GetIncludeDocID returns whether document ID is included in results.

func (*VectorQuery) GetIncludeVector 

func (q *VectorQuery) GetIncludeVector() bool

GetIncludeVector returns whether vector data is included in results.

func (*VectorQuery) GetTopK 

func (q *VectorQuery) GetTopK() int

GetTopK returns the top-k parameter.

func (*VectorQuery) SetFieldName 

func (q *VectorQuery) SetFieldName(name string) error

SetFieldName sets the field name for the vector query.

func (*VectorQuery) SetFilter 

func (q *VectorQuery) SetFilter(filter string) error

SetFilter sets the filter expression for the query.

func (*VectorQuery) SetFlatParams 

func (q *VectorQuery) SetFlatParams(params *FlatQueryParams) error

SetFlatParams sets the Flat query parameters.

func (*VectorQuery) SetHNSWParams 

func (q *VectorQuery) SetHNSWParams(params *HNSWQueryParams) error

SetHNSWParams sets the HNSW query parameters. Note: ownership of params is transferred to the query.

func (*VectorQuery) SetIVFParams 

func (q *VectorQuery) SetIVFParams(params *IVFQueryParams) error

SetIVFParams sets the IVF query parameters.

func (*VectorQuery) SetIncludeDocID 

func (q *VectorQuery) SetIncludeDocID(include bool) error

SetIncludeDocID sets whether to include document ID in results.

func (*VectorQuery) SetIncludeVector 

func (q *VectorQuery) SetIncludeVector(include bool) error

SetIncludeVector sets whether to include vector data in results.

func (*VectorQuery) SetOutputFields 

func (q *VectorQuery) SetOutputFields(fields []string) error

SetOutputFields sets the output fields for the query.

func (*VectorQuery) SetQueryVector 

func (q *VectorQuery) SetQueryVector(data []float32) error

SetQueryVector sets the query vector data.

func (*VectorQuery) SetTopK 

func (q *VectorQuery) SetTopK(topk int) error

SetTopK sets the top-k parameter for the query.

type WriteResult 

type WriteResult struct {
	SuccessCount uint64
	ErrorCount   uint64
}

WriteResult holds the result of a write operation (insert/update/upsert/delete).

Source Files

View all Source files

Directories

Path Synopsis
cmd
download-libs command
download-libs downloads the pre-built zvec C-API libraries for the current platform from the upstream zvec-ai/zvec-go GitHub Releases.
 download-libs downloads the pre-built zvec C-API libraries for the current platform from the upstream zvec-ai/zvec-go GitHub Releases.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.