zvec

package module
v0.6.0 Latest Latest
Warning

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

 Go to latest Published: Jul 20, 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 — 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.6.0

# Use in your project with replace directive
# In your project's go.mod:
#   require github.com/zvec-ai/zvec-go v0.6.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.6.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.6.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:

This file exists to enable `go generate github.com/zvec-ai/zvec-go` for downloading pre-built zvec C-API libraries from GitHub Releases.

Usage: 

go generate github.com/zvec-ai/zvec-go

This will run the download-libs command which: 1. Detects your current platform (darwin/arm64, linux/amd64, etc.) 2. Downloads the pre-built library archive from GitHub Releases 3. Extracts it to the ./lib directory

The version defaults to the latest published GitHub release (queried via the GitHub Releases API), or can be specified via the -version flag.

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 (
	ErrNotFound           = &Error{Code: NotFound, Message: "resource not found"}
	ErrAlreadyExists      = &Error{Code: AlreadyExists, Message: "resource already exists"}
	ErrInvalidArgument    = &Error{Code: InvalidArgument, Message: "invalid argument"}
	ErrPermissionDenied   = &Error{Code: PermissionDenied, Message: "permission denied"}
	ErrFailedPrecondition = &Error{Code: FailedPrecondition, Message: "failed precondition"}
	ErrResourceExhausted  = &Error{Code: ResourceExhausted, Message: "resource exhausted"}
	ErrUnavailable        = &Error{Code: Unavailable, Message: "unavailable"}
	ErrInternalError      = &Error{Code: InternalError, Message: "internal error"}
	ErrNotSupported       = &Error{Code: NotSupported, Message: "not supported"}
	ErrUnknown            = &Error{Code: Unknown, 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 GetDefaultJiebaDictDir added in v0.5.0 

func GetDefaultJiebaDictDir() string

GetDefaultJiebaDictDir returns the process-wide default jieba dictionary directory.

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 SetDefaultJiebaDictDir added in v0.5.0 

func SetDefaultJiebaDictDir(dir string)

SetDefaultJiebaDictDir sets the process-wide default jieba dictionary directory. Thread-safe. Pass empty string to clear.

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, opts *FetchOptions) ([]*Doc, error)

Fetch retrieves documents by primary keys. Pass nil for opts to use defaults (all fields, no vectors). 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) MultiQuery added in v0.5.0 

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

MultiQuery performs a multi-query search combining multiple sub-queries. The caller is responsible for calling Destroy() on each returned Doc, or using FreeDocs() to free all at once.

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 *SearchQuery) ([]*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) GetFTSBruteForceByKeysRatio added in v0.5.0 

func (c *ConfigData) GetFTSBruteForceByKeysRatio() float32

GetFTSBruteForceByKeysRatio returns the FTS brute force by keys ratio.

func (*ConfigData) GetJiebaDictDir added in v0.5.0 

func (c *ConfigData) GetJiebaDictDir() string

GetJiebaDictDir returns the jieba dictionary directory.

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) SetFTSBruteForceByKeysRatio added in v0.5.0 

func (c *ConfigData) SetFTSBruteForceByKeysRatio(ratio float32) error

SetFTSBruteForceByKeysRatio sets the FTS brute force by keys ratio.

func (*ConfigData) SetFileLog 

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

SetFileLog configures file logging.

func (*ConfigData) SetJiebaDictDir added in v0.5.0 

func (c *ConfigData) SetJiebaDictDir(dir string) error

SetJiebaDictDir sets the jieba dictionary directory.

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
)

func (DataType) String added in v0.5.0 

func (d DataType) String() string

type DiskANNQueryParams added in v0.6.0 

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

DiskANNQueryParams represents query parameters for DiskANN index.

func NewDiskANNQueryParams added in v0.6.0 

func NewDiskANNQueryParams(listSize int) *DiskANNQueryParams

NewDiskANNQueryParams creates a new DiskANN query parameters instance.

func (*DiskANNQueryParams) Destroy added in v0.6.0 

func (p *DiskANNQueryParams) Destroy()

Destroy releases the DiskANN query parameters resources.

func (*DiskANNQueryParams) GetIsLinear added in v0.6.0 

func (p *DiskANNQueryParams) GetIsLinear() bool

GetIsLinear returns the linear search mode.

func (*DiskANNQueryParams) GetIsUsingRefiner added in v0.6.0 

func (p *DiskANNQueryParams) GetIsUsingRefiner() bool

GetIsUsingRefiner returns whether to use refiner.

