Vector
Vector scalar type for AI/ML embeddings and similarity search (PostgreSQL pgvector)
Basic Usage
import { s } from "viborm";
s.vector() // Required number[]
s.vector().dimension(3) // Fixed-length number[]
s.vector().nullable() // number[] | null
Stored as a pgvector vector(n) column. Vectors support .nullable(), .default(), .map(), and .dimension(n) — but not .array(), .id(), .unique(), or .schema(). See the support matrix.
Components must be finite numbers. PostgreSQL components must also fit float32;
an out-of-range value is refused before dispatch. Cosine distance is null
when either vector has zero norm; L2 distance remains defined for zero vectors.
A nullable source vector produces a nullable distance for either metric.
PostgreSQL Setup
Enable the pgvector extension:
CREATE EXTENSION IF NOT EXISTS vector;
Complete Example
const document = s.model({
id: s.string().id().ulid(),
content: s.string(),
embedding: s.vector().dimension(1536), // Store embedding
createdAt: s.dateTime().now(),
}).map("documents");
// Store a document with embedding
await client.document.create({
data: {
content: "Hello, world!",
embedding: [0.1, 0.2, 0.3 /* 1533 more values */],
}
});
Similarity Search
Use _distance in orderBy for nearest-neighbor searches:
const queryEmbedding = [0.1, 0.2, 0.3 /* 1533 more values */];
const similar = await client.document.findMany({
select: { id: true, content: true },
orderBy: {
embedding: {
_distance: {
to: queryEmbedding,
metric: "cosine", // "l2" | "cosine"
},
},
},
take: 10,
});
Set sort: "desc" to return farthest matches first. You can also select the distance score; it is returned as _distance: number:
const scored = await client.document.findMany({
select: {
id: true,
embedding: {
_distance: {
to: queryEmbedding,
metric: "l2",
},
},
},
orderBy: {
embedding: {
_distance: {
to: queryEmbedding,
metric: "l2",
},
},
},
});
scored[0]?._distance; // number | undefined
Vector Dimensions
| Model | Dimensions |
|---|---|
| OpenAI text-embedding-ada-002 | 1536 |
| OpenAI text-embedding-3-small | 1536 |
| OpenAI text-embedding-3-large | 3072 |
| Cohere embed-english-v3.0 | 1024 |
| sentence-transformers | 384-768 |
Indexing Vectors
Without an index, distance ordering reads the whole table: exact, and fine for
small tables. For larger tables, declare an approximate nearest-neighbour index
in the database’s own language with .rawIndex(), chained on the model like
.index(). Migrations create it, recognize it and recreate it when its text
changes. On the document model above:
const indexedDocument = document.rawIndex("documents_embedding_hnsw", {
pg: "CREATE INDEX {name} ON {table} USING hnsw ({embedding} vector_cosine_ops)",
surrealdb:
"DEFINE INDEX {name} ON {table} FIELDS {embedding} HNSW DIMENSION 1536 DIST COSINE",
});
{name}, {table} and {embedding} become the escaped index, table and column
names, so the declaration follows renames and tenant namespaces. A dialect left
out has no such index. Match the index to the metric you order by: pgvector’s
vector_cosine_ops serves metric: "cosine" and vector_l2_ops serves
metric: "l2"; on SurrealDB DIST COSINE serves cosine and DIST EUCLIDEAN
(the default) serves l2.
Approximate nearest neighbours
An index answers a different question than the exact order: it finds rows
that are probably nearest, quickly. VibORM keeps the two apart. A distance
order stays exact even when an index exists, and the index is used only when
you ask for it with approximate: true:
const nearby = await client.document.findMany({
select: { id: true, content: true },
where: { content: { contains: "launch" } },
orderBy: {
embedding: {
_distance: { to: queryEmbedding, metric: "cosine", approximate: true },
},
},
take: 10,
});
What approximate: true means:
- The rows are approximate neighbours, returned nearest first by their exact distance. Some true neighbours may be missing.
- A read can return fewer rows than
take. pgvector’s HNSW search keeps at mosthnsw.ef_searchcandidates (40 by default), and filters — yourwhereand those extensions add, such as soft delete or permissions — apply to what the index found, after the search. - Rows whose vector is
nullare never returned, and an index may also skip zero vectors (pgvector does for cosine). - The flag is honored only where an index can answer: a root
findManyorfindFirstwhose firstorderByterm is the distance, ascending, withtake > 0(implied byfindFirst) and nocursor,skipordistinct. Everywhere else — aninclude, a nested read, an aggregate — it is ignored and the order is exact. approximate: falseand leaving it out are the same exact order.- On SurrealDB, the read uses the HNSW index only when the model declares
exactly one
.rawIndex()HNSW index on that field with a matchingDIST, the field carries no read permission, and the read is of the table itself. When the search finds nothing (for example the index is not built yet), the exact order answers instead.
On PostgreSQL the planner still decides: a selective where may lead it to
read the table instead, which returns the exact answer.
When to Use Vector
| Use Case | Recommendation |
|---|---|
| Semantic search | Vector embeddings |
| Image similarity | Vector embeddings |
| Recommendation | Vector embeddings |
| Full-text search | PostgreSQL tsvector or dedicated search |
| Exact matching | Regular scalars with indexes |