DOCSEARCHbyAlgolia
Submit Docs

SQLite-Vector

repository·main·Indexed 19 days ago

https://github.com/sqliteai/sqlite-vector

A high-performance, cross-platform SQLite extension for production-grade vector search, enabling semantic search and Retrieval-Augmented Generation (RAG) in mobile, edge, and server environments. It supports storing vectors as BLOBs and provides distance metrics including L1, COSINE, DOT, SQUARED_L2, and HAMMING. Official packages are available for Node.js (@sqliteai/sqlite-vector), Python (sqlite-vector), and Flutter/Dart (sqlite_vector), with WASM support via @sqliteai/sqlite-wasm.

Tokens
8.7K
Snippets
34
Records
42
Agent score
76%

What's inside sqlite-vector

  1. Understand the core concepts of SQLite Vector

    main

    Instant Vector Search

    Unlike traditional vector databases that require long preprocessing/indexing phases (like HNSW or DiskANN), sqlite-vector allows for immediate search on existing data.

    • No Preindexing: Start searching as soon as data is inserted.
    • Zero-cost Updates: Add, remove, or modify vectors without rebuilding an index.
    • Standard Schema: Works directly with BLOB columns in ordinary SQLite tables.

    Supported Vector Formats

    Vectors are stored as binary blobs in BLOB columns. Supported types include:

    • float32 (4 bytes/element)
    • float16 (2 bytes/element)
    • bfloat16 (2 bytes/element)
    • int8 (1 byte/element)
    • uint8 (1 byte/element)
    • 1bit (1 bit/element)

    Supported Distance Metrics

    • L2 Distance (Euclidean)
    • Squared L2
    • L1 Distance (Manhattan)
    • Cosine Distance
    • Dot Product
    • Hamming Distance (only for 1bit vectors)

  2. How the semantic search workflow works

    main

    The semantic search implementation relies on three core components:

    1. Embeddings: Uses sentence-transformers to convert text into dense vector representations. The default model is all-MiniLM-L6-v2, which produces 384-dimensional vectors.
    2. Vector Store: Uses the sqlite-vector extension to store these embeddings within a SQLite database.
    3. Similarity Search: Performs fast similarity searches (specifically using cosine distance) directly within the SQLite database to find documents semantically related to a query.

  3. Getting started with SQLite Vector

    main

    To use the SQLite Vector extension, follow these core requirements:

    1. Fixed Dimensions: All vectors in a specific column must have a fixed dimension, which you define during initialization using vector_init.
    2. Explicit Initialization: Only tables that have been explicitly initialized with vector_init are eligible for vector search.
    3. Quantization Workflow: For fast approximate nearest neighbor (ANN) search, you must run vector_quantize() before using vector_quantize_scan().
    4. Preloading: To optimize performance at startup, use vector_quantize_preload() to load quantized data into memory.

  5. Load the SQLite-Vector extension

    main

    Once you have the binary, you can load the extension into your SQLite environment using the following methods:

    Using the SQLite CLI: Use the .load dot-command followed by the path to the extension file.

    Using SQL: Use the load_extension() function within a SQL statement.

    Alternatively, you can embed the extension directly into your application code.

    -- In SQLite CLI
.load ./vector

-- In SQL
SELECT load_extension('./vector');

  6. Install the SQLite Vector Python package

    main

    To use SQLite Vector in Python, install the package via pip. The package includes prebuilt binaries for various platforms and architectures (Linux, Windows, and macOS). pip will automatically select and install the correct binary package for your specific platform and architecture.

    pip install sqlite-vector

  8. Use the SQLite-Vector WASM version

    main

    For web-based or browser environments, you can use a WebAssembly (WASM) version of SQLite that has the SQLite-Vector extension pre-enabled. This is available via the @sqliteai/sqlite-wasm package on npm.

    npm install @sqliteai/sqlite-wasm

  9. Load the sqlite-vector extension in Python

    main

    To use vector search features, you must load the sqlite-vector extension into your SQLite connection. You can locate the extension binary using importlib.resources from the sqlite_vector.binaries package.

    Note: Some SQLite installations may have extension loading disabled by default. You must call conn.enable_load_extension(True) before attempting to load the extension, and it is a best practice to disable it again via conn.enable_load_extension(False) after loading for security.

    import importlib.resources
import sqlite3

# Connect to your SQLite database
conn = sqlite3.connect("example.db")

# Load the sqlite-vector extension
# pip will install the correct binary package for your platform and architecture
ext_path = importlib.resources.files("sqlite_vector.binaries") / "vector"

conn.enable_load_extension(True)
conn.load_extension(str(ext_path))
conn.enable_load_extension(False)

# Now you can use sqlite-vector features in your SQL queries
print(conn.execute("SELECT vector_version();").fetchone())

  10. Integrate SQLite Vector into a Swift project

    main

    To use SQLite Vector in Swift, add the repository as a package dependency in Xcode. After adding the dependency, you must manually enable extension loading in your SQLite connection and load the vector extension using its path.

    Note: You must follow standard SQLite extension loading procedures for iOS/macOS to ensure the library is accessible at runtime.

    import vector

var db: OpaquePointer?
sqlite3_open(":memory:", &db)
sqlite3_enable_load_extension(db, 1)
var errMsg: UnsafeMutablePointer<Int8>? = nil
sqlite3_load_extension(db, vector.path, nil, &errMsg)

var stmt: OpaquePointer?
sqlite3_prepare_v2(db, "SELECT vector_version()", -1, &stmt, nil)
defer { sqlite3_finalize(stmt) }
sqlite3_step(stmt)
print("vector_version(): \(String(cString: sqlite3_column_text(stmt, 0)))")
sqlite3_close(db)

  11. Add SQLite Vector to Android via Gradle

    main

    Add the ai.sqlite:vector artifact to your Gradle dependencies to use the extension in Android applications.

    implementation 'ai.sqlite:vector:0.9.80'

    To initialize the extension, create a SQLiteCustomExtension using the native library directory and pass it into a SQLiteDatabaseConfiguration.

    SQLiteCustomExtension vectorExtension = new SQLiteCustomExtension(getApplicationInfo().nativeLibraryDir + "/vector", null);
SQLiteDatabaseConfiguration config = new SQLiteDatabaseConfiguration(
    getCacheDir().getPath() + "/vector_test.db",
    SQLiteDatabase.CREATE_IF_NECESSARY | SQLiteDatabase.OPEN_READWRITE,
    Collections.emptyList(),
    Collections.emptyList(),
    Collections.singletonList(vectorExtension)
);
SQLiteDatabase db = SQLiteDatabase.openDatabase(config, null, null);