func (*DiskANNQueryParams) GetListSize added in v0.6.0 

func (p *DiskANNQueryParams) GetListSize() int

GetListSize returns the search frontier size.

func (*DiskANNQueryParams) GetRadius added in v0.6.0 

func (p *DiskANNQueryParams) GetRadius() float32

GetRadius returns the search radius.

func (*DiskANNQueryParams) SetIsLinear added in v0.6.0 

func (p *DiskANNQueryParams) SetIsLinear(isLinear bool) error

SetIsLinear sets the linear search mode.

func (*DiskANNQueryParams) SetIsUsingRefiner added in v0.6.0 

func (p *DiskANNQueryParams) SetIsUsingRefiner(isUsingRefiner bool) error

SetIsUsingRefiner sets whether to use refiner.

func (*DiskANNQueryParams) SetListSize added in v0.6.0 

func (p *DiskANNQueryParams) SetListSize(listSize int) error

SetListSize sets the search frontier size.

func (*DiskANNQueryParams) SetRadius added in v0.6.0 

func (p *DiskANNQueryParams) SetRadius(radius float32) error

SetRadius sets the search radius.

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.

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.

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
)

func (DocOperator) String added in v0.5.0 

func (d DocOperator) String() string

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 (
	OK                 ErrorCode = 0
	NotFound           ErrorCode = 1
	AlreadyExists      ErrorCode = 2
	InvalidArgument    ErrorCode = 3
	PermissionDenied   ErrorCode = 4
	FailedPrecondition ErrorCode = 5
	ResourceExhausted  ErrorCode = 6
	Unavailable        ErrorCode = 7
	InternalError      ErrorCode = 8
	NotSupported       ErrorCode = 9
	Unknown            ErrorCode = 10
)

func (ErrorCode) String added in v0.5.0 

func (c ErrorCode) String() string

String returns the string representation of the error code.

type FTS added in v0.5.0 

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

FTS represents an FTS query payload (query string + match string).

func NewFTS added in v0.5.0 

func NewFTS() *FTS

NewFTS creates a new FTS query payload.

func (*FTS) Destroy added in v0.5.0 

func (f *FTS) Destroy()

Destroy releases the FTS query payload resources. Must not be called on FTS instances returned by SearchQuery.GetFTS().

func (*FTS) GetMatchString added in v0.5.0 

func (f *FTS) GetMatchString() string

GetMatchString returns the FTS match string.

func (*FTS) GetQueryString added in v0.5.0 

func (f *FTS) GetQueryString() string

GetQueryString returns the FTS query expression.

func (*FTS) SetMatchString added in v0.5.0 

func (f *FTS) SetMatchString(match string) error

SetMatchString sets the FTS natural-language match string.

func (*FTS) SetQueryString added in v0.5.0 

func (f *FTS) SetQueryString(query string) error

SetQueryString sets the FTS boolean / advanced query expression.

type FTSQueryParams added in v0.5.0 

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

FTSQueryParams represents query parameters for FTS index.

func NewFTSQueryParams added in v0.5.0 

func NewFTSQueryParams(defaultOperator string) *FTSQueryParams

NewFTSQueryParams creates a new FTS query parameters instance. defaultOperator is the boolean operator for adjacent bare terms ("OR" or "AND"). Pass empty string to use the built-in default.

func (*FTSQueryParams) Destroy added in v0.5.0 

func (p *FTSQueryParams) Destroy()

Destroy releases the FTS query parameters resources.

func (*FTSQueryParams) GetDefaultOperator added in v0.5.0 

func (p *FTSQueryParams) GetDefaultOperator() string

GetDefaultOperator returns the default boolean operator.

func (*FTSQueryParams) SetDefaultOperator added in v0.5.0 

func (p *FTSQueryParams) SetDefaultOperator(op string) error

SetDefaultOperator sets the default boolean operator.

type FetchOptions added in v0.5.0 

type FetchOptions struct {
	OutputFields  []string
	IncludeVector bool
}

FetchOptions controls optional parameters for Fetch.

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 GroupBySearchQuery added in v0.5.0 

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

GroupBySearchQuery represents a group-by vector query operation.

func NewGroupBySearchQuery added in v0.5.0 

func NewGroupBySearchQuery() *GroupBySearchQuery

NewGroupBySearchQuery creates a new group-by vector query instance.

func (*GroupBySearchQuery) Destroy added in v0.5.0 

func (q *GroupBySearchQuery) Destroy()

