Vector search with sqlite-vec

Use createVectorTable() and knnSearch() from react-native-nitro-sqlite-vec to store vectors and find nearby matches. Vectors are numeric arrays, often called embeddings. The optional package adds sqlite-vec's vec0 virtual tables to SQLite for those queries.

Enable vector search

Install react-native-nitro-sqlite-vec alongside react-native-nitro-sqlite. Enable it for each platform you ship using the iOS, macOS, or Android configuration page, then rebuild the native app. Check availability with isVecAvailable(db) before running vector queries. A JavaScript update alone cannot enable the extension.

Create and search a vector table

import { open } from 'react-native-nitro-sqlite'
import {
  createVectorTable,
  isVecAvailable,
  knnSearch,
  vecVersion,
} from 'react-native-nitro-sqlite-vec'

const db = open({ name: 'vectors.sqlite' })

if (!isVecAvailable(db)) {
  db.close()
  throw new Error('Enable sqlite-vec in the native build')
}

console.log(vecVersion(db))
createVectorTable(db, 'embeddings', { dimensions: 3 })
db.execute('INSERT INTO embeddings (rowid, embedding) VALUES (?, ?)', [
  1,
  '[0.1, 0.2, 0.3]',
])

const matches = knnSearch(db, 'embeddings', [0.1, 0.2, 0.25], 10)
// Each match has rowid and distance.
db.close()

vecVersion(db) calls vec_version() and returns its version string. isVecAvailable(db) returns false if that call fails. createVectorTable(db, table, options) creates a vec0 virtual table if it does not exist. knnSearch(db, table, query, k, options?) returns an array of { rowid, distance } matches, ordered by distance; query can be a numeric array or a JSON vector string.

All four helpers are synchronous and take an open NitroSQLiteConnection:

isVecAvailable() catches any error from vecVersion(), so false means its availability query failed, not necessarily that the build flag is absent. The other helpers let query errors propagate from db.execute().

CreateVectorTableOptions has dimensions: number, optional type: VectorColumnType, optional distanceMetric: VectorDistanceMetric, and optional column: string. VectorColumnType is 'float' | 'int8' | 'bit'; 'float' is the default. VectorDistanceMetric is 'L2' | 'cosine' | 'L1'; sqlite-vec's default is L2. The column defaults to 'embedding'. KnnSearchOptions has an optional column: string with the same default. For int8 and bit tables, construct vectors with sqlite-vec's vec_int8() and vec_bit() SQL functions as appropriate.

The package's five named type exports are VectorColumnType, VectorDistanceMetric, CreateVectorTableOptions, KnnSearchOptions, and KnnMatch. KnnMatch has rowid: number, distance: number, and a [column: string]: unknown index signature. The current knnSearch() helper selects only rowid and distance; write SQL through the core connection when you need more columns.

The helpers interpolate table and column identifiers into SQL. Only pass identifiers you control. They bind the query vector and k as parameters. The core connection query methods can also run sqlite-vec SQL directly for features these small helpers do not wrap.