uql-orm 0.70.0 → 0.72.0

package/dist/dialect/pgLikeSqlDialect.d.ts

@@ -1,3 +1,4 @@
+import type { IndexType } from '../schema/types.js';
 import { type DriverCapabilities, type EntityMeta, type FieldOptions, type JsonColumnType, type Query, type QueryContext, type QueryTextSearchOptions, type SqlDialectFeatures, type Type, type VectorDistance, type VectorMetric } from '../type/index.js';
 import type { DialectOptions } from './abstractDialect.js';
 import { AbstractSqlDialect, type RelationRows } from './abstractSqlDialect.js';
@@ -45,11 +46,11 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
     readonly maxBindValues: number;
     readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
     /**
-     * The GUC each pgvector index type reads for "how much of the index to explore". They are not the
+     * The setting each vector index type reads for "how much of the index to explore". They are not the
      * same quantity - `ef_search` is a candidate-list size, `probes` a count of lists - which is why
      * `$candidates` is documented in the index's own units rather than as a portable number.
      */
-    private static readonly ANN_SETTINGS;
+    protected readonly annSettings: ReadonlyMap<IndexType, string>;
     /**
      * `SET LOCAL hnsw.ef_search = N`, plus `hnsw.iterative_scan = strict_order` where the query also filters
      * by distance, which would otherwise drop rows the candidate list missed.
@@ -58,11 +59,26 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
     normalizeValue(value: unknown): unknown;
     placeholder(index: number): string;
     /**
-     * `TO_TSVECTOR(...) @@ WEBSEARCH_TO_TSQUERY(...)`. `WEBSEARCH_TO_TSQUERY` takes free-form user input
-     * (quoted phrases, `or`, `-negation`) and never raises a syntax error, unlike `TO_TSQUERY`, which
-     * rejects anything unparseable - including a plain two-word search.
+     * `<document> @@ WEBSEARCH_TO_TSQUERY(...)`, under the `$config` asked for, else that of the fulltext
+     * index over these fields, which the planner serves it from. `WEBSEARCH_TO_TSQUERY` takes free-form
+     * input (quoted phrases, `or`, `-negation`) and never raises a syntax error, unlike `TO_TSQUERY`.
      */
     protected appendTextSearch<E>(ctx: QueryContext, _entity: Type<E>, meta: EntityMeta<E>, search: QueryTextSearchOptions<E>): void;
+    /** `TS_RANK` of the document the predicate matches, against the same search. */
+    protected appendTextRank<E>(ctx: QueryContext, meta: EntityMeta<E>, search: QueryTextSearchOptions<E>): void;
+    /** The document a search reads and the search itself, open for its value. */
+    private textSearchParts;
+    /**
+     * The document, `TO_TSVECTOR('english'::regconfig, COALESCE("a", '') || ' ' || COALESCE("b", ''))`, a
+     * `NULL` column read as empty rather than emptying it all. The config is a literal: an index is built
+     * over one, and a bound one reaches it only where the driver leaves the parameter untyped.
+     */
+    textSearchTarget(columns: readonly string[], config?: string): string;
+    /** A config as the text-search functions' first argument, or nothing, for the server's default. */
+    private textConfigArg;
+    /** How a config literal is typed, and the function reading a search's text: CockroachDB lacks both of these. */
+    protected readonly textConfigCast: string;
+    protected readonly textQueryFn: string;
     protected jsonContains(ctx: QueryContext, slot: JsonSlot, values: readonly unknown[]): string;
     protected jsonLength(slot: JsonSlot): string;
     /** Each element stays `jsonb`, so it is read as any path is: `->` for the value, `->>` for its text. */

package/dist/dialect/pgLikeSqlDialect.js

@@ -1,5 +1,5 @@
 import { QueryRaw, } from '../type/index.js';
-import { hasVectorNear, textSearchFields } from '../util/dialect.util.js';
+import { fulltextConfig, fulltextIndexOver, hasVectorNear, textSearchFields } from '../util/dialect.util.js';
 import { escapeSingleQuotes } from '../util/sqlLiteral.js';
 import { AbstractSqlDialect } from './abstractSqlDialect.js';
 import { JSON_PULL_ALIAS, RELATION_ROW_ALIAS } from './aliases.js';
@@ -13,6 +13,8 @@ export const PG_VECTOR_METRICS = new Map([
     ['inner', { op: '<#>', index: 'ip' }],
     ['l1', { op: '<+>', index: 'l1' }],
 ]);
