uql-orm 0.37.1 → 0.39.0

package/dist/dialect/abstractSqlDialect.js

@@ -1,15 +1,15 @@
 import { getMeta } from '../entity/index.js';
-import { parseQueryLock, QueryRaw, RAW_ALIAS, RAW_VALUE, } from '../type/index.js';
+import { parseQueryLock, QueryRaw, RAW_ALIAS, RAW_VALUE, VECTOR_QUERY_KEYS, } from '../type/index.js';
 import { asSelectMap, assertNonNegativeInteger, buildQueryWhereAsMap, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getSoftDeleteValue, hasKeys, isBooleanType, isJsonType, isJsonUpdateOp, isNumericType, isOperatorMap, isOperatorObject, isOperatorOnlyObject, isVectorSearch, normalizeScalarFieldSelection, parseGroupMap, parseRelationSize, parseSortByCount, populatesRelations, raw, someValue, throwUnknownAggregateColumn, withoutSoftDeleteFilter, } from '../util/index.js';
 import { escapeAnsiSqlLiteral, escapeSingleQuotes } from '../util/sqlLiteral.js';
 import { COUNT_ALIAS, DISTINCT_DERIVED_ALIAS, JSON_ELEM_ALIAS_PREFIX } from './aliases.js';
-import { IndexSqlDialect } from './indexSqlDialect.js';
 import { buildElemMatchConditions } from './jsonArrayElemMatchUtils.js';
 import { isJsonbOp, jsonCompareMode, jsonElemExists } from './jsonSql.js';
 import { SqlQueryContext } from './queryContext.js';
 import { NO_JOINS, resolveQueryJoins, resolveSortableJoin, } from './queryJoins.js';
 import { isVectorFieldType, resolveVectorCast } from './vectorCast.js';
