vec

package module
v0.0.0-...-effd846 Latest Latest
Warning

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

 Go to latest Published: Jun 29, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

README

vec

A modern, high-performance, low-latency vector database in pure Go that looks and feels like SQLite: the whole database, the vectors, the ANN indexes, the scalar metadata columns, the catalog, and the free space, lives in one self-describing .vec file with an optional -wal/-shm sidecar. You open it with a path and a line of code.

vec is the vector sibling of kv (an embedded key/value engine) and gr (a graph engine). It reuses their durability lineage, a pager with a buffer pool, a write-ahead log, group commit, MVCC snapshot isolation, and crash recovery, and adds the parts a vector database needs: SIMD distance kernels, a pluggable approximate-nearest-neighbor index seam, quantization with full-precision rerank, metadata filtering, and hybrid search.

The promise SQLite makes, "the database is a file you can copy, email, and trust," is the promise vec keeps, at a latency level SQLite was never designed for: a target of p50 < 1 ms, p99 < 5 ms, and more than 10k QPS for one million 768-dimensional vectors at recall@10 above 0.95.

Design stance

  • The file is the database. One self-describing file, a documented byte format (magic tamnd vector format 1), forward-and-backward version negotiation, copy-to-back-up. The WAL and shared-memory index are sidecars that vanish on clean close.
  • One copy of every vector. Indexes hold positions, not vectors. The flat index is a brute-force oracle; HNSW is the default; IVF-PQ and DiskANN scale out. All plug into one Index SPI.
  • Quantization is orthogonal to the index. Scalar int8, product quantization, OPQ, binary, and fp16 are layered under any index, with a full-precision rerank pass that restores recall.
  • Pure Go, no cgo. SIMD distance kernels are written in Go assembly with runtime CPU dispatch and a portable fallback. The GC is a design constraint, not an afterthought.

Status

Implementation in progress, tracking the design specification in ~/notes/Spec/2062 (26 documents). Each subsystem is built bottom-up and documented as it lands in ~/notes/Spec/2062/implementation. The specification is the source of truth; where an implementation and the spec disagree, the spec is the bug until a doc is updated to match a deliberate change.

Layer Package Spec Implementation doc
On-disk format format 02, 03, 04 implementation/01-format.md
File abstraction vfs 05 implementation/02-pager.md
Pager + buffer pool pager 05 implementation/02-pager.md
Write-ahead log + recovery wal 05 implementation/03-wal.md
MVCC + transactions mvcc 06 implementation/04-mvcc.md
Distance kernels distance 09, 19 implementation/05-distance.md
Quantization quant 09 implementation/06-quant.md
Index SPI + HNSW index 07 implementation/07-index-hnsw.md
IVF / DiskANN index 08 implementation/08-index-ivf-diskann.md
Storage engine storage 04 implementation/09-storage.md
Catalog + data model catalog 02 implementation/10-catalog.md
Query execution + planner query 10, 13 implementation/11-query.md
Filtering + hybrid search hybrid 11 implementation/12-hybrid.md
VectorSQL vsql 12 implementation/13-vsql.md
Integration + library API db, vec 14 implementation/14-api.md
CLI cmd/vec 15 implementation/15-cli.md
Server server 16 implementation/16-server.md

Repository

Public, github.com/tamnd/vec, binary vec, module github.com/tamnd/vec. Pure Go, Go 1.23, no cgo on the build path.

Documentation

Overview

Package vec is the embedded library API for the vec vector database (spec 14).

vec stores vectors, ANN indexes, scalar metadata columns, the catalog, and free space in one self-describing file with the look and feel of SQLite. This root package is the public facade: it wires the storage engine, catalog, query planner and executor, ANN index SPI, and VectorSQL binder behind a small, goroutine-safe surface centered on *DB, *Collection, *Txn, and *QueryBuilder.

The typical lifecycle is open a database, create a collection, upsert points, build an index, and run filtered ANN queries: 

db, err := vec.Open("articles.vec")
if err != nil { log.Fatal(err) }
defer db.Close()

db.CreateCollection(ctx, vec.CollectionSchema{
    Name: "articles",
    Columns: []vec.ColumnDef{
        {Name: "embedding", Type: vec.TypeVector, Dim: 768, Metric: vec.MetricCosine},
        {Name: "author", Type: vec.TypeText},
    },
})
coll, _ := db.Collection("articles")
coll.UpsertBatch(ctx, points)
db.BuildIndex(ctx, "articles", "hnsw_embedding", vec.IndexParams{"m": 32})
rows, _ := coll.Query("embedding", q).K(10).Filter("author = ?", "alice").Exec(ctx)

A *DB is safe for concurrent use; a *Txn and a *Rows are owned by one goroutine from creation to close (spec 14 §11).

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrNotFound        = errors.New("vec: not found")
	ErrAlreadyExists   = errors.New("vec: already exists")
	ErrConflict        = errors.New("vec: write conflict")
	ErrReadOnly        = errors.New("vec: read only")
	ErrClosed          = errors.New("vec: closed")
	ErrDimMismatch     = errors.New("vec: dimension mismatch")
	ErrSchemaViolation = errors.New("vec: schema violation")
	ErrCorrupt         = errors.New("vec: corrupt")
	ErrNeedsRecovery   = errors.New("vec: needs recovery")
	ErrBusy            = errors.New("vec: database is busy")
	ErrTxnTooBig       = errors.New("vec: transaction too big")
	ErrOptionConflict  = errors.New("vec: option conflicts with stored value")
	ErrUnknownColumn   = errors.New("vec: unknown column")
	ErrUnknownParam    = errors.New("vec: unknown index param")
	ErrNotTrainable    = errors.New("vec: not enough vectors for training")
	ErrInvalidSparse   = errors.New("vec: invalid sparse vector")
	ErrOutOfOrder      = errors.New("vec: points out of order")
	ErrCanceled        = errors.New("vec: canceled")
	ErrVersionMismatch = errors.New("vec: version mismatch")
	ErrEncrypted       = errors.New("vec: file is encrypted")
	ErrKeyRequired     = errors.New("vec: encryption key required")
	ErrWrongPassphrase = errors.New("vec: authentication failed")
	ErrNotEncrypted    = errors.New("vec: database is not encrypted")
)

Sentinel errors form the stable error vocabulary of the library (spec 14 §10.1). Each has the numeric code used by the C ABI (spec 14 §13) and the server's JSON responses, so a Go caller, a Python binding, and a REST client all branch on the same integer. Callers test these with errors.Is and extract structured detail with errors.As against the typed error structs below.

Functions

func BuildInfo 

func BuildInfo() (ver, commitHash, buildDate string)

BuildInfo returns the version, commit, and build date. The commit and date are empty for a build that was not made by the release pipeline.

func PragmaInt 

func PragmaInt(db *DB, name string) (int64, error)

PragmaInt is the package-level helper shown in spec 22 §19.5; it reads with a background context.

func PragmaString 

func PragmaString(db *DB, name string) (string, error)

PragmaString is the package-level string helper (spec 22 §19.5).

func RedactFieldKey 

func RedactFieldKey(name string) bool

RedactFieldKey reports whether a structured-log field name names a secret and its value should be replaced with [REDACTED] (spec 23 section 12.3 item 2). The match is case-insensitive on the substrings key, secret, password, token, and passphrase. The logger calls this before writing each field.

func Version 

func Version() string

Version returns the vec library version string (semver).

Types

type APIKey 

