Semantic search: native vector similarity in a multi-dialect ORM

One $vector sort compiled to PostgreSQL, MariaDB, SQLite and MongoDB Atlas syntax side by side

Aug 27, 2026

Most ORMs stop short of vector similarity. The moment you need it, you drop to raw SQL, hand-writing distance expressions and working around dialect quirks outside your type-safe query API.

UQL 0.3 adds native semantic search to the regular query API, including automatic index migration for HNSW and IVFFlat indexes.

What it looks like

1
const results = await pool.findMany(Article, {
2
  $select: { id: true, title: true },
3
  $sort: { embedding: { $vector: queryEmbedding, $distance: 'cosine' } },
4
  $limit: 10,
5
});

UQL generates the right SQL for your database:

1
SELECT "id", "title" FROM "Article"
2
ORDER BY "embedding" <=> $1::vector
3
LIMIT 10

1
SELECT `id`, `title` FROM `Article`
2
ORDER BY VEC_DISTANCE_COSINE(`embedding`, VEC_FromText(?))
3
LIMIT 10

1
SELECT `id`, `title` FROM `Article`
2
ORDER BY vec_distance_cosine(`embedding`, ?)
3
LIMIT 10

The same query works on every dialect, with no raw SQL or dialect checks in your code.

For MongoDB, UQL translates the same query into an Atlas $vectorSearch pipeline. The Atlas search index itself has to be created in Atlas; see the reference for details.

MongoDB Atlas

1
[
2
  {
3
    "$vectorSearch": {
4
      "index": "embedding_index",
5
      "path": "embedding",
6
      "queryVector": ["..."],
7
      "numCandidates": 100,
8
      "limit": 10
9
    }
10
  }
11
]

Entity setup

Define your vector field and index; UQL handles schema generation, extension creation, and index building:

1
import { Entity, Id, Field, Index } from 'uql-orm';
2

3
@Entity()
4
@Index(['embedding'], {
5
  type: 'hnsw',
6
  distance: 'cosine',
7
  m: 16,
8
  efConstruction: 64,
9
})
10
export class Article {
11
  @Id({ type: Number }) id?: number;
12
  @Field({ type: String }) title?: string;
13

14
  @Field({ type: 'vector', dimensions: 1536 })
15
  embedding?: number[];
16
}

For Postgres, UQL automatically emits CREATE EXTENSION IF NOT EXISTS vector. MariaDB has vector support built in; SQLite requires loading the sqlite-vec extension.

What else shipped

$project returns the computed distance as a named field, typed with the exported WithDistance helper, without computing it twice. Alongside it came four distance metrics (cosine, l2, inner, l1), three vector types (vector, halfvec, sparsevec), and HNSW, IVFFlat and native vector indexes, each where the engine has it. Which engine has which lives in the reference, kept current as engines are added.

Why `$sort`?

Vector similarity search is fundamentally sorting by distance. UQL reuses the existing $sort API, which composes naturally with $where, $select, $limit, and regular sort fields:

1
const results = await pool.findMany(Article, {
2
  $where: { category: 'science' },
3
  $sort: {
4
    embedding: { $vector: queryVec, $distance: 'cosine' },
5
    title: 'asc',
6
  },
7
  $limit: 10,
8
});

Get started

1
npm i uql-orm

If you run into issues or missing features, open an issue on GitHub.

UQL is a JSON-native TypeScript ORM for Node.js, Bun and Deno. Supports PostgreSQL, PGlite, MySQL, MariaDB, MSSQL, SQLite, CockroachDB, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.