Destroy releases the group-by vector query resources.

func (*GroupBySearchQuery) SetDiskANNParams added in v0.6.0 

func (q *GroupBySearchQuery) SetDiskANNParams(params *DiskANNQueryParams) error

SetDiskANNParams sets the DiskANN query parameters. Ownership of params is transferred to the query on success.

func (*GroupBySearchQuery) SetFieldName added in v0.5.0 

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

SetFieldName sets the field name for the vector query.

func (*GroupBySearchQuery) SetFilter added in v0.5.0 

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

SetFilter sets the filter expression for the query.

func (*GroupBySearchQuery) SetFlatParams added in v0.5.0 

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

SetFlatParams sets the Flat query parameters.

func (*GroupBySearchQuery) SetGroupByFieldName added in v0.5.0 

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

SetGroupByFieldName sets the group-by field name.

func (*GroupBySearchQuery) SetGroupCount added in v0.5.0 

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

SetGroupCount sets the group count parameter.

func (*GroupBySearchQuery) SetHNSWParams added in v0.5.0 

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

SetHNSWParams sets the HNSW query parameters.

func (*GroupBySearchQuery) SetIVFParams added in v0.5.0 

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

SetIVFParams sets the IVF query parameters.

func (*GroupBySearchQuery) SetIncludeVector added in v0.5.0 

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

SetIncludeVector sets whether to include vector data in results.

func (*GroupBySearchQuery) SetOutputFields added in v0.5.0 

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

SetOutputFields sets the output fields for the query.

func (*GroupBySearchQuery) SetQueryVector added in v0.5.0 

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

SetQueryVector sets the query vector data.

func (*GroupBySearchQuery) SetTopkPerGroup added in v0.6.0 

func (q *GroupBySearchQuery) SetTopkPerGroup(topk uint32) error

SetTopkPerGroup sets the maximum number of results per group.

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 NewDiskANNIndexParams added in v0.6.0 

func NewDiskANNIndexParams(metric MetricType, maxDegree, listSize, pqChunkNum int) (*IndexParams, error)

NewDiskANNIndexParams creates DiskANN index parameters with the specified metric type.

func NewFTSIndexParams added in v0.5.0 

func NewFTSIndexParams(tokenizerName string, filters []string, extraParams string) (*IndexParams, error)

NewFTSIndexParams creates FTS index parameters with the specified tokenizer and filters.

func NewFlatIndexParams 

func NewFlatIndexParams(metric MetricType) (*IndexParams, error)

NewFlatIndexParams creates Flat index parameters with the specified metric type.

func NewHNSWIndexParams 

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

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

func NewIVFIndexParams 

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

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, error)

NewInvertIndexParams creates invert index parameters with the specified options.

func (*IndexParams) Destroy 

func (p *IndexParams) Destroy()

Destroy releases the index parameters resources.

func (*IndexParams) GetDiskANNListSize added in v0.6.0 

func (p *IndexParams) GetDiskANNListSize() int

GetDiskANNListSize returns the DiskANN list_size parameter.

func (*IndexParams) GetDiskANNMaxDegree added in v0.6.0 

func (p *IndexParams) GetDiskANNMaxDegree() int

GetDiskANNMaxDegree returns the DiskANN max_degree parameter.

func (*IndexParams) GetDiskANNPQChunkNum added in v0.6.0 

func (p *IndexParams) GetDiskANNPQChunkNum() int

GetDiskANNPQChunkNum returns the DiskANN pq_chunk_num parameter.

func (*IndexParams) GetFTSParams added in v0.5.0 

func (p *IndexParams) GetFTSParams() (tokenizerName string, filters []string, extraParams string, err error)

GetFTSParams returns FTS index parameters.

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) SetDiskANNParams added in v0.6.0 

func (p *IndexParams) SetDiskANNParams(maxDegree, listSize, pqChunkNum int) error

SetDiskANNParams sets DiskANN specific parameters.

func (*IndexParams) SetFTSParams added in v0.5.0 

func (p *IndexParams) SetFTSParams(tokenizerName string, filters []string, extraParams string) error

SetFTSParams sets FTS index specific parameters.

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
	IndexTypeDiskANN   IndexType = 5
	IndexTypeInvert    IndexType = 10
	IndexTypeFTS       IndexType = 11
)

func (IndexType) String added in v0.5.0 

func (i IndexType) String() string

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
)

func (LogLevel) String added in v0.5.0 

func (l LogLevel) String() string

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
)

func (MetricType) String added in v0.5.0 