-export class AbstractSqlDialect extends IndexSqlDialect {
+import { VectorSqlDialect } from './vectorSqlDialect.js';
+export class AbstractSqlDialect extends VectorSqlDialect {
     /**
      * How this engine declares a namespace, so a generated migration creates the schemas its tables
      * need before creating them. Only reached where {@link DialectFeatures.schemas} is on. MySQL and
@@ -394,6 +394,17 @@ export class AbstractSqlDialect extends IndexSqlDialect {
         ['$lt', ' < '],
         ['$lte', ' <= '],
     ]);
+    /** What a `$near` says about the search itself; everything else in it is a bound. */
+    static VECTOR_QUERY_KEYS = new Set(VECTOR_QUERY_KEYS);
+    /**
+     * The runtime half of {@link QueryVectorNear}'s bounds, derived from the map above rather than
+     * spelled again: both are `QueryOrderedOp`, so `$near` can never accept a comparison the renderer
+     * below has no operator for.
+     */
+    static NEAR_BOUND_OPS = new Set([
+        ...AbstractSqlDialect.COMPARE_OP_MAP.keys(),
+        '$between',
+    ]);
     /**
      * Every `$like`-family operator: the pattern it wraps its value in, and whether it ignores case.
      * Each case-sensitive operator is paired here with the `$i` twin that shares its pattern, so the
@@ -479,6 +490,9 @@ export class AbstractSqlDialect extends IndexSqlDialect {
             case '$elemMatch':
                 ctx.append(this.jsonElemMatch(ctx, field, val));
                 break;
+            case '$near':
+                this.compareVectorNear(ctx, getMeta(entity), key, val);
+                break;
             default:
                 throw TypeError(`unknown operator: ${op}`);
         }
@@ -547,34 +561,35 @@ export class AbstractSqlDialect extends IndexSqlDialect {
      * All dialect-specific behavior comes from overridable methods on `this`.
      */
     buildJsonFieldCondition(ctx, fieldAccessor, jsonPath, op, value, asJson = false) {
-        const jsonField = fieldAccessor(jsonPath);
+        const jsonField = fieldAccessor(jsonPath, asJson ? 'json' : 'text');
+        // The left side of a comparison reads the path the way its operand is compared: a numeric one
+        // cast to a number, a boolean as the JSON value.
+        const comparand = (val) => fieldAccessor(jsonPath, jsonCompareMode(val));
         // The `$like` family reads a JSON path exactly as it reads a column, case folding included.
         const like = this.likeCondition(ctx, jsonField, op, value);
         if (like) {
             return like;
         }
+        // The ordered comparisons read the path as a number whatever the operand is, and spell their
+        // operator out of the same table a comparison against a column does.
+        const compareOp = AbstractSqlDialect.COMPARE_OP_MAP.get(op);
+        if (compareOp) {
+            return `${fieldAccessor(jsonPath, 'numeric')}${compareOp}${this.addValue(ctx.values, value)}`;
+        }
         switch (op) {
             case '$eq':
                 if (value === null)
                     return `${jsonField} IS NULL`;
-                return `${this.jsonComparand(jsonField, value)} = ${this.jsonOperand(ctx, value, asJson)}`;
+                return `${comparand(value)} = ${this.jsonOperand(ctx, value, asJson)}`;
             case '$ne':
                 if (value === null)
                     return `${jsonField} IS NOT NULL`;
-                return this.neExpr(this.jsonComparand(jsonField, value), this.jsonOperand(ctx, value, asJson));
-            case '$gt':
-                return `${this.numericCast(jsonField)} > ${this.addValue(ctx.values, value)}`;
-            case '$gte':
-                return `${this.numericCast(jsonField)} >= ${this.addValue(ctx.values, value)}`;
-            case '$lt':
-                return `${this.numericCast(jsonField)} < ${this.addValue(ctx.values, value)}`;
-            case '$lte':
-                return `${this.numericCast(jsonField)} <= ${this.addValue(ctx.values, value)}`;
+                return this.neExpr(comparand(value), this.jsonOperand(ctx, value, asJson));
             case '$regex':
                 return `${jsonField} ${this.regexpOp} ${this.addValue(ctx.values, value)}`;
             case '$in':
             case '$nin':
-                return this.jsonInNin(ctx, jsonField, op, value, asJson);
+                return this.jsonInNin(ctx, jsonField, comparand, op, value, asJson);
             case '$all':
                 return this.jsonAll(ctx, jsonField, value);
             case '$size':
@@ -585,11 +600,11 @@ export class AbstractSqlDialect extends IndexSqlDialect {
                 throw TypeError(`unknown operator: ${op}`);
         }
     }
-    jsonInNin(ctx, jsonField, op, value, asJson) {
+    jsonInNin(ctx, jsonField, comparand, op, value, asJson) {
         const values = Array.isArray(value) ? value : [];
         const negate = op === '$nin';
         if (!asJson) {
-            return `${this.jsonComparand(jsonField, values)}${this.formatIn(ctx, values, negate)}`;
+            return `${comparand(values)}${this.formatIn(ctx, values, negate)}`;
         }
         // JSON values have no portable array literal, so the set expands into explicit comparisons.
         const comparisons = values.map((val) => `${jsonField} ${negate ? '<>' : '='} ${this.jsonScalarParam(ctx, val)}`);
@@ -599,13 +614,6 @@ export class AbstractSqlDialect extends IndexSqlDialect {
     jsonOperand(ctx, value, asJson) {
         return asJson ? this.jsonScalarParam(ctx, value) : this.addValue(ctx.values, value);
     }
-    /**
-     * The left side of a comparison against a JSON scalar, cast when the operand is numeric - see
-     * {@link jsonCompareMode} for why each mode exists.
-     */
-    jsonComparand(jsonField, value) {
-        return jsonCompareMode(value) === 'numeric' ? this.numericCast(jsonField) : jsonField;
-    }
     /**
      * Whether the dialect's array containment ({@link jsonAll}) matches an object element that merely
      * *includes* the given keys, as PostgreSQL's `@>` and MySQL's `JSON_CONTAINS` do. SQLite compares
@@ -634,7 +642,7 @@ export class AbstractSqlDialect extends IndexSqlDialect {
             const entries = Object.entries(match);
             const asJson = !this.jsonScalarElemKeepsType && entries.every(([op, val]) => isJsonbOp(op, val));
             const alias = ctx.nextAlias(JSON_ELEM_ALIAS_PREFIX);
-            const conditions = entries.map(([op, val]) => this.buildJsonFieldCondition(ctx, () => this.jsonElemRef(alias, undefined, asJson), '', op, val, asJson));
+            const conditions = entries.map(([op, val]) => this.buildJsonFieldCondition(ctx, this.elemAccessor(alias, asJson), '', op, val, asJson));
             return jsonElemExists(this.jsonElemFrom(jsonField, [], alias, asJson), conditions);
         }
         if (isOperatorObject(match)) {
@@ -648,10 +656,21 @@ export class AbstractSqlDialect extends IndexSqlDialect {
         const alias = ctx.nextAlias(JSON_ELEM_ALIAS_PREFIX);
         const conditions = buildElemMatchConditions(match, (field, op, opVal) => {
             const asJson = isJsonbOp(op, opVal);
-            return this.buildJsonFieldCondition(ctx, (f) => this.jsonElemRef(alias, f, asJson), field, op, opVal, asJson);
+            return this.buildJsonFieldCondition(ctx, this.elemAccessor(alias, asJson), field, op, opVal, asJson);
         });
         return jsonElemExists(this.jsonElemFrom(jsonField, Object.keys(match), alias), conditions);
     }
+    /**
+     * How a `$elemMatch` reads one exploded element: {@link jsonPathExpr}'s counterpart, over a column
+     * of the derived table rather than a path of the document. An empty field names the element itself,
+     * which is what the operator-only form matches on.
+     */
+    elemAccessor(alias, asJson) {
+        return (field, mode) => {
+            const ref = this.jsonElemRef(alias, field || undefined, asJson);
+            return mode === 'numeric' ? this.numericCast(ref) : ref;
+        };
+    }
     /**
      * A JSON-encoded bound parameter, cast to the dialect's JSON type. Only the positional-placeholder
      * dialects use this - PostgreSQL binds JSON through {@link PgLikeSqlDialect.jsonScalarParam} instead.
@@ -735,7 +754,8 @@ export class AbstractSqlDialect extends IndexSqlDialect {
         if (field) {
             return field.virtual ? this.escapeId(key) : this.columnWithPrefix(key, field, prefix);
         }
-        return this.resolveJsonDotPath(meta, key, prefix)?.accessor() ?? this.escapeId(key);
+        const json = this.resolveJsonDotPath(meta, key, prefix);
+        return json ? this.jsonPathExpr(json.column, json.jsonPath, 'text') : this.escapeId(key);
     }
     pager(ctx, opts) {
         // `!== undefined`, not truthiness: `$limit: 0` asks for no rows, where "unset" means every row.
@@ -1339,20 +1359,29 @@ export class AbstractSqlDialect extends IndexSqlDialect {
         if (!field || !isJsonType(field.type)) {
             return undefined;
         }
-        const jsonPath = key.slice(dotIndex + 1);
         const colName = this.resolveColumnName(root, field);
-        const escapedCol = (prefix ? this.escapeId(prefix, true, true) : '') + this.escapeId(colName);
-        return {
-            jsonPath,
-            accessor: (asJsonb) => asJsonb ? this.getJsonPathJsonbExpr(escapedCol, jsonPath) : this.getJsonPathScalarExpr(escapedCol, jsonPath),
-        };
+        const prefixed = (prefix ? this.escapeId(prefix, true, true) : '') + this.escapeId(colName);
+        return { jsonPath: key.slice(dotIndex + 1), column: prefixed };
+    }
+    /**
+     * One JSON path, read the way `mode` asks for: the one place the three readings are chosen between,
+     * so `$where`, `$sort` and every operator reach a path the same way. Public because a JSON index
+     * is matched back by its own text, so the migrator's `CREATE INDEX` has to spell it from here too.
+     */
+    jsonPathExpr(escapedColumn, jsonPath, mode) {
+        if (mode === 'json') {
+            return this.getJsonPathJsonbExpr(escapedColumn, jsonPath);
+        }
+        const scalar = this.getJsonPathScalarExpr(escapedColumn, jsonPath);
+        return mode === 'numeric' ? this.numericCast(scalar) : scalar;
     }
     /**
      * Compare a JSONB dot-notation path, e.g. `'settings.isArchived': { $ne: true }`.
      * Receives a pre-resolved `resolveJsonDotPath` result to avoid redundant computation.
      */
     compareJsonPath(ctx, resolved, val) {
-        const { jsonPath, accessor } = resolved;
+        const { jsonPath, column } = resolved;
+        const accessor = (path, mode) => this.jsonPathExpr(column, path, mode);
         const value = this.normalizeWhereValue(val);
         const operators = getKeys(value);
         if (operators.length > 1) {
@@ -1362,7 +1391,7 @@ export class AbstractSqlDialect extends IndexSqlDialect {
             if (index > 0)
                 ctx.append(' AND ');
             const asJson = isJsonbOp(op, value[op]);
-            const sql = this.buildJsonFieldCondition(ctx, () => accessor(asJson), jsonPath, op, value[op], asJson);
+            const sql = this.buildJsonFieldCondition(ctx, accessor, jsonPath, op, value[op], asJson);
             if (sql) {
                 ctx.append(sql);
             }
@@ -1485,18 +1514,13 @@ export class AbstractSqlDialect extends IndexSqlDialect {
         this.buildSizeComparison(ctx, () => this.appendRelationSubquery(ctx, getMeta(entity), rel, opts, 'COUNT(*)', {}), sizeVal);
     }
     /**
-     * Build a complete `$size` comparison expression.
-     * Handles both single and multiple comparison operators by repeating the size expression.
-     * @param sizeExprFn - function that appends the size expression to ctx (e.g. `jsonb_array_length("col")`)
+     * `<expr> <op> <value>` for each operator, AND-joined and parenthesized when there is more than
+     * one. `exprFn` is re-run per operator because what it appends is an expression, not a column:
+     * a `WHERE` has no output alias to refer back to, so the only way to compare it twice is to spell
+     * it twice. Shared by `$size`, which counts, and `$near`, which measures a distance.
      */
-    buildSizeComparison(ctx, sizeExprFn, sizeVal) {
-        if (typeof sizeVal === 'number') {
-            sizeExprFn();
-            ctx.append(' = ');
-            ctx.addValue(sizeVal);
-            return;
-        }
-        const entries = Object.entries(sizeVal).filter(([, v]) => v !== undefined);
+    buildExprComparison(ctx, exprFn, ops, appendOp) {
+        const entries = Object.entries(ops).filter(([, v]) => v !== undefined);
         if (entries.length > 1) {
             ctx.append('(');
         }
@@ -1504,13 +1528,58 @@ export class AbstractSqlDialect extends IndexSqlDialect {
             if (index > 0) {
                 ctx.append(' AND ');
             }
-            sizeExprFn();
-            this.appendSizeOp(ctx, op, val);
+            exprFn();
+            appendOp(op, val);
         });
         if (entries.length > 1) {
             ctx.append(')');
         }
     }
+    /**
+     * Build a complete `$size` comparison expression.
+     * @param sizeExprFn - function that appends the size expression to ctx (e.g. `jsonb_array_length("col")`)
+     */
+    buildSizeComparison(ctx, sizeExprFn, sizeVal) {
+        if (typeof sizeVal === 'number') {
+            sizeExprFn();
+            ctx.append(' = ');
+            ctx.addValue(sizeVal);
+            return;
+        }
+        this.buildExprComparison(ctx, sizeExprFn, sizeVal, (op, val) => this.appendSizeOp(ctx, op, val));
+    }
+    /**
+     * `<distance expr> <op> ?` - the `$where` half of vector search, where `$sort` is the ranking half.
+     *
+     * The bounds are validated here rather than left to the shared renderer, which also knows `$like`
+     * and `$in`; and `$eq`/`$ne` are absent on purpose, since a distance is a float. `/http` casts
+     * client JSON straight to `Query`, so an unknown key has to be refused rather than ignored.
+     */
+    compareVectorNear(ctx, meta, key, near) {
+        const bounds = {};
+        for (const [op, val] of Object.entries(near)) {
+            if (AbstractSqlDialect.VECTOR_QUERY_KEYS.has(op) || val === undefined) {
+                continue;
+            }
+            if (!AbstractSqlDialect.NEAR_BOUND_OPS.has(op)) {
+                throw TypeError(`unsupported $near bound: ${op}`);
+            }
+            bounds[op] = val;
+        }
+        if (!hasKeys(bounds)) {
+            const boundOps = [...AbstractSqlDialect.NEAR_BOUND_OPS].join(', ');
+            throw TypeError(`$near on '${key}' needs a bound (${boundOps}); without one it filters nothing`);
+        }
+        // Required by the type, so this only fires for a query that never met it: `/http` casts client
+        // JSON straight to `Query`. A `$near` never borrows the `$sort`'s vector, which is what keeps the
+        // predicate meaning the same thing in a `count`, or in an entity filter merged into a `$where`.
+        const { $vector, $distance } = near;
+        if (!$vector) {
+            throw TypeError(`$near on '${key}' needs its own $vector`);
+        }
+        const search = { $vector, $distance };
+        this.buildExprComparison(ctx, () => this.appendVectorSort(ctx, meta, key, search), bounds, (op, val) => this.appendOperatorCondition(ctx, '', op, val));
+    }
     /** The runtime half of {@link QuerySizeComparisonOps}: what a count can sensibly be compared with. */
     static SIZE_COMPARE_OPS = new Set([
         '$eq',

package/dist/dialect/aliases.d.ts

@@ -22,6 +22,12 @@ export declare const JSON_PULL_ALIAS = "_uql_pull";
 export declare const REL_TEMP_PREFIX = "_uql_rel_";
 /** The field a ManyToMany lookup nests its target match under, inside the junction's own pipeline. */
 export declare const REL_NESTED_KEY = "_uql_target";
+/**
+ * The alias MySQL's upsert gives the row being inserted, so its `ON DUPLICATE KEY UPDATE`
+ * assignments read `_uql_new.col` instead of the deprecated `VALUES(col)`. MariaDB has no such
+ * syntax and keeps `VALUES(col)`.
+ */
+export declare const UPSERT_NEW_ROW_ALIAS = "_uql_new";
 /**
  * Where a `$sort` by a relation's size parks its tally until the ordering has run. A function, so the
  * `$sort` that names the field and the stage that produces it cannot spell it differently - MongoDB

package/dist/dialect/aliases.js

@@ -22,6 +22,12 @@ export const JSON_PULL_ALIAS = '_uql_pull';
 export const REL_TEMP_PREFIX = '_uql_rel_';
 /** The field a ManyToMany lookup nests its target match under, inside the junction's own pipeline. */
 export const REL_NESTED_KEY = '_uql_target';
+/**
+ * The alias MySQL's upsert gives the row being inserted, so its `ON DUPLICATE KEY UPDATE`
+ * assignments read `_uql_new.col` instead of the deprecated `VALUES(col)`. MariaDB has no such
+ * syntax and keeps `VALUES(col)`.
+ */
+export const UPSERT_NEW_ROW_ALIAS = '_uql_new';
 /**
  * Where a `$sort` by a relation's size parks its tally until the ordering has run. A function, so the
  * `$sort` that names the field and the stage that produces it cannot spell it differently - MongoDB

package/dist/dialect/index.d.ts

@@ -1,9 +1,4 @@
-export { MariaDialect } from '../maria/mariaDialect.js';
-export { MySqlDialect } from '../mysql/mysqlDialect.js';
-export { PostgresDialect } from '../postgres/postgresDialect.js';
-export { SqliteDialect } from '../sqlite/sqliteDialect.js';
 export * from './abstractDialect.js';
 export * from './abstractSqlDialect.js';
-export * from './indexSqlDialect.js';
 export * from './mysqlLikeSqlDialect.js';
 export * from './queryContext.js';

package/dist/dialect/index.js

@@ -1,9 +1,6 @@
-export { MariaDialect } from '../maria/mariaDialect.js';
-export { MySqlDialect } from '../mysql/mysqlDialect.js';
-export { PostgresDialect } from '../postgres/postgresDialect.js';
-export { SqliteDialect } from '../sqlite/sqliteDialect.js';
+// The concrete dialects are behind their own entries (`uql-orm/postgres`, `/mysql`, `/maria`,
+// `/sqlite`, `/cockroachdb`): importing the root should not carry four engines' worth of SQL.
 export * from './abstractDialect.js';
 export * from './abstractSqlDialect.js';
-export * from './indexSqlDialect.js';
 export * from './mysqlLikeSqlDialect.js';
 export * from './queryContext.js';

package/dist/dialect/jsonSql.d.ts

@@ -1,4 +1,4 @@
-import type { FieldOptions } from '../type/index.js';
+import type { FieldOptions, FieldType } from '../type/index.js';
 /**
  * A `'$.a.b'` JSON path literal, each dot-separated segment escaped. `suffix` appends an accessor
  * such as `[#]` or `[*]`. Shared across dialects unchanged: no dialect escapes a JSON path key
@@ -21,6 +21,12 @@ export declare function jsonSetTarget(expr: string, field: FieldOptions | undefi
 export declare function jsonRemoveCall(fn: string, expr: string, keys: readonly string[]): string;
 /** `WHERE` is omitted for an empty `$elemMatch`, which asks only that the array has an element. */
 export declare function jsonElemExists(from: string, conditions: readonly string[]): string;
+/**
+ * How a JSON value is read out of its document: as the JSON value itself, as a number to compare
+ * against, or as the text a path yields. One vocabulary for every operand of a comparison, so the
+ * left side is read the way the right side is compared - see {@link jsonCompareMode}.
+ */
+export type JsonAccessMode = 'json' | 'numeric' | 'text';
 /**
  * How a JSON scalar has to be compared against `value` (or, for `$in`/`$nin`, against every element
  * of it). Extracting a JSON value yields *text*, which loses the type, so each operand type is
@@ -33,7 +39,16 @@ export declare function jsonElemExists(from: string, conditions: readonly string
  *
  * Mixed operand types fall back to `text`, since one comparison cannot be two shapes at once.
  */
-export declare function jsonCompareMode(value: unknown): 'json' | 'numeric' | 'text';
+export declare function jsonCompareMode(value: unknown): JsonAccessMode;
+/**
+ * The mode a *declared* type asks for: {@link jsonCompareMode}'s twin, reading the type instead of an
+ * operand. An index over a JSON path is only reachable by a comparison that extracts it the same way,
+ * so the two have to answer alike - which is why they are one pair over one vocabulary.
+ *
+ * Reads the type through `util/field.util`'s predicates, which the dialects already carry: resolving
+ * it through `schema/canonicalType` instead pulls that whole module into every consumer bundle.
+ */
+export declare function jsonTypeMode(type: FieldType): JsonAccessMode;
 /**
  * Whether the operator reads the JSON *value* instead of its text form. The array operators always
  * do. Equality joins them for boolean operands, because extracting JSON as text loses the type in

package/dist/dialect/jsonSql.js

@@ -1,3 +1,4 @@
+import { isBooleanType, isNumericType } from '../util/field.util.js';
 import { escapeSingleQuotes } from '../util/sqlLiteral.js';
 /**
  * A `'$.a.b'` JSON path literal, each dot-separated segment escaped. `suffix` appends an accessor
@@ -56,6 +57,20 @@ export function jsonCompareMode(value) {
     }
     return operands.every((operand) => typeof operand === 'number') ? 'numeric' : 'text';
 }
+/**
+ * The mode a *declared* type asks for: {@link jsonCompareMode}'s twin, reading the type instead of an
+ * operand. An index over a JSON path is only reachable by a comparison that extracts it the same way,
+ * so the two have to answer alike - which is why they are one pair over one vocabulary.
+ *
+ * Reads the type through `util/field.util`'s predicates, which the dialects already carry: resolving
+ * it through `schema/canonicalType` instead pulls that whole module into every consumer bundle.
+ */
+export function jsonTypeMode(type) {
+    if (isNumericType(type)) {
+        return 'numeric';
+    }
+    return isBooleanType(type) ? 'json' : 'text';
+}
 /**
  * Whether the operator reads the JSON *value* instead of its text form. The array operators always
  * do. Equality joins them for boolean operands, because extracting JSON as text loses the type in

package/dist/dialect/mysqlLikeSqlDialect.d.ts

@@ -1,4 +1,4 @@
-import type { DialectFeatures, EntityMeta, FieldOptions, IndexFeature, IndexSchema, InsertIdSource, QueryConflictPaths, QueryContext, QueryPager, QuerySizeComparisonOps, QueryTextSearchOptions, Type } from '../type/index.js';
+import type { DialectFeatures, EntityMeta, FieldOptions, InsertIdSource, QueryConflictPaths, QueryContext, QueryPager, QuerySizeComparisonOps, QueryTextSearchOptions, Type } from '../type/index.js';
 import { AbstractSqlDialect } from './abstractSqlDialect.js';
 /**
  * Shared JSON-array / JSON-object operator implementation between MySQL and MariaDB.
@@ -9,6 +9,9 @@ import { AbstractSqlDialect } from './abstractSqlDialect.js';
  * - `$elemMatch` (JSON_TABLE, or fast JSON_CONTAINS for the simple case)
  * - the update operators `$set` (JSON_SET), `$unset` (JSON_REMOVE), `$push` (JSON_MERGE_PRESERVE)
  *   and `$pull` (JSON_REPLACE over JSON_TABLE)
+ *
+ * Neither has `FOR NO KEY UPDATE`/`FOR KEY SHARE`, PostgreSQL's weaker pair, so asking for one is
+ * rejected rather than served a stronger lock.
  */
 export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
     /** Default {@link DialectFeatures} for MySQL-compatible SQL dialects. */
@@ -40,8 +43,8 @@ export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
      * unique index for you.
      *
      * The update assignments are built into their own context and pushed afterwards, since they read
-     * `VALUES(col)` rather than binding, and any value they *do* bind (an `onUpdate` field absent from the
-     * payload) has to land after the insert's for a `?`-placeholder driver.
+     * the inserted row rather than binding, and any value they *do* bind (an `onUpdate` field absent from
+     * the payload) has to land after the insert's for a `?`-placeholder driver.
      */
     upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[]): void;
     /**
@@ -49,6 +52,13 @@ export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
      * 10.5+ has it, and used to restate this whole method just to add it.
      */
     protected upsertReturning<E>(_entity: Type<E>): string;
+    /**
+     * The alias the inserted row is given after the values list, and read back by the assignments.
+     * Undefined where the dialect has no such syntax - MariaDB, which reads that row through
+     * `VALUE(col)` instead: it renamed `VALUES()` in 10.3.3, the old name clashing with the standard
+     * table value constructors, where MySQL deprecated the function outright in favour of the alias.
+     */
+    protected readonly upsertNewRowAlias: string | undefined;
     readonly maxBindValues: number;
     escape(value: unknown): string;
     /**
@@ -57,17 +67,6 @@ export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
      * `@Index([...], { type: 'fulltext' })`.
      */
     protected appendTextSearch<E>(ctx: QueryContext, _entity: Type<E>, meta: EntityMeta<E>, search: QueryTextSearchOptions<E>): void;
-    /**
-     * A full-text index is its own keyword here (`CREATE FULLTEXT INDEX ... (cols)`); `USING fulltext`
-     * is a syntax error, so it is the keyword that changes rather than the access method.
-     */
-    protected indexKeyword(index: IndexSchema): string;
-    protected readonly indexFeatures: Set<IndexFeature>;
-    /**
-     * No `FOR NO KEY UPDATE`/`FOR KEY SHARE`: those are PostgreSQL's weaker pair and the family has
-     * no equivalent, so asking for one is rejected rather than served a stronger lock.
-     */
-    protected indexAccessMethod(index: IndexSchema): string;
     protected numericCast(expr: string): string;
     protected neExpr(field: string, ph: string): string;
     /** How a surviving element is fed back into the array a `$pull` rebuilds. */

package/dist/dialect/mysqlLikeSqlDialect.js

@@ -15,6 +15,9 @@ const MAX_LIMIT = BigInt.asUintN(64, -1n);
  * - `$elemMatch` (JSON_TABLE, or fast JSON_CONTAINS for the simple case)
  * - the update operators `$set` (JSON_SET), `$unset` (JSON_REMOVE), `$push` (JSON_MERGE_PRESERVE)
  *   and `$pull` (JSON_REPLACE over JSON_TABLE)
+ *
+ * Neither has `FOR NO KEY UPDATE`/`FOR KEY SHARE`, PostgreSQL's weaker pair, so asking for one is
+ * rejected rather than served a stronger lock.
  */
 export class MysqlLikeSqlDialect extends AbstractSqlDialect {
     /** Default {@link DialectFeatures} for MySQL-compatible SQL dialects. */
@@ -29,7 +32,7 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
         renameColumn: true,
         foreignKeyAlter: true,
         columnComment: true,
-        inlineVectorIndex: false,
+        vectorIndexRequiresNotNull: false,
         vectorSupportsLength: false,
         supportsTimestamptz: false,
         defaultStringAsText: false,
@@ -80,17 +83,18 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
      * unique index for you.
      *
      * The update assignments are built into their own context and pushed afterwards, since they read
-     * `VALUES(col)` rather than binding, and any value they *do* bind (an `onUpdate` field absent from the
-     * payload) has to land after the insert's for a `?`-placeholder driver.
+     * the inserted row rather than binding, and any value they *do* bind (an `onUpdate` field absent from
+     * the payload) has to land after the insert's for a `?`-placeholder driver.
      */
     upsert(ctx, entity, conflictPaths, payload) {
         const meta = getMeta(entity);
+        const alias = this.upsertNewRowAlias && this.escapeId(this.upsertNewRowAlias, true);
         const updateCtx = this.createContext();
-        const update = this.getUpsertUpdateAssignments(updateCtx, meta, conflictPaths, payload, (name) => `VALUES(${name})`);
+        const update = this.getUpsertUpdateAssignments(updateCtx, meta, conflictPaths, payload, (name) => alias ? `${alias}.${name}` : `VALUE(${name})`);
         const returning = this.upsertReturning(entity);
         if (update) {
             this.appendInsertValues(ctx, entity, payload);
-            ctx.append(` ON DUPLICATE KEY UPDATE ${update}${returning}`);
+            ctx.append(`${alias ? ` AS ${alias}` : ''} ON DUPLICATE KEY UPDATE ${update}${returning}`);
             ctx.pushValue(...updateCtx.values);
             return;
         }
@@ -107,6 +111,13 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
     upsertReturning(_entity) {
         return '';
     }
+    /**
+     * The alias the inserted row is given after the values list, and read back by the assignments.
+     * Undefined where the dialect has no such syntax - MariaDB, which reads that row through
+     * `VALUE(col)` instead: it renamed `VALUES()` in 10.3.3, the old name clashing with the standard
+     * table value constructors, where MySQL deprecated the function outright in favour of the alias.
+     */
+    upsertNewRowAlias = undefined;
     maxBindValues = 65535;
     escape(value) {
         return escapeMysqlSqlLiteral(value);
@@ -123,21 +134,6 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
         ctx.addValue(search.$value);
         ctx.append(')');
     }
-    /**
-     * A full-text index is its own keyword here (`CREATE FULLTEXT INDEX ... (cols)`); `USING fulltext`
-     * is a syntax error, so it is the keyword that changes rather than the access method.
-     */
-    indexKeyword(index) {
-        return index.type === 'fulltext' ? 'FULLTEXT INDEX' : super.indexKeyword(index);
-    }
-    indexFeatures = new Set(['expression', 'prefixLength']);
-    /**
-     * No `FOR NO KEY UPDATE`/`FOR KEY SHARE`: those are PostgreSQL's weaker pair and the family has
-     * no equivalent, so asking for one is rejected rather than served a stronger lock.
-     */
-    indexAccessMethod(index) {
-        return index.type && index.type !== 'fulltext' ? ` USING ${index.type}` : '';
-    }
     numericCast(expr) {
         return `CAST(${expr} AS DECIMAL)`;
     }

package/dist/dialect/pgLikeSqlDialect.d.ts

@@ -1,4 +1,4 @@
-import { type DialectFeatures, type EntityMeta, type FieldOptions, type IndexColumnSchema, type IndexFeature, type IndexSchema, type JsonColumnType, type QueryContext, type QuerySizeComparisonOps, type QueryTextSearchOptions, type QueryVectorSearch, type Type, type VectorDistance } from '../type/index.js';
+import { type DialectFeatures, type EntityMeta, type FieldOptions, type JsonColumnType, type Query, type QueryContext, type QuerySizeComparisonOps, type QueryTextSearchOptions, type Type, type VectorDistance, type VectorOperatorMetric } from '../type/index.js';
 import { AbstractSqlDialect } from './abstractSqlDialect.js';
 /**
  * Shared AST/quoting/JSONB/full-text-search/vector-search implementation between Postgres and
@@ -30,25 +30,24 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
      * place so a dialect cannot end up with the operator but not the opclass. The key set is the single
      * source of truth for which metrics the dialect supports at all: CockroachDB narrows it to three.
      */
-    readonly vectorMetrics: ReadonlyMap<VectorDistance, {
-        op: string;
-        opsSuffix: string;
-    }>;
-    normalizeValue(value: unknown): unknown;
-    /** pgvector's own index types; CockroachDB's native one widens this. */
-    protected isVectorIndex(index: IndexSchema): boolean;
-    protected indexAccessMethod(index: IndexSchema): string;
-    protected readonly indexFeatures: Set<IndexFeature>;
+    readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorOperatorMetric>;
+    /** `SET LOCAL` applies to the enclosing transaction and to nothing at all without one. */
+    readonly 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.
+     */
+    private static readonly ANN_SETTINGS;
     /**
-     * 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.
      */
-    protected indexColumnOpsClass(entry: IndexColumnSchema, index: IndexSchema): string;
-    protected indexInclude(index: IndexSchema): string;
-    protected indexTuning(index: IndexSchema): string;
+    vectorTuningStatements<E>(meta: EntityMeta<E>, q: Query<E>): readonly string[];
+    normalizeValue(value: unknown): unknown;
     placeholder(index: number): string;
     /**
      * `to_tsvector(...) @@ websearch_to_tsquery(...)`. `websearch_to_tsquery` takes free-form user input
@@ -90,6 +89,4 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
      * Helper to add a JSON value to context with appropriate stringification and cast.
      */
     private jsonVal;
-    /** Emit a pgvector-style distance expression: `"col" <op> $N::<vectorType>`. */
-    protected appendVectorSort<E>(ctx: QueryContext, meta: EntityMeta<E>, key: string, search: QueryVectorSearch): void;
 }