vec

Documentation

Overview

Package vec implements a SQLite virtual table for vector search with MATCH semantics. Each virtual table has a per-table shadow table that stores dataset identifiers, document ids, content, metadata, and embeddings. A generic index blob is persisted in the shared vector_storage table, and an in-memory cache accelerates queries.

Features:

• WHERE doc_id MATCH ? using an encoded embedding BLOB
• Optional match_score column for inspecting similarity scores
• Auto-created shadow tables and triggers
• Index persistence in vector_storage and cache invalidation on writes
• Pluggable index (brute-force baseline)

Index

• func InvalidateCache(shadow, dataset string) int
• func Register(db *sql.DB) error
• type Cursor
  • func (c *Cursor) Close() error
  • func (c *Cursor) Column(col int) (vtab.Value, error)
  • func (c *Cursor) Eof() bool
  • func (c *Cursor) Filter(idxNum int, idxStr string, vals []vtab.Value) error
  • func (c *Cursor) Next() error
  • func (c *Cursor) Rowid() (int64, error)
• type Module
  • func (m *Module) Connect(ctx vtab.Context, args []string) (vtab.Table, error)
  • func (m *Module) Create(ctx vtab.Context, args []string) (vtab.Table, error)
• type Table
  • func (t *Table) BestIndex(info *vtab.IndexInfo) error
  • func (t *Table) Destroy() error
  • func (t *Table) Disconnect() error
  • func (t *Table) Open() (vtab.Cursor, error)

Functions

func InvalidateCache

func InvalidateCache(shadow, dataset string) int

InvalidateCache clears cached indices for a given shadow/dataset across active connections.

func Register

func Register(db *sql.DB) error

Register registers the vec virtual table module with the provided *sql.DB.

Types

type Cursor

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

Cursor scans results from a vec table.

func (*Cursor) Close

func (c *Cursor) Close() error

Close releases resources.

func (*Cursor) Column

func (c *Cursor) Column(col int) (vtab.Value, error)

Column returns the value of a column in the current row.

func (*Cursor) Eof

func (c *Cursor) Eof() bool

Eof reports end-of-rows.

func (*Cursor) Filter

func (c *Cursor) Filter(idxNum int, idxStr string, vals []vtab.Value) error

Filter computes the result set based on idxNum/vals.

func (*Cursor) Next

func (c *Cursor) Next() error

Next advances the cursor.

func (*Cursor) Rowid

func (c *Cursor) Rowid() (int64, error)

Rowid returns the current rowid.

type Module

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

Module implements vtab.Module for the vec virtual table. It creates a per-table shadow store and supports MATCH-based similarity scans.

func (*Module) Connect

func (m *Module) Connect(ctx vtab.Context, args []string) (vtab.Table, error)

Connect attaches to an existing vec table instance.

func (*Module) Create

func (m *Module) Create(ctx vtab.Context, args []string) (vtab.Table, error)

Create initializes a vec table instance and ensures shadow/index tables.

type Table

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

Table represents a single vec virtual table instance.

func (*Table) BestIndex

func (t *Table) BestIndex(info *vtab.IndexInfo) error

BestIndex pushes down MATCH on first column.

func (*Table) Destroy

func (t *Table) Destroy() error

Destroy drops nothing for now; shadow persists.

func (*Table) Disconnect

func (t *Table) Disconnect() error

Disconnect cleans up per-connection resources.

func (*Table) Open

func (t *Table) Open() (vtab.Cursor, error)

Open allocates a new cursor.