type APIKey string

APIKey is a server bearer token that redacts itself. It is the wire form an operator pastes into a client; the auth package stores only its hash.

func (APIKey) GoString 

func (APIKey) GoString() string

func (APIKey) MarshalJSON 

func (APIKey) MarshalJSON() ([]byte, error)

func (APIKey) Reveal 

func (k APIKey) Reveal() string

Reveal returns the token text.

func (APIKey) String 

func (APIKey) String() string

type AnyVector 

type AnyVector struct {
	Dense  Vector
	Sparse *SparseVector
	Multi  MultiVector
}

AnyVector is the vector payload for one column of a point (spec 14 §3.4). Exactly one of Dense, Sparse, or Multi is set, matching the column kind.

type BatchOpt 

type BatchOpt func(*batchConfig)

BatchOpt tunes a batch write (spec 14 §4.4). Options are additive; the zero value is the default behavior.

func WithDurableBatch 

func WithDurableBatch() BatchOpt

WithDurableBatch asks a batch to fsync on commit regardless of the open sync level.

type BulkWriter 

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

BulkWriter is the append-only ingest sink returned by NewBulkWriter (spec 14 §6, spec 17). The streaming ingest pipeline lands with the bulk subsystem; the writer is defined here so the option and loader signatures are stable.

func (*BulkWriter) Add 

func (bw *BulkWriter) Add(p Point) error

Add appends a point to the bulk stream (spec 14 §6). The streaming ingest path is delivered with the bulk subsystem (spec 17).

func (*BulkWriter) Close 

func (bw *BulkWriter) Close() error

Close finalizes the bulk load (spec 14 §6).

func (*BulkWriter) Flush 

func (bw *BulkWriter) Flush() error

Flush flushes buffered points (spec 14 §6).

type BulkWriterOptions 

type BulkWriterOptions struct {
	// Sorted declares the input is already sorted by id, enabling the fast path.
	Sorted bool
	// BatchSize bounds the points buffered before a flush.
	BatchSize int
	// BuildIndex builds the ANN index as part of the load when true.
	BuildIndex bool
}

BulkWriterOptions tunes a BulkWriter (spec 14 §6).

type CheckpointMode 

type CheckpointMode int

CheckpointMode selects how aggressively a checkpoint runs (spec 14 §9). 

const (
	// CheckpointPassive checkpoints what it can without blocking writers.
	CheckpointPassive CheckpointMode = iota
	// CheckpointFull blocks new writers until the WAL is fully applied.
	CheckpointFull
	// CheckpointTruncate is a full checkpoint that also truncates the WAL.
	CheckpointTruncate
)

type CheckpointStats 

type CheckpointStats struct {
	Mode         CheckpointMode
	PagesWritten int64
	WALFrames    int64
}

CheckpointStats reports the result of a checkpoint (spec 14 §9).

type Collection 

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

Collection is a stateless, goroutine-safe reference to a named collection (spec 14 §4.3). It carries no mutable state of its own; every operation resolves the live collection through the *DB.

func (*Collection) Count 

func (c *Collection) Count(ctx context.Context) (int64, error)

Count returns the number of live points in the collection (spec 14 §4.4).

func (*Collection) Delete 

func (c *Collection) Delete(txn *Txn, id PointID) error

Delete deletes a point by id inside txn (spec 14 §4.4).

func (*Collection) DeleteBatch 

func (c *Collection) DeleteBatch(ctx context.Context, ids []PointID, opts ...BatchOpt) error

DeleteBatch removes multiple points (spec 14 §4.4).

func (*Collection) Export 

func (c *Collection) Export(ctx context.Context, w io.Writer, opts ExportOptions) error

Export writes all points to w in the specified format (spec 14 §4.4). The export pipeline is delivered with the bulk subsystem (spec 17).

func (*Collection) Get 

func (c *Collection) Get(txn *Txn, id PointID) (Point, error)

Get fetches a point by id (spec 14 §4.4).

func (*Collection) GetBatch 

func (c *Collection) GetBatch(txn *Txn, ids []PointID) ([]Point, error)

GetBatch fetches multiple points (spec 14 §4.4).

func (*Collection) Insert 

func (c *Collection) Insert(txn *Txn, p Point) (PointID, error)

Insert inserts a point, failing with ErrAlreadyExists if the id exists.

func (*Collection) MultiQuery 

func (c *Collection) MultiQuery(column string, q MultiVector) *QueryBuilder

MultiQuery begins a multi-vector ANN query builder (spec 14 §5). Multi-vector columns are not yet stored, so executing the builder returns an unsupported error.

func (*Collection) Name 

func (c *Collection) Name() string

Name returns the collection name.

func (*Collection) Query 

func (c *Collection) Query(column string, q Vector) *QueryBuilder

Query begins a fluent ANN query builder over a dense vector column (spec 14 §5).

func (*Collection) Scan 

func (c *Collection) Scan(ctx context.Context, fn func(Point) error) error

Scan calls fn for every live point in the collection at a read snapshot taken when Scan begins (spec 17 §3.1). It is the enumeration primitive the bulk dump and logical export paths build on. fn returning a non-nil error stops the scan and that error is returned. Points are visited in storage order, which is not the insertion order after compaction.

func (*Collection) Schema 

func (c *Collection) Schema(ctx context.Context) (CollectionSchema, error)

Schema returns the current schema (spec 14 §4.5).

func (*Collection) SparseQuery 

func (c *Collection) SparseQuery(column string, q SparseVector) *QueryBuilder

SparseQuery begins a sparse ANN query builder (spec 14 §5). Sparse columns are not yet stored, so executing the builder returns ErrInvalidSparse.

func (*Collection) Upsert 

func (c *Collection) Upsert(txn *Txn, p Point) (PointID, error)

Upsert inserts or replaces a point inside txn (spec 14 §4.4).

func (*Collection) UpsertBatch 

func (c *Collection) UpsertBatch(ctx context.Context, points []Point) ([]PointID, error)

UpsertBatch writes many points in a single implicit transaction (spec 14 §4.4).

type CollectionInfo 

type CollectionInfo struct {
	Name       string
	Columns    []ColumnDef
	PointCount int64
}

CollectionInfo is a snapshot of a collection's identity and size (spec 14 §4.6).

type CollectionSchema 

type CollectionSchema struct {
	Name    string
	Columns []ColumnDef
	Comment string
}

CollectionSchema describes a collection at creation (spec 14 §4.1).

type ColumnDef 

type ColumnDef struct {
	Name    string
	Type    ColumnType
	Dim     int    // vector columns only: element count
	Metric  Metric // vector columns only: distance metric
	NotNull bool
	Default *Value
}

ColumnDef declares one column of a collection schema (spec 14 §4.2).

type ColumnType 

type ColumnType uint8

ColumnType is the declared type of a collection column (spec 14 §4.2). A vector column carries a dimension and a metric; the remaining types are scalar metadata columns. 

const (
	TypeVector ColumnType = iota // a fixed-length dense vector column
	TypeInt64
	TypeFloat64
	TypeBool
	TypeText
	TypeBytes
	TypeJSON
	TypeTimestamp
)

func (ColumnType) String 

func (t ColumnType) String() string

String renders a ColumnType as its canonical type name.

type Config 

type Config struct {
	PageSize    int
	CacheBytes  int64
	Synchronous string
	MMap        bool
	Session     SessionConfig
}

