uql-orm 0.37.1 → 0.39.0

package/dist/dialect/pgLikeSqlDialect.js

@@ -1,4 +1,5 @@
 import { QueryRaw, } from '../type/index.js';
+import { hasVectorNear } from '../util/dialect.util.js';
 import { escapeSingleQuotes } from '../util/sqlLiteral.js';
 import { AbstractSqlDialect } from './abstractSqlDialect.js';
 import { JSON_PULL_ALIAS } from './aliases.js';
@@ -28,7 +29,7 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
         renameColumn: true,
         foreignKeyAlter: true,
         columnComment: false,
-        inlineVectorIndex: false,
+        vectorIndexRequiresNotNull: false,
         vectorSupportsLength: true,
         supportsTimestamptz: true,
         defaultStringAsText: true,
@@ -59,64 +60,41 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
         ['inner', { op: '<#>', opsSuffix: 'ip' }],
         ['l1', { op: '<+>', opsSuffix: 'l1' }],
     ]);
-    normalizeValue(value) {
-        if (value != null && typeof value === 'object' && Array.isArray(value)) {
-            return this.features.nativeArrays ? value : toPgArray(value);
-        }
-        return super.normalizeValue(value);
-    }
-    /** pgvector's own index types; CockroachDB's native one widens this. */
-    isVectorIndex(index) {
-        return index.type === 'hnsw' || index.type === 'ivfflat';
-    }
-    indexAccessMethod(index) {
-        return index.type ? ` USING ${index.type}` : '';
-    }
-    indexFeatures = new Set([
-        'expression',
-        'partial',
-        'nullsOrder',
-        'opsClass',
-        'include',
+    /** `SET LOCAL` applies to the enclosing transaction and to nothing at all without one. */
+    vectorTuningNeedsTransaction = true;
+    /**
+     * The GUC each pgvector 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'],
+        ['ivfflat', 'ivfflat.probes'],
     ]);
     /**
-     * A vector index's operator class is named `{type}_{metric}_ops`: an index on a `halfvec` column
-     * needs `halfvec_cosine_ops`, and `vector_cosine_ops` there is rejected outright. An unsupported
-     * distance throws rather than being omitted, since a bare `USING hnsw ("embedding")` would build
-     * with the dialect's default metric instead of the one requested, with nothing signalling it.
-     * Everything else takes the operator class the entry declares, e.g. `jsonb_path_ops` for GIN.
+     * `SET LOCAL hnsw.ef_search = N`, plus `hnsw.iterative_scan` when the query also filters by
+     * distance. Without iterative scan, HNSW returns its candidate list and the predicate then removes
+     * from it, so a `$near` can hand back fewer rows than qualify - the recall bug `$candidates`
+     * exists to answer. `strict_order`, never `relaxed_order`: the latter returns rows out of distance
+     * order, which would quietly contradict the `ORDER BY` the caller asked for.
      */
-    indexColumnOpsClass(entry, index) {
-        if (!this.isVectorIndex(index) || !index.distance) {
-            return entry.opsClass ? ` ${entry.opsClass}` : '';
-        }
-        const metric = this.vectorMetrics.get(index.distance);
-        if (!metric) {
-            throw new TypeError(`${this.dialectName} does not support vector distance metric: ${index.distance} (index "${index.name}")`);
+    vectorTuningStatements(meta, q) {
+        const indexType = this.tunedVectorIndex(meta, q)?.type;
+        const setting = indexType ? PgLikeSqlDialect.ANN_SETTINGS.get(indexType) : undefined;
+        if (!setting) {
+            return [];
         }
-        const vectorType = this.supportedVectorType(index.vectorType ?? 'vector');
-        const opsClass = `${vectorType}_${metric.opsSuffix}_ops`;
-        // IVFFlat has neither a sparsevec nor an L1 operator class; HNSW has all of them (pgvector 0.8.2).
-        if (index.type === 'ivfflat' && (vectorType === 'sparsevec' || index.distance === 'l1')) {
-            throw new TypeError(`ivfflat has no ${opsClass} operator class (index "${index.name}"); use hnsw`);
+        const statements = [`SET LOCAL ${setting} = ${q.$candidates}`];
+        if (indexType === 'hnsw' && hasVectorNear(q.$where)) {
+            statements.push('SET LOCAL hnsw.iterative_scan = strict_order');
         }
-        return ` ${opsClass}`;
-    }
-    indexInclude(index) {
-        return index.include?.length ? ` INCLUDE (${index.include.map((column) => this.escapeId(column)).join(', ')})` : '';
+        return statements;
     }
-    indexTuning(index) {
-        if (!this.isVectorIndex(index)) {
-            return '';
+    normalizeValue(value) {
+        if (value != null && typeof value === 'object' && Array.isArray(value)) {
+            return this.features.nativeArrays ? value : toPgArray(value);
         }
-        const params = [];
-        if (index.m !== undefined)
-            params.push(`m = ${index.m}`);
-        if (index.efConstruction !== undefined)
-            params.push(`ef_construction = ${index.efConstruction}`);
-        if (index.lists !== undefined)
-            params.push(`lists = ${index.lists}`);
-        return params.length > 0 ? ` WITH (${params.join(', ')})` : '';
+        return super.normalizeValue(value);
     }
     placeholder(index) {
         return `$${index}`;
@@ -223,16 +201,6 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
         const ph = this.addValue(ctx.values, json);
         return this.features.explicitJsonCast ? `(${ph}::text)::${type}` : `${ph}::${type}`;
     }
-    /** Emit a pgvector-style distance expression: `"col" <op> $N::<vectorType>`. */
-    appendVectorSort(ctx, meta, key, search) {
-        const { colName, distance, field } = this.resolveVectorSortParams(meta, key, search);
-        const metric = this.vectorMetrics.get(distance);
-        if (!metric) {
-            throw new TypeError(`${this.dialectName} does not support vector distance metric: ${distance}`);
-        }
-        ctx.append(`${this.escapeId(colName)} ${metric.op} `);
-        this.appendVectorValue(ctx, search.$vector, field);
-    }
 }
 /**
  * Converts a JS array to a Postgres array literal string: `{"val1","val2"}`.

package/dist/dialect/vectorCast.d.ts

@@ -2,17 +2,8 @@
  * Kept out of `schema/canonicalType.ts`: importing one function from that migration/codegen module
  * pulled all ~18 KB of its type-mapping tables into every consumer's bundle.
  */
-import type { DialectName } from '../type/querier.js';
 /** Vector cast types supported by pgvector. */
 export type VectorCast = 'vector' | 'halfvec' | 'sparsevec';
-/**
- * The dialects that have more than one vector column type. pgvector is the only one: `halfvec` and
- * `sparsevec` exist nowhere else (`HALFVEC(3)` is a syntax error on CockroachDB 26.2 and MariaDB 12.3,
- * not merely unsupported at runtime), so a field declaring one is stored - and therefore cast - as
- * plain `vector`. Both halves of that used to be stated separately, in this dialect layer and in the
- * migration type maps.
- */
-export declare const MULTI_VECTOR_TYPE_DIALECTS: ReadonlySet<DialectName>;
 /**
  * Whether a declared field type is a vector of any width. Every dialect that treats vectors specially
  * has to answer this for all three, not just `vector`: matching that one alone left `halfvec` and

package/dist/dialect/vectorCast.js

@@ -2,14 +2,6 @@
  * Kept out of `schema/canonicalType.ts`: importing one function from that migration/codegen module
  * pulled all ~18 KB of its type-mapping tables into every consumer's bundle.
  */
-/**
- * The dialects that have more than one vector column type. pgvector is the only one: `halfvec` and
- * `sparsevec` exist nowhere else (`HALFVEC(3)` is a syntax error on CockroachDB 26.2 and MariaDB 12.3,
- * not merely unsupported at runtime), so a field declaring one is stored - and therefore cast - as
- * plain `vector`. Both halves of that used to be stated separately, in this dialect layer and in the
- * migration type maps.
- */
-export const MULTI_VECTOR_TYPE_DIALECTS = new Set(['postgres']);
 /**
  * Whether a declared field type is a vector of any width. Every dialect that treats vectors specially
  * has to answer this for all three, not just `vector`: matching that one alone left `halfvec` and

package/dist/dialect/vectorSqlDialect.d.ts

@@ -1,6 +1,6 @@
-import type { EntityMeta, FieldOptions, QueryContext, QueryVectorSearch, VectorDistance } from '../type/index.js';
+import type { EntityIndexMeta, EntityMeta, FieldOptions, Query, QueryContext, QueryVectorSearch, VectorDistance, VectorMetric } from '../type/index.js';
 import { AbstractDialect } from './abstractDialect.js';
-import { type VectorCast } from './vectorCast.js';
+import type { VectorCast } from './vectorCast.js';
 /**
  * Vector similarity search for SQL dialects: the `ORDER BY <distance>` expression, its projection as
  * a named score, and the index metadata the schema generator reads.
@@ -9,18 +9,48 @@ import { type VectorCast } from './vectorCast.js';
  * dialect above it - unlike the JSON operators, which are woven into the generic comparison
  * machinery (`neExpr`, `numericCast`, `formatIn`, ...) and belong with it.
  *
- * Two shapes exist across dialects: an operator (`"col" <=> $1`, Postgres/CockroachDB) or a function
- * call (`VEC_DISTANCE_COSINE(col, ?)`, MariaDB/SQLite). Dialects pick one by either overriding
- * {@link appendVectorSort} or filling {@link vectorDistanceFns}.
+ * A dialect declares which metrics it has, and how it spells each, in {@link vectorMetrics}. Both
+ * shapes live in that one map - an operator (`"col" <=> $1`, Postgres/CockroachDB) or a function call
+ * (`VEC_DISTANCE_COSINE(col, ?)`, MariaDB/SQLite) - so {@link appendVectorSort} is written once and an
+ * engine with no vector search at all is simply the empty map.
  */
 export declare abstract class VectorSqlDialect extends AbstractDialect {
     readonly vectorExtension: string | undefined;
     /**
-     * Mapping of UQL vector distance metrics to native SQL functions.
-     * Override in dialects that use function-call syntax (e.g. SQLite, MariaDB).
-     * Dialects with operator-based syntax (e.g. Postgres) leave this empty and override `appendVectorSort` directly.
+     * Whether {@link vectorTuningStatements} only applies inside a transaction. `SET LOCAL` does
+     * nothing outside one, so the querier - the only layer that knows whether a transaction is open -
+     * refuses instead of running a tuning that would silently not apply.
      */
-    protected readonly vectorDistanceFns: ReadonlyMap<VectorDistance, string>;
+    readonly vectorTuningNeedsTransaction: boolean;
+    /**
+     * `SET`s that widen an ANN index's search for one query, run before it on the same connection.
+     *
+     * Keyed off `$sort` rather than a `$where` `$near`, because the ANN index is what ranks: pgvector
+     * reaches for HNSW on an `ORDER BY distance LIMIT`, while a bare distance predicate scans whatever
+     * the planner picks. Tuning a query that never touches the index would set a knob for nothing.
+     *
+     * Empty by default: SQLite, libSQL and Turso compute every distance, so there is no candidate list
+     * to widen, and a field with no ANN index has nothing to tune either.
+     */
+    vectorTuningStatements<E>(_meta: EntityMeta<E>, _q: Query<E>): readonly string[];
+    /** The `$sort` key carrying a vector search, if the query ranks by one. */
+    protected vectorSortKey<E>(q: Query<E>): string | undefined;
+    /**
+     * The ANN index `$candidates` would tune for this query, and nothing when there is none to tune -
+     * no `$candidates`, no vector ranking, or a field with no ANN index on it. One place, so the two
+     * dialects that act on it cannot disagree about when tuning applies.
+     *
+     * Validates here rather than at each emitter because the number is spelled into the statement
+     * rather than bound: `SET LOCAL hnsw.ef_search = $1` is not a thing either engine accepts. `/http`
+     * casts client JSON straight to `Query`, so `'abc'` and `null` both reach this.
+     */
+    protected tunedVectorIndex<E>(meta: EntityMeta<E>, q: Query<E>): EntityIndexMeta | undefined;
+    /**
+     * Every distance metric this dialect has, and how it spells 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", so a metric cannot be searchable and unindexable or the reverse.
+     */
+    readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
     /** Quotes an identifier; supplied by the SQL dialect built on top of this layer. */
     abstract escapeId(val: string | undefined, forbidQualified?: boolean, addDot?: boolean): string;
     /**
@@ -38,23 +68,23 @@ export declare abstract class VectorSqlDialect extends AbstractDialect {
      */
     protected appendVectorValue(ctx: QueryContext, value: readonly unknown[], _field?: FieldOptions): void;
     /**
-     * The vector type this dialect actually has for a declared one, so the cast follows the column
-     * rather than naming a type the engine does not define. See {@link MULTI_VECTOR_TYPE_DIALECTS}.
+     * Whether this engine has pgvector's narrower vector types (`halfvec`, `sparsevec`) or only the one.
+     * Declared by the dialect that has them rather than looked up in a table keyed by dialect name.
      */
-    protected supportedVectorType(cast: VectorCast): VectorCast;
+    protected readonly hasNarrowVectorTypes: boolean;
     /**
-     * Append a vector similarity function call: `fn(col, ?)`.
-     * Used by dialects that express vector distance via SQL functions (SQLite, MariaDB).
+     * The vector type this dialect actually has for a declared one, so the cast follows the column
+     * rather than naming a type the engine does not define.
      */
-    protected appendFunctionVectorSort<E>(ctx: QueryContext, meta: EntityMeta<E>, key: string, search: QueryVectorSearch): void;
+    supportedVectorType(cast: VectorCast): VectorCast;
     /**
      * Append a vector distance projection.
      * Delegates to `appendVectorSort` so each dialect's distance syntax is written once.
      */
     protected appendVectorProjection<E>(ctx: QueryContext, meta: EntityMeta<E>, key: string, search: QueryVectorSearch): void;
     /**
-     * Append a vector similarity expression for `ORDER BY`.
-     * Default: auto-delegates to `appendFunctionVectorSort` when `vectorDistanceFns` has entries.
+     * The distance expression, in whichever of the two shapes this dialect spells it. One method for
+     * both, so the metric lookup and its refusal exist once rather than per shape.
      */
     protected appendVectorSort<E>(ctx: QueryContext, meta: EntityMeta<E>, key: string, search: QueryVectorSearch): void;
 }

package/dist/dialect/vectorSqlDialect.js

@@ -1,5 +1,7 @@
+import { unsupportedVectorMetric } from '../type/vector.js';
+import { findVectorIndex, findVectorSort } from '../util/dialect.util.js';
+import { entityName } from '../util/object.util.js';
 import { AbstractDialect } from './abstractDialect.js';
-import { MULTI_VECTOR_TYPE_DIALECTS } from './vectorCast.js';
 /**
  * Vector similarity search for SQL dialects: the `ORDER BY <distance>` expression, its projection as
  * a named score, and the index metadata the schema generator reads.
@@ -8,18 +10,62 @@ import { MULTI_VECTOR_TYPE_DIALECTS } from './vectorCast.js';
  * dialect above it - unlike the JSON operators, which are woven into the generic comparison
  * machinery (`neExpr`, `numericCast`, `formatIn`, ...) and belong with it.
  *
- * Two shapes exist across dialects: an operator (`"col" <=> $1`, Postgres/CockroachDB) or a function
- * call (`VEC_DISTANCE_COSINE(col, ?)`, MariaDB/SQLite). Dialects pick one by either overriding
- * {@link appendVectorSort} or filling {@link vectorDistanceFns}.
+ * A dialect declares which metrics it has, and how it spells each, in {@link vectorMetrics}. Both
+ * shapes live in that one map - an operator (`"col" <=> $1`, Postgres/CockroachDB) or a function call
+ * (`VEC_DISTANCE_COSINE(col, ?)`, MariaDB/SQLite) - so {@link appendVectorSort} is written once and an
+ * engine with no vector search at all is simply the empty map.
  */
 export class VectorSqlDialect extends AbstractDialect {
     vectorExtension = undefined;
     /**
-     * Mapping of UQL vector distance metrics to native SQL functions.
-     * Override in dialects that use function-call syntax (e.g. SQLite, MariaDB).
-     * Dialects with operator-based syntax (e.g. Postgres) leave this empty and override `appendVectorSort` directly.
+     * Whether {@link vectorTuningStatements} only applies inside a transaction. `SET LOCAL` does
+     * nothing outside one, so the querier - the only layer that knows whether a transaction is open -
+     * refuses instead of running a tuning that would silently not apply.
      */
-    vectorDistanceFns = new Map();
+    vectorTuningNeedsTransaction = false;
+    /**
+     * `SET`s that widen an ANN index's search for one query, run before it on the same connection.
+     *
+     * Keyed off `$sort` rather than a `$where` `$near`, because the ANN index is what ranks: pgvector
+     * reaches for HNSW on an `ORDER BY distance LIMIT`, while a bare distance predicate scans whatever
+     * the planner picks. Tuning a query that never touches the index would set a knob for nothing.
+     *
+     * Empty by default: SQLite, libSQL and Turso compute every distance, so there is no candidate list
+     * to widen, and a field with no ANN index has nothing to tune either.
+     */
+    vectorTuningStatements(_meta, _q) {
+        return [];
+    }
+    /** The `$sort` key carrying a vector search, if the query ranks by one. */
+    vectorSortKey(q) {
+        return findVectorSort(q.$sort)?.key;
+    }
+    /**
+     * The ANN index `$candidates` would tune for this query, and nothing when there is none to tune -
+     * no `$candidates`, no vector ranking, or a field with no ANN index on it. One place, so the two
+     * dialects that act on it cannot disagree about when tuning applies.
+     *
+     * Validates here rather than at each emitter because the number is spelled into the statement
+     * rather than bound: `SET LOCAL hnsw.ef_search = $1` is not a thing either engine accepts. `/http`
+     * casts client JSON straight to `Query`, so `'abc'` and `null` both reach this.
+     */
+    tunedVectorIndex(meta, q) {
+        const candidates = q.$candidates;
+        if (candidates === 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;
+    }
+    /**
+     * Every distance metric this dialect has, and how it spells 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", so a metric cannot be searchable and unindexable or the reverse.
+     */
+    vectorMetrics = new Map();
     /**
      * Resolve common parameters for a vector similarity ORDER BY expression.
      * Shared by all dialect overrides of `appendVectorSort`.
@@ -38,25 +84,16 @@ export class VectorSqlDialect extends AbstractDialect {
         ctx.addValue(`[${value.join(',')}]`);
     }
     /**
-     * The vector type this dialect actually has for a declared one, so the cast follows the column
-     * rather than naming a type the engine does not define. See {@link MULTI_VECTOR_TYPE_DIALECTS}.
+     * Whether this engine has pgvector's narrower vector types (`halfvec`, `sparsevec`) or only the one.
+     * Declared by the dialect that has them rather than looked up in a table keyed by dialect name.
      */
-    supportedVectorType(cast) {
-        return MULTI_VECTOR_TYPE_DIALECTS.has(this.dialectName) ? cast : 'vector';
-    }
+    hasNarrowVectorTypes = false;
     /**
-     * Append a vector similarity function call: `fn(col, ?)`.
-     * Used by dialects that express vector distance via SQL functions (SQLite, MariaDB).
+     * The vector type this dialect actually has for a declared one, so the cast follows the column
+     * rather than naming a type the engine does not define.
      */
-    appendFunctionVectorSort(ctx, meta, key, search) {
-        const { colName, distance, field } = this.resolveVectorSortParams(meta, key, search);
-        const fn = this.vectorDistanceFns.get(distance);
-        if (!fn) {
-            throw Error(`${this.dialectName} does not support vector distance metric: ${distance}`);
-        }
-        ctx.append(`${fn}(${this.escapeId(colName)}, `);
-        this.appendVectorValue(ctx, search.$vector, field);
-        ctx.append(')');
+    supportedVectorType(cast) {
+        return this.hasNarrowVectorTypes ? cast : 'vector';
     }
     /**
      * Append a vector distance projection.
@@ -68,20 +105,31 @@ export class VectorSqlDialect extends AbstractDialect {
         // under that name and the driver keeps whichever it read last. Checked here rather than in the
         // type because TypeScript cannot say "any string except these".
         if (meta.fields[alias]) {
-            throw new TypeError(`$project '${alias}' collides with a field of '${meta.name ?? String(meta.entity.name)}'`);
+            throw new TypeError(`$project '${alias}' collides with a field of '${entityName(meta)}'`);
         }
         this.appendVectorSort(ctx, meta, key, search);
         ctx.append(` AS ${this.escapeId(alias)}`);
     }
     /**
-     * Append a vector similarity expression for `ORDER BY`.
-     * Default: auto-delegates to `appendFunctionVectorSort` when `vectorDistanceFns` has entries.
+     * The distance expression, in whichever of the two shapes this dialect spells it. One method for
+     * both, so the metric lookup and its refusal exist once rather than per shape.
      */
     appendVectorSort(ctx, meta, key, search) {
-        if (this.vectorDistanceFns.size > 0) {
-            this.appendFunctionVectorSort(ctx, meta, key, search);
+        if (this.vectorMetrics.size === 0) {
+            throw new TypeError(`${this.dialectName} does not support vector similarity search. Use raw() for vector queries.`);
+        }
+        const { colName, distance, field } = this.resolveVectorSortParams(meta, key, search);
+        const metric = this.vectorMetrics.get(distance);
+        if (!metric) {
+            throw unsupportedVectorMetric(this.dialectName, distance);
+        }
+        if ('fn' in metric) {
+            ctx.append(`${metric.fn}(${this.escapeId(colName)}, `);
+            this.appendVectorValue(ctx, search.$vector, field);
+            ctx.append(')');
             return;
         }
-        throw new TypeError(`${this.dialectName} does not support vector similarity sort. Use raw() for vector queries.`);
+        ctx.append(`${this.escapeId(colName)} ${metric.op} `);
+        this.appendVectorValue(ctx, search.$vector, field);
     }
 }

package/dist/entity/decorator/entity.d.ts

@@ -25,4 +25,4 @@ export declare function Filter<E>(name: string, opts: FilterOptions<E>): (entity
  * @example `@Index(['email'], { unique: true })`
  * @example `@Index(['status'], { where: "status = 'active'" })`
  */
-export declare function Index<E>(columns: readonly IndexColumnInput<FieldKey<E>>[], options?: IndexOptions): (entity: Type<E>) => void;
+export declare function Index<E>(columns: readonly IndexColumnInput<FieldKey<E>, E>[], options?: IndexOptions<E>): (entity: Type<E>) => void;

package/dist/entity/metadata/definition.d.ts

@@ -7,7 +7,7 @@ export declare function defineHook<E>(entity: Type<E>, methodName: string, event
  * Declares a composite index. `unique` and the authored column sugar are normalized here, which is what
  * lets the dialects render one shape instead of re-parsing it.
  */
-export declare function defineIndex<E>(entity: Type<E>, index: EntityIndexInput<FieldKey<E>>): EntityMeta<E>;
+export declare function defineIndex<E>(entity: Type<E>, index: EntityIndexInput<FieldKey<E>, E>): EntityMeta<E>;
 export declare function defineFilter<E>(entity: Type<E>, name: string, opts: FilterOptions<E>): EntityMeta<E>;
 /**
  * What a decorator bag and {@link EntityOptions} have in common at registration time. The keyed mapped

package/dist/entity/metadata/definition.js

@@ -1,3 +1,4 @@
+import { SOFT_DELETE_FILTER } from '../../type/index.js';
 import { getKeys, hasKeys, isToManyRelation, lowerFirst, normalizeIndexColumn, upperFirst } from '../../util/index.js';
 import { ownRegistrations } from '../decorator/bag.js';
 // Held on `globalThis` via the global symbol registry so a single metadata map survives multiple
@@ -67,8 +68,8 @@ export function defineIndex(entity, index) {
 }
 export function defineFilter(entity, name, opts) {
     const meta = ensureMeta(entity);
-    if (name === 'softDelete') {
-        throw TypeError(`'${entity.name}' filter name 'softDelete' is reserved; it is auto-registered from @Field({ softDelete })`);
+    if (name === SOFT_DELETE_FILTER) {
+        throw TypeError(`'${entity.name}' filter name '${SOFT_DELETE_FILTER}' is reserved; it is auto-registered from @Field({ softDelete })`);
     }
     if (opts.security && opts.onMissing === 'skip') {
         throw TypeError(`'${entity.name}' security filter '${name}' cannot use onMissing: 'skip' (it must fail closed)`);
@@ -155,7 +156,7 @@ export function defineEntity(entity, opts = {}) {
         meta.softDelete = softDeleteKeys[0];
         if (!meta.filters)
             meta.filters = {};
-        meta.filters['softDelete'] = { condition: { [meta.softDelete]: null }, default: true };
+        meta.filters[SOFT_DELETE_FILTER] = { condition: { [meta.softDelete]: null }, default: true };
     }
     const id = getIdKey(meta);
     if (!id) {

package/dist/http/query.js

@@ -1,5 +1,5 @@
 // the clause lists themselves, not the barrel: this module is in the browser bundle's graph
-import { QUERY_BOOLEAN_CLAUSES, QUERY_NUMBER_CLAUSES, QUERY_OBJECT_CLAUSES, QUERY_ROOT_OBJECT_CLAUSES, } from '../type/query.js';
+import { QUERY_BOOLEAN_CLAUSES, QUERY_NUMBER_CLAUSES, QUERY_OBJECT_CLAUSES, QUERY_ROOT_NUMBER_CLAUSES, QUERY_ROOT_OBJECT_CLAUSES, } from '../type/query.js';
 // the specific util module, not the barrel, so the browser bundle does not pull in entity metadata
 import { getKeys } from '../util/object.util.js';
 /**
@@ -12,6 +12,7 @@ const ALLOWED_QUERY_KEYS = new Set([
     ...QUERY_OBJECT_CLAUSES,
     ...QUERY_ROOT_OBJECT_CLAUSES,
     ...QUERY_NUMBER_CLAUSES,
+    ...QUERY_ROOT_NUMBER_CLAUSES,
     ...QUERY_BOOLEAN_CLAUSES,
     'hardDelete',
     'count',
@@ -52,7 +53,7 @@ export function parseQueryParams(params = {}) {
     // A query string carries every value as text, so what decodes a clause is the shape its group
     // declares. `'false'` is the reason the boolean pass exists rather than the raw value being taken:
     // it is a non-empty string, so a `$distinct=false` would otherwise read as asking for one.
-    for (const key of QUERY_NUMBER_CLAUSES) {
+    for (const key of [...QUERY_NUMBER_CLAUSES, ...QUERY_ROOT_NUMBER_CLAUSES]) {
         if (query[key] !== undefined) {
             query[key] = Number(query[key]);
         }

package/dist/libsql/libsqlDialect.d.ts

@@ -1,5 +1,5 @@
 import { SqliteDialect } from '../sqlite/sqliteDialect.js';
-import type { VectorDistance } from '../type/index.js';
+import type { VectorDistance, VectorMetric } from '../type/index.js';
 /**
  * SQLite Dialect specialization for the `@libsql/client` driver.
  *
@@ -15,5 +15,5 @@ export declare class LibsqlDialect extends SqliteDialect {
      * engine (see `TursoDialect`) and no libSQL build has an L1 metric. Both raise the same
      * "does not support vector distance metric" error as any other unsupported metric.
      */
-    protected readonly vectorDistanceFns: ReadonlyMap<VectorDistance, string>;
+    readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
 }

package/dist/libsql/libsqlDialect.js

@@ -14,8 +14,8 @@ export class LibsqlDialect extends SqliteDialect {
      * engine (see `TursoDialect`) and no libSQL build has an L1 metric. Both raise the same
      * "does not support vector distance metric" error as any other unsupported metric.
      */
-    vectorDistanceFns = new Map([
-        ['cosine', 'vector_distance_cos'],
-        ['l2', 'vector_distance_l2'],
+    vectorMetrics = new Map([
+        ['cosine', { fn: 'vector_distance_cos' }],
+        ['l2', { fn: 'vector_distance_l2' }],
     ]);
 }

package/dist/maria/mariaDialect.d.ts

@@ -1,19 +1,15 @@
 import { MysqlLikeSqlDialect } from '../dialect/mysqlLikeSqlDialect.js';
-import type { DialectFeatures, FieldOptions, IndexFeature, IndexSchema, QueryContext, Type, VectorDistance } from '../type/index.js';
+import type { DialectFeatures, FieldOptions, Query, QueryContext, QueryOptions, Type, VectorDistance, VectorMetric } from '../type/index.js';
 export declare class MariaDialect extends MysqlLikeSqlDialect {
     readonly dialectName = "mariadb";
     readonly insertIdSource = "returning";
-    /**
-     * MariaDB has no functional indexes: `CREATE INDEX ... ((lower(col)))` is a syntax error even on
-     * 12.3, where the documented workaround is a generated column. So it keeps the prefix lengths the
-     * family shares and drops expressions.
-     */
-    protected readonly indexFeatures: Set<IndexFeature>;
     /** MariaDB has no `FOR ... OF`, so a lock cannot be narrowed to one table of a join. */
     readonly supportsLockOf = false;
-    /** Unlike MySQL: `VECTOR(n)` takes its dimension, and its vector index is declared inline. */
+    /**
+     * Unlike MySQL: `VECTOR(n)` takes its dimension, every column of a vector index has to be NOT NULL,
+     * and `CREATE INDEX` takes `IF NOT EXISTS` - which MySQL's grammar has no place for.
+     */
     protected readonly featureOverrides: Partial<DialectFeatures>;
-    /** MariaDB 10.5+ supports `INSERT ... RETURNING`, so the ids are exact per row. */
     protected upsertReturning<E>(entity: Type<E>): string;
     /**
      * MariaDB supports neither MySQL's `->`/`->>` shorthand nor the base's chained form. `JSON_VALUE`
@@ -30,10 +26,8 @@ export declare class MariaDialect extends MysqlLikeSqlDialect {
     protected jsonPullElem(alias: string): string;
     /** Text-backed JSON compares as text, so use JSON_EQUALS for key-order-independent equality. */
     protected jsonPullKeep(alias: string, operand: string): string;
-    /** MariaDB's own names for the metrics its vector index accepts. */
-    private static readonly INLINE_VECTOR_METRICS;
-    /** MariaDB 11.7+ vector distance functions. */
-    protected readonly vectorDistanceFns: ReadonlyMap<VectorDistance, string>;
+    /** `VEC_DISTANCE_COSINE`/`VEC_DISTANCE_EUCLIDEAN`, 11.7+: the metric's own name, uppercased. */
+    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
@@ -42,11 +36,12 @@ export declare class MariaDialect extends MysqlLikeSqlDialect {
      */
     protected appendVectorValue(ctx: QueryContext, value: readonly unknown[]): void;
     /**
-     * MariaDB declares a vector index inside `CREATE TABLE`: `VECTOR INDEX (col) M=n DISTANCE=metric`.
-     * Its metric names are its own (`euclidean`, not `l2`), and an unsupported one throws rather than
-     * being dropped, which would silently build the index on cosine instead.
+     * `SET STATEMENT mhnsw_ef_search=N FOR SELECT ...` - MariaDB scopes a variable to one statement, so
+     * the tuning needs neither a transaction nor a restore afterwards, and cannot leak to the next
+     * query on this pooled connection. That is why it prefixes the SQL here instead of coming back
+     * from `vectorTuningStatements`, which is Postgres's `SET LOCAL` shape.
      */
-    getInlineVectorIndexDeclaration(index: IndexSchema): string;
+    find<E>(ctx: QueryContext, entity: Type<E>, q?: Query<E>, opts?: QueryOptions, totalAlias?: string): void;
     /** The reverse: selecting a `VECTOR` column raw yields that blob, so it is read back as text. */
     protected selectFieldExpr(escapedColumn: string, field: FieldOptions): string;
 }