func (m MetricType) String() string

type MultiQuery added in v0.5.0 

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

MultiQuery represents a multi-query operation combining multiple sub-queries.

func NewMultiQuery added in v0.5.0 

func NewMultiQuery() *MultiQuery

NewMultiQuery creates a new multi-query instance.

func (*MultiQuery) AddSubQuery added in v0.5.0 

func (q *MultiQuery) AddSubQuery(sub *SubQuery) error

AddSubQuery adds a sub-query to the multi-query. The sub-query is copied; the caller retains ownership.

func (*MultiQuery) Destroy added in v0.5.0 

func (q *MultiQuery) Destroy()

Destroy releases the multi-query resources.

func (*MultiQuery) GetFilter added in v0.5.0 

func (q *MultiQuery) GetFilter() string

GetFilter returns the filter expression.

func (*MultiQuery) GetIncludeVector added in v0.5.0 

func (q *MultiQuery) GetIncludeVector() bool

GetIncludeVector returns whether vector data is included in results.

func (*MultiQuery) GetSubQueryCount added in v0.5.0 

func (q *MultiQuery) GetSubQueryCount() int

GetSubQueryCount returns the number of sub-queries.

func (*MultiQuery) GetTopK added in v0.5.0 

func (q *MultiQuery) GetTopK() int

GetTopK returns the top-k parameter.

func (*MultiQuery) SetFilter added in v0.5.0 

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

SetFilter sets the filter expression for the multi-query.

func (*MultiQuery) SetIncludeVector added in v0.5.0 

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

SetIncludeVector sets whether to include vector data in results.

func (*MultiQuery) SetOutputFields added in v0.5.0 

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

SetOutputFields sets the output fields for the multi-query.

func (*MultiQuery) SetRerankRRF added in v0.5.0 

func (q *MultiQuery) SetRerankRRF(rankConstant int) error

SetRerankRRF sets the RRF (Reciprocal Rank Fusion) rerank strategy.

func (*MultiQuery) SetRerankWeighted added in v0.5.0 

func (q *MultiQuery) SetRerankWeighted(weights []float64) error

SetRerankWeighted sets the Weighted rerank strategy with the given per-sub-query weights.

func (*MultiQuery) SetTopK added in v0.5.0 

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

SetTopK sets the top-k parameter for the multi-query.

type QuantizeType 

type QuantizeType uint32

QuantizeType represents the quantization type. 

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

func (QuantizeType) String added in v0.5.0 

func (q QuantizeType) String() string

type SearchQuery added in v0.5.0 

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

SearchQuery represents a vector query operation.

func NewSearchQuery added in v0.5.0 

func NewSearchQuery() *SearchQuery

NewSearchQuery creates a new vector query instance.

func (*SearchQuery) Destroy added in v0.5.0 

func (q *SearchQuery) Destroy()

Destroy releases the vector query resources.

func (*SearchQuery) GetFTS added in v0.5.0 

func (q *SearchQuery) GetFTS() *FTS

GetFTS returns the FTS query payload attached to this query. Returns nil if no FTS payload is attached. The returned FTS is owned by the query and must NOT be destroyed by the caller.

func (*SearchQuery) GetFieldName added in v0.5.0 

func (q *SearchQuery) GetFieldName() string

GetFieldName returns the field name.

func (*SearchQuery) GetFilter added in v0.5.0 

func (q *SearchQuery) GetFilter() string

GetFilter returns the filter expression.

func (*SearchQuery) GetIncludeDocID added in v0.5.0 

func (q *SearchQuery) GetIncludeDocID() bool

GetIncludeDocID returns whether document ID is included in results.

func (*SearchQuery) GetIncludeVector added in v0.5.0 

func (q *SearchQuery) GetIncludeVector() bool

GetIncludeVector returns whether vector data is included in results.

func (*SearchQuery) GetTopK added in v0.5.0 

func (q *SearchQuery) GetTopK() int

GetTopK returns the top-k parameter.

func (*SearchQuery) SetDiskANNParams added in v0.6.0 

func (q *SearchQuery) SetDiskANNParams(params *DiskANNQueryParams) error

SetDiskANNParams sets the DiskANN query parameters. Ownership of params is transferred to the query on success.

func (*SearchQuery) SetFTS added in v0.5.0 

func (q *SearchQuery) SetFTS(fts *FTS) error

SetFTS sets the FTS query payload on this query. The payload is copied; the caller retains ownership of fts.

func (*SearchQuery) SetFTSParams added in v0.5.0 

