Documentation
¶
Overview ¶
DECISION: using modernc.org/sqlite (pure-Go, no CGo) + modernc.org/sqlite/vec subpackage. Probe on Day 0 confirmed that modernc.org/sqlite v1.50.0 ships sqlite-vec as a bundled subpackage (modernc.org/sqlite/vec) that self-registers via sqlite3_auto_extension on import. No load_extension() call needed. Zero CGo, full cross-compile support maintained.
Index ¶
- type Store
- func (s *Store) Close() error
- func (s *Store) CountChunks(ctx context.Context) (int, error)
- func (s *Store) DeleteFile(ctx context.Context, id int64) error
- func (s *Store) DeleteSymbolsByFile(ctx context.Context, fileID int64) error
- func (s *Store) GetCalleeEdges(ctx context.Context, srcIDs []int64, limitPerSymbol int) (map[int64][]int64, error)
- func (s *Store) GetCallerEdges(ctx context.Context, dstIDs []int64, limitPerSymbol int) (map[int64][]int64, error)
- func (s *Store) GetEdges(ctx context.Context, symbolID int64) ([]store.Edge, error)
- func (s *Store) GetEmbedding(ctx context.Context, symbolID int64) ([]float32, bool, error)
- func (s *Store) GetEmbeddingsByIDs(ctx context.Context, ids []int64) (map[int64][]float32, error)
- func (s *Store) GetFileByPath(ctx context.Context, path string) (*store.File, error)
- func (s *Store) GetFilesByIDs(ctx context.Context, ids []int64) (map[int64]string, error)
- func (s *Store) GetSymbolBody(ctx context.Context, symbolID int64) (store.SymbolBody, error)
- func (s *Store) GetSymbolsByIDs(ctx context.Context, ids []int64) ([]store.Symbol, error)
- func (s *Store) IndexContentVersion(ctx context.Context) (int, error)
- func (s *Store) ListAllEdges(ctx context.Context) ([]store.Edge, error)
- func (s *Store) ListAllSymbolIDs(ctx context.Context) ([]int64, error)
- func (s *Store) ListFiles(ctx context.Context) ([]store.File, error)
- func (s *Store) ListSymbolMeta(ctx context.Context) ([]store.Symbol, error)
- func (s *Store) ListSymbolsByFile(ctx context.Context, fileID int64) ([]store.Symbol, error)
- func (s *Store) ListSymbolsByLanguage(ctx context.Context, language string) ([]store.Symbol, error)
- func (s *Store) ListSymbolsMissingEmbedding(ctx context.Context) ([]store.SymbolToEmbed, error)
- func (s *Store) RebuildVecCacheFile(ctx context.Context) error
- func (s *Store) SaveEdge(ctx context.Context, e store.Edge) error
- func (s *Store) SaveEdgeBatch(ctx context.Context, edges []store.Edge) error
- func (s *Store) SaveFile(ctx context.Context, f *store.File) (int64, error)
- func (s *Store) SaveSymbol(ctx context.Context, sym *store.Symbol) (int64, error)
- func (s *Store) SaveSymbolBatch(ctx context.Context, symbols []store.Symbol) ([]int64, error)
- func (s *Store) SaveSymbolChunks(ctx context.Context, chunks []store.SymbolChunk) ([]int64, error)
- func (s *Store) SearchByBodyText(ctx context.Context, query string, k int) ([]store.ScoredSymbol, error)
- func (s *Store) SearchByChunkVector(ctx context.Context, vec []float32, k int) ([]store.ScoredSymbol, error)
- func (s *Store) SearchByText(ctx context.Context, query string, k int) ([]store.ScoredSymbol, error)
- func (s *Store) SearchByVector(ctx context.Context, embedding []float32, topK int) ([]store.Symbol, error)
- func (s *Store) SearchByVectorScored(ctx context.Context, vec []float32, k int) ([]store.ScoredSymbol, error)
- func (s *Store) SetIndexContentVersion(ctx context.Context, version int) error
- func (s *Store) UpsertChunkEmbeddingBatch(ctx context.Context, embeddings []store.ChunkEmbedding) error
- func (s *Store) UpsertEmbedding(ctx context.Context, symbolID int64, vec []float32) error
- func (s *Store) UpsertEmbeddingBatch(ctx context.Context, embeddings []store.Embedding) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
func New ¶
DECISION: New requires modelName+dim so it can (a) create symbol_vec with the correct dimension on first init, and (b) refuse to open an existing index built with a different model — preventing silent dimension mismatches that would corrupt vec0 knn results.
func (*Store) CountChunks ¶
CountChunks reports how many chunk rows exist, for diagnostics and to tell an index that predates chunking from one that simply has no capped symbols.
func (*Store) DeleteFile ¶
DECISION(2026-08): the five deletes below run in ONE transaction. They used to be five independent statements, the only multi-table mutation in this package that was not atomic, and the failure mode is not hypothetical: this machine lost power mid-afternoon during a watch reindex, and afterwards bm25(symbol_body_fts) returned NULL for the repository being indexed — every query against it answered "tool error" until the scan was made defensive. A half-applied delete leaves the FTS indexes disagreeing with their content tables, which SQLite documents as undefined behaviour. ASSUMES: a rollback is always preferable to a partial delete — a file that is still indexed is stale, a file that is half-deleted is corrupt.
func (*Store) DeleteSymbolsByFile ¶
func (*Store) GetCalleeEdges ¶
func (*Store) GetCallerEdges ¶
func (*Store) GetEmbedding ¶
func (*Store) GetEmbeddingsByIDs ¶
func (*Store) GetFileByPath ¶
func (*Store) GetFilesByIDs ¶
func (*Store) GetSymbolBody ¶
GetSymbolBody returns the exact body captured by the index. A legacy truncated excerpt without its lossless side-table row is never passed off as complete: callers get a reindex-required error instead.
func (*Store) GetSymbolsByIDs ¶
func (*Store) IndexContentVersion ¶
func (*Store) ListAllEdges ¶
ListAllEdges returns the whole edge table, served from RAM after the first call (the PPR graph build and graph-context enrichment both consume it on every query).
func (*Store) ListAllSymbolIDs ¶
func (*Store) ListSymbolMeta ¶
ListSymbolMeta returns every symbol's identity and location WITHOUT the text columns (signature/docstring/body_excerpt), served from RAM after the first call. The full-table hydration this replaced churned ~180MB per query on a 90K-symbol index.
func (*Store) ListSymbolsByFile ¶
func (*Store) ListSymbolsByLanguage ¶
func (*Store) ListSymbolsMissingEmbedding ¶
ListSymbolsMissingEmbedding returns symbols with no symbol_vec row, joined with their file's path/language (EmbeddingText inputs). These exist after a structure-only (--fast) index; the backfill embeds them later.
func (*Store) RebuildVecCacheFile ¶
RebuildVecCacheFile bumps the index generation token, loads the embedding matrix from the DB, and writes the on-disk sidecar. Called at the end of indexing so the first query after an index is fast (no cold 90k-row load).
func (*Store) SaveEdgeBatch ¶
func (*Store) SaveSymbol ¶
func (*Store) SaveSymbolBatch ¶
func (*Store) SaveSymbolChunks ¶
SaveSymbolChunks records the chunk rows for one symbol and returns their ids in order. Vectors are written separately, after embedding.
func (*Store) SearchByBodyText ¶
func (s *Store) SearchByBodyText(ctx context.Context, query string, k int) ([]store.ScoredSymbol, error)
SearchByBodyText searches the lossless bodies. It is a separate ranking, not extra rows on SearchByText's: seeding fuses channels by rank, so appending these to the head list would hand them the worst ranks and a vote near zero however well they matched. Callers fuse it as its own channel.
func (*Store) SearchByChunkVector ¶
func (s *Store) SearchByChunkVector(ctx context.Context, vec []float32, k int) ([]store.ScoredSymbol, error)
SearchByChunkVector runs KNN over the chunk vectors and reports the owning symbols, best chunk first. A long function contributes many chunks, so the results are deduplicated by symbol — otherwise one sprawling function would fill the whole seed pool with its own windows.
func (*Store) SearchByText ¶
func (s *Store) SearchByText(ctx context.Context, query string, k int) ([]store.ScoredSymbol, error)
DECISION: bm25() in FTS5 returns negative values (lower = more relevant). We invert to Score = -bm25_value so higher Score = better match, consistent with SearchByVectorScored where Score = 1/(1+distance). ORDER BY rank uses the raw bm25 implicitly (SQLite FTS5 sets rank = bm25 by default).
func (*Store) SearchByVector ¶
func (s *Store) SearchByVector(ctx context.Context, embedding []float32, topK int) ([]store.Symbol, error)
SearchByVector returns the topK nearest symbols. Served from the in-memory vector cache; see SearchByVectorScored.
func (*Store) SearchByVectorScored ¶
func (s *Store) SearchByVectorScored(ctx context.Context, vec []float32, k int) ([]store.ScoredSymbol, error)
DECISION: score = 1/(1+distance) where distance is L2. For L2-normalized vectors, cosine similarity = 1 - d²/2, but 1/(1+d) is simpler and monotonically equivalent for ranking. Served from the in-memory vector cache (see veccache.go); falls back to the vec0 KNN query if the cache cannot answer (load failure, dim mismatch).
func (*Store) SetIndexContentVersion ¶
func (*Store) UpsertChunkEmbeddingBatch ¶
func (*Store) UpsertEmbedding ¶
DECISION: vec0 virtual tables don't support INSERT OR REPLACE; use DELETE+INSERT in a tx. Vector accepted as JSON array string — confirmed by modernc.org/sqlite vec_test.go.
Source Files