Config is a read-only snapshot of the effective configuration at Open time plus any Options applied (spec 22 §26.3). It does not update when a PRAGMA is set after Open; use db.PragmaInt/PragmaString for the current stored value.

func (Config) CacheSizeBytes 

func (c Config) CacheSizeBytes() int64

CacheSizeBytes returns the cache budget in bytes (spec 22 §26.3).

type CorruptError 

type CorruptError struct {
	PageNum          uint32
	Offset           int64
	ChecksumExpected uint32
	ChecksumGot      uint32
}

CorruptError carries the corrupted page or offset (spec 14 §10.3).

func (*CorruptError) Error 

func (e *CorruptError) Error() string

func (*CorruptError) Unwrap 

func (e *CorruptError) Unwrap() error

Unwrap returns ErrCorrupt.

type DB 

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

DB is the long-lived, goroutine-safe handle to one vec database (spec 14 §2). It owns the storage engine and catalog and assembles the query stack on demand. In this build the engine is process-resident: a file path names the database for diagnostics and future on-disk durability, while :memory: is explicitly ephemeral. All collection metadata and points live for the life of the *DB.

func Open 

func Open(path string, opts ...Option) (*DB, error)

Open opens or creates a database at path (spec 14 §2.1). A path of ":memory:" (or a DSN naming mode=memory) creates an ephemeral database.

func OpenDSN 

func OpenDSN(dsn string) (*DB, error)

OpenDSN opens using a DSN/URI with options in the query string (spec 14 §2.1), for example "file:data.vec?mode=ro&cache=256mb".

func OpenReadOnly 

func OpenReadOnly(path string, opts ...Option) (*DB, error)

OpenReadOnly opens path for reading only (spec 14 §2.1).

func (*DB) AlterCollection 

func (db *DB) AlterCollection(ctx context.Context, name string, add ...ColumnDef) error

AlterCollection applies a schema change (spec 14 §4.9). Only adding a metadata column is supported in this build; other alterations report unsupported.

func (*DB) Backup 

func (db *DB) Backup(ctx context.Context, w io.Writer) error

Backup writes a consistent copy of the database to w (spec 14 §8). The backup pipeline lands with the backup subsystem (spec 17).

func (*DB) Begin 

func (db *DB) Begin(ctx context.Context, writable bool) (*Txn, error)

Begin starts a transaction (spec 14 §11.1). A writable transaction blocks until the previous writer commits or rolls back, or until ctx is canceled.

func (*DB) BuildIndex 

func (db *DB) BuildIndex(ctx context.Context, collection string) error

BuildIndex rebuilds the index recorded on the collection (spec 14 §6.2).

func (*DB) BuildIndexAsync 

func (db *DB) BuildIndexAsync(ctx context.Context, collection string) (*IndexBuild, error)

BuildIndexAsync starts an index build and returns a handle to await it (spec 14 §6.6). The embedded build is synchronous, so the returned handle is already done.

func (*DB) BulkLoad 

func (db *DB) BulkLoad(ctx context.Context, collection string, fn LoadFunc, opts BulkWriterOptions) error

BulkLoad runs a load function against a fresh bulk writer (spec 14 §6).

func (*DB) ChangePassphrase 

func (db *DB) ChangePassphrase(ctx context.Context, oldPass, newPass Passphrase) error

ChangePassphrase replaces the passphrase that unlocks the database (spec 23 §9.1). The old passphrase is verified first; a wrong one returns ErrWrongPassphrase and changes nothing.

In a persisted database this is an O(1) operation: the master key is wrapped by a key-encryption key derived from the passphrase, so only the wrapped-key envelope in the header is rewritten and no data page is touched. That envelope lives with the on-disk header, which lands with the pager wiring. This build is process-resident with no persisted header, so the call re-derives the key material under the new passphrase in memory after checking the old one.

func (*DB) Checkpoint 

func (db *DB) Checkpoint(ctx context.Context, mode CheckpointMode) (CheckpointStats, error)

Checkpoint flushes the write-ahead log into the main database (spec 14 §9). The embedded engine is process-resident, so a checkpoint is a no-op that reports zero pending frames; it becomes meaningful with the on-disk durability subsystem.

func (*DB) Close 

func (db *DB) Close() error

Close closes the database; it must be called exactly once (spec 14 §2.6).

func (*DB) Collection 

func (db *DB) Collection(name string) (*Collection, error)

Collection returns a handle to the named collection (spec 14 §4.5).

func (*DB) Collections 

func (db *DB) Collections() ([]*Collection, error)

Collections returns handles to all collections (spec 14 §4.5).

func (*DB) Config 

func (db *DB) Config() Config

Config returns the effective configuration snapshot (spec 22 §26.3).

func (*DB) CreateCollection 

func (db *DB) CreateCollection(ctx context.Context, schema CollectionSchema) error

CreateCollection creates a new collection (spec 14 §4.1). It is an error if the collection already exists.

func (*DB) CreateIndex 

func (db *DB) CreateIndex(ctx context.Context, collection string, spec IndexSpec) error

CreateIndex creates and builds an ANN index over a collection's vector column (spec 14 §6.1). In this build CREATE INDEX populates the index synchronously from the live points; BuildIndex and Reindex rebuild it.

func (*DB) DropCollection 

func (db *DB) DropCollection(ctx context.Context, name string) error

DropCollection drops a collection and all its indexes (spec 14 §4.7).

func (*DB) DropIndex 

func (db *DB) DropIndex(ctx context.Context, collection, name string) error

DropIndex drops the index on a collection (spec 14 §6.7).

func (*DB) Encryption 

func (db *DB) Encryption() EncryptionInfo

Encryption returns the encryption state (spec 23 §3). It never returns key material; the fields describe the configuration, not the secrets.

func (*DB) Exec 

func (db *DB) Exec(ctx context.Context, sql string) (*Rows, error)

Exec runs a VectorSQL statement and returns a cursor (spec 14 §12). Only kNN SELECT statements with a literal query vector execute in this build; DDL and DML flow through the typed collection API.

func (*DB) ExecTxn 

func (db *DB) ExecTxn(ctx context.Context, txn *Txn, sql string) (*Rows, error)

ExecTxn runs a VectorSQL statement inside txn (spec 14 §12).

func (*DB) GetCollection 

func (db *DB) GetCollection(ctx context.Context, name string) (CollectionInfo, error)

GetCollection returns info for one collection (spec 14 §4.6).

func (*DB) IndexStats 

func (db *DB) IndexStats(ctx context.Context, collection string) (IndexStatsDetail, error)

IndexStats reports live statistics for the index on a collection (spec 14 §6.5).

func (*DB) ListCollections 

func (db *DB) ListCollections(ctx context.Context) ([]CollectionInfo, error)

ListCollections lists all collections (spec 14 §4.6).

func (*DB) ListIndexes 

func (db *DB) ListIndexes(ctx context.Context, collection string) ([]IndexInfo, error)

ListIndexes lists the indexes on a collection (spec 14 §6.4).

func (*DB) Metrics 

func (db *DB) Metrics() *obs.Metrics

Metrics returns the database's observability registry (spec 18 §1.3). The same instance backs the library hooks and the server's /metrics endpoint, so there is one set of counters and no double count. It is created on first use.

func (*DB) NewBulkWriter 

func (db *DB) NewBulkWriter(ctx context.Context, collection string, opts BulkWriterOptions) (*BulkWriter, error)

NewBulkWriter opens a streaming bulk-ingest writer (spec 14 §6). The streaming ingest pipeline lands with the bulk subsystem (spec 17).

