xvec

xvec is a pure-Go reimplementation of Alibaba zvec, providing an embedded vector database with durable local storage. It runs inside your application without CGO, a separate database server, or prebuilt native libraries.

• Dense and sparse vector storage with exact and approximate nearest-neighbor search.
• Flat, HNSW, HNSW-RaBitQ, IVF, Vamana, and DiskANN indexes.
• L2, inner-product, cosine, and MIPS-L2 metrics with optional quantization and refinement.
• Scalar filtering, block-max WAND BM25 full-text search, grouping, and hybrid multi-query retrieval.
• Configurable WAL durability batching, crash recovery, segment-native incremental indexes, and atomic compaction.
• Pure Go on Linux, macOS, and Windows.

xvec requires Go 1.26 or later.

go get github.com/gorse-io/xvec

Then import it in your application:

import "github.com/gorse-io/xvec"

The following program creates a local collection, stores vectors with metadata, and returns the two nearest documents.

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/gorse-io/xvec"
)

func main() {
	ctx := context.Background()

	schema := xvec.NewCollectionSchema("articles",
		xvec.NewField("title", xvec.DataTypeString),
		xvec.NewField("category", xvec.DataTypeString),
		xvec.FieldSchema{
			Name:      "embedding",
			DataType:  xvec.DataTypeVectorFP32,
			Dimension: 3,
			Index:     xvec.NewFlatIndexParams(xvec.MetricTypeCosine),
		},
	)

	collection, err := xvec.CreateAndOpen(
		ctx,
		"./data/articles",
		schema,
		xvec.NewCollectionOptions(),
	)
	if err != nil {
		log.Fatal(err)
	}
	defer collection.Close()

	_, err = collection.Insert(ctx, []xvec.Document{
		{
			PrimaryKey: "go",
			Fields: map[string]any{
				"title":     "The Go Programming Language",
				"category":  "programming",
				"embedding": xvec.VectorFP32{1.0, 0.1, 0.0},
			},
		},
		{
			PrimaryKey: "vector",
			Fields: map[string]any{
				"title":     "Vector Search Fundamentals",
				"category":  "search",
				"embedding": xvec.VectorFP32{0.9, 0.2, 0.1},
			},
		},
		{
			PrimaryKey: "sql",
			Fields: map[string]any{
				"title":     "Database Internals",
				"category":  "database",
				"embedding": xvec.VectorFP32{0.0, 0.2, 1.0},
			},
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	results, err := collection.Query(ctx, xvec.VectorQuery{
		Field:       "embedding",
		DenseVector: xvec.VectorFP32{1.0, 0.0, 0.0},
		TopK:        2,
		Projection: xvec.Projection{
			OutputFields: []string{"title", "category"},
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	for _, result := range results {
		fmt.Printf("%s: %s (score %.4f)\n",
			result.PrimaryKey,
			result.Fields["title"],
			result.Score,
		)
	}
}

The collection is persisted under ./data/articles. Reopen it after restarting your application with:

collection, err := xvec.Open(
    context.Background(),
    "./data/articles",
    xvec.NewCollectionOptions(),
)

Use Insert, Upsert, Update, and Delete for document mutations. Call Flush to publish an immutable segment and Optimize to compact stored data; Close synchronizes pending WAL records. Set CollectionOptions.WALSyncEvery to synchronize automatically after a chosen number of successful records; zero disables automatic record-count-based synchronization. Query also accepts PrimaryKey as a vector target, a single FTS clause, or a filter-only request with no target. MultiQuery fuses dense, sparse, primary-key-vector, and FTS branches over one snapshot.

Dense vectors support FP16 and FP32 storage, plus supported scalar quantization options. Sparse vectors support exact Flat and HNSW inner-product search. See the Collection API and vector query semantics for filters, radius queries, projections, ANN parameters, grouping, and refinement.

• Collection API
• Vector query semantics
• Hybrid MultiQuery
• Segment-native indexes
• Runtime configuration
• Native Go disk format
• VectorDBBench-compatible Go benchmark

The root xvec package is the public API. xvec uses native Go disk format v2 and does not read C++ zvec collection files. Version 1 collections are rejected; there is no compatibility, migration, fallback, or dual-write path.

Apache License 2.0. See LICENSE and NOTICE.