uql-orm 0.70.0 → 0.71.0

package/dist/migrate/introspection/sqliteIntrospector.js

@@ -4,12 +4,17 @@ import { AbstractSqlSchemaIntrospector } from './abstractSqlSchemaIntrospector.j
  * SQLite schema introspector
  */
 export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
+    /** Whether an index is libSQL's vector index, where the engine has one; elsewhere a declared one is built plain. */
+    indexFacets = new Set(this.dialect.hasVectorIndex() ? ['vector'] : []);
+    /** Not SQLite's own tables, nor the ones libSQL keeps a vector index in: its metadata and `<index>_shadow`. */
     getTableNamesQuery() {
         return /*sql*/ `
       SELECT name
       FROM sqlite_master
       WHERE type = 'table'
         AND name NOT LIKE 'sqlite_%'
+        AND name <> 'libsql_vector_meta_shadow'
+        AND name NOT IN (SELECT name || '_shadow' FROM sqlite_master WHERE type = 'index')
       ORDER BY name
     `;
     }
@@ -85,15 +90,24 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
             const isCompositeUnique = index.origin === 'u' && columns.length > 1;
             // `PRAGMA index_info` names an expression entry `null` (its `cid` is -2), and the expression text
             // lives only in `sqlite_master.sql`. Reporting `{ column: null }` put a column literally named
-            // `null` into the diff, so an index UQL cannot describe is left out entirely instead.
+            // `null` into the diff, so an index UQL cannot describe is left out, libSQL's vector index aside.
             const named = columns.filter((column) => column.name !== null);
-            if (named.length === columns.length && (isUserCreated || isCompositeUnique)) {
+            if (!isUserCreated && !isCompositeUnique) {
+                continue;
+            }
+            if (named.length === columns.length) {
                 indexSchemas.push({
                     name: index.name,
                     entries: named.map((column) => ({ column: column.name })),
                     unique: Boolean(index.unique),
                 });
             }
+            else {
+                const vectorIndex = await this.getVectorIndex(read, index.name);
+                if (vectorIndex) {
+                    indexSchemas.push(vectorIndex);
+                }
+            }
         }
         return indexSchemas;
     }
@@ -143,12 +157,24 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         }
         return uniqueColumns;
     }
