uql-orm 0.70.0 → 0.72.0

package/dist/mongo/mongoDialect.js

@@ -1,11 +1,13 @@
 import { ObjectId } from 'mongodb';
 import { AbstractDialect } from '../dialect/abstractDialect.js';
-import { AGGREGATE_VALUE_ALIAS, REL_NESTED_KEY, REL_TEMP_PREFIX, SUM_COUNT_ALIAS, sortCountField, } from '../dialect/aliases.js';
+import { AGGREGATE_VALUE_ALIAS, REL_NESTED_KEY, REL_TEMP_PREFIX, SUM_COUNT_ALIAS, sortCountField, TEXT_SCORE_ALIAS, } from '../dialect/aliases.js';
 import { groupPathField, resolveGroupJoins, resolveQueryJoins, resolveSortableJoin, } from '../dialect/queryJoins.js';
 import { assertSoleId, fieldOf, getMeta, relationOf, soleIdOf } from '../entity/index.js';
 import { COUNT_RESULT_KEY } from '../type/query.js';
 import { QueryRaw } from '../type/queryRaw.js';
-import { aggregateOf, asSelectMap, assertAggregateColumns, assertNonNegativeInteger, columnFamily, countedRelations, entityName, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, getKeys, getRelationRequestSummary, hasKeys, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorObject, isRecord, isVectorSearch, normalizeScalarFieldSelection, parentJoins, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortByCount, someKey, targetKeyColumns, } from '../util/index.js';
+import { aggregateOf, asSelectMap, assertAggregateColumns, assertNonNegativeInteger, columnFamily, countedRelations, entityName, fieldUpdateOf, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, getKeys, getRelationRequestSummary, hasKeys, isFieldUpdateOp, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorObject, isRecord, isVectorSearch, normalizeScalarFieldSelection, parentJoins, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortByCount, rankedTextSearch, someKey, targetKeyColumns, } from '../util/index.js';
+/** A scalar field's operator as the aggregation operator computing it. */
+const MONGO_ARITHMETIC = { $inc: '$add', $mul: '$multiply' };
 /** Default {@link DialectFeatures} for MongoDB. */
 export const mongoDialectFeatures = {
     ifNotExists: false,
@@ -18,6 +20,7 @@ export const mongoDialectFeatures = {
     commentSyntax: 'none',
     vectorIndexRequiresNotNull: false,
     vectorSupportsLength: false,
+    vectorBytes: false,
     supportsTimestamptz: false,
     stringSizing: 'bounded-text',
     supportsUnsigned: false,
@@ -453,9 +456,13 @@ export class MongoDialect extends AbstractDialect {
      * means a *populated* one, at every level of the path: a lookup adds a field to the result, so one
      * added for the sort alone would change what the caller gets back.
      */
-    sort(entity, sort, populate) {
+    sort(entity, { $sort: sort, $populate: populate, $where: where }) {
         const meta = getMeta(entity);
         const normalized = {};
+        // Refused as the SQL dialects refuse it, before MongoDB answers a missing score with its own error.
+        if (sort?.$text) {
+            rankedTextSearch(where);
+        }
         // The same join set the lookups are built from, so what an ordering may address and what the
         // pipeline actually produces cannot drift apart - `$sort` contributes its own to-one joins here
         // exactly as it does on the SQL dialects.
@@ -466,6 +473,13 @@ export class MongoDialect extends AbstractDialect {
     collectSort(meta, sort, joins, path, out) {
         for (const [key, value] of Object.entries(sort ?? {})) {
             const relation = meta.relations[key];
+            if (key === '$text') {
+                if (path) {
+                    throw new TypeError(`$sort by $text is only supported on the queried entity, not on relation '${path.slice(0, -1)}'`);
+                }
+                out[TEXT_SCORE_ALIAS] = { $meta: 'textScore' };
+                continue;
+            }
             if (!relation) {
                 // The queried entity's own vector search is lifted out before this walk, so one reaching it
                 // sits under a relation, which a `$lookup` brings in one row at a time - there is nothing to
@@ -552,7 +566,7 @@ export class MongoDialect extends AbstractDialect {
         const relOpts = relationOf(meta, spec.relation);
         const query = spec.query ?? {};
         const tail = [
-            ...(query.$sort ? [{ $sort: this.sort(relOpts.entity(), query.$sort) }] : []),
+            ...(query.$sort ? [{ $sort: this.sort(relOpts.entity(), query) }] : []),
             ...this.pagerStages(query),
             spec.field
                 ? {
@@ -668,7 +682,7 @@ export class MongoDialect extends AbstractDialect {
         return [
             ...this.matchStages(entity, q.$where, opts, this.aggregateKeys(entity, q)),
             ...this.readStages(entity, q, {
-                sort: this.sort(entity, q.$sort, q.$populate),
+                sort: this.sort(entity, q),
                 pager: this.pagerStages(q),
             }),
         ];
@@ -911,8 +925,14 @@ export class MongoDialect extends AbstractDialect {
         const set = {};
         const push = {};
         const pull = {};
+        const arithmetic = {};
         const unset = new Set();
         for (const [key, value] of Object.entries(persistable)) {
+            if (isFieldUpdateOp(value)) {
+                const [op, operand] = fieldUpdateOf(value);
+                arithmetic[key] = { [MONGO_ARITHMETIC[op]]: [{ $ifNull: [`$${key}`, 0] }, { $literal: operand }] };
+                continue;
+            }
             if (!isJsonUpdateOp(value)) {
                 set[key] = value;
                 continue;
@@ -930,7 +950,7 @@ export class MongoDialect extends AbstractDialect {
                 pull[`${key}.${path}`] = v;
             }
         }
-        return { set, push, pull, unset };
+        return { set, push, pull, arithmetic, unset };
     }
     /**
      * Turn a persistable payload into a MongoDB update, mapping UQL's JSON operators onto their native
@@ -939,12 +959,12 @@ export class MongoDialect extends AbstractDialect {
      */
     getUpdateFilter(persistable) {
         const groups = this.groupUpdateOperators(persistable);
-        const { set, push, pull, unset } = groups;
+        const { set, push, pull, arithmetic, unset } = groups;
         const exprKeys = [...Object.keys(pull), ...Object.keys(set), ...Object.keys(push)];
-        // Native `$pull` fails on a value that is no array, and MongoDB rejects two operators targeting one
-        // path in a single update document: either forces the pipeline form.
+        // Native `$pull` fails on a value that is no array, native `$inc`/`$mul` on a `null`, and MongoDB
+        // rejects two operators targeting one path in a single update document: each forces the pipeline form.
         const allPaths = [...exprKeys, ...unset];
-        if (hasKeys(pull) || new Set(allPaths).size < allPaths.length) {
+        if (hasKeys(pull) || hasKeys(arithmetic) || new Set(allPaths).size < allPaths.length) {
             return this.getUpdatePipeline(groups, new Set(exprKeys));
         }
         return {
@@ -954,11 +974,11 @@ export class MongoDialect extends AbstractDialect {
         };
     }
     /**
-     * A JSON update as one pipeline, since MongoDB refuses two operators on one path: each path composed as
+     * An update as one pipeline, since MongoDB refuses two operators on one path: each path composed as
      * `$pull`, `$set`, `$push`, then `$unset`, as SQL does, with values as `$literal` so `$x` stays data.
      */
-    getUpdatePipeline({ set, push, pull, unset }, exprPaths) {
-        const assignments = {};
+    getUpdatePipeline({ set, push, pull, arithmetic, unset }, exprPaths) {
+        const assignments = { ...arithmetic };
         for (const path of exprPaths) {
             let expr = { $ifNull: [`$${path}`, []] };
             if (path in pull) {
@@ -1016,10 +1036,10 @@ export class MongoDialect extends AbstractDialect {
      */
     buildAggregateStages(entity, q, opts) {
         const meta = getMeta(entity);
-        const joins = resolveGroupJoins(meta, q.$group);
+        const { joins, where } = resolveGroupJoins(meta, q);
         const { groupId, accumulators, columns, named } = this.buildGroupSpec(meta, parseGroupMap(q.$group, q.$select), joins);
         const pipeline = [
-            ...this.matchStages(entity, q.$where, opts, named),
+            ...this.matchStages(entity, where, opts, named),
             ...this.lookupStages(meta, joins),
             { $group: { _id: hasKeys(groupId) ? groupId : null, ...accumulators } },
             // `$group` answers with `_id` even when grouping by nothing, and with what `columns` read to the end.
@@ -1220,6 +1240,10 @@ export class MongoDialect extends AbstractDialect {
         }
         return { vectorKey: found.key, vectorSearch: found.search, regularSort: regularSort };
     }
+    /** The Atlas index a `$vectorSearch` over `column` reads, and migrations create: its declared name, else `<column>_index`. */
+    vectorSearchIndexName(name, column) {
+        return name ?? `${column}_index`;
+    }
     /**
      * Build a `$vectorSearch` aggregation pipeline stage.
      * Merges `$where` into `$vectorSearch.filter` for optimal pre-filtering.
@@ -1231,8 +1255,7 @@ export class MongoDialect extends AbstractDialect {
             throw new TypeError(`Field '${key}' not found in entity '${meta.name}'`);
         }
         const colName = this.resolveColumnName(key, field);
-        // Resolve index name from @Index metadata, or fall back to convention
-        const indexName = findVectorIndex(meta, key)?.name ?? `${colName}_index`;
+        const indexName = this.vectorSearchIndexName(findVectorIndex(meta, key)?.name, colName);
         if (!limit) {
             throw new TypeError(`$vectorSearch requires $limit (vector sort on '${key}' of '${meta.name}')`);
         }

package/dist/mongo/mongodbQuerier.js

@@ -2,7 +2,7 @@ import { AGGREGATE_VALUE_ALIAS } from '../dialect/aliases.js';
 import { hasRequiredJoin } from '../dialect/queryJoins.js';
 import { fieldOf, getMeta, namesKey, soleIdOf } from '../entity/index.js';
 import { AbstractQuerier, enrichError } from '../querier/index.js';
-import { clone, getKeys, getSoftDeleteValue, hasKeys, populatesRelations, throwNoPendingTransaction, throwPendingTransaction, withoutSoftDeleteFilter, } from '../util/index.js';
+import { clone, getKeys, getSoftDeleteValue, hasKeys, populatesRelations, throwNoPendingTransaction, throwPendingTransaction, vectorCandidates, withoutSoftDeleteFilter, } from '../util/index.js';
 /**
  * `$limit: 0` asks for no rows, the way it does on every SQL dialect - but MongoDB reads `limit(0)`
  * as *unlimited*, so a read that passed it straight to the driver came back with the whole
@@ -93,7 +93,7 @@ export class MongodbQuerier extends AbstractQuerier {
         if (hasKeys(select)) {
             cursor.project(select);
         }
-        const sort = this.dialect.sort(entity, q.$sort, q.$populate);
+        const sort = this.dialect.sort(entity, q);
         if (hasKeys(sort)) {
             cursor.sort(sort);
         }
@@ -113,13 +113,13 @@ export class MongodbQuerier extends AbstractQuerier {
     buildVectorPipeline(entity, q, vectorSort, opts) {
         const scoreAlias = vectorSort.vectorSearch.$project;
         return [
-            this.dialect.buildVectorSearchStage(entity, vectorSort.vectorKey, vectorSort.vectorSearch, q.$where, q.$limit ?? 10, opts, q.$candidates),
+            this.dialect.buildVectorSearchStage(entity, vectorSort.vectorKey, vectorSort.vectorSearch, q.$where, q.$limit ?? 10, opts, vectorCandidates(q)),
             // The score becomes a real field before anything reads it, so the lookups and the projection
             // that follow treat it like any other - and a query with no projection keeps its own columns.
             ...(scoreAlias ? [{ $addFields: { [scoreAlias]: { $meta: 'vectorSearchScore' } } }] : []),
             // `$vectorSearch` has already applied `$limit`, so the pager is its own.
             ...this.dialect.readStages(entity, q, {
-                sort: this.dialect.sort(entity, vectorSort.regularSort, q.$populate),
+                sort: this.dialect.sort(entity, { ...q, $sort: vectorSort.regularSort }),
                 project: scoreAlias ? { [scoreAlias]: 1 } : undefined,
             }),
         ];
@@ -189,7 +189,6 @@ export class MongodbQuerier extends AbstractQuerier {
         return this.timed('internalUpdateMany', undefined, async () => {
             const persistable = this.dialect.getPersistable(getMeta(entity), payload, 'onUpdate');
             const filter = this.dialect.where(entity, qm.$where, opts);
-            // Maps JSON operators ($set/$unset/$push/$pull) onto their native MongoDB equivalents.
             const update = this.dialect.getUpdateFilter(persistable);
             const { matchedCount } = await this.execute((session) => this.collection(entity).updateMany(filter, update, { session }));
             return matchedCount;

package/dist/mssql/mssqlDialect.js

@@ -25,6 +25,7 @@ const MSSQL_FEATURES = {
     commentSyntax: 'none',
     vectorIndexRequiresNotNull: false,
     vectorSupportsLength: true,
+    vectorBytes: false,
     supportsTimestamptz: false,
     stringSizing: 'varchar',
     supportsUnsigned: false,

package/dist/schema/canonicalType.js

@@ -80,6 +80,7 @@ const SQL_TO_CANONICAL = {
     image: { category: 'blob', size: 'big' },
     // === Vector (for AI/embeddings) ===
     vector: { category: 'vector' },
+    f32_blob: { category: 'vector' },
     halfvec: { category: 'halfvec' },
     sparsevec: { category: 'sparsevec' },
 };
@@ -204,8 +205,8 @@ const ENGINE_TYPES = {
         sizes: MYSQL_SIZES,
         decimal: { precision: 10, scale: 2 },
     },
-    // SQLite uses affinity, so no size variants.
-    sqlite: { scalars: withVectorType(SQLITE_SCALAR_MAP, 'TEXT') },
+    // SQLite uses affinity, so no size variants. `F32_BLOB` is libSQL's vector type; elsewhere just a name of BLOB affinity.
+    sqlite: { scalars: withVectorType(SQLITE_SCALAR_MAP, 'F32_BLOB') },
     // 2025 and up; below that the server refuses the type rather than storing it as text.
     mssql: { scalars: withVectorType(MSSQL_SCALAR_MAP, 'VECTOR'), sizes: MSSQL_SIZES },
     mongodb: { scalars: withVectorType(MONGO_SCALAR_MAP, 'array') },
@@ -238,7 +239,7 @@ export function sqlToCanonical(sqlType) {
     const unsigned = normalized.includes('unsigned');
     const withoutUnsigned = normalized.replace(/\s*unsigned\s*/i, ' ').trim();
     // Extract base type and parameters: "VARCHAR(255)" -> ["varchar", "255"]
-    const match = withoutUnsigned.match(/^([a-z][a-z0-9 ]*?)(?:\(([^)]+)\))?$/);
+    const match = withoutUnsigned.match(/^([a-z][a-z0-9_ ]*?)(?:\(([^)]+)\))?$/);
     const base = match ? SQL_TO_CANONICAL[match[1]] : undefined;
     if (!match || !base) {
         return { category: 'string', raw: sqlType };
@@ -332,8 +333,13 @@ export function canonicalToTypeScript(type) {
  * the engine settles an unstated bound. Migrations and drift both compare through it.
  */
 export function engineType(dialect) {
-    return (type) => sqlToCanonical(canonicalToSql(type, dialect));
+    return (type) => {
+        const stored = sqlToCanonical(canonicalToSql(type, dialect));
+        // SQLite keeps a vector in any column, so one created as `TEXT` before vectors were blobs stays as it is.
+        return dialect.dialectName === 'sqlite' && isVectorCategory(stored.category) ? SQLITE_TEXT : stored;
+    };
 }
+const SQLITE_TEXT = { category: 'string', size: 'small' };
 /**
  * Convert UQL FieldOptions to a canonical type.
  */

package/dist/schema/indexDifferences.d.ts

@@ -1,6 +1,9 @@
 import type { IndexNode } from './types.js';
-/** What an introspector reports about an index, and so all a diff may compare; apart from `IndexFeature`, what an engine emits. */
-export type IndexFacet = 'order' | 'nulls' | 'opsClass' | 'accessMethod' | 'include';
+/**
+ * What an introspector reports about an index, and so all a diff may compare; apart from `IndexFeature`, what an engine emits.
+ * `vector` is whether it is a vector index at all, for an engine with one vector index whatever type declared it.
+ */
+export type IndexFacet = 'order' | 'nulls' | 'opsClass' | 'accessMethod' | 'include' | 'vector';
 /**
  * Whether the table has this index already, by shape rather than name, uniqueness included. An index
  * over an expression, whose text the engine reprints, falls back to its name.

package/dist/schema/indexDifferences.js

@@ -1,3 +1,4 @@
+import { isVectorIndexType } from '../type/vector.js';
 /**
  * Whether the table has this index already, by shape rather than name, uniqueness included. An index
  * over an expression, whose text the engine reprints, falls back to its name.
@@ -45,6 +46,10 @@ export function describeIndexDifferences(source, target, facets) {
     if (facets.has('accessMethod') && (source.type ?? 'btree') !== (target.type ?? 'btree')) {
         differences.push(`type: ${target.type ?? 'btree'} -> ${source.type ?? 'btree'}`);
     }
+    if (facets.has('vector') && isVectorIndexType(source.type) !== isVectorIndexType(target.type)) {
+        const [expected, actual] = [source, target].map((index) => (isVectorIndexType(index.type) ? 'yes' : 'no'));
+        differences.push(`vector index: ${actual} -> ${expected}`);
+    }
     if (facets.has('include')) {
         // Order carries no meaning in an `INCLUDE` list, so it is compared as a set.
         const [sourceInclude, targetInclude] = [source.include ?? [], target.include ?? []].map((columns) => [...columns].sort().join(', '));

package/dist/schema/schemaASTBuilder.js

@@ -1,5 +1,5 @@
 import { fieldOf, foreignKeysOf, getMeta, soleIdOf } from '../entity/metadata/definition.js';
-import { declaredIndexes, indexNameParts, renderIndexColumn } from '../util/ddlExpression.util.js';
+import { declaredIndexes, declaredIndexName, renderIndexColumn } from '../util/ddlExpression.util.js';
 import { isInlinedExpression } from '../util/field.util.js';
 import { isSoleIdField } from '../util/field.util.js';
 import { isAutoIncrement } from '../util/field.util.js';
@@ -198,7 +198,7 @@ function addCompositeIndex(ctx, table, meta, idxMeta) {
     });
     if (!resolved.length)
         return;
-    const name = idxMeta.name ?? derivedIndexName(table.name, indexNameParts(resolved));
+    const name = declaredIndexName(idxMeta.name, table.name, resolved);
     ctx.ast.addIndex({
         name,
         table,
@@ -211,5 +211,6 @@ function addCompositeIndex(ctx, table, meta, idxMeta) {
         m: idxMeta.m,
         efConstruction: idxMeta.efConstruction,
         lists: idxMeta.lists,
+        config: idxMeta.config,
     });
 }

package/dist/sqlite/localSqliteQuerierPool.d.ts

@@ -1,7 +1,6 @@
 import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandleQuerierPool.js';
-import type { ExtraOptions } from '../type/index.js';
-import { SqliteDialect } from './sqliteDialect.js';
-import { type SqlitePreparedStatement, SqliteQuerier } from './sqliteQuerier.js';
+import type { SqliteDialect } from './sqliteDialect.js';
+import { type SqliteDatabase, type SqlitePreparedStatement, SqliteQuerier } from './sqliteQuerier.js';
 /** What every local SQLite pool accepts on top of its driver's own options. */
 export type LocalSqlitePoolOptions = {
     /**
@@ -27,12 +26,12 @@ export type LocalSqliteDatabase = {
 export declare function adaptSqlite<S extends Omit<SqlitePreparedStatement, 'reader'>>(db: Omit<LocalSqliteDatabase, 'prepare'> & {
     prepare(sql: string): S;
 }, reads: (stmt: S) => boolean): LocalSqliteDatabase;
-/** A pool for a SQLite file opened in this process, configured the same way whichever driver's {@link createDb} opens it. */
-export declare abstract class AbstractLocalSqliteQuerierPool<O extends LocalSqlitePoolOptions> extends AbstractSharedHandleQuerierPool<LocalSqliteDatabase, SqliteQuerier, SqliteDialect> {
-    readonly opts?: O | undefined;
-    constructor(opts?: O | undefined, extra?: ExtraOptions);
-    /** Opens the driver's database, and nothing more: the caller configures it. */
-    protected abstract createDb(): Promise<LocalSqliteDatabase>;
-    protected openDb(): Promise<LocalSqliteDatabase>;
-    protected buildQuerier(db: LocalSqliteDatabase): SqliteQuerier;
+/** `db` with each loadable extension installed, which `node:sqlite` refuses unless opened to allow them. */
+export declare function loadExtensions(db: LocalSqliteDatabase, extensions?: readonly string[]): LocalSqliteDatabase;
+/** A pool for a database file opened in this process, configured the same way whichever driver's {@link createDb} opens it. */
+export declare abstract class AbstractLocalSqliteQuerierPool<DB extends SqliteDatabase, D extends SqliteDialect> extends AbstractSharedHandleQuerierPool<DB, SqliteQuerier, D> {
+    /** Opens the driver's database, reading integers as `bigint`, which the querier decodes exactly past 2^53. */
+    protected abstract createDb(): Promise<DB>;
+    protected openDb(): Promise<DB>;
+    protected buildQuerier(db: DB): SqliteQuerier;
 }

package/dist/sqlite/localSqliteQuerierPool.js

@@ -1,6 +1,4 @@
-import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
 import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandleQuerierPool.js';
-import { SqliteDialect } from './sqliteDialect.js';
 import { applySqlitePragmas } from './sqlitePragmas.js';
 import { SqliteQuerier } from './sqliteQuerier.js';
 /**
@@ -22,19 +20,18 @@ export function adaptSqlite(db, reads) {
         close: () => db.close(),
     };
 }
-/** A pool for a SQLite file opened in this process, configured the same way whichever driver's {@link createDb} opens it. */
-export class AbstractLocalSqliteQuerierPool extends AbstractSharedHandleQuerierPool {
-    opts;
-    constructor(opts, extra) {
-        super(new SqliteDialect(dialectOptionsFrom(extra)), extra);
-        this.opts = opts;
+/** `db` with each loadable extension installed, which `node:sqlite` refuses unless opened to allow them. */
+export function loadExtensions(db, extensions = []) {
+    for (const extension of extensions) {
+        db.loadExtension(extension);
     }
+    return db;
+}
+/** A pool for a database file opened in this process, configured the same way whichever driver's {@link createDb} opens it. */
+export class AbstractLocalSqliteQuerierPool extends AbstractSharedHandleQuerierPool {
     async openDb() {
         const db = await this.createDb();
         await applySqlitePragmas(db);
-        for (const extension of this.opts?.extensions ?? []) {
-            db.loadExtension(extension);
-        }
         return db;
     }
     buildQuerier(db) {

package/dist/sqlite/nodeSqliteQuerierPool.d.ts

@@ -1,5 +1,6 @@
 import type { ExtraOptions } from '../type/index.js';
 import { AbstractLocalSqliteQuerierPool, type LocalSqliteDatabase, type LocalSqlitePoolOptions } from './localSqliteQuerierPool.js';
+import { SqliteDialect } from './sqliteDialect.js';
 /**
  * The `DatabaseSync` options worth surfacing, plus the loadable extensions to install. Declared here
  * rather than imported from `node:sqlite` so this module needs no ambient Node types; unknown keys
@@ -15,8 +16,9 @@ export type NodeSqlitePoolOptions = LocalSqlitePoolOptions & {
  * A pool over Node's built-in `node:sqlite`, needing no dependency at all. {@link Sqlite3QuerierPool} is the
  * faster choice for read-heavy work, and the one on Bun.
  */
-export declare class NodeSqliteQuerierPool extends AbstractLocalSqliteQuerierPool<NodeSqlitePoolOptions> {
+export declare class NodeSqliteQuerierPool extends AbstractLocalSqliteQuerierPool<LocalSqliteDatabase, SqliteDialect> {
     readonly filename: string;
-    constructor(filename?: string, opts?: NodeSqlitePoolOptions, extra?: ExtraOptions);
+    readonly opts?: NodeSqlitePoolOptions | undefined;
+    constructor(filename?: string, opts?: NodeSqlitePoolOptions | undefined, extra?: ExtraOptions);
     protected createDb(): Promise<LocalSqliteDatabase>;
 }

package/dist/sqlite/nodeSqliteQuerierPool.js

@@ -1,24 +1,27 @@
-import { AbstractLocalSqliteQuerierPool, adaptSqlite, } from './localSqliteQuerierPool.js';
+import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
+import { AbstractLocalSqliteQuerierPool, adaptSqlite, loadExtensions, } from './localSqliteQuerierPool.js';
+import { SqliteDialect } from './sqliteDialect.js';
 /**
  * A pool over Node's built-in `node:sqlite`, needing no dependency at all. {@link Sqlite3QuerierPool} is the
  * faster choice for read-heavy work, and the one on Bun.
  */
 export class NodeSqliteQuerierPool extends AbstractLocalSqliteQuerierPool {
     filename;
+    opts;
     constructor(filename = ':memory:', opts, extra) {
-        super(opts, extra);
+        super(new SqliteDialect(dialectOptionsFrom(extra)), extra);
         this.filename = filename;
+        this.opts = opts;
     }
     async createDb() {
         const { DatabaseSync } = await import('node:sqlite');
         const { extensions, ...driverOpts } = this.opts ?? {};
         const nodeDb = new DatabaseSync(this.filename, {
             ...driverOpts,
-            // Integers as `bigint`, which the querier decodes exactly past 2^53.
             readBigInts: true,
             // `node:sqlite` refuses `loadExtension` unless the database was opened with this on.
             ...(extensions?.length ? { allowExtension: true } : undefined),
         });
-        return adaptSqlite(nodeDb, (stmt) => stmt.columns().length > 0);
+        return loadExtensions(adaptSqlite(nodeDb, (stmt) => stmt.columns().length > 0), extensions);
     }
 }

package/dist/sqlite/sqliteDialect.d.ts

@@ -1,6 +1,6 @@
 import { AbstractSqlDialect, type DerivedRelation, type HydrateKind, type RelationRows } from '../dialect/abstractSqlDialect.js';
 import { type JsonAccessMode, type JsonSlot } from '../dialect/jsonSql.js';
-import type { EntityMeta, FieldOptions, QueryContext, QueryPager, QueryTextSearchOptions, SqlDialectFeatures, Type, VectorDistance, VectorMetric } from '../type/index.js';
+import { type EntityMeta, type FieldOptions, type Query, type QueryContext, type QueryPager, type QueryTextSearchOptions, type QueryWhere, type SqlDialectFeatures, type Type, type VectorDistance, type VectorMetric } from '../type/index.js';
 /** What SQLite and the engines derived from it have. */
 export declare const SQLITE_FEATURES: SqlDialectFeatures;
 export declare class SqliteDialect extends AbstractSqlDialect {
@@ -24,6 +24,12 @@ export declare class SqliteDialect extends AbstractSqlDialect {
      * their own vector functions instead, so `LibsqlDialect` overrides this.
      */
     readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
+    /**
+     * A read ranked by the metric its field's vector index measures, and paged, narrowed to the rowids of
+     * that index's nearest rows, which libSQL's `vector_top_k` answers: `$candidates` of them, else as many
+     * as the page reaches. Their exact distance still orders them. Unchanged on an engine with no such index.
+     */
+    protected rankedWhere<E>(meta: EntityMeta<E>, q: Query<E>, prefix: string | undefined): QueryWhere<E> | undefined;
     /**
      * SQLite does not support the `DEFAULT` keyword inside `VALUES`. Inline the metadata default
      * when declared, else `NULL` (which is also how SQLite auto-generates INTEGER PRIMARY KEYs).
@@ -51,7 +57,9 @@ export declare class SqliteDialect extends AbstractSqlDialect {
     protected readonly carriedFields: {
         numeric: (expr: string, field: FieldOptions) => string;
         blob: (expr: string) => string;
+        vector: (expr: string) => string;
     };
+    private bytesAsText;
     /** A date reads back as SQLite stored it, a number or text, which JSON carries unchanged. */
     protected hydrateKind(field: FieldOptions | undefined): HydrateKind | undefined;
     /**
@@ -59,6 +67,8 @@ export declare class SqliteDialect extends AbstractSqlDialect {
      * FTS5 virtual table (UQL does not create those; declare it outside your entities).
      */
     protected appendTextSearch<E>(ctx: QueryContext, entity: Type<E>, meta: EntityMeta<E>, search: QueryTextSearchOptions<E>): void;
+    /** FTS5's `BM25` of the match, lower for a better one, so negated to rank as every other engine does. */
+    protected appendTextRank<E>(ctx: QueryContext, meta: EntityMeta<E>): void;
     protected jsonLength(slot: JsonSlot): string;
     /** `JSON_EACH` walks the array at the path itself, each element's `fullkey` naming it from the column. */
     protected jsonElemFrom(slot: JsonSlot, alias: string): string;

package/dist/sqlite/sqliteDialect.js

@@ -1,7 +1,10 @@
 import { AbstractSqlDialect, } from '../dialect/abstractSqlDialect.js';
 import { BYTES_PREFIX } from '../dialect/hydrateColumn.js';
 import { chainedCall, groupsPerCall, jsonSetCall, jsonPath, jsonArraySlotArgs, jsonSlotArgs, jsonRemoveCall, jsonSetTarget, } from '../dialect/jsonSql.js';
-import { textSearchFields } from '../util/dialect.util.js';
+import { QueryRaw, } from '../type/index.js';
+import { indexDistance, isVectorIndexType } from '../type/vector.js';
+import { declaredIndexName } from '../util/ddlExpression.util.js';
+import { findVectorIndex, findVectorSort, textSearchFields, vectorCandidates } from '../util/dialect.util.js';
 import { columnFamily, isIntegerColumn } from '../util/field.util.js';
 /** What SQLite and the engines derived from it have. */
 export const SQLITE_FEATURES = {
@@ -14,7 +17,8 @@ export const SQLITE_FEATURES = {
     generatedColumnAdd: false, // accepted in a CREATE TABLE, rejected in an ALTER
     commentSyntax: 'none',
     vectorIndexRequiresNotNull: false,
-    vectorSupportsLength: false,
+    vectorSupportsLength: true,
+    vectorBytes: true,
     supportsTimestamptz: false,
     stringSizing: 'text',
     supportsUnsigned: false,
@@ -55,6 +59,37 @@ export class SqliteDialect extends AbstractSqlDialect {
         ['l2', { fn: 'vec_distance_L2' }],
         ['l1', { fn: 'vec_distance_L1' }],
     ]);
+    /**
+     * A read ranked by the metric its field's vector index measures, and paged, narrowed to the rowids of
+     * that index's nearest rows, which libSQL's `vector_top_k` answers: `$candidates` of them, else as many
+     * as the page reaches. Their exact distance still orders them. Unchanged on an engine with no such index.
+     */
+    rankedWhere(meta, q, prefix) {
+        const ranked = findVectorSort(q.$sort);
+        const k = vectorCandidates(q) ?? (q.$limit === undefined ? undefined : (q.$skip ?? 0) + q.$limit);
+        const index = ranked && findVectorIndex(meta, ranked.key);
+        if (!ranked || !index || !isVectorIndexType(index.type) || k === undefined) {
+            return q.$where;
+        }
+        const { colName, distance, field } = this.resolveVectorDistance(meta, ranked.key, ranked.search);
+        if (indexDistance(index) !== distance || !this.vectorMetrics.get(distance)?.index) {
+            return q.$where;
+        }
+        const name = declaredIndexName(index.name, this.resolveTableName(meta), [{ column: colName }]);
+        const table = this.escapeId(prefix ?? this.resolveTableAlias(meta), true, true);
+        const nearest = new QueryRaw(({ ctx }) => {
+            ctx.append(`${table}rowid IN (SELECT id FROM vector_top_k(`);
+            ctx.addValue(name);
+            ctx.append(', ');
+            this.appendVectorValue(ctx, ranked.search.$vector, field);
+            ctx.append(', ');
+            ctx.addValue(k);
+            ctx.append('))');
+        });
+        const where = {};
+        where.$and = q.$where ? [q.$where, nearest] : [nearest];
+        return where;
+    }
     /**
      * SQLite does not support the `DEFAULT` keyword inside `VALUES`. Inline the metadata default
      * when declared, else `NULL` (which is also how SQLite auto-generates INTEGER PRIMARY KEYs).
@@ -109,8 +144,12 @@ export class SqliteDialect extends AbstractSqlDialect {
      */
     carriedFields = {
         numeric: (expr, field) => (isIntegerColumn(field) ? `CAST(${expr} AS TEXT)` : expr),
-        blob: (expr) => `${this.escape(BYTES_PREFIX)} || hex(${expr})`,
+        blob: (expr) => this.bytesAsText(expr),
+        vector: (expr) => `CASE WHEN typeof(${expr}) = 'blob' THEN ${this.bytesAsText(expr)} ELSE ${expr} END`,
     };
+    bytesAsText(expr) {
+        return `${this.escape(BYTES_PREFIX)} || hex(${expr})`;
+    }
     /** A date reads back as SQLite stored it, a number or text, which JSON carries unchanged. */
     hydrateKind(field) {
         return columnFamily(field?.type) === 'date' ? undefined : super.hydrateKind(field);
@@ -124,6 +163,10 @@ export class SqliteDialect extends AbstractSqlDialect {
         ctx.append(`${this.escapedTableName(meta)} MATCH {${columns.join(' ')}} : `);
         ctx.addValue(search.$value);
     }
+    /** FTS5's `BM25` of the match, lower for a better one, so negated to rank as every other engine does. */
+    appendTextRank(ctx, meta) {
+        ctx.append(`-BM25(${this.escapedTableName(meta)})`);
+    }
     jsonLength(slot) {
         return `JSON_ARRAY_LENGTH(${jsonArraySlotArgs(slot, this.jsonIsArray(slot))})`;
     }

package/dist/sqlite/sqliteQuerierPool.d.ts

@@ -1,19 +1,20 @@
 import type { Options } from 'better-sqlite3';
 import type { ExtraOptions } from '../type/index.js';
 import { AbstractLocalSqliteQuerierPool, type LocalSqliteDatabase, type LocalSqlitePoolOptions } from './localSqliteQuerierPool.js';
+import { SqliteDialect } from './sqliteDialect.js';
 /** Driver options, plus the loadable extensions to install on the connection. */
 export type Sqlite3PoolOptions = Options & LocalSqlitePoolOptions;
 /**
  * Pool for `better-sqlite3`, or `bun:sqlite` when running under Bun - the same file, through whichever
  * driver the runtime provides.
  */
-export declare class Sqlite3QuerierPool extends AbstractLocalSqliteQuerierPool<Sqlite3PoolOptions> {
+export declare class Sqlite3QuerierPool extends AbstractLocalSqliteQuerierPool<LocalSqliteDatabase, SqliteDialect> {
     readonly filename: string | Buffer;
-    constructor(filename?: string | Buffer, opts?: Sqlite3PoolOptions, extra?: ExtraOptions);
+    readonly opts?: Sqlite3PoolOptions | undefined;
+    constructor(filename?: string | Buffer, opts?: Sqlite3PoolOptions | undefined, extra?: ExtraOptions);
     /**
-     * Both drivers read integers as `bigint`, which the querier decodes exactly past 2^53. `bun:sqlite`
-     * rejects option keys it does not know, so `extensions` is stripped out, and opens only a path, so a
-     * serialized database - which better-sqlite3 takes as its filename - is deserialized there instead.
+     * `bun:sqlite` rejects option keys it does not know, so `extensions` is stripped out, and opens only a
+     * path, so a serialized database - which better-sqlite3 takes as its filename - is deserialized there instead.
      */
     protected createDb(): Promise<LocalSqliteDatabase>;
 }

package/dist/sqlite/sqliteQuerierPool.js

@@ -1,18 +1,21 @@
-import { AbstractLocalSqliteQuerierPool, adaptSqlite, } from './localSqliteQuerierPool.js';
+import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
+import { AbstractLocalSqliteQuerierPool, adaptSqlite, loadExtensions, } from './localSqliteQuerierPool.js';
+import { SqliteDialect } from './sqliteDialect.js';
 /**
  * Pool for `better-sqlite3`, or `bun:sqlite` when running under Bun - the same file, through whichever
  * driver the runtime provides.
  */
 export class Sqlite3QuerierPool extends AbstractLocalSqliteQuerierPool {
     filename;
+    opts;
     constructor(filename = ':memory:', opts, extra) {
-        super(opts, extra);
+        super(new SqliteDialect(dialectOptionsFrom(extra)), extra);
         this.filename = filename;
+        this.opts = opts;
     }
     /**
-     * Both drivers read integers as `bigint`, which the querier decodes exactly past 2^53. `bun:sqlite`
-     * rejects option keys it does not know, so `extensions` is stripped out, and opens only a path, so a
-     * serialized database - which better-sqlite3 takes as its filename - is deserialized there instead.
+     * `bun:sqlite` rejects option keys it does not know, so `extensions` is stripped out, and opens only a
+     * path, so a serialized database - which better-sqlite3 takes as its filename - is deserialized there instead.
      */
     async createDb() {
         const { extensions, ...driverOpts } = this.opts ?? {};
@@ -22,9 +25,9 @@ export class Sqlite3QuerierPool extends AbstractLocalSqliteQuerierPool {
             const bunDb = typeof this.filename === 'string'
                 ? new Database(this.filename, bunOpts)
                 : Database.deserialize(this.filename, bunOpts);
-            return adaptSqlite(bunDb, (stmt) => stmt.columnNames.length > 0);
+            return loadExtensions(adaptSqlite(bunDb, (stmt) => stmt.columnNames.length > 0), extensions);
         }
         const { default: BetterSqlite3 } = await import('better-sqlite3');
-        return new BetterSqlite3(this.filename, driverOpts).defaultSafeIntegers(true);
+        return loadExtensions(new BetterSqlite3(this.filename, driverOpts).defaultSafeIntegers(true), extensions);
     }
 }

package/dist/turso/tursoLocalDialect.d.ts

@@ -2,7 +2,7 @@ import type { VectorDistance, VectorMetric } from '../type/index.js';
 import { TursoDialect } from './tursoDialect.js';
 /**
  * SQLite Dialect specialization for the embedded Turso engine, the Rust engine alone: it adds a
- * dot-product distance to libSQL's cosine and L2, and caps no function call.
+ * dot-product distance to libSQL's cosine and L2, caps no function call, and has no vector index.
  */
 export declare class TursoLocalDialect extends TursoDialect {
     readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;