func (*DB) NewSortedBulkWriter 

func (db *DB) NewSortedBulkWriter(ctx context.Context, collection string, opts BulkWriterOptions) (*BulkWriter, error)

NewSortedBulkWriter opens a bulk writer that assumes id-sorted input (spec 14 §6).

func (*DB) Path 

func (db *DB) Path() string

Path returns the path or DSN the database was opened with.

func (*DB) Pragma 

func (db *DB) Pragma(ctx context.Context, name, value string) (string, error)

Pragma reads or sets a database knob by name (spec 22 §19). An empty value reads the current effective value; a non-empty value sets it and returns the canonical stored form. Reads of diagnostic and configuration PRAGMAs are also handled here. Unknown names return *ErrUnknownPragma; read-only and create-time knobs reject writes with *ErrPragmaReadOnly and *ErrPragmaImmutable.

func (*DB) PragmaInt 

func (db *DB) PragmaInt(ctx context.Context, name string) (int64, error)

PragmaInt reads a knob as an int64. It is the typed counterpart of Pragma for integer knobs (spec 22 §19.5).

func (*DB) PragmaString 

func (db *DB) PragmaString(ctx context.Context, name string) (string, error)

PragmaString reads a knob as its string form (spec 22 §19.5).

func (*DB) ReadSnapshot 

func (db *DB) ReadSnapshot(ctx context.Context) (*Snapshot, error)

ReadSnapshot opens a read snapshot at the current committed sequence (spec 14 §11.4). A snapshot does not take the write lock and never blocks writers.

func (*DB) Reindex 

func (db *DB) Reindex(ctx context.Context, collection string) error

Reindex is an alias for BuildIndex that rebuilds from scratch (spec 14 §6.2).

func (*DB) RekeyVacuum 

func (db *DB) RekeyVacuum(ctx context.Context, secret Passphrase) (RekeyVacuumStats, error)

RekeyVacuum rewrites every page under a fresh epoch and retires every older key (spec 23 §9.3). It is the heavy counterpart to RotateDEK: where rotation is lazy and leaves old-epoch pages in place, a vacuum re-encrypts the whole database so the old DEKs can be released.

The rewrite walks the pager, which this process-resident build does not persist to yet, so there are no on-disk pages to rewrite. The method rotates the epoch and reports zero pages rewritten; it becomes a full pass once the pager writes encrypted pages to a file.

func (*DB) RenameCollection 

func (db *DB) RenameCollection(ctx context.Context, oldName, newName string) error

RenameCollection renames a collection (spec 14 §4.8). The engine keeps the collection by id, so the rename updates the catalog name binding.

func (*DB) RotateDEK 

func (db *DB) RotateDEK(ctx context.Context, secret Passphrase) error

RotateDEK advances the data encryption key to a new epoch (spec 23 §9.2). New page writes use the new key; pages written under earlier epochs stay readable because their epoch is recorded in each page and the old key stays loaded. The supplied secret re-authenticates the caller and re-derives the master key, which the database does not keep in memory between calls.

Rotation is lazy: existing pages are not rewritten here. RekeyVacuum forces a full re-encryption when an operator wants to retire an old epoch's key.

func (*DB) Update 

func (db *DB) Update(ctx context.Context, fn func(txn *Txn) error) error

Update runs fn in a read-write transaction, committing on success and rolling back on error (spec 14 §11). Write conflicts are retried up to the configured maximum.

func (*DB) View 

func (db *DB) View(ctx context.Context, fn func(txn *Txn) error) error

View runs fn in a read-only snapshot transaction (spec 14 §11).

type DimError 

type DimError struct {
	Column   string
	Expected int
	Got      int
}

DimError carries dimension mismatch detail (spec 14 §10.3). It unwraps to ErrDimMismatch so callers can both errors.Is and errors.As.

func (*DimError) Error 

func (e *DimError) Error() string

func (*DimError) Unwrap 

func (e *DimError) Unwrap() error

Unwrap returns ErrDimMismatch.

type EncryptionInfo 

type EncryptionInfo struct {
	Enabled bool
	Cipher  string // "AES-256-GCM" or "ChaCha20-Poly1305"
	KDF     string // "argon2id" or "raw-key"
	Epoch   uint16 // the current write epoch
}

EncryptionInfo reports the at-rest encryption state of a database (spec 23 §3). For an unencrypted database Enabled is false and the other fields are zero.

type EncryptionKey 

type EncryptionKey []byte

EncryptionKey is a raw key that redacts itself. The real bytes are reachable only through Bytes, which the crypto package calls explicitly; nothing prints them.

func (EncryptionKey) Bytes 

func (k EncryptionKey) Bytes() []byte

Bytes returns the underlying key material. Callers must not log or store the result; it exists so the crypto layer can derive the master key.

func (EncryptionKey) GoString 

func (EncryptionKey) GoString() string

func (EncryptionKey) MarshalJSON 

func (EncryptionKey) MarshalJSON() ([]byte, error)

func (EncryptionKey) String 

func (EncryptionKey) String() string

type ErrInvalidConfig 

type ErrInvalidConfig struct {
	Knob   string
	Value  any
	Reason string
}

ErrInvalidConfig reports a knob value that fails validation (spec 22 §27). It carries the knob name, the offending value, and a human-readable reason so a caller can branch on errors.As and still log something useful.

func (*ErrInvalidConfig) Error 

func (e *ErrInvalidConfig) Error() string

type ErrPragmaImmutable 

type ErrPragmaImmutable struct {
	Pragma    string
	FileValue string
	NewValue  string
}

ErrPragmaImmutable reports an attempt to set a create-time PRAGMA on a database that already exists (spec 22 §27). The create-time value in the header wins.

func (*ErrPragmaImmutable) Error 

func (e *ErrPragmaImmutable) Error() string

type ErrPragmaReadOnly 

type ErrPragmaReadOnly struct {
	Pragma string
}

ErrPragmaReadOnly reports an attempt to set a read-only PRAGMA (spec 22 §27).

func (*ErrPragmaReadOnly) Error 

func (e *ErrPragmaReadOnly) Error() string

type ErrSnapshotTooOld 

type ErrSnapshotTooOld struct {
	Age    time.Duration
	MaxAge time.Duration
}

ErrSnapshotTooOld reports a read transaction that outlived max_snapshot_age (spec 22 §16.2, §27).

func (*ErrSnapshotTooOld) Error 

func (e *ErrSnapshotTooOld) Error() string

type ErrUnknownPragma 

type ErrUnknownPragma struct {
	Pragma string
}

ErrUnknownPragma reports a PRAGMA name that is not in the registry (spec 22 §27).

func (*ErrUnknownPragma) Error 

func (e *ErrUnknownPragma) Error() string

type ExportOptions 

type ExportOptions struct {
	// Format is the output encoding: "jsonl" (default), "csv", or "fvecs".
	Format string
	// IncludeVectors writes the stored vectors alongside metadata.
	IncludeVectors bool
	// BatchSize bounds how many points are buffered per flush.
	BatchSize int
}

ExportOptions controls Collection.Export (spec 14 §4.4).

type IndexBuild 

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

IndexBuild is a handle to an asynchronous index build (spec 14 §6.6).

func (*IndexBuild) Done 

func (b *IndexBuild) Done() bool

Done reports whether the build has finished.

func (*IndexBuild) Progress 

