asg017/sqlite-vec sqlite-vec

Version: 0.1.7 Tags: latest: 0.1.7, alpha: 0.1.7-alpha.13

References: package.json — exports, entry points • README — setup, basic usage • Docs — API reference, guides • GitHub Issues — bugs, workarounds, edge cases • Releases — changelog, breaking changes, new APIs

Search

Use skilld search instead of grepping .skilld/ directories — hybrid semantic + keyword search across all indexed docs, issues, and releases. If skilld is unavailable, use npx -y skilld search.

skilld search "query" -p sqlite-vec
skilld search "issues:error handling" -p sqlite-vec
skilld search "releases:deprecated" -p sqlite-vec

Filters: docs:, issues:, releases: prefix narrows by source type.

API Changes

This section documents version-specific API changes — prioritize recent major/minor releases.

• BREAKING: DELETE operations now properly clear vector data and free space — v0.1.7 changed behavior from only setting validity bits. Code using DELETE statements may see different storage behavior source

• NEW: Distance column constraints in KNN queries — v0.1.7 adds support for >, >=, <, <= constraints on the distance column, enabling pagination-like patterns without requiring large k values source

• NEW: Metadata columns in vec0 virtual tables — v0.1.6 added ability to declare metadata columns that can be filtered in WHERE clauses of KNN queries alongside vector matching source

• NEW: Partition keys for internal index sharding — v0.1.6 added partition key syntax to internally shard vector indexes by column values source

• NEW: Auxiliary columns with + prefix — v0.1.6 added support for auxiliary columns (prefix with +) that are unindexed but available for fast lookups in KNN query results source

• BREAKING: vec_npy_each table function removed from default entrypoint — v0.1.3 moved this experimental function out due to CVE-2024-46488 security mitigation; affected code using untrusted SQL or the rare vec_npy_each function source

Also changed: Static linking support for SQLite 3.31.1+ · serialize_float32() / serialize_int8() Python functions added

Best Practices

• Use two-column re-scoring pattern for binary quantization — store both quantized and full-precision vectors; query coarse index with quantized vectors, then re-score top candidates with full precision to recover quality lost from extreme dimensionality reduction source

• Combine vec_slice() with vec_normalize() for Matryoshka embeddings — truncating dimensions requires subsequent normalization to maintain embedding quality and semantic meaning source

• Prefer scalar quantization over binary quantization for moderate storage savings — trade off storage efficiency against quality loss; vec_quantize_float16 (2 bytes per value) and vec_quantize_int8 (1 byte per value) offer better quality retention than binary quantization for many use cases source

• Use partition keys to shard large vector datasets — declare a partition key column in CREATE VIRTUAL TABLE to internally shard the vector index on that column, improving query performance by reducing search scope source

• Combine metadata columns (indexed) with auxiliary columns (unindexed) for efficient filtering — use regular metadata columns for dimensions you filter on in KNN WHERE clauses; prefix columns with + to store related data without indexing overhead source

• Use distance constraints instead of oversampling for pagination — as of v0.1.7, apply distance > threshold or distance < threshold constraints in WHERE clauses to paginate through KNN results without fetching excess candidates source

• Monitor the k value limit when performing large KNN queries — the default maximum k is 4096 (configurable) to prevent memory exhaustion; be aware that kNN results are materialized in memory and internally use O(n²) complexity on k source

• Rely on v0.1.7+ for automatic DELETE cleanup — vector space is now reclaimed when enough vectors are deleted to clear a chunk (~1024 vectors); previous versions only marked entries as deleted without freeing space source

• Select embedding models with quantization support for better results — models like nomic-embed-text-v1.5, mxbai-embed-large-v1, and OpenAI's text-embedding-3 are specifically trained to maintain quality after quantization and Matryoshka truncation source