DOCSEARCHbyAlgolia
Submit Docs

sqlite-vec

repository·main·Indexed 27 days ago

https://github.com/asg017/sqlite-vec

An extremely small, fast vector search SQLite extension written in pure C. It enables storing and querying float, int8, and binary vectors within SQLite using `vec0` virtual tables. The library supports K-Nearest Neighbor (KNN) style queries using the `match` operator and provides bindings for Python, Node.js, Ruby, Go, Rust, Datasette, rqlite, and sqlite-utils.

Tokens
14.9K
Snippets
61
Records
85
Agent score
85%

What's inside sqlite-vec

  1. The `sqlite-vec-wasm-demo` NPM package

    main

    The sqlite-vec-wasm-demo package provides a demonstration of sqlite-vec in WebAssembly.

    Warning: This package is intended for demonstration purposes only. It may change at any time and does not follow the standard sqlite-vec semantic versioning. Use it with caution in production environments.

  2. Understand the `sqlite-vec` in-memory benchmark scope

    main

    The sqlite-vec in-memory benchmarks compare K-Nearest Neighbor (KNN) query performance against other in-process vector search tools.

    Important Constraints:

    • Brute Force Only: The benchmarks use brute force linear scans only. They do not test Approximate Nearest Neighbor (ANN) implementations.
    • In-Memory Only: Tests are conducted using in-memory datasets. While sqlite-vec and other tools support disk serialization or mmap, this specific benchmark focuses on in-memory performance.
    • Sequential Queries: Queries are executed one after another (not batched) to emulate sequential "server request" style queries. Note that sqlite-vec does not currently support batched queries.
    • CPU Only: Performance is measured using CPU only.
    • Implementation: Tests are written in Python. Vectors are provided as in-memory numpy arrays and converted to the appropriate format for each tool (e.g., sqlite-vec reads vectors into a SQLite table).

  3. Integrate `sqlite-vec` into C or C++ projects

    main
    To use sqlite-vec in a C or C++ project, vendor the sqlite-vec.c and sqlite-vec.h files directly into your source tree. You can then compile them along with your existing project files using your standard build system.

  4. Use Metadata Columns in `vec0` Virtual Tables

    main

    Metadata columns allow you to store boolean, integer, floating point, or text data alongside vectors. These columns can be used in the WHERE clause of a KNN query to filter results during the vector search calculation.

    Supported Types:

    • TEXT
    • INTEGER (8-byte)
    • FLOAT (8-byte)
    • BOOLEAN (1-bit 0 or 1)

    Constraints & Limitations:

    • Maximum of 16 metadata columns per table.
    • Column names are case-insensitive.
    • Additional constraints like UNIQUE or NOT NULL are not supported.
    • Supported operators in WHERE clauses: =, !=, >, >=, <, <=.
    • Note: Boolean columns only support = and !=. Using LIKE, GLOB, REGEXP, or IS NULL will result in errors or incorrect results.
    create virtual table vec_movies using vec0(
  movie_id integer primary key,
  synopsis_embedding float[1024],
  genre text,
  num_reviews int,
  mean_rating float,
  contains_violence boolean
);

-- Querying with metadata constraints
select *
from vec_movies
where synopsis_embedding match '[...]'
  and k = 5
  and genre = 'scifi'
  and num_reviews between 100 and 500
  and mean_rating > 3.5
  and contains_violence = false;

  5. Compile `sqlite-vec` from the amalgamation build

    main

    The amalgamation build provides pre-configured sqlite-vec.c and sqlite-vec.h files in a .zip or .tar.gz archive. You can download these from the Releases page. Once extracted, you can compile the extension manually using your platform's compiler. Note that different platforms or architectures may require different flags.

    # Download and unzip (replace {{data.VERSION}} with actual version)
wget https://github.com/asg017/sqlite-vec/releases/download/v{{data.VERSION}}/sqlite-vec-{{data.VERSION}}-amalgamation.zip
unzip sqlite-vec-{{data.VERSION}}-amalgamation.zip

# Linux 
gcc -g -fPIC -shared sqlite-vec.c -o vec0.so

# MacOS
gcc -g -fPIC -dynamiclib sqlite-vec.c -o vec0.dylib

