---
title: Vector
description: Vector scalar type for AI/ML embeddings and similarity search (PostgreSQL pgvector)
icon: sparkles
---

:::info
Vector scalars require PostgreSQL with the `pgvector` extension. On MySQL and SQLite the values are stored as JSON and similarity search is unavailable.
:::

## Basic Usage

```ts
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](/docs/schema/scalars).

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:

```sql
CREATE EXTENSION IF NOT EXISTS vector;
```

## Complete Example

```ts
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:

```ts
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`:

```ts
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
```

:::warning
Distance ordering and selection require a pgvector-enabled PostgreSQL driver, for example `new PgDriver({ pgvector: true })`. Other drivers throw `FeatureNotSupportedError`, and the query vector length must match `.dimension(...)` when a dimension is declared.
:::

## 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:

```ts
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`:

```ts
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.

:::warning[An index VibORM does not know blocks migrations]
A vector index created by hand, outside `.rawIndex()`, makes every `push` and
`migrate` apply in the namespace fail with `V8001` before it changes anything:
VibORM keeps the index but cannot synchronize a table that holds an index it
cannot declare. Declare it with `.rawIndex()` instead, and drop the hand-made
one once: an HNSW or IVFFlat index VibORM did not create still refuses after it
is declared, and the next `push` creates the declared one.
:::

## 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 |