func (b *IndexBuild) Progress() IndexBuildStats

Progress returns the latest build progress.

func (*IndexBuild) Wait 

func (b *IndexBuild) Wait() error

Wait blocks until the build finishes and returns its error.

type IndexBuildStats 

type IndexBuildStats struct {
	Phase       string
	PointsDone  int64
	PointsTotal int64
}

IndexBuildStats is the progress callback payload during an index build (spec 14 §6.6, §7.7).

type IndexInfo 

type IndexInfo struct {
	Name   string
	Column string
	Type   IndexType
	Params IndexParams
}

IndexInfo describes one ANN index on a collection (spec 14 §6.4).

type IndexParams 

type IndexParams map[string]any

IndexParams holds index-build tuning knobs by name (spec 14 §6.3), such as "m" and "ef_construction" for HNSW or "nlist" and "nprobe" for IVF.

type IndexSpec 

type IndexSpec struct {
	Name   string
	Column string
	Type   IndexType
	Params IndexParams
}

IndexSpec describes an index to create on a collection (spec 14 §6.1).

type IndexStatsDetail 

type IndexStatsDetail struct {
	Name           string
	Type           IndexType
	NodeCount      int64
	TombstoneCount int64
	MemoryBytes    int64
}

IndexStatsDetail reports live statistics for one index (spec 14 §6.5).

type IndexType 

type IndexType uint8

IndexType selects the ANN index implementation for a vector column (spec 14 §6.2). IndexFlat is the exact brute-force oracle; the rest are approximate. 

const (
	IndexFlat IndexType = iota
	IndexHNSW
	IndexIVFFlat
	IndexIVFPQ
	IndexDiskANN
)

func (IndexType) String 

func (t IndexType) String() string

String renders an IndexType as its canonical name.

type JWTSecret 

type JWTSecret []byte

JWTSecret is the HS256 shared signing secret that redacts itself.

func (JWTSecret) Bytes 

func (s JWTSecret) Bytes() []byte

Bytes returns the underlying secret for the JWT validator.

func (JWTSecret) GoString 

func (JWTSecret) GoString() string

func (JWTSecret) MarshalJSON 

func (JWTSecret) MarshalJSON() ([]byte, error)

func (JWTSecret) String 

func (JWTSecret) String() string

type LoadFunc 

type LoadFunc func(ctx context.Context, bw *BulkWriter) error

LoadFunc is the callback signature for BulkLoad (spec 14 §8).

type Logger 

type Logger interface {
	// Log is called with a level ("DEBUG", "INFO", "WARN", "ERROR"), a message,
	// and key-value pairs.
	Log(level, msg string, kvs ...any)
}

Logger receives internal log events (spec 14 §12.2). Implement it to route vec's logs into slog, zap, logrus, or any other framework. 

var DefaultLogger Logger = stderrLogger{}

DefaultLogger writes to stderr in a structured format (spec 14 §12.2).

type Metric 

type Metric uint8

Metric is the distance metric bound to a vector column (spec 14 §4.3). It is fixed at collection creation and governs both index construction and query distance computation. 

const (
	MetricL2 Metric = iota
	MetricCosine
	MetricDot
	MetricHamming
	MetricJaccard
)

type MetricSink 

type MetricSink interface {
	Counter(name string, delta int64, tags ...string)
	Gauge(name string, value float64, tags ...string)
	Histogram(name string, value float64, tags ...string)
}

MetricSink receives metric observations (spec 14 §12.4).

type MultiVector 

type MultiVector []Vector

MultiVector is a set of dense vectors for late-interaction retrieval (spec 14 §3.3), such as ColBERT token embeddings.

type Option 

type Option func(*openConfig)

Option configures a database at open time (spec 14 §2.2). Options are applied in order; a later option overrides an earlier one.

func OptionsFromEnv 

func OptionsFromEnv(environ []string) ([]Option, error)

OptionsFromEnv reads VEC_ environment variables from environ (each "KEY=value") and turns the database-level ones into Options (spec 22 §22.2). The variable name is the knob name uppercased with VEC_ prepended and dots as underscores; the section prefixes (SERVER_, DATABASE_, etc.) are stripped so VEC_EF_SEARCH and VEC_DATABASE_CACHE_SIZE both resolve. Names that match no knob are skipped.

func ParseOptions 

func ParseOptions(pragmas map[string]string) ([]Option, error)

ParseOptions converts a map of PRAGMA name to value into a slice of Options (spec 22 §26.2). It is the bridge for opening a database from a DSN query string, an environment, or any external key-value source. An unknown name or an invalid value returns an error and no options.

func WithBusyTimeout 

func WithBusyTimeout(d time.Duration) Option

WithBusyTimeout sets how long Begin waits for the write lock before ErrBusy.

func WithCacheSize 

func WithCacheSize(bytes int64) Option

WithCacheSize sets the buffer-pool budget in bytes.

func WithCipher 

func WithCipher(c crypto.Cipher) Option

WithCipher selects the page cipher for a newly created encrypted database (spec 23 §2.2). The default is AES-256-GCM; ChaCha20-Poly1305 is the choice for hosts without AES hardware acceleration. The setting is ignored when opening an existing encrypted database, which uses the cipher recorded in its header.

func WithCreateIfMissing 

func WithCreateIfMissing(v bool) Option

WithCreateIfMissing controls whether Open creates the file when it is absent.

func WithEncryptionKey 

func WithEncryptionKey(key EncryptionKey) Option

WithEncryptionKey enables at-rest encryption with a caller-supplied 32-byte raw key (spec 23 §3), for deployments that manage keys in an external KMS or HSM and inject the key at open time. The key is used as the master key directly with no passphrase KDF.

func WithLogger 

func WithLogger(l Logger) Option

WithLogger routes internal log events to l.

func WithMMap 

func WithMMap(on bool) Option

WithMMap enables or disables memory-mapped reads of the data file.

func WithMaxRetries 

func WithMaxRetries(n int) Option

WithMaxRetries caps the conflict-retry count for Update.

func WithMetrics 

func WithMetrics(m MetricSink) Option

WithMetrics routes metric observations to m.

func WithPageSize 

func WithPageSize(bytes int) Option

WithPageSize sets the database page size in bytes; it must be a power of two and is fixed for the life of the file (spec 14 §2.2).

func WithParallelism 

func WithParallelism(n int) Option

WithParallelism sets the goroutine count for index builds and batch upserts.

func WithPassphrase 

func WithPassphrase(p Passphrase) Option

WithPassphrase enables at-rest encryption with a passphrase (spec 23 §3). The master key is derived with Argon2id; opening the same database later needs the same passphrase, and a wrong one fails with ErrWrongPassphrase before any data page is read.

func WithPragma 

func WithPragma(name, value string) Option

WithPragma sets one knob through the Option surface (spec 22 §26.1). The value is validated and canonicalized when Open applies the option; an invalid value surfaces as an *ErrInvalidConfig from Open.

func WithProgress 

func WithProgress(fn func(IndexBuildStats)) Option

WithProgress registers an index-build progress callback.

func WithReadOnly 

func WithReadOnly(v bool) Option

WithReadOnly opens the database for reading only.

func WithSynchronous 

func WithSynchronous(level SyncLevel) Option

WithSynchronous sets the WAL sync level.

func WithTracer 

func WithTracer(t Tracer) Option

WithTracer routes span events to t.

type Passphrase 

type Passphrase string

Passphrase is a human-entered secret that redacts itself.

