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.
NBase note: NBase vector integration is documented for the TypeScript runtime. The examples below use an NBase-only adapter; no relational table is required.
Notice: A verified vector-search example for Golang + Nbase is not available. Please choose another combination from the header above; do not assume another runtime's API applies.
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
- AI Agent - Natural language database queries
- Raw Queries - Execute raw SQL