+    /** libSQL's `libsql_vector_idx(col, 'metric=...')`, read back from the statement that created it. */
+    async getVectorIndex(read, indexName) {
+        const [row] = await read(
+        /*sql*/ `SELECT sql FROM sqlite_master WHERE type = 'index' AND name = ?`, [indexName]);
+        const column = row?.sql?.match(/libsql_vector_idx\s*\(\s*[`"[]?([^`"\],\s)]+)/i)?.[1];
+        if (!column) {
+            return undefined;
+        }
+        const metric = row.sql?.match(/'metric=(\w+)'/i)?.[1]?.toLowerCase();
+        const distances = new Map([...this.dialect.vectorMetrics].map(([distance, { index }]) => [index, distance]));
+        return { name: indexName, entries: [{ column }], unique: false, type: 'vector', distance: distances.get(metric) };
+    }
     getIndexColumns(read, indexName) {
         return read(/*sql*/ `PRAGMA index_info(${this.escapeId(indexName)})`);
     }
     normalizeType(type) {
         // Extract base type without length/precision
-        const match = type.match(/^([A-Za-z]+)/);
+        const match = type.match(/^([A-Za-z][A-Za-z0-9_]*)/);
         return match ? match[1].toUpperCase() : type.toUpperCase();
     }
     extractLength(type) {

package/dist/mongo/mongoDialect.d.ts

@@ -275,6 +275,8 @@ export declare class MongoDialect extends AbstractDialect {
      * Returns `undefined` if no vector sort is present.
      */
     extractVectorSort<E extends Document>(sort: QuerySortMap<E> | undefined): ExtractedVectorSort<E> | undefined;
+    /** The Atlas index a `$vectorSearch` over `column` reads, and migrations create: its declared name, else `<column>_index`. */
+    protected vectorSearchIndexName(name: string | undefined, column: string): string;
     /**
      * Build a `$vectorSearch` aggregation pipeline stage.
      * Merges `$where` into `$vectorSearch.filter` for optimal pre-filtering.

package/dist/mongo/mongoDialect.js

@@ -18,6 +18,7 @@ export const mongoDialectFeatures = {
     commentSyntax: 'none',
     vectorIndexRequiresNotNull: false,
     vectorSupportsLength: false,
+    vectorBytes: false,
     supportsTimestamptz: false,
     stringSizing: 'bounded-text',
     supportsUnsigned: false,
@@ -1016,10 +1017,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 +1221,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 +1236,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
@@ -113,7 +113,7 @@ 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' } } }] : []),

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;
     /**

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);

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

package/dist/turso/tursoLocalDialect.js

@@ -1,7 +1,7 @@
 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 class TursoLocalDialect extends TursoDialect {
     vectorMetrics = new Map([

package/dist/turso/tursoLocalQuerierPool.d.ts

@@ -1,15 +1,14 @@
 import type { connect } from '@tursodatabase/database';
-import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandleQuerierPool.js';
-import { type SqliteDatabase, SqliteQuerier } from '../sqlite/sqliteQuerier.js';
+import { AbstractLocalSqliteQuerierPool } from '../sqlite/localSqliteQuerierPool.js';
+import type { SqliteDatabase } from '../sqlite/sqliteQuerier.js';
 import type { ExtraOptions } from '../type/index.js';
 import { TursoLocalDialect } from './tursoLocalDialect.js';
 /** The engine's own options: `readonly`, `timeout`, `encryption`, `experimental` and the rest. */
 export type TursoLocalOptions = NonNullable<Parameters<typeof connect>[1]>;
 /** A pool for the embedded Turso engine, on `uql-orm/turso/local` so its native binaries stay out of edge bundles. */
-export declare class TursoLocalQuerierPool extends AbstractSharedHandleQuerierPool<SqliteDatabase, SqliteQuerier, TursoLocalDialect> {
+export declare class TursoLocalQuerierPool extends AbstractLocalSqliteQuerierPool<SqliteDatabase, TursoLocalDialect> {
     readonly filename: string;
     readonly opts?: TursoLocalOptions | undefined;
     constructor(filename?: string, opts?: TursoLocalOptions | undefined, extra?: ExtraOptions);
-    protected openDb(): Promise<SqliteDatabase>;
-    protected buildQuerier(db: SqliteDatabase): SqliteQuerier;
+    protected createDb(): Promise<SqliteDatabase>;
 }

package/dist/turso/tursoLocalQuerierPool.js

@@ -1,10 +1,8 @@
 import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
-import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandleQuerierPool.js';
-import { applySqlitePragmas } from '../sqlite/sqlitePragmas.js';
-import { SqliteQuerier } from '../sqlite/sqliteQuerier.js';
+import { AbstractLocalSqliteQuerierPool } from '../sqlite/localSqliteQuerierPool.js';
 import { TursoLocalDialect } from './tursoLocalDialect.js';
 /** A pool for the embedded Turso engine, on `uql-orm/turso/local` so its native binaries stay out of edge bundles. */
-export class TursoLocalQuerierPool extends AbstractSharedHandleQuerierPool {
+export class TursoLocalQuerierPool extends AbstractLocalSqliteQuerierPool {
     filename;
     opts;
     constructor(filename = ':memory:', opts, extra) {
@@ -12,15 +10,10 @@ export class TursoLocalQuerierPool extends AbstractSharedHandleQuerierPool {
         this.filename = filename;
         this.opts = opts;
     }
-    async openDb() {
+    async createDb() {
         const { connect } = await import('@tursodatabase/database');
         const db = await connect(this.filename, this.opts);
-        // Integers as `bigint`, which the querier decodes exactly past 2^53.
         db.defaultSafeIntegers(true);
-        await applySqlitePragmas(db);
         return db;
     }
-    buildQuerier(db) {
-        return new SqliteQuerier(db, this.dialect, this.extra);
-    }
 }

package/dist/type/dialect.d.ts

@@ -107,6 +107,11 @@ export interface DialectFeatures {
     readonly vectorIndexRequiresNotNull: boolean;
     /** Whether the dialect requires/allows (n) length constraints on vector types. */
     readonly vectorSupportsLength: boolean;
+    /**
+     * Whether a vector binds as its packed little-endian float32 bytes, which a blob column holds and the
+     * SQLite family and MariaDB read, rather than as `[1,2,3]` text they would reparse per row.
+     */
+    readonly vectorBytes: boolean;
     /** Whether the dialect natively supports the TIMESTAMPTZ alias/type. */
     readonly supportsTimestamptz: boolean;
     /**