func (q *SearchQuery) SetFTSParams(params *FTSQueryParams) error

SetFTSParams sets the FTS query parameters. Ownership of params is transferred to the query on success.

func (*SearchQuery) SetFieldName added in v0.5.0 

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

SetFieldName sets the field name for the vector query.

func (*SearchQuery) SetFilter added in v0.5.0 

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

SetFilter sets the filter expression for the query.

func (*SearchQuery) SetFlatParams added in v0.5.0 

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

SetFlatParams sets the Flat query parameters.

func (*SearchQuery) SetHNSWParams added in v0.5.0 

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

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

func (*SearchQuery) SetIVFParams added in v0.5.0 

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

SetIVFParams sets the IVF query parameters.

func (*SearchQuery) SetIncludeDocID added in v0.5.0 

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

SetIncludeDocID sets whether to include document ID in results.

func (*SearchQuery) SetIncludeVector added in v0.5.0 

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

SetIncludeVector sets whether to include vector data in results.

func (*SearchQuery) SetOutputFields added in v0.5.0 

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

SetOutputFields sets the output fields for the query.

func (*SearchQuery) SetQueryVector added in v0.5.0 

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

SetQueryVector sets the query vector data.

func (*SearchQuery) SetTopK added in v0.5.0 

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

SetTopK sets the top-k parameter for the query.

type SubQuery added in v0.5.0 

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

SubQuery represents a sub-query within a multi-query.

func NewSubQuery added in v0.5.0 

func NewSubQuery() *SubQuery

NewSubQuery creates a new sub-query instance.

func (*SubQuery) Destroy added in v0.5.0 

func (q *SubQuery) Destroy()

Destroy releases the sub-query resources.

func (*SubQuery) GetFieldName added in v0.5.0 

func (q *SubQuery) GetFieldName() string

GetFieldName returns the field name.

func (*SubQuery) GetNumCandidates added in v0.5.0 

func (q *SubQuery) GetNumCandidates() int

GetNumCandidates returns the number of candidates.

func (*SubQuery) SetDiskANNParams added in v0.6.0 

func (q *SubQuery) SetDiskANNParams(params *DiskANNQueryParams) error

SetDiskANNParams sets the DiskANN query parameters on the sub-query (takes ownership).

Available since zvec v0.6.0 (c_api: zvec_sub_query_set_diskann_params). Ownership of params is transferred to the sub-query on success.

func (*SubQuery) SetFTS added in v0.5.1 

func (q *SubQuery) SetFTS(fts *FTS) error

SetFTS attaches an FTS clause to the sub-query. The clause is copied; the caller retains ownership of fts.

Available since zvec v0.5.1 (c_api: zvec_sub_query_set_fts).

func (*SubQuery) SetFTSParams added in v0.5.1 

func (q *SubQuery) SetFTSParams(params *FTSQueryParams) error

SetFTSParams sets the FTS query parameters on the sub-query (takes ownership).

Available since zvec v0.5.1 (c_api: zvec_sub_query_set_fts_params). This enables FTS as a sub-query inside a MultiQuery, allowing combinations like FTS + Vector rerank via RRF/Weighted. Ownership of params is transferred to the sub-query on success.

func (*SubQuery) SetFieldName added in v0.5.0 

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

SetFieldName sets the field name for the sub-query.

func (*SubQuery) SetFlatParams added in v0.5.0 

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

SetFlatParams sets the Flat query parameters. Ownership of params is transferred to the sub-query on success.

func (*SubQuery) SetHNSWParams added in v0.5.0 

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

SetHNSWParams sets the HNSW query parameters. Ownership of params is transferred to the sub-query on success.

func (*SubQuery) SetIVFParams added in v0.5.0 

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

SetIVFParams sets the IVF query parameters. Ownership of params is transferred to the sub-query on success.

func (*SubQuery) SetNumCandidates added in v0.5.0 

func (q *SubQuery) SetNumCandidates(n int) error

SetNumCandidates sets the number of candidates to retrieve per field.

func (*SubQuery) SetQueryVector added in v0.5.0 

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

SetQueryVector sets the query vector data.

func (*SubQuery) SetSparseVector added in v0.5.0 

func (q *SubQuery) SetSparseVector(indices []uint32, values []float32) error

SetSparseVector sets the sparse vector indices and values.

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.
examples
fts_query command
Package main demonstrates Full-Text Search (FTS) in zvec.
 Package main demonstrates Full-Text Search (FTS) in zvec.

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.