# Windows, MSVC compiler
cl sqlite-vec.c -link -dll -out:sqlite-vec.dll

# Windows, MinGW
gcc -g -shared sqlite-vec.c -o vec0.dll

  6. Load sqlite-vec into a SQLite connection in Ruby

    main

    After installing the gem, you can load sqlite-vec SQL functions into an existing SQLite3::Database connection using SqliteVec.load(db). Note that you must enable extension loading on the database connection before calling load(), and it is recommended to disable it immediately after.

    require 'sqlite3'
require 'sqlite_vec'

db = SQLite3::Database.new(':memory:')
db.enable_load_extension(true)
SqliteVec.load(db)
db.enable_load_extension(false)

# Verify installation by checking the version
result = db.execute('SELECT vec_version()')
puts result.first.first

  7. Use sqlite-vec with ncruces/go-sqlite3 (WASM-based)

    main

    To avoid CGO, you can use github.com/ncruces/go-sqlite3, which uses a custom WASM build of SQLite. To include sqlite-vec support, use the specialized WASM binary provided in the github.com/asg017/sqlite-vec-go-bindings/ncruces package.

    Note: Because github.com/asg017/sqlite-vec-go-bindings/ncruces embeds the custom WASM build, you do not need to use github.com/ncruces/go-sqlite3/embed.

    go get -u github.com/asg017/sqlite-vec-go-bindings/ncruces

  8. Install sqlite-vec via package managers

    main

    You can install sqlite-vec using various language-specific package managers depending on your environment.

    pip install sqlite-vec
    npm install sqlite-vec
    bun install sqlite-vec
    deno add npm:sqlite-vec
    gem install sqlite-vec
    cargo add sqlite-vec
    go get -u github.com/asg017/sqlite-vec-go-bindings/cgo
    go get -u github.com/asg017/sqlite-vec-go-bindings/ncruces
    datasette install datasette-sqlite-vec
    sqlite-utils install sqlite-utils-sqlite-vec

  9. Download amalgamated builds of `sqlite-vec`

    main

    Pre-compiled or amalgamated builds of sqlite-vec are available for download on the official GitHub Releases page. These builds are intended to simplify the integration process by providing the necessary source files in a single unit.

    https://github.com/asg017/sqlite-vec/releases

  10. Pass vectors as Float32Array buffers to SQL functions

    main

    When working with vectors in JavaScript, represent them as a Float32Array. To bind them as parameters to sqlite-vec SQL functions, use the .buffer accessor (or wrap it in a Uint8Array depending on the driver).

    const embedding = new Float32Array([0.1, 0.2, 0.3, 0.4]);
const stmt = db.prepare("select vec_length(?)");
console.log(stmt.run(embedding.buffer)); // 4

  11. Perform KNN queries using `vec0` virtual tables

    main

    For high-performance and compact K-nearest-neighbors (KNN) searches, use the vec0 virtual table. This method is faster than manual SQL searches but requires joining back to your source tables to retrieve non-vector data.

    To use vec0:

    1. Create a virtual table using vec0 with a defined schema (e.g., float[768]).
    2. Populate the virtual table with vector data.
    3. Query using the MATCH operator and specify the number of neighbors with the k parameter.

    Note on SQLite versions: If you are using SQLite 3.41+, you can use LIMIT instead of the k = N syntax, but k = N is the standard approach for sqlite-vec.

    -- 1. Create the virtual table
create virtual table vec_documents using vec0(
  document_id integer primary key,
  contents_embedding float[768]
);

-- 2. Populate the table
insert into vec_documents(document_id, contents_embedding)
  select id, embed(contents)
  from documents;

-- 3. Perform KNN query
select
  document_id,
  distance
from vec_documents
where contents_embedding match :query
  and k = 10;

  12. Install pre-compiled extensions

    main

    You can download pre-compiled loadable extensions directly from the sqlite-vec Github Releases.

    Alternatively, you can use the install.sh script to automatically download the appropriate pre-compiled extension for your machine.

    # Quick install (yolo)
curl -L 'https://github.com/asg017/sqlite-vec/releases/latest/download/install.sh' | sh

# Safe install (inspect before running)
curl -o install.sh -L https://github.com/asg017/sqlite-vec/releases/latest/download/install.sh
cat install.sh
./install.sh