Skip to content
VibORM
Esc
↑↓navigate↵open⌘Jpreview
On this page

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 */],
  }
});

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 most hnsw.ef_search candidates (40 by default), and filters — your where and those extensions add, such as soft delete or permissions — apply to what the index found, after the search.
  • Rows whose vector is null are 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 findMany or findFirst whose first orderBy term is the distance, ascending, with take > 0 (implied by findFirst) and no cursor, skip or distinct. Everywhere else — an include, a nested read, an aggregate — it is ignored and the order is exact.
  • approximate: false and 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 matching DIST, 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

Was this page helpful?