+/** pgvector's HNSW candidate list, the one setting an iterative scan goes with. */
+const HNSW_EF_SEARCH = 'hnsw.ef_search';
 /** What the Postgres-wire engines have. */
 export const PG_FEATURES = {
     ifNotExists: true,
@@ -25,6 +27,7 @@ export const PG_FEATURES = {
     commentSyntax: 'statement',
     vectorIndexRequiresNotNull: false,
     vectorSupportsLength: true,
+    vectorBytes: false,
     supportsTimestamptz: true,
     stringSizing: 'bounded-text',
     supportsUnsigned: false,
@@ -87,12 +90,12 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
     maxBindValues = 65535;
     vectorMetrics = PG_VECTOR_METRICS;
     /**
-     * The GUC each pgvector index type reads for "how much of the index to explore". They are not the
+     * The setting each vector index type reads for "how much of the index to explore". They are not the
      * same quantity - `ef_search` is a candidate-list size, `probes` a count of lists - which is why
      * `$candidates` is documented in the index's own units rather than as a portable number.
      */
-    static ANN_SETTINGS = new Map([
-        ['hnsw', 'hnsw.ef_search'],
+    annSettings = new Map([
+        ['hnsw', HNSW_EF_SEARCH],
         ['ivfflat', 'ivfflat.probes'],
     ]);
     /**
@@ -101,12 +104,12 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
      */
     vectorTuningStatements(meta, q) {
         const indexType = this.tunedVectorIndex(meta, q)?.type;
-        const setting = indexType ? PgLikeSqlDialect.ANN_SETTINGS.get(indexType) : undefined;
+        const setting = indexType ? this.annSettings.get(indexType) : undefined;
         if (!setting) {
             return [];
         }
         const statements = [`SET LOCAL ${setting} = ${q.$candidates}`];
-        if (indexType === 'hnsw' && hasVectorNear(q.$where)) {
+        if (setting === HNSW_EF_SEARCH && hasVectorNear(q.$where)) {
             statements.push('SET LOCAL hnsw.iterative_scan = strict_order');
         }
         return statements;
@@ -121,20 +124,50 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
         return `$${index}`;
     }
     /**
-     * `TO_TSVECTOR(...) @@ WEBSEARCH_TO_TSQUERY(...)`. `WEBSEARCH_TO_TSQUERY` takes free-form user input
-     * (quoted phrases, `or`, `-negation`) and never raises a syntax error, unlike `TO_TSQUERY`, which
-     * rejects anything unparseable - including a plain two-word search.
+     * `<document> @@ WEBSEARCH_TO_TSQUERY(...)`, under the `$config` asked for, else that of the fulltext
+     * index over these fields, which the planner serves it from. `WEBSEARCH_TO_TSQUERY` takes free-form
+     * input (quoted phrases, `or`, `-negation`) and never raises a syntax error, unlike `TO_TSQUERY`.
      */
     appendTextSearch(ctx, _entity, meta, search) {
-        const fields = textSearchFields(meta, search)
-            .map((key) => this.escapeId(this.resolveColumnName(key, meta.fields[key])))
-            .join(` || ' ' || `);
-        // The config is bound once and its numbered placeholder reused by both calls.
-        const config = search.$config ? `${this.addValue(ctx, search.$config)}::regconfig, ` : '';
-        ctx.append(`TO_TSVECTOR(${config}${fields}) @@ WEBSEARCH_TO_TSQUERY(${config}`);
+        const { document, query } = this.textSearchParts(meta, search);
+        ctx.append(`${document} @@ ${query}`);
         ctx.addValue(search.$value);
         ctx.append(')');
     }
+    /** `TS_RANK` of the document the predicate matches, against the same search. */
+    appendTextRank(ctx, meta, search) {
+        const { document, query } = this.textSearchParts(meta, search);
+        ctx.append(`TS_RANK(${document}, ${query}`);
+        ctx.addValue(search.$value);
+        ctx.append('))');
+    }
+    /** The document a search reads and the search itself, open for its value. */
+    textSearchParts(meta, search) {
+        const keys = textSearchFields(meta, search);
+        const index = fulltextIndexOver(meta, keys);
+        const config = search.$config ?? (index && fulltextConfig(index));
+        const columns = keys.map((key) => this.escapeId(this.resolveColumnName(key, meta.fields[key])));
+        return {
+            document: this.textSearchTarget(columns, config),
+            query: `${this.textQueryFn}(${this.textConfigArg(config)}`,
+        };
+    }
+    /**
+     * The document, `TO_TSVECTOR('english'::regconfig, COALESCE("a", '') || ' ' || COALESCE("b", ''))`, a
+     * `NULL` column read as empty rather than emptying it all. The config is a literal: an index is built
+     * over one, and a bound one reaches it only where the driver leaves the parameter untyped.
+     */
+    textSearchTarget(columns, config) {
+        const document = columns.map((column) => `COALESCE(${column}, '')`).join(` || ' ' || `);
+        return `TO_TSVECTOR(${this.textConfigArg(config)}${document})`;
+    }
+    /** A config as the text-search functions' first argument, or nothing, for the server's default. */
+    textConfigArg(config) {
+        return config === undefined ? '' : `${this.escape(config)}${this.textConfigCast}, `;
+    }
+    /** How a config literal is typed, and the function reading a search's text: CockroachDB lacks both of these. */
+    textConfigCast = '::regconfig';
+    textQueryFn = 'WEBSEARCH_TO_TSQUERY';
     jsonContains(ctx, slot, values) {
         return `${this.jsonValue(slot)} @> ${this.jsonVal(ctx, values)}`;
     }

package/dist/dialect/queryJoins.d.ts

@@ -1,4 +1,4 @@
-import type { EntityMeta, Query, QueryGroupMap, QuerySortMap, RelationMeta, RelationQuery, Type } from '../type/index.js';
+import type { EntityMeta, Query, QueryGroupMap, QuerySortMap, QueryWhere, RelationMeta, RelationQuery, Type } from '../type/index.js';
 /**
  * One relation a statement joins, keyed by the alias its columns are addressed by (`tax`,
  * `tax.category`). `projected` tells a `$populate` join, whose columns are selected, from one only
@@ -32,15 +32,25 @@ export type QuerySortOptions = {
     /** Alias the queried entity's own columns are qualified by, when the statement qualifies them. */
     readonly prefix?: string;
     readonly joins?: QueryJoins;
-    readonly distinct?: boolean;
 };
 /**
  * What the statement joins, from `$populate` and from a `$sort` by a to-one relation's field, so the
  * columns, the `ORDER BY` and the lock agree. `claimAlias` names each join's table, parents first.
  */
 export declare function resolveQueryJoins<E>(meta: EntityMeta<E>, q: Query<E>, claimAlias?: (path: string) => string): QueryJoins;
-/** What an aggregate joins: each to-one relation a `$group` path passes through. */
-export declare function resolveGroupJoins<E>(meta: EntityMeta<E>, group: QueryGroupMap<E> | undefined, claimAlias?: (path: string) => string): QueryJoins;
+/**
+ * What an aggregate joins, and the `$where` left to it. Each to-one relation a `$group` path passes through
+ * is an `INNER` join, since a group of a path names a related row; a filter on one of them, keyed at the top
+ * of the `$where` where an `AND` joins it, moves into that join rather than reading its table again. Under a
+ * `$not` it could not: the join would drop the rows the negation keeps.
+ */
+export declare function resolveGroupJoins<E>(meta: EntityMeta<E>, q: {
+    readonly $group?: QueryGroupMap<E>;
+    readonly $where?: QueryWhere<E>;
+}, claimAlias?: (path: string) => string): {
+    readonly joins: QueryJoins;
+    readonly where: QueryWhere<E> | undefined;
+};
 /** The field a grouped `path` reads, and the join it reads it through: none for the entity's own. */
 export declare function groupPathField(joins: QueryJoins, path: readonly string[]): {
     readonly key: string;

package/dist/dialect/queryJoins.js

@@ -1,5 +1,5 @@
 import { getMeta, relationOf } from '../entity/index.js';
-import { getKeys, getRelationRequestSummary, isRecord, isToManyRelation, parseRelationAtKey } from '../util/index.js';
+import { getKeys, getRelationRequestSummary, isRecord, isToManyRelation, parseRelationAtKey, parseRelationSize, } from '../util/index.js';
 export const NO_JOINS = new Map();
 /**
  * What the statement joins, from `$populate` and from a `$sort` by a to-one relation's field, so the
@@ -11,18 +11,35 @@ export function resolveQueryJoins(meta, q, claimAlias = (path) => path) {
     }
     const joins = new Map();
     addPopulateJoins(joins, claimAlias, meta, q.$populate);
-    addPathJoins(joins, claimAlias, meta, q.$sort);
+    addPathJoins(joins, claimAlias, meta, q.$sort, false);
     return joins;
 }
-/** What an aggregate joins: each to-one relation a `$group` path passes through. */
-export function resolveGroupJoins(meta, group, claimAlias = (path) => path) {
+/**
+ * What an aggregate joins, and the `$where` left to it. Each to-one relation a `$group` path passes through
+ * is an `INNER` join, since a group of a path names a related row; a filter on one of them, keyed at the top
+ * of the `$where` where an `AND` joins it, moves into that join rather than reading its table again. Under a
+ * `$not` it could not: the join would drop the rows the negation keeps.
+ */
+export function resolveGroupJoins(meta, q, claimAlias = (path) => path) {
     const joins = new Map();
-    for (const ref of Object.values(group ?? {})) {
+    for (const ref of Object.values(q.$group ?? {})) {
         if (isRecord(ref)) {
-            addPathJoins(joins, claimAlias, meta, ref);
+            addPathJoins(joins, claimAlias, meta, ref, true);
         }
     }
-    return joins;
+    if (!q.$where) {
+        return { joins, where: q.$where };
+    }
+    const where = { ...q.$where };
+    for (const key of getKeys(q.$where)) {
+        const join = joins.get(key);
+        const filter = q.$where[key];
+        if (join && isRecord(filter) && parseRelationSize(filter) === undefined) {
+            joins.set(key, { ...join, query: { $where: filter } });
+            delete where[key];
+        }
+    }
+    return { joins, where };
 }
 /** The field a grouped `path` reads, and the join it reads it through: none for the entity's own. */
 export function groupPathField(joins, path) {
@@ -93,8 +110,11 @@ function addPopulateJoins(joins, claimAlias, meta, populate, parent) {
         addPopulateJoins(joins, claimAlias, join.meta, query.$populate, join);
     }
 }
-/** The to-one relations a nested map of fields passes through, a `$sort` or a `$group` path, as joins adding no columns. */
-function addPathJoins(joins, claimAlias, meta, map, parent) {
+/**
+ * The to-one relations a nested map of fields passes through, a `$sort` or a `$group` path, as joins adding
+ * no columns: `required` where the path names a related row, as a group's does, and a sort's does not.
+ */
+function addPathJoins(joins, claimAlias, meta, map, required, parent) {
     if (!map) {
         return;
     }
@@ -106,9 +126,9 @@ function addPathJoins(joins, claimAlias, meta, map, parent) {
         if (!relation || isToManyRelation(relation) || !isSortMap(value)) {
             continue;
         }
-        const join = addJoin(joins, claimAlias, parent, key, relation, {}, false, false);
+        const join = addJoin(joins, claimAlias, parent, key, relation, {}, required, false);
         // `E` stated: inferred from the nested map, it lands on the nested relation's target.
-        addPathJoins(joins, claimAlias, join.meta, value, join);
+        addPathJoins(joins, claimAlias, join.meta, value, required, join);
     }
 }
 /** The join a sort may address at `path` with the relation's own sort map, or why it may not; `unjoinable` is the dialect's remedy. */

package/dist/dialect/vectorCast.d.ts

@@ -20,5 +20,7 @@ export declare function toSparsevecLiteral(values: readonly unknown[]): string;
  * as it was written, `{1:1,3:2}/3` or `[1,2,3]`; `undefined` where the text matches neither.
  */
 export declare function parseVectorLiteral(raw: string, cast: VectorCast): number[] | undefined;
+/** The packed little-endian float32s a blob vector column holds, and {@link decodeFloat32s} reads back. */
+export declare function encodeFloat32s(values: readonly unknown[]): Uint8Array;
 /** Packed little-endian float32s, each read as {@link shortestFloat32}. */
 export declare function decodeFloat32s(bytes: Uint8Array): number[];

package/dist/dialect/vectorCast.js

@@ -62,6 +62,13 @@ function parseDense(text) {
         return undefined;
     }
 }
+/** The packed little-endian float32s a blob vector column holds, and {@link decodeFloat32s} reads back. */
+export function encodeFloat32s(values) {
+    const bytes = new Uint8Array(values.length * 4);
+    const view = new DataView(bytes.buffer);
+    values.forEach((value, at) => view.setFloat32(at * 4, Number(value), true));
+    return bytes;
+}
 /** Packed little-endian float32s, each read as {@link shortestFloat32}. */
 export function decodeFloat32s(bytes) {
     const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);

package/dist/dialect/vectorSqlDialect.d.ts

@@ -1,6 +1,6 @@
-import type { EntityIndexMeta, EntityMeta, FieldOptions, Query, QueryContext, QueryVectorSearch, SqlDialectFeatures, VectorDistance, VectorMetric } from '../type/index.js';
+import type { EntityIndexMeta, EntityMeta, FieldOptions, Query, QueryContext, QueryVectorSearch, QueryWhere, SqlDialectFeatures, VectorDistance, VectorMetric } from '../type/index.js';
 import { AbstractDialect } from './abstractDialect.js';
-import type { VectorCast } from './vectorCast.js';
+import { type VectorCast } from './vectorCast.js';
 /**
  * Vector search for the SQL dialects: the distance a `$sort` ranks by and projects, and the ANN tuning.
  * Each dialect lists its metrics in {@link vectorMetrics}, an operator or a function; empty means no search.
@@ -20,12 +20,16 @@ export declare abstract class VectorSqlDialect extends AbstractDialect {
      * spelled into a `SET` rather than bound, and `/http` input is untyped.
      */
     protected tunedVectorIndex<E>(meta: EntityMeta<E>, q: Query<E>): EntityIndexMeta | undefined;
+    /** The `$where` a read runs: the query's own, which an engine reading its vector index as a table narrows. */
+    protected rankedWhere<E>(_meta: EntityMeta<E>, q: Query<E>, _prefix: string | undefined): QueryWhere<E> | undefined;
     /**
      * Every distance metric this dialect has, and how a search and an index spell each. Empty means no
      * vector search at all, which is what MySQL and D1 are. The key set is the single answer to "is this
      * metric supported here", for a query and an index alike.
      */
     readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
+    /** Whether this engine has a vector index: the one a metric's `index` names. */
+    hasVectorIndex(): boolean;
     /** Quotes an identifier; supplied by the SQL dialect built on top of this layer. */
     abstract escapeId(val: string | undefined, forbidQualified?: boolean, addDot?: boolean): string;
     /**
@@ -39,7 +43,7 @@ export declare abstract class VectorSqlDialect extends AbstractDialect {
     };
     /**
      * Binds a vector, both as a persisted value and as the query vector of a distance expression, so a
-     * dialect needing a conversion around it (`$1::vector`, `VEC_FromText(?)`) declares it once.
+     * dialect needing a conversion around it (`$1::vector`, `CAST(? AS VECTOR(n))`) declares it once.
      */
     protected appendVectorValue(ctx: QueryContext, value: readonly unknown[], _field?: FieldOptions): void;
     /**

package/dist/dialect/vectorSqlDialect.js

@@ -1,7 +1,8 @@
-import { unsupportedVectorMetric } from '../type/vector.js';
-import { findVectorIndex, findVectorSort } from '../util/dialect.util.js';
+import { DEFAULT_VECTOR_DISTANCE, unsupportedVectorMetric } from '../type/vector.js';
+import { findVectorIndex, findVectorSort, vectorCandidates } from '../util/dialect.util.js';
 import { entityName } from '../util/object.util.js';
 import { AbstractDialect } from './abstractDialect.js';
+import { encodeFloat32s } from './vectorCast.js';
 /**
  * Vector search for the SQL dialects: the distance a `$sort` ranks by and projects, and the ANN tuning.
  * Each dialect lists its metrics in {@link vectorMetrics}, an operator or a function; empty means no search.
@@ -24,22 +25,26 @@ export class VectorSqlDialect extends AbstractDialect {
      * spelled into a `SET` rather than bound, and `/http` input is untyped.
      */
     tunedVectorIndex(meta, q) {
-        const candidates = q.$candidates;
-        if (candidates === undefined) {
+        if (vectorCandidates(q) === undefined) {
             return undefined;
         }
-        if (!Number.isInteger(candidates) || candidates < 1) {
-            throw new TypeError(`$candidates must be a positive integer, got ${JSON.stringify(candidates)}`);
-        }
         const key = this.vectorSortKey(q);
         return key ? findVectorIndex(meta, key) : undefined;
     }
+    /** The `$where` a read runs: the query's own, which an engine reading its vector index as a table narrows. */
+    rankedWhere(_meta, q, _prefix) {
+        return q.$where;
+    }
     /**
      * Every distance metric this dialect has, and how a search and an index spell each. Empty means no
      * vector search at all, which is what MySQL and D1 are. The key set is the single answer to "is this
      * metric supported here", for a query and an index alike.
      */
     vectorMetrics = new Map();
+    /** Whether this engine has a vector index: the one a metric's `index` names. */
+    hasVectorIndex() {
+        return [...this.vectorMetrics.values()].some((metric) => metric.index);
+    }
     /**
      * What a distance expression reads, for a `$sort` and a `$near` alike. The metric falls back to the
      * field's, then its index's, which serves no other, then cosine.
@@ -47,15 +52,15 @@ export class VectorSqlDialect extends AbstractDialect {
     resolveVectorDistance(meta, key, search) {
         const field = meta.fields[key];
         const colName = this.resolveColumnName(key, field);
-        const distance = search.$distance ?? field?.distance ?? findVectorIndex(meta, key)?.distance ?? 'cosine';
+        const distance = search.$distance ?? field?.distance ?? findVectorIndex(meta, key)?.distance ?? DEFAULT_VECTOR_DISTANCE;
         return { colName, distance, field };
     }
     /**
      * Binds a vector, both as a persisted value and as the query vector of a distance expression, so a
-     * dialect needing a conversion around it (`$1::vector`, `VEC_FromText(?)`) declares it once.
+     * dialect needing a conversion around it (`$1::vector`, `CAST(? AS VECTOR(n))`) declares it once.
      */
     appendVectorValue(ctx, value, _field) {
-        ctx.addValue(`[${value.join(',')}]`);
+        ctx.addValue(this.features.vectorBytes ? encodeFloat32s(value) : `[${value.join(',')}]`);
     }
     /**
      * The vector type this dialect actually has for a declared one, so the cast follows the column

package/dist/libsql/libsqlDialect.d.ts

@@ -7,6 +7,6 @@ import type { VectorDistance, VectorMetric } from '../type/index.js';
  * functions, which `TursoDialect` inherits.
  */
 export declare class LibsqlDialect extends SqliteDialect {
-    /** libSQL's built-in vector functions; no `inner` (only the Rust engine has it) and no `l1`. */
+    /** libSQL's built-in vector functions, and the metric its DiskANN index names; no `inner` (only the Rust engine has it) and no `l1`. */
     readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
 }

package/dist/libsql/libsqlDialect.js

@@ -6,9 +6,9 @@ import { SqliteDialect } from '../sqlite/sqliteDialect.js';
  * functions, which `TursoDialect` inherits.
  */
 export class LibsqlDialect extends SqliteDialect {
-    /** libSQL's built-in vector functions; no `inner` (only the Rust engine has it) and no `l1`. */
+    /** libSQL's built-in vector functions, and the metric its DiskANN index names; no `inner` (only the Rust engine has it) and no `l1`. */
     vectorMetrics = new Map([
-        ['cosine', { fn: 'vector_distance_cos' }],
-        ['l2', { fn: 'vector_distance_l2' }],
+        ['cosine', { fn: 'vector_distance_cos', index: 'cosine' }],
+        ['l2', { fn: 'vector_distance_l2', index: 'l2' }],
     ]);
 }

package/dist/maria/mariaDialect.d.ts

@@ -6,8 +6,9 @@ export declare class MariaDialect extends MysqlLikeSqlDialect {
     readonly dialectName = "mariadb";
     readonly insertIdSource = "returning";
     /**
-     * Unlike MySQL: `VECTOR(n)` takes its dimension, every column of a vector index has to be NOT NULL,
-     * `CREATE INDEX` takes `IF NOT EXISTS`, and a lock cannot be narrowed to one table of a join.
+     * Unlike MySQL: `VECTOR(n)` takes its dimension and binds as packed float32 bytes, every column of a
+     * vector index has to be NOT NULL, `CREATE INDEX` takes `IF NOT EXISTS`, and a lock cannot be narrowed
+     * to one table of a join.
      */
     readonly features: SqlDialectFeatures;
     /**
@@ -34,13 +35,6 @@ export declare class MariaDialect extends MysqlLikeSqlDialect {
     protected jsonDiffers(elem: string, operand: string): string;
     /** `VEC_DISTANCE_COSINE`/`VEC_DISTANCE_EUCLIDEAN`, 11.7+, which the index's `DISTANCE=` names alike. */
     readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
-    /**
-     * A `VECTOR` column holds a packed little-endian float32 blob, and MariaDB refuses text where one
-     * belongs: inserting `'[1,2,3]'` fails with `Incorrect vector value`, and passing it to
-     * `VEC_DISTANCE_COSINE` with `Illegal parameter data type varchar`. `VEC_FromText` is the
-     * conversion, needed on both paths.
-     */
-    protected appendVectorValue(ctx: QueryContext, value: readonly unknown[]): void;
     /**
      * `mhnsw_ef_search` too, where a vector search is tuned. A setting scoped to one statement needs
      * neither a transaction nor a restore, and cannot leak to the next query on this pooled connection,

package/dist/maria/mariaDialect.js

@@ -8,12 +8,14 @@ export class MariaDialect extends MysqlLikeSqlDialect {
     // MariaDB 10.5+ has `INSERT ... RETURNING`, so ids come back exact per row - the upsert's too.
     insertIdSource = 'returning';
     /**
-     * Unlike MySQL: `VECTOR(n)` takes its dimension, every column of a vector index has to be NOT NULL,
-     * `CREATE INDEX` takes `IF NOT EXISTS`, and a lock cannot be narrowed to one table of a join.
+     * Unlike MySQL: `VECTOR(n)` takes its dimension and binds as packed float32 bytes, every column of a
+     * vector index has to be NOT NULL, `CREATE INDEX` takes `IF NOT EXISTS`, and a lock cannot be narrowed
+     * to one table of a join.
      */
     features = {
         ...MYSQL_FEATURES,
         vectorSupportsLength: true,
+        vectorBytes: true,
         vectorIndexRequiresNotNull: true,
         indexIfNotExists: true,
         rowLockOf: false,
@@ -25,8 +27,7 @@ export class MariaDialect extends MysqlLikeSqlDialect {
     appendRelationArray(ctx, { entity, query, alias, joins }) {
         const meta = getMeta(entity);
         const terms = this.projection(ctx, entity, query, { prefix: alias, json: true }, joins);
-        const sortOpts = { prefix: alias, joins, distinct: query.$distinct };
-        const order = this.buildFragment(ctx, (fragmentCtx) => this.sort(fragmentCtx, entity, query.$sort, sortOpts));
+        const order = this.buildFragment(ctx, (fragmentCtx) => this.sort(fragmentCtx, entity, query, { prefix: alias, joins }));
         const page = this.buildFragment(ctx, (fragmentCtx) => this.pager(fragmentCtx, query));
         const from = this.buildFragment(ctx, (fragmentCtx) => {
             this.selectRelationJoins(fragmentCtx, meta, alias, joins);
@@ -69,17 +70,6 @@ export class MariaDialect extends MysqlLikeSqlDialect {
         ['cosine', { fn: 'VEC_DISTANCE_COSINE', index: 'cosine' }],
         ['l2', { fn: 'VEC_DISTANCE_EUCLIDEAN', index: 'euclidean' }],
     ]);
-    /**
-     * A `VECTOR` column holds a packed little-endian float32 blob, and MariaDB refuses text where one
-     * belongs: inserting `'[1,2,3]'` fails with `Incorrect vector value`, and passing it to
-     * `VEC_DISTANCE_COSINE` with `Illegal parameter data type varchar`. `VEC_FromText` is the
-     * conversion, needed on both paths.
-     */
-    appendVectorValue(ctx, value) {
-        ctx.append('VEC_FromText(');
-        super.appendVectorValue(ctx, value);
-        ctx.append(')');
-    }
     /**
      * `mhnsw_ef_search` too, where a vector search is tuned. A setting scoped to one statement needs
      * neither a transaction nor a restore, and cannot leak to the next query on this pooled connection,

package/dist/maria/mariadbQuerier.js

@@ -1,19 +1,25 @@
 import { AbstractPoolQuerier } from '../querier/abstractPoolQuerier.js';
 import { decodeBigInts } from '../util/wideNumber.js';
+/** This driver binds only a `Buffer` as bytes: any other `Uint8Array` goes as the JSON of its indices. */
+function toBindValues(values) {
+    return values?.map((value) => value instanceof Uint8Array && !Buffer.isBuffer(value)
+        ? Buffer.from(value.buffer, value.byteOffset, value.byteLength)
+        : value);
+}
 export class MariadbQuerier extends AbstractPoolQuerier {
     async internalAll(query, values) {
-        const rows = await this.getConn().query(query, values);
+        const rows = await this.getConn().query(query, toBindValues(values));
         return Array.from(rows, decodeBigInts);
     }
     async internalRun(query, values) {
-        const res = await this.getConn().query(query, values);
+        const res = await this.getConn().query(query, toBindValues(values));
         // An OK packet reports `affectedRows`; a `RETURNING` statement answers rows instead, and counts by them.
         const changes = res.affectedRows ?? res.length;
         const rows = res.length ? Array.from(res, decodeBigInts) : [];
         return this.buildUpdateResult({ rows, changes, upsertStatus: res.affectedRows });
     }
     async *internalStream(query, values) {
-        const stream = this.getConn().queryStream(query, values);
+        const stream = this.getConn().queryStream(query, toBindValues(values));
         try {
             for await (const row of stream) {
                 yield decodeBigInts(row);

package/dist/migrate/ddl/index.d.ts

@@ -6,6 +6,7 @@ export { MsSqlIndexDdl } from './mssqlIndexDdl.js';
 export { MsSqlTableDdl } from './mssqlTableDdl.js';
 export { MariaIndexDdl, MySqlIndexDdl, MysqlLikeIndexDdl } from './mysqlIndexDdl.js';
 export { CockroachIndexDdl, PgIndexDdl } from './pgIndexDdl.js';
+export { SqliteIndexDdl } from './sqliteIndexDdl.js';
 export { TableDdl } from './tableDdl.js';
 export declare function indexDdlFor(dialect: AbstractSqlDialect): IndexDdl;
 /**

package/dist/migrate/ddl/index.js

@@ -3,16 +3,18 @@ import { MsSqlIndexDdl } from './mssqlIndexDdl.js';
 import { MsSqlTableDdl } from './mssqlTableDdl.js';
 import { MariaIndexDdl, MySqlIndexDdl } from './mysqlIndexDdl.js';
 import { CockroachIndexDdl, PgIndexDdl } from './pgIndexDdl.js';
+import { SqliteIndexDdl } from './sqliteIndexDdl.js';
 import { TableDdl } from './tableDdl.js';
 export { IndexDdl } from './indexDdl.js';
 export { MsSqlIndexDdl } from './mssqlIndexDdl.js';
 export { MsSqlTableDdl } from './mssqlTableDdl.js';
 export { MariaIndexDdl, MySqlIndexDdl, MysqlLikeIndexDdl } from './mysqlIndexDdl.js';
 export { CockroachIndexDdl, PgIndexDdl } from './pgIndexDdl.js';
+export { SqliteIndexDdl } from './sqliteIndexDdl.js';
 export { TableDdl } from './tableDdl.js';
 /**
  * Each engine's index DDL, by the `dialectName` a subclass inherits: by name, so this entry carries no
- * dialect, and exhaustive, so a new engine has to name its own. SQLite's is the portable form.
+ * dialect, and exhaustive, so a new engine has to name its own.
  */
 const INDEX_DDL = {
     postgres: PgIndexDdl,
@@ -20,7 +22,7 @@ const INDEX_DDL = {
     mysql: MySqlIndexDdl,
     mariadb: MariaIndexDdl,
     mssql: MsSqlIndexDdl,
-    sqlite: IndexDdl,
+    sqlite: SqliteIndexDdl,
 };
 export function indexDdlFor(dialect) {
     return new INDEX_DDL[dialect.dialectName](dialect);

package/dist/migrate/ddl/indexDdl.d.ts

@@ -37,6 +37,8 @@ export declare class IndexDdl<D extends AbstractSqlDialect = AbstractSqlDialect>
     protected readonly indexTypeKeywords: ReadonlyMap<IndexType, string>;
     /** The keyword an index type replaces `INDEX` with, or `INDEX` for the types that do not. */
     protected indexKeyword(index: IndexSchema): string;
+    /** What the index is over, between the parentheses: a fulltext one's columns as a search matches them, else its entries. */
+    protected indexTarget(index: IndexSchema): string;
     /** One index entry: what is indexed, its operator class if any, then its stored order. */
     protected indexColumn(entry: IndexColumnSchema, index: IndexSchema): string;
     /**

package/dist/migrate/ddl/indexDdl.js

@@ -1,7 +1,7 @@
 import { jsonTypeMode } from '../../dialect/jsonSql.js';
 import { INDEX_TYPES } from '../../schema/types.js';
 import { INDEX_FEATURE_LABELS, } from '../../type/index.js';
-import { getKeys } from '../../util/index.js';
+import { fulltextConfig, getKeys } from '../../util/index.js';
 /**
  * What in an index asks for each feature. A `Record` over the feature union rather than a list, so a
  * feature added to {@link INDEX_FEATURE_LABELS} cannot reach a dialect without the test that decides
@@ -45,7 +45,7 @@ export class IndexDdl {
         assertIndexFeatures(index, this.indexFeatures, this.dialect.dialectName);
         const unique = index.unique ? 'UNIQUE ' : '';
         const ifNotExists = (opts.ifNotExists ?? this.dialect.features.indexIfNotExists) ? 'IF NOT EXISTS ' : '';
-        const columns = index.entries.map((entry) => this.indexColumn(entry, index)).join(', ');
+        const columns = this.indexTarget(index);
         return (`CREATE ${unique}${this.indexKeyword(index)} ${ifNotExists}${this.dialect.escapeId(index.name)} ` +
             `ON ${this.dialect.escapeId(tableName)}${this.indexAccessMethod(index)} (${columns})` +
             `${this.indexInclude(index)}${this.indexTuning(index)}${this.indexPredicate(index)};`);
@@ -78,6 +78,14 @@ export class IndexDdl {
     indexKeyword(index) {
         return (index.type && this.indexTypeKeywords.get(index.type)) || 'INDEX';
     }
+    /** What the index is over, between the parentheses: a fulltext one's columns as a search matches them, else its entries. */
+    indexTarget(index) {
+        if (index.type === 'fulltext' && !index.entries.some((entry) => entry.expression)) {
+            const columns = index.entries.map((entry) => this.dialect.escapeId(entry.column));
+            return this.dialect.textSearchTarget(columns, fulltextConfig(index));
+        }
+        return index.entries.map((entry) => this.indexColumn(entry, index)).join(', ');
+    }
     /** One index entry: what is indexed, its operator class if any, then its stored order. */
     indexColumn(entry, index) {
         return `${this.indexColumnTarget(entry)}${this.indexColumnOpsClass(entry, index)}${this.indexColumnOrder(entry)}`;

package/dist/migrate/ddl/pgIndexDdl.d.ts

@@ -2,9 +2,8 @@ import type { IndexColumnSchema, IndexSchema } from '../../type/index.js';
 import { IndexDdl } from './indexDdl.js';
 /** `CREATE INDEX ... USING hnsw ("embedding" vector_cosine_ops) WITH (m = ...)`, pgvector's form. */
 export declare class PgIndexDdl extends IndexDdl {
-    /** Postgres 18's `pg_am`, with pgvector's two. */
+    /** Postgres 18's `pg_am`, with pgvector's two, and `fulltext`, which builds a `gin` one. */
     protected readonly indexTypes: Set<"brin" | "btree" | "fulltext" | "gin" | "gist" | "hash" | "hnsw" | "ivfflat" | "vector" | "vectorSearch">;
-    protected readonly indexTypeHints: ReadonlyMap<"brin" | "btree" | "fulltext" | "gin" | "gist" | "hash" | "hnsw" | "ivfflat" | "vector" | "vectorSearch", string>;
     protected readonly indexFeatures: Set<"expression" | "include" | "jsonArray" | "jsonPath" | "nullsOrder" | "opsClass" | "partial" | "prefixLength">;
     /** pgvector's own index types; CockroachDB's native one widens this. */
     protected isVectorIndex(index: IndexSchema): boolean;
@@ -27,6 +26,6 @@ export declare class CockroachIndexDdl extends PgIndexDdl {
     protected isVectorIndex(index: IndexSchema): boolean;
     protected indexKeyword(index: IndexSchema): string;
     protected indexAccessMethod(index: IndexSchema): string;
-    /** None of pgvector's knobs: `WITH (m = 16)` answers "invalid storage parameter", `hnsw` included. */
-    protected indexTuning(): string;
+    /** Its build-time candidate list alone: pgvector's `WITH (m = 16)` answers "invalid storage parameter", `hnsw` included. */
+    protected indexTuning(index: IndexSchema): string;
 }