Documentation
¶
Overview ¶
Package store provides SQLite-backed storage primitives for Stroma indexes.
Index ¶
- Constants
- func CheckSQLiteReady() error
- func CheckSQLiteReadyContext(ctx context.Context) error
- func CosineScoreFromDistance(distance float64) float64
- func DecodeVectorBlob(blob []byte) ([]float64, error)
- func DecodeVectorBlobBinary(blob []byte) ([]float64, error)
- func DecodeVectorBlobInt8(blob []byte) ([]float64, error)
- func EncodeVectorBlob(vector []float64) ([]byte, error)
- func EncodeVectorBlobBinary(vector []float64) ([]byte, error)
- func EncodeVectorBlobInt8(vector []float64) ([]byte, error)
- func IsMissingIndex(err error) bool
- func MissingIndexPath(err error) string
- func OpenReadOnly(path string) (*sql.DB, error)
- func OpenReadOnlyContext(ctx context.Context, path string) (*sql.DB, error)
- func OpenReadOnlyContextWithOptions(ctx context.Context, path string, opts SQLiteOptions) (*sql.DB, error)
- func OpenReadOnlyWithOptions(path string, opts SQLiteOptions) (*sql.DB, error)
- func OpenReadWrite(path string) (*sql.DB, error)
- func OpenReadWriteContext(ctx context.Context, path string) (*sql.DB, error)
- func OpenReadWriteContextWithOptions(ctx context.Context, path string, opts SQLiteOptions) (*sql.DB, error)
- func OpenReadWriteWithOptions(path string, opts SQLiteOptions) (*sql.DB, error)
- type MissingIndexError
- type SQLiteJournalMode
- type SQLiteOptions
- type SQLiteTempStore
Constants ¶
const ( // QuantizationFloat32 is the default float32 vector quantization. QuantizationFloat32 = "float32" // QuantizationInt8 uses signed 8-bit scalar quantization. QuantizationInt8 = "int8" // QuantizationBinary uses sign-based 1-bit quantization for the // prefilter and pairs it with a full-precision float32 companion // column for rescoring. The embedder dimension must be a multiple of // 8 because each byte of the packed blob carries 8 consecutive dims. QuantizationBinary = "binary" )
Variables ¶
This section is empty.
Functions ¶
func CheckSQLiteReady ¶
func CheckSQLiteReady() error
CheckSQLiteReady validates that the SQLite driver and sqlite-vec extension are usable.
func CheckSQLiteReadyContext ¶
CheckSQLiteReadyContext validates that the SQLite driver and sqlite-vec extension are usable.
func CosineScoreFromDistance ¶
CosineScoreFromDistance converts sqlite-vec cosine distance into a clamped score.
func DecodeVectorBlob ¶
DecodeVectorBlob decodes a sqlite-vec float32 blob into float64 values. The hot path does one allocation (the returned []float64) and reads each 4-byte little-endian float32 directly from the input buffer — the earlier binary.Read + bytes.Reader route allocated an intermediate []float32 plus a reader wrapper per call, which compounded on reuse-heavy rebuilds where this runs for every stored chunk.
func DecodeVectorBlobBinary ¶
DecodeVectorBlobBinary expands a bit-packed vector blob back to {-1, 1} float64 values. The returned vector has length blob-bytes * 8.
func DecodeVectorBlobInt8 ¶
DecodeVectorBlobInt8 decodes a sqlite-vec int8 vector blob back to float64.
func EncodeVectorBlob ¶
EncodeVectorBlob encodes float64 embeddings into the sqlite-vec blob format.
func EncodeVectorBlobBinary ¶
EncodeVectorBlobBinary packs the vector into a sqlite-vec bit blob using sign-based quantization: each output bit is 1 when the corresponding component is non-negative, 0 otherwise. The dimension must be a multiple of 8. The bit ordering matches sqlite-vec's vec_bit() parser: within each byte, dimension k occupies bit (k % 8) counted from the LSB.
func EncodeVectorBlobInt8 ¶
EncodeVectorBlobInt8 L2-normalizes the input vector and then quantizes it to signed 8-bit integers for sqlite-vec int8 vector columns. Normalizing before quantization ensures any embedder output is mapped into [-1, 1] without silent clamping or hidden preconditions.
func IsMissingIndex ¶
IsMissingIndex reports whether err wraps a missing-index failure.
func MissingIndexPath ¶
MissingIndexPath returns the configured path for a missing-index failure.
func OpenReadOnly ¶
OpenReadOnly opens a fresh read-only SQLite handle.
func OpenReadOnlyContext ¶
OpenReadOnlyContext opens a fresh read-only SQLite handle.
func OpenReadOnlyContextWithOptions ¶
func OpenReadOnlyContextWithOptions(ctx context.Context, path string, opts SQLiteOptions) (*sql.DB, error)
OpenReadOnlyContextWithOptions opens a fresh read-only SQLite handle with caller-supplied SQLite tuning options.
func OpenReadOnlyWithOptions ¶
func OpenReadOnlyWithOptions(path string, opts SQLiteOptions) (*sql.DB, error)
OpenReadOnlyWithOptions opens a fresh read-only SQLite handle with caller-supplied SQLite tuning options.
func OpenReadWrite ¶
OpenReadWrite opens a read-write SQLite handle.
func OpenReadWriteContext ¶
OpenReadWriteContext opens a read-write SQLite handle.
func OpenReadWriteContextWithOptions ¶
func OpenReadWriteContextWithOptions(ctx context.Context, path string, opts SQLiteOptions) (*sql.DB, error)
OpenReadWriteContextWithOptions opens a read-write SQLite handle with caller-supplied SQLite tuning options.
func OpenReadWriteWithOptions ¶
func OpenReadWriteWithOptions(path string, opts SQLiteOptions) (*sql.DB, error)
OpenReadWriteWithOptions opens a read-write SQLite handle with caller-supplied SQLite tuning options.
Types ¶
type MissingIndexError ¶
type MissingIndexError struct {
Path string
}
MissingIndexError reports that the requested index file does not exist yet.
func (*MissingIndexError) Error ¶
func (e *MissingIndexError) Error() string
type SQLiteJournalMode ¶
type SQLiteJournalMode string
SQLiteJournalMode selects an optional journal-mode policy for newly opened SQLite handles. The zero value leaves SQLite's current/default journal mode unchanged; WAL and other non-default modes are opt-in so embedders do not get unexpected sidecar files or durability tradeoffs.
const ( // SQLiteJournalModeDefault leaves SQLite's current/default journal mode unchanged. SQLiteJournalModeDefault SQLiteJournalMode = "" // SQLiteJournalModeDelete selects SQLite's DELETE rollback journal mode. SQLiteJournalModeDelete SQLiteJournalMode = "DELETE" // SQLiteJournalModeTruncate selects SQLite's TRUNCATE rollback journal mode. SQLiteJournalModeTruncate SQLiteJournalMode = "TRUNCATE" // SQLiteJournalModePersist selects SQLite's PERSIST rollback journal mode. SQLiteJournalModePersist SQLiteJournalMode = "PERSIST" // SQLiteJournalModeMemory selects SQLite's in-memory rollback journal mode. SQLiteJournalModeMemory SQLiteJournalMode = "MEMORY" // SQLiteJournalModeWAL selects SQLite's write-ahead log journal mode. SQLiteJournalModeWAL SQLiteJournalMode = "WAL" // SQLiteJournalModeOff disables SQLite rollback journal creation. SQLiteJournalModeOff SQLiteJournalMode = "OFF" )
type SQLiteOptions ¶
type SQLiteOptions struct {
// BusyTimeout controls how long SQLite waits for a locked table/database
// before returning SQLITE_BUSY. A nil value uses the Stroma default (5s).
// A non-nil zero disables SQLite's busy timeout.
BusyTimeout *time.Duration
// JournalMode optionally sets PRAGMA journal_mode. The default leaves the
// database's current mode unchanged; set SQLiteJournalModeWAL explicitly when
// the embedding application wants WAL sidecar files and WAL concurrency.
JournalMode SQLiteJournalMode
// CacheSizePages optionally sets PRAGMA cache_size using SQLite page units.
// Leave zero to use SQLite's default or database-configured value.
CacheSizePages int
// MmapSizeBytes optionally sets PRAGMA mmap_size. Leave zero to use SQLite's
// default. Values must be non-negative.
MmapSizeBytes int64
// TempStore optionally sets PRAGMA temp_store. The zero value leaves SQLite's
// default unchanged.
TempStore SQLiteTempStore
}
SQLiteOptions configures SQLite handles opened by this package.
Zero values are conservative: foreign keys are enabled and BusyTimeout defaults to five seconds to make ordinary reader/writer lock contention wait briefly instead of failing immediately. JournalMode, CacheSizePages, MmapSizeBytes, and TempStore are opt-in tuning knobs for library users; Stroma does not set WAL, mmap, cache, or temp-store policy by default.
type SQLiteTempStore ¶
type SQLiteTempStore int
SQLiteTempStore selects where SQLite stores temporary tables and indexes. The zero value leaves SQLite's default unchanged.
const ( // SQLiteTempStoreDefault leaves SQLite's temp_store policy unchanged. SQLiteTempStoreDefault SQLiteTempStore = iota // SQLiteTempStoreFile stores SQLite temporary tables and indexes in files. SQLiteTempStoreFile // SQLiteTempStoreMemory stores SQLite temporary tables and indexes in memory. SQLiteTempStoreMemory )
Source Files