1. Overview

Vec1 is an SQLite extension that provides approximate nearest-neighbor (ANN) vector search using SQLite's virtual table interface. Euclidean (L2) and cosine distances are supported. Vec1 is implemented in portable C and has no external dependencies. It uses AVX2 on x86 and NEON on ARM.

Vec1 uses IVFADC (Inverted File with Asymmetric Distance Computation) with OPQ (Optimized Product Quantization).

Tests on publicly available datasets are available here.

2. Building The Extension

The extension is implemented in a single C file, "vec1.c". The current release is version 0.8. The easiest way to compile vec1.c to a loadable extension on unix-like platforms is to use the configure script at the root of the full SQLite source tree as follows (replace vec1.so with vec1.dylib on OSX):

./configure && make vec1.so

Or on windows, using the Makefile.msc file at the root of the full SQLite source tree:

nmake /F Makefile.msc vec1.dll

Alternatively, it may be compiled in the same way as other SQLite extensions. For best performance, compile with SIMD support and aggressive compiler optimizations.

For example, on Linux or macOS x86-64 with gcc or clang:

cc -g -O3 -DNDEBUG -mavx2 -mfma vec1.c -shared -fPIC -o vec1.so

Or with MSVC on x86-64:

cl /Zi /O2 /DNDEBUG /arch:AVX2 vec1.c -link -dll -out:vec1.dll

No special switches are required to enable NEON on ARM. The compiler should still be passed -O3 or the equivalent to enable loop-unrolling and other aggressive optimizations.

Binaries compiled with SIMD instructions enabled on x86-64 platforms as shown above will not work on systems that lack them. A method for building vec1 to support multiple x86-64 architectures is found in this Makefile (target "vec1multi.so"). The configure script and Makefile.msc methods of building describe above do this automatically.

3. Usage

A user manual and reference docs are available. Also a video "Vector Queries with SQLite Vec1".

4. Roadmap

Future developments may include:

• More and better testing.
• More and better optimization of almost all paths.
• Add an option for a modern graph-based index as an alternative to IVFADC. HNSW? DiskANN? Some variant?
• Optimization of "SELECT count(*) FROM vec1tbl".
• Add support for SIMD on wasm.
• Support vectors constructed of elements other than 32-bit IEEE floats - e.g. 8-bit or 32-bit integers, or 16-bit floats.
• Support for partition keys.
• Add the ability to open and use databases created on platforms that use different byte orders for floating point values.
• Implement dot-product as a distance metric for search.
• Allow queries to use multiple threads.

This page was last updated on 2026-10-01 11:21:38Z