func (Passphrase) GoString 

func (Passphrase) GoString() string

func (Passphrase) MarshalJSON 

func (Passphrase) MarshalJSON() ([]byte, error)

func (Passphrase) Reveal 

func (p Passphrase) Reveal() string

Reveal returns the passphrase text. Used only at the key-derivation call site.

func (Passphrase) String 

func (Passphrase) String() string

type PhaseStats 

type PhaseStats struct {
	Name     string
	Duration time.Duration
}

PhaseStats is one timed phase of query execution.

type Point 

type Point struct {
	ID      PointID
	Vectors map[string]AnyVector
	Meta    map[string]Value
}

Point is a row to upsert: its identity, its vectors keyed by column name, and its metadata keyed by column name (spec 14 §3.6). For a single-vector collection the Vectors map has one entry.

type PointID 

type PointID struct {
	N       uint64
	B       []byte
	IsBytes bool
}

PointID is the identity of a point (spec 14 §3.5). A collection uses one form, fixed at creation: an integer N, or a byte/text key B with IsBytes set.

func BytesID 

func BytesID(b []byte) PointID

BytesID builds a bytes point id.

func IntID 

func IntID(n uint64) PointID

IntID builds an integer point id.

func TextID 

func TextID(s string) PointID

TextID builds a text point id.

type ProfileResult 

type ProfileResult struct {
	Plan     string
	Phases   []PhaseStats
	Total    time.Duration
	RowsRead int64
}

ProfileResult is the per-query profile (spec 14 §12.5). Phase-level timings land with the observability subsystem (spec 18).

type QueryBuilder 

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

QueryBuilder builds and executes ANN queries with a fluent API (spec 14 §5). It is created by Collection.Query and is not goroutine-safe; build and execute it from one goroutine.

func (*QueryBuilder) All 

func (qb *QueryBuilder) All(ctx context.Context) ([]Result, error)

All executes the query and returns every result (spec 14 §5).

func (*QueryBuilder) BM25 

func (qb *QueryBuilder) BM25(field, queryText string) *QueryBuilder

BM25 adds a lexical BM25 scoring term over a text field (spec 14 §5, hybrid).

func (*QueryBuilder) Ef 

func (qb *QueryBuilder) Ef(ef int) *QueryBuilder

Ef sets the HNSW ef_search beam width for this query.

func (*QueryBuilder) Exec 

func (qb *QueryBuilder) Exec(ctx context.Context) (*Rows, error)

Exec executes the query and returns a streaming cursor (spec 14 §5).

func (*QueryBuilder) ExecTxn 

func (qb *QueryBuilder) ExecTxn(ctx context.Context, txn *Txn) (*Rows, error)

ExecTxn executes the query inside txn (spec 14 §5).

func (*QueryBuilder) Explain 

func (qb *QueryBuilder) Explain(ctx context.Context) (string, error)

Explain returns the query plan without executing it (spec 14 §12.5).

func (*QueryBuilder) Filter 

func (qb *QueryBuilder) Filter(expr string, args ...any) *QueryBuilder

Filter adds a VectorSQL WHERE clause with positional ? arguments.

func (*QueryBuilder) First 

func (qb *QueryBuilder) First(ctx context.Context) (Result, error)

First executes the query and returns the single nearest result (spec 14 §5).

func (*QueryBuilder) K 

func (qb *QueryBuilder) K(k int) *QueryBuilder

K sets the number of results to return.

func (*QueryBuilder) Nprobe 

func (qb *QueryBuilder) Nprobe(n int) *QueryBuilder

Nprobe sets the IVF probe count for this query.

func (*QueryBuilder) OrderBy 

func (qb *QueryBuilder) OrderBy(column string, desc bool) *QueryBuilder

OrderBy adds a secondary ordering by a metadata column.

func (*QueryBuilder) Profile 

func (qb *QueryBuilder) Profile(ctx context.Context) (*ProfileResult, error)

Profile executes the query and returns a profile report (spec 14 §12.5). The phase-level breakdown lands with the observability subsystem (spec 18).

func (*QueryBuilder) RRF 

func (qb *QueryBuilder) RRF(k float64) *QueryBuilder

RRF sets the reciprocal-rank-fusion constant for hybrid queries.

func (*QueryBuilder) Rerank 

func (qb *QueryBuilder) Rerank(r int) *QueryBuilder

Rerank requests an exact rerank over r widened candidates.

func (*QueryBuilder) Select 

func (qb *QueryBuilder) Select(columns ...string) *QueryBuilder

Select restricts the projected metadata columns.

func (*QueryBuilder) WithFetchSize 

func (qb *QueryBuilder) WithFetchSize(n int) *QueryBuilder

WithFetchSize sets the streaming fetch size for the cursor.

func (*QueryBuilder) WithIndex 

func (qb *QueryBuilder) WithIndex(indexName string) *QueryBuilder

WithIndex pins a named index for this query.

func (*QueryBuilder) WithScoreMode 

func (qb *QueryBuilder) WithScoreMode(annWeight, bm25Weight float64) *QueryBuilder

WithScoreMode is reserved for weighted hybrid fusion (spec 14 §5).

func (*QueryBuilder) WithVectors 

func (qb *QueryBuilder) WithVectors(columns ...string) *QueryBuilder

WithVectors requests the stored vectors of the named columns in each Result.

type RekeyVacuumStats 

type RekeyVacuumStats struct {
	PagesRewritten uint64
	OldEpoch       uint16
	NewEpoch       uint16
}

RekeyVacuumStats reports the result of a full re-encryption pass (spec 23 §9.3).

type Result 

type Result struct {
	ID       PointID
	Distance float32
	Score    float32
	Point    Point
	// contains filtered or unexported fields
}

Result is one row from a query (spec 14 §5.6).

func (Result) Column 

func (r Result) Column(name string) (Value, bool)

Column returns a projected metadata column value by name.

func (Result) DistanceValue 

func (r Result) DistanceValue() float32

DistanceValue returns the distance of the result.

func (Result) Meta 

func (r Result) Meta() map[string]Value

Meta returns the projected metadata columns of the result keyed by name. The CLI uses it to render a result row without knowing the projection in advance.

func (Result) Scan 

func (r Result) Scan(dest ...any) error

