Documentation
¶
Index ¶
- func MatchText(ctx context.Context, db *sql.DB, virtualTable string, embed EmbedFunc, ...) ([]string, error)
- func ShadowTableName(virtualTable string) string
- func UpsertShadowDocument(ctx context.Context, db *sql.DB, shadowTable string, embed EmbedFunc, ...) error
- func UpsertVirtualTableDocument(ctx context.Context, db *sql.DB, virtualTable string, embed EmbedFunc, ...) error
- type Document
- type EmbedFunc
- type Index
- type Match
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func MatchText ¶
func MatchText( ctx context.Context, db *sql.DB, virtualTable string, embed EmbedFunc, datasetID string, query string, limit int, ) ([]string, error)
MatchText executes a MATCH query against a vec virtual table by first converting the free-form query text into an embedding via EmbedFunc.
It returns the list of ids (the visible column of the virtual table) in the order returned by the underlying index. When limit <= 0, all matches are returned; otherwise a SQL LIMIT is applied.
func ShadowTableName ¶
ShadowTableName derives the default shadow table name for a given vec virtual table. It mirrors the naming convention used by the vec module, which prefixes the table name with _vec_.
For example:
ShadowTableName("vec_basic") == "_vec_vec_basic".
Schema/database qualification (e.g. main.) is handled by SQLite; this helper only returns the bare table name.
func UpsertShadowDocument ¶
func UpsertShadowDocument( ctx context.Context, db *sql.DB, shadowTable string, embed EmbedFunc, datasetID string, id, content, meta string, ) error
UpsertShadowDocument inserts or updates a document row in a vec shadow table, computing the embedding from content using the provided EmbedFunc.
The shadowTable is typically derived via ShadowTableName or known explicitly. It is assumed to follow the schema used by sqlite-vec tests:
id TEXT PRIMARY KEY content TEXT meta TEXT embedding BLOB
Table and column names are interpolated into SQL; callers should ensure that shadowTable is trusted and not derived from untrusted input.
func UpsertVirtualTableDocument ¶
func UpsertVirtualTableDocument( ctx context.Context, db *sql.DB, virtualTable string, embed EmbedFunc, datasetID string, id, content, meta string, ) error
UpsertVirtualTableDocument is a convenience wrapper around UpsertShadowDocument that derives the shadow table name from the virtual table name using ShadowTableName.
Types ¶
type Document ¶
Document represents a logical document stored in the vec shadow table. Metadata is modeled as a raw JSON (or other encoding) string for maximum flexibility.
type EmbedFunc ¶
EmbedFunc converts free-form text into an embedding.
Implementations can call any embedding provider (OpenAI, local model, other cloud APIs, etc.) as long as they return a slice of float32 values. The core sqlite-vec packages remain embedding-agnostic and only depend on the numeric vectors and their encoded BLOB representation.
type Index ¶
type Index struct {
DB *sql.DB
VirtualName string
ShadowName string
DatasetID string
Embed EmbedFunc
}
Index provides a higher-level, Pinecone-style API on top of a vec virtual table and its shadow table. It remains embedding-agnostic by requiring an EmbedFunc supplied by the caller.
func NewIndex ¶
NewIndex constructs an Index for a given vec virtual table name.
The shadow table name is derived using ShadowTableName. The caller is responsible for having created both the virtual table and its shadow table schema (see README examples).
func (*Index) DeleteDocuments ¶
DeleteDocuments removes documents with the given ids from the shadow table. Triggers installed by the vec module will invalidate any persisted index entries, causing them to be rebuilt on the next MATCH query.
func (*Index) QueryText ¶
QueryText performs a similarity search using the provided query text. It uses the vec virtual table for kNN ordering and then computes cosine similarity scores in Go for each match.
When k <= 0, all matches returned by the underlying index are included.
func (*Index) UpsertDocumentsText ¶
UpsertDocumentsText upserts the provided documents into the shadow table, computing embeddings from Content using the Index's EmbedFunc.
This is analogous to client-side text upsert flows in hosted vector databases: callers supply free-form text and optional metadata; the index handles embedding and storage.
Source Files