Vector Search

an5 ORM includes built-in vector search capabilities for AI and machine learning applications.

Overview

Vector search allows you to find similar items based on semantic meaning rather than exact matches. This is useful for:

  • Semantic search in documentation
  • Recommendation systems
  • Image similarity search
  • Natural language queries

Choosing a backend

The TypeScript runtime tries the backends in this order and uses the first one that works. Other runtimes have their own provider support, so switch the language and provider in the header toolbar above to see what yours reaches.

SQLite is the exception: every runtime stores and ranks a VECTOR(n) column the same way, so that section applies whatever language you picked.

Order Backend Needs
1 Dedicated Vector Databases (NBase, Qdrant, Chroma, Pinecone, Weaviate, Milvus) Vector store endpoint configured via connectionString
2 PostgreSQL pgvector extension
3 SQL Server 2025 VECTOR_DISTANCE
4 SQLite sqlite-vec, built-in distance functions, or json_each
5 In-memory Nothing, but candidate rows are scored in memory

Use a dedicated vector database when the embedding table is too large to scan: the vectors live in the vector database and the rows stay in your relational table, so a search never loads the table into memory.

PostgreSQL note: Enable pgvector and store embeddings in a vector column with the same dimension as the query. Native search requires a compatible column; otherwise the runtime falls back to scanning rows in memory.

Generate the Document model client first and configure its adapter for the selected provider. The snippets assume an initialized runtime table client named table (or a generated TypeScript client named db) and a query embedding with the same dimension as stored embeddings.

var results = table.VectorSearch(
    vector: queryEmbedding,
    take: 10,
    vectorField: "embedding",
    distanceMetric: "cosine"
);

Advanced NBase and relation examples are available in the TypeScript reference.

SQLite

SQLite has no vector type, so a VECTOR(n) column stores a BLOB of little-endian float32 — 4 bytes per dimension, about a third of the JSON text it replaces. Write a plain array of numbers and the adapters encode it for you; read it back and you get the same array, so nothing in your code deals with bytes.

A column that already holds JSON text ('[0.1, 0.2]') keeps working: the adapters read both, so a database written by an older version needs no migration.

How the search is ranked

Every runtime tries the same four strategies in order, and uses the first one that runs:

Order Strategy Needs Reaches
1 sqlite-vec The extension loaded Scalar distance queries over ordinary tables
2 udf A driver that can register a function BLOB and legacy text columns
3 sql JSON1 (built in since SQLite 3.38) Legacy text columns
4 memory Nothing Any column, whole table loaded

Strategies 1-3 rank inside the database and transfer only the rows that match, which is the reason to prefer them over the in-memory path. A row whose stored vector cannot be scored — no vector, another dimension — is left out rather than reported with a null distance.

Which strategies a given runtime can reach:

Runtime sqlite-vec udf sql memory
TypeScript (better-sqlite3) yes yes yes yes
TypeScript (browser sql.js) only in a WASM build that can load one with registerFunction yes yes
Python (sqlite3) yes yes yes yes
.NET (Microsoft.Data.Sqlite) yes yes yes yes
Go (database/sql) if the driver loaded it if the driver registered them yes yes
Rust (sqlx) no no yes yes
Java / Kotlin (JDBC) if the driver loaded it no yes yes
Swift (CSQLite) yes yes yes yes

sqlx pools connections and JDBC has no API for either, which is why those two reach the sql and memory strategies without driver-specific hooks. For JSON text columns, SQL avoids transferring all candidate rows. Float32 BLOB columns use the in-memory fallback when no vector functions are available.

Loading sqlite-vec

For native support for all three metrics, including dot product, use the AN5 C extension. Run npm run build:sqlite:native -w an5Adapters from the workspace and pass the printed library path as sqliteVec. The extension reads BLOBs directly, uses SSE2 on x86-64 and caches the query vector per statement. It is discovered under the existing udf strategy, but computes distances in C; adapters keep the native functions instead of registering language callbacks over them.

sqlite-vec provides native vector distance functions and exact nearest-neighbour search. The adapter uses scalar distance functions over an ordinary table. Pass the extension binary when opening it:

Version 0.1.9 supplies cosine and Euclidean scalar distances, but no inner-product scalar function. dot therefore uses a driver function or the remaining fallback strategies. vec0 table creation, synchronization and queries are application-managed through raw SQL; no ANN index is created by the adapter.

Pinning a strategy

Pinning skips the probing and uses one strategy, which is useful for pinning a benchmark or for reproducing a query exactly. The four values are the same in every runtime — 'sqlite-vec', 'udf', 'sql', 'memory' — and only the spelling of the option differs: vectorStrategy in TypeScript, vector_strategy in Python and Rust, VectorStrategy in .NET, VectorSupport in Go, An5.vectorStrategy(...) in Kotlin, An5Adapter.vectorStrategy in Swift, and setVectorStrategy(...) in Java.

In-Memory Fallback

Last resort: for development, or when no vector backend is configured, vectorSearch scans the table and compares vectors in memory. No separate store class is needed — pass the same arguments and the ORM handles the fallback.

It is correct but does not scale: every call loads the matching rows, so reach for NBase or a native engine once the table grows.

Next Steps