Scan copies the id and distance of the result into dest. Supported destinations are *uint64/*int64 (id) and *float32/*float64 (distance), in that order.

func (Result) Similarity 

func (r Result) Similarity() float32

Similarity returns a similarity score derived from the distance.

func (Result) Vector 

func (r Result) Vector(column string) (Vector, bool)

Vector returns a requested stored vector by column name.

type Rows 

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

Rows is a streaming result cursor (spec 14 §5.6). It is not goroutine-safe.

func (*Rows) Close 

func (r *Rows) Close() error

Close releases the cursor.

func (*Rows) Err 

func (r *Rows) Err() error

Err returns the first error encountered during iteration.

func (*Rows) Next 

func (r *Rows) Next() bool

Next advances the cursor; it reports whether a row is available.

func (*Rows) Result 

func (r *Rows) Result() Result

Result returns the current row.

func (*Rows) Scan 

func (r *Rows) Scan(dest ...any) error

Scan copies the current row's id and distance into dest (spec 14 §5.6).

type SchemaError 

type SchemaError struct {
	Column string
	Reason string
}

SchemaError carries schema violation detail (spec 14 §10.3).

func (*SchemaError) Error 

func (e *SchemaError) Error() string

func (*SchemaError) Unwrap 

func (e *SchemaError) Unwrap() error

Unwrap returns ErrSchemaViolation.

type SessionConfig 

type SessionConfig struct {
	EfSearch int
	NProbe   int
	RerankR  int
}

SessionConfig holds the session-tier defaults a connection starts with.

type Snapshot 

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

Snapshot is a read-only view pinned at a committed sequence (spec 14 §11.4).

func (*Snapshot) Seq 

func (s *Snapshot) Seq() uint64

Seq returns the committed sequence the snapshot reads at.

type Span 

type Span interface {
	SetAttribute(key string, value any)
	End()
	RecordError(err error)
}

Span is one tracing span.

type SparseVector 

type SparseVector struct {
	Indices []uint32
	Values  []float32
	Dim     uint32
}

SparseVector is a sparse vector as parallel index/value arrays (spec 14 §3.2). Indices must be strictly increasing.

type SyncLevel 

type SyncLevel int

SyncLevel controls how aggressively the WAL is flushed to stable storage on commit (spec 14 §2.3, mirroring the WAL sync levels of spec 05). 

const (
	SyncOff    SyncLevel = iota // never fsync; fastest, least durable
	SyncNormal                  // fsync at checkpoints (the default)
	SyncFull                    // fsync at every commit
	SyncExtra                   // fsync commit and the directory entry
)

func (SyncLevel) String 

func (s SyncLevel) String() string

String renders the sync level as the pragma keyword used by Pragma and the CLI.

type Tracer 

type Tracer interface {
	StartSpan(ctx context.Context, name string) (context.Context, Span)
}

Tracer receives span events for distributed tracing (spec 14 §12.3). vec creates one span per query, transaction, and index build.

type Txn 

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

Txn is a transaction (spec 14 §11.4). It is NOT goroutine-safe: one goroutine owns it from Begin to Commit or Rollback. The closure forms View and Update avoid sharing a Txn across goroutines entirely.

func (*Txn) Commit 

func (txn *Txn) Commit() error

Commit commits the transaction (spec 14 §11). A write conflict returns ErrConflict; the transaction is finished either way.

func (*Txn) IsDone 

func (txn *Txn) IsDone() bool

IsDone reports whether the transaction has committed or rolled back.

func (*Txn) Release 

func (txn *Txn) Release(name string) error

Release releases a savepoint (spec 14 §11).

func (*Txn) Rollback 

func (txn *Txn) Rollback() error

Rollback rolls back the transaction (spec 14 §11). It is safe to call after a commit or a previous rollback.

func (*Txn) RollbackTo 

func (txn *Txn) RollbackTo(name string) error

RollbackTo rolls back to a savepoint (spec 14 §11). The engine does not yet support partial rollback, so this is reported as unsupported when the savepoint has uncommitted work to discard.

func (*Txn) Savepoint 

func (txn *Txn) Savepoint(name string) error

Savepoint sets a named savepoint (spec 14 §11). Savepoints are tracked at the db layer; nested rollback discards work since the named point.

func (*Txn) Snapshot 

func (txn *Txn) Snapshot() uint64

Snapshot returns the read version pinned at Begin (spec 14 §11.4).

type Value 

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

Value is a typed metadata value (spec 14 §5). It is a discriminated union over the scalar, text, bytes, and timestamp types a metadata column may hold. The zero Value is NULL. Construct values with the *Value functions and read them back with the typed accessors.

func BoolValue 

func BoolValue(b bool) Value

BoolValue builds a boolean value.

func BytesValue 

func BytesValue(b []byte) Value

BytesValue builds a raw byte value.

func FloatValue 

func FloatValue(f float64) Value

FloatValue builds a 64-bit float value.

func IntValue 

func IntValue(i int64) Value

IntValue builds a 64-bit integer value.

func JSONValue 

func JSONValue(s string) Value

JSONValue builds a JSON value stored as UTF-8.

func NullValue 

func NullValue() Value

NullValue is the absent value (spec 14 §5.2).

func TextValue 

func TextValue(s string) Value

TextValue builds a UTF-8 string value.

func TimestampValue 

func TimestampValue(t time.Time) Value

TimestampValue builds a timestamp value.

func (Value) Bool 

func (v Value) Bool() bool

Bool returns the boolean payload.

func (Value) Bytes 

func (v Value) Bytes() []byte

Bytes returns the byte payload.

func (Value) Float 

func (v Value) Float() float64

Float returns the float payload (zero for other kinds).

func (Value) Int 

func (v Value) Int() int64

Int returns the integer payload (zero for other kinds).

func (Value) IsNull 

func (v Value) IsNull() bool

IsNull reports whether the value is NULL.

func (Value) String 

func (v Value) String() string

String renders the value for diagnostics and the %s verb.

func (Value) Text 

func (v Value) Text() string

Text returns the string payload.

func (Value) Time 

func (v Value) Time() time.Time

Time returns the timestamp payload as a UTC time.Time.

func (Value) Type 

func (v Value) Type() ColumnType

Type returns the value's column type.

type Vector 

type Vector []float32

Vector is a dense float32 vector (spec 14 §3.1). It is the in-memory form a caller passes to Upsert and Query; the engine stores one copy per point and the indexes reference positions, never copies.

func FromSlice32 

func FromSlice32(s []float32) Vector

FromSlice32 wraps a float32 slice as a Vector without copying.

func FromSlice64 

func FromSlice64(s []float64) Vector

FromSlice64 builds a Vector from a float64 slice, narrowing each element.

func NewVector 

func NewVector(dim int) Vector

NewVector returns a zeroed vector of the given dimension.

func (Vector) Cosine 

func (v Vector) Cosine(o Vector) float32

Cosine returns the cosine similarity of v and o in [-1, 1].

func (Vector) Dot 

func (v Vector) Dot(o Vector) float32

Dot returns the dot product of v and o; mismatched lengths return 0.

func (Vector) HalfPrecision 

func (v Vector) HalfPrecision() Vector

HalfPrecision rounds each element to the nearest IEEE half-precision value, returning a float32 vector. It models the precision loss of an fp16 column so a caller can preview quantization effects.

func (Vector) L2Norm 

func (v Vector) L2Norm() float32

L2Norm returns the Euclidean norm of the vector.

func (Vector) Normalize 

func (v Vector) Normalize() Vector

Normalize returns a unit-length copy of the vector; a zero vector is returned unchanged.

func (Vector) ToSlice32 

func (v Vector) ToSlice32() []float32

ToSlice32 returns the vector as a float32 slice without copying.

func (Vector) ToSlice64 

func (v Vector) ToSlice64() []float64

ToSlice64 returns the vector widened to a float64 slice.

Source Files

View all Source files

Directories

Path Synopsis
Package audit implements the security audit log from spec 23 section 11: an append-only NDJSON record of who did what to which collection at what time.
 Package audit implements the security audit log from spec 23 section 11: an append-only NDJSON record of who did what to which collection at what time.
Package auth implements the server authentication and authorization surface from spec 23 sections 6 and 7: API keys, JWT validation, mutual-TLS principal mapping, local password accounts, the role model, and the collection-scoped access control list.
 Package auth implements the server authentication and authorization surface from spec 23 sections 6 and 7: API keys, JWT validation, mutual-TLS principal mapping, local password accounts, the role model, and the collection-scoped access control list.
Package bench is the benchmark harness from spec 20: dataset loaders for the standard ANN file formats, recall computation against ground truth, a latency recorder with coordinated-omission-correct percentiles, the parameter sweep that drives a searcher across effort values, the result JSON and TSV writers, and the CI regression gate.
 Package bench is the benchmark harness from spec 20: dataset loaders for the standard ANN file formats, recall computation against ground truth, a latency recorder with coordinated-omission-correct percentiles, the parameter sweep that drives a searcher across effort values, the result JSON and TSV writers, and the CI regression gate.
Package bulk implements the bulk import, logical dump/load, and backup-format pieces of spec 17 on top of the public vec facade.
 Package bulk implements the bulk import, logical dump/load, and backup-format pieces of spec 17 on top of the public vec facade.
Package catalog implements the vec data model and schema authority (spec 02): the value type system, point identity, distance-metric binding, collection schemas, the three system collections, schema definition and evolution rules, constraints, and the write-path validation every insert and upsert must pass.
 Package catalog implements the vec data model and schema authority (spec 02): the value type system, point identity, distance-metric binding, collection schemas, the three system collections, schema definition and evolution rules, constraints, and the write-path validation every insert and upsert must pass.
Package cli implements the vec command-line tool: the interactive shell, the batch SQL surface, and the administrative subcommands (spec 15).
 Package cli implements the vec command-line tool: the interactive shell, the batch SQL surface, and the administrative subcommands (spec 15).
cmd
vec command
Command vec is the single-file vector database shell and tool.
 Command vec is the single-file vector database shell and tool.
Package config is the knob catalogue for vec (spec 22).
 Package config is the knob catalogue for vec (spec 22).
Package crypto implements vec's encryption at rest: the page-level AEAD envelope, the key hierarchy (master key, per-epoch DEK, per-page key, per-write nonce), key rotation, and the verification tag that detects a wrong passphrase before any data page is read.
 Package crypto implements vec's encryption at rest: the page-level AEAD envelope, the key hierarchy (master key, per-epoch DEK, per-page key, per-write nonce), key rotation, and the verification tag that detects a wrong passphrase before any data page is read.
Package distance implements vec's scalar distance kernels and the kernel dispatch architecture (spec 09 §11-13).
 Package distance implements vec's scalar distance kernels and the kernel dispatch architecture (spec 09 §11-13).
Package format defines the on-disk byte layout of a vec database file: the database header, the common page header, page types, varint and record encodings, and the page checksum.
 Package format defines the on-disk byte layout of a vec database file: the database header, the common page header, page types, varint and record encodings, and the page checksum.
Package hybrid implements vec's lexical and multi-modal retrieval layer (spec 11): the BM25 keyword index (§9), reciprocal-rank and score-normalized fusion (§10), learned-sparse (SPLADE) dot-product search (§11), and multi-vector (ColBERT) MaxSim late interaction (§12).
 Package hybrid implements vec's lexical and multi-modal retrieval layer (spec 11): the BM25 keyword index (§9), reciprocal-rank and score-normalized fusion (§10), learned-sparse (SPLADE) dot-product search (§11), and multi-vector (ColBERT) MaxSim late interaction (§12).
Package index implements vec's vector index access paths behind one SPI: the flat brute-force baseline and the HNSW graph (spec 07).
 Package index implements vec's vector index access paths behind one SPI: the flat brute-force baseline and the HNSW graph (spec 07).
Package mvcc implements vec's multi-version concurrency control: snapshot isolation by default, an optional serializable level, a monotonic commit clock, per-key version chains (the delta-over-base model), a watermark oracle that governs version reclamation, and first-committer-wins conflict detection (spec 06).
 Package mvcc implements vec's multi-version concurrency control: snapshot isolation by default, an optional serializable level, a monotonic commit clock, per-key version chains (the delta-over-base model), a watermark oracle that governs version reclamation, and first-committer-wins conflict detection (spec 06).
Package obs is the observability surface from spec 18: the metrics catalogue, the structured slow-query log, the flat-oracle recall sampler, and the health and readiness report.
 Package obs is the observability surface from spec 18: the metrics catalogue, the structured slow-query log, the flat-oracle recall sampler, and the health and readiness report.
Package pager is the layer between the storage and index cores and the file (spec 05).
 Package pager is the layer between the storage and index cores and the file (spec 05).
Package quant implements vec's vector codecs: flat (no compression), scalar quantization (SQ int8), product quantization (PQ), optimized product quantization (OPQ), binary (1-bit Hamming), and RaBitQ (spec 09 §2-8).
 Package quant implements vec's vector codecs: flat (no compression), scalar quantization (SQ int8), product quantization (PQ), optimized product quantization (OPQ), binary (1-bit Hamming), and RaBitQ (spec 09 §2-8).
Package query is vec's read-path query engine: the cost-based planner that turns a bound logical query into a physical plan (spec 13) and the vectorized executor that runs that plan against the index SPI, the storage engine, and the distance kernels (spec 10).
 Package query is vec's read-path query engine: the cost-based planner that turns a bound logical query into a physical plan (spec 13) and the vectorized executor that runs that plan against the index SPI, the storage engine, and the distance kernels (spec 10).
Package server turns the embedded vec library into a networked service (spec 16).
 Package server turns the embedded vec library into a networked service (spec 16).
pgwire
Package pgwire implements the PostgreSQL v3 frontend/backend wire protocol over net.Conn so pgvector clients (psql, psycopg, pgx, asyncpg, JDBC) talk to the vec engine without code changes (spec 16 §4, §17, §18).
 Package pgwire implements the PostgreSQL v3 frontend/backend wire protocol over net.Conn so pgvector clients (psql, psycopg, pgx, asyncpg, JDBC) talk to the vec engine without code changes (spec 16 §4, §17, §18).
vecpb
Package vecpb is a hand-written proto3 wire codec for the VecService messages (spec 16 §2.2).
 Package vecpb is a hand-written proto3 wire codec for the VecService messages (spec 16 §2.2).
Package storage implements the vec storage engine (spec 04): fixed-stride columnar vector segments, a separate columnar metadata store, and an id-map that mediates between stable application point ids and dense engine positions.
 Package storage implements the vec storage engine (spec 04): fixed-stride columnar vector segments, a separate columnar metadata store, and an id-map that mediates between stable application point ids and dense engine positions.
Package vectorsql implements the VectorSQL language surface of spec 12: a hand-written recursive-descent lexer and parser over the formal grammar (§15), the AST the parser emits (§17.2), the strict error model (§14), and a binder that resolves a parsed statement against the catalog and lowers a kNN SELECT to the planner's BoundQuery.
 Package vectorsql implements the VectorSQL language surface of spec 12: a hand-written recursive-descent lexer and parser over the formal grammar (§15), the AST the parser emits (§17.2), the strict error model (§14), and a binder that resolves a parsed statement against the catalog and lowers a kNN SELECT to the planner's BoundQuery.
Package verify holds vec's correctness machinery from spec 21: the recall oracle, the reference model, the conformance and metamorphic drivers, and the fault-injecting VFS used for crash testing.
 Package verify holds vec's correctness machinery from spec 21: the recall oracle, the reference model, the conformance and metamorphic drivers, and the fault-injecting VFS used for crash testing.
Package vfs is the file-I/O seam for vec (spec 05).
 Package vfs is the file-I/O seam for vec (spec 05).
Package wal is the write-ahead log: the durability spine the database commits through (spec 05).
 Package wal is the write-ahead log: the durability spine the database commits through (spec 05).

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.