uql-orm 0.67.0 → 0.68.0

package/dist/dialect/pgLikeSqlDialect.js

@@ -5,8 +5,14 @@ import { AbstractSqlDialect } from './abstractSqlDialect.js';
 import { JSON_PULL_ALIAS, RELATION_ROW_ALIAS } from './aliases.js';
 import { BYTES_PREFIX } from './hydrateColumn.js';
 import { jsonSetTarget } from './jsonSql.js';
-import { PG_VECTOR_METRICS } from './pgVectorMetrics.js';
 import { resolveVectorCast, toSparsevecLiteral } from './vectorCast.js';
+/** Each metric's pgvector distance operator, and the infix of the operator class its index is built with. */
+export const PG_VECTOR_METRICS = new Map([
+    ['cosine', { op: '<=>', index: 'cosine' }],
+    ['l2', { op: '<->', index: 'l2' }],
+    ['inner', { op: '<#>', index: 'ip' }],
+    ['l1', { op: '<+>', index: 'l1' }],
+]);
 /** What the Postgres-wire engines have. */
 export const PG_FEATURES = {
     ifNotExists: true,
@@ -28,8 +34,6 @@ export const PG_FEATURES = {
     rowLockOf: true,
     orderedUpsertReturning: true,
     orderedJsonAggregates: true,
-    partialJsonContainment: true,
-    typedJsonElements: false,
     narrowVectorTypes: false,
     vectorTuningNeedsTransaction: true,
     serialDeclaresPrimaryKey: false,
@@ -130,25 +134,44 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
         ctx.addValue(search.$value);
         ctx.append(')');
     }
-    jsonAll(ctx, jsonField, value) {
-        return `${jsonField} @> ${this.jsonVal(ctx, value)}`;
+    jsonContains(ctx, slot, values) {
+        return `${this.jsonValue(slot)} @> ${this.jsonVal(ctx, values)}`;
     }
-    jsonSize(ctx, jsonField, value) {
-        return this.buildFragment(ctx, (fragmentCtx) => this.buildSizeComparison(fragmentCtx, () => fragmentCtx.append(`JSONB_ARRAY_LENGTH(${jsonField})`), value));
+    jsonLength(slot) {
+        return `JSONB_ARRAY_LENGTH(${this.jsonArray(slot)})`;
     }
-    /**
-     * Object elements stay `jsonb` so each field can pick `->` or `->>`. Scalar elements are exploded
-     * as text unless they are compared as JSON, where `_text` would yield `text = jsonb`.
-     */
-    jsonElemFrom(jsonField, fields, alias, asJson = false) {
-        const fn = fields.length || asJson ? 'JSONB_ARRAY_ELEMENTS' : 'JSONB_ARRAY_ELEMENTS_TEXT';
-        return `${fn}(${jsonField}) AS ${alias}`;
+    /** Each element stays `jsonb`, so it is read as any path is: `->` for the value, `->>` for its text. */
+    jsonElemFrom(slot, alias) {
+        return `JSONB_ARRAY_ELEMENTS(${this.jsonArray(slot)}) AS ${alias}`;
+    }
+    jsonIsArray(slot) {
+        return `JSONB_TYPEOF(${this.jsonValue(slot)}) = 'array'`;
+    }
+    /** The array at `slot`, NULL where the value there is none: the array functions fail the whole read on one. */
+    jsonArray(slot) {
+        return `CASE WHEN ${this.jsonIsArray(slot)} THEN ${this.jsonValue(slot)} END`;
+    }
+    jsonElemDoc(alias) {
+        return alias;
     }
-    jsonElemRef(alias, field, asJson = false) {
-        if (field === undefined) {
-            return alias;
+    /** `->` down the path and `->>` for its text, the document's own text being `#>> '{}'`. */
+    jsonPathReading(escapedColumn, path, mode) {
+        if (!path) {
+            return mode === 'json' ? escapedColumn : `(${escapedColumn} #>> '{}')`;
         }
-        return asJson ? `${alias}->'${escapeSingleQuotes(field)}'` : `${alias}->>'${escapeSingleQuotes(field)}'`;
+        const segments = path.split('.');
+        return segments.reduce((expr, segment, index) => {
+            const op = mode === 'text' && index === segments.length - 1 ? '->>' : '->';
+            return `(${expr}${op}'${escapeSingleQuotes(segment)}')`;
+        }, escapedColumn);
+    }
+    /** A number only where the value is one: the cast throws on any other text, failing the whole read. */
+    jsonPathExpr(escapedColumn, path, mode) {
+        const read = super.jsonPathExpr(escapedColumn, path, mode);
+        if (mode !== 'numeric') {
+            return read;
+        }
+        return `CASE WHEN JSONB_TYPEOF(${this.jsonValue({ base: escapedColumn, path })}) = 'number' THEN ${read} END`;
     }
     get regexpOp() {
         return '~';
@@ -157,10 +180,13 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
     get neOp() {
         return 'IS DISTINCT FROM';
     }
-    /** One array parameter, which a context that inlines values has none of: it lists them instead. */
-    formatIn(ctx, operand, values, negate) {
+    /**
+     * One array parameter, which a context that inlines values has none of: it lists them instead. The
+     * array takes its type from `operand`, so it needs none of the casts `bind` would give each value.
+     */
+    formatIn(ctx, operand, values, negate, bind) {
         if (!values.length || ctx.inlineValues) {
-            return super.formatIn(ctx, operand, values, negate);
+            return super.formatIn(ctx, operand, values, negate, bind);
         }
         const ph = this.addValue(ctx, values);
         return negate ? `${operand} <> ALL(${ph})` : `${operand} = ANY(${ph})`;
@@ -181,13 +207,14 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
         ctx.append(`::${vectorType}`);
     }
     /**
-     * `create_if_missing => false` keeps an absent key (and a NULL column) untouched; `WITH
-     * ORDINALITY` keeps the surviving elements in their original order.
+     * `create_if_missing => false` keeps an absent key (and a NULL column) untouched, and a value that is no
+     * array is set back as it is; `WITH ORDINALITY` keeps the surviving elements in their original order.
      */
     jsonPullKey(ctx, expr, escapedCol, key, value) {
-        const escapedKey = escapeSingleQuotes(key);
-        const kept = `SELECT JSONB_AGG(${JSON_PULL_ALIAS}.val ORDER BY ${JSON_PULL_ALIAS}.ord) FROM JSONB_ARRAY_ELEMENTS(${escapedCol}->'${escapedKey}') WITH ORDINALITY AS ${JSON_PULL_ALIAS}(val, ord) WHERE ${JSON_PULL_ALIAS}.val <> ${this.jsonVal(ctx, value)}`;
-        return `JSONB_SET(${expr}, '{${escapedKey}}', COALESCE((${kept}), '[]'::jsonb), false)`;
+        const slot = { base: escapedCol, path: key };
+        const kept = `SELECT JSONB_AGG(${JSON_PULL_ALIAS}.val ORDER BY ${JSON_PULL_ALIAS}.ord) FROM JSONB_ARRAY_ELEMENTS(${this.jsonValue(slot)}) WITH ORDINALITY AS ${JSON_PULL_ALIAS}(val, ord) WHERE ${JSON_PULL_ALIAS}.val <> ${this.jsonVal(ctx, value)}`;
+        const pulled = `CASE WHEN ${this.jsonIsArray(slot)} THEN COALESCE((${kept}), '[]'::jsonb) ELSE COALESCE(${this.jsonValue(slot)}, 'null') END`;
+        return `JSONB_SET(${expr}, '{${escapeSingleQuotes(key)}}', ${pulled}, false)`;
     }
     /**
      * The plain values merge as one bound object; a `raw()` one is an SQL expression rather than JSON,

package/dist/dialect/vectorCast.d.ts

@@ -20,3 +20,5 @@ 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;
+/** Packed little-endian float32s, each read as {@link shortestFloat32}. */
+export declare function decodeFloat32s(bytes: Uint8Array): number[];

package/dist/dialect/vectorCast.js

@@ -17,11 +17,8 @@ export function resolveVectorCast(field) {
  * declaring `type: 'sparsevec'` still hands UQL the dense array its field type promises.
  */
 export function toSparsevecLiteral(values) {
-    const pairs = values
-        .map((value, index) => `${index + 1}:${value}`)
-        .filter((_, index) => Number(values[index]) !== 0)
-        .join(',');
-    return `{${pairs}}/${values.length}`;
+    const pairs = values.flatMap((value, index) => (Number(value) === 0 ? [] : [`${index + 1}:${value}`]));
+    return `{${pairs.join(',')}}/${values.length}`;
 }
 /**
  * A vector column's text as the dense array its field promises (pgvector returns text), read by `cast`
@@ -65,3 +62,26 @@ function parseDense(text) {
         return undefined;
     }
 }
+/** Packed little-endian float32s, each read as {@link shortestFloat32}. */
+export function decodeFloat32s(bytes) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    return Array.from({ length: bytes.byteLength / 4 }, (_, at) => shortestFloat32(view.getFloat32(at * 4, true)));
+}
+/**
+ * `value` in the fewest significant digits that read back to it as a float32, by bisection: nine always
+ * do, and a count past one that does nearly always does too, so at worst it keeps a digit it could drop.
+ */
+function shortestFloat32(value) {
+    let low = 1;
+    let high = 9;
+    while (low < high) {
+        const mid = (low + high) >> 1;
+        if (Math.fround(Number(value.toPrecision(mid))) === value) {
+            high = mid;
+        }
+        else {
+            low = mid + 1;
+        }
+    }
+    return Number(value.toPrecision(low));
+}

package/dist/dialect/vectorSqlDialect.d.ts

@@ -21,18 +21,18 @@ export declare abstract class VectorSqlDialect extends AbstractDialect {
      */
     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.
+     * 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>;
     /** Quotes an identifier; supplied by the SQL dialect built on top of this layer. */
     abstract escapeId(val: string | undefined, forbidQualified?: boolean, addDot?: boolean): string;
     /**
-     * Resolve common parameters for a vector similarity ORDER BY expression.
-     * Shared by all dialect overrides of `appendVectorSort`.
+     * 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.
      */
-    protected resolveVectorSortParams<E>(meta: EntityMeta<E>, key: string, search: QueryVectorSearch): {
+    protected resolveVectorDistance<E>(meta: EntityMeta<E>, key: string, search: QueryVectorSearch): {
         colName: string;
         distance: VectorDistance;
         field: FieldOptions | undefined;
@@ -49,12 +49,12 @@ export declare abstract class VectorSqlDialect extends AbstractDialect {
     supportedVectorType(cast: VectorCast): VectorCast;
     /**
      * The distance a vector `$sort` projects, which the projection names after `$project`. Delegates to
-     * `appendVectorSort` so each dialect's distance syntax is written once.
+     * `appendVectorDistance` so each dialect's distance syntax is written once.
      */
     protected appendVectorProjection<E>(ctx: QueryContext, meta: EntityMeta<E>, key: string, search: QueryVectorSearch): void;
     /**
      * 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;
+    protected appendVectorDistance<E>(ctx: QueryContext, meta: EntityMeta<E>, key: string, search: QueryVectorSearch): void;
 }

package/dist/dialect/vectorSqlDialect.js

@@ -35,19 +35,19 @@ export class VectorSqlDialect extends AbstractDialect {
         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.
+     * 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();
     /**
-     * Resolve common parameters for a vector similarity ORDER BY expression.
-     * Shared by all dialect overrides of `appendVectorSort`.
+     * 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.
      */
-    resolveVectorSortParams(meta, key, search) {
+    resolveVectorDistance(meta, key, search) {
         const field = meta.fields[key];
         const colName = this.resolveColumnName(key, field);
-        const distance = search.$distance ?? field?.distance ?? 'cosine';
+        const distance = search.$distance ?? field?.distance ?? findVectorIndex(meta, key)?.distance ?? 'cosine';
         return { colName, distance, field };
     }
     /**
@@ -66,7 +66,7 @@ export class VectorSqlDialect extends AbstractDialect {
     }
     /**
      * The distance a vector `$sort` projects, which the projection names after `$project`. Delegates to
-     * `appendVectorSort` so each dialect's distance syntax is written once.
+     * `appendVectorDistance` so each dialect's distance syntax is written once.
      */
     appendVectorProjection(ctx, meta, key, search) {
         const alias = search.$project;
@@ -76,17 +76,17 @@ export class VectorSqlDialect extends AbstractDialect {
         if (meta.fields[alias]) {
             throw new TypeError(`$project '${alias}' collides with a field of '${entityName(meta)}'`);
         }
-        this.appendVectorSort(ctx, meta, key, search);
+        this.appendVectorDistance(ctx, meta, key, search);
     }
     /**
      * 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) {
+    appendVectorDistance(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 { colName, distance, field } = this.resolveVectorDistance(meta, key, search);
         const metric = this.vectorMetrics.get(distance);
         if (!metric) {
             throw unsupportedVectorMetric(this.dialectName, distance);

package/dist/index.d.ts

@@ -5,5 +5,6 @@ export * from './namingStrategy/index.js';
 export * from './querier/index.js';
 export * from './type/index.js';
 export { withDeleted } from './util/filters.util.js';
+export type { HookContext } from './util/hook.util.js';
 export { DefaultLogger } from './util/logger.js';
 export { raw, refs } from './util/raw.js';

package/dist/maria/mariaDialect.d.ts

@@ -1,4 +1,5 @@
 import { type RelationRows } from '../dialect/abstractSqlDialect.js';
+import { type JsonAccessMode } from '../dialect/jsonSql.js';
 import { MysqlLikeSqlDialect } from '../dialect/mysqlLikeSqlDialect.js';
 import type { EntityMeta, FieldOptions, Query, QueryContext, SqlDialectFeatures, Type, VectorDistance, VectorMetric } from '../type/index.js';
 export declare class MariaDialect extends MysqlLikeSqlDialect {
@@ -16,21 +17,22 @@ export declare class MariaDialect extends MysqlLikeSqlDialect {
     protected appendRelationArray(ctx: QueryContext, { entity, query, alias, joins }: RelationRows): void;
     protected upsertReturning<E>(meta: EntityMeta<E>): string;
     /**
-     * MariaDB supports neither MySQL's `->`/`->>` shorthand nor the base's chained form. `JSON_VALUE`
-     * reads a scalar and `JSON_EXTRACT` the subtree that the array operators need.
+     * `JSON_EXTRACT` for the value and `JSON_VALUE` for its text, which every version has: MySQL's `->`/`->>`
+     * arrive only in 13.1.
      */
-    protected getJsonPathScalarExpr(escapedColumn: string, jsonPathStr: string): string;
-    protected getJsonPathJsonbExpr(escapedColumn: string, jsonPathStr: string): string;
+    protected jsonPathReading(escapedColumn: string, path: string, mode: 'json' | 'text'): string;
+    /** MariaDB orders JSON as the text it stores, so a number sorts by its value first. */
+    protected readonly jsonSortModes: readonly JsonAccessMode[];
     /** MariaDB has no `CAST(val AS JSON)`; `JSON_EXTRACT` at the root reads a value as JSON. */
     protected jsonCast(operand: string): string;
     /**
-     * MariaDB stores JSON as text, so JSON_ARRAYAGG would re-quote each element into a string
-     * (`["\"a\""]`). JSON_COMPACT marks it back as JSON, keeping element types intact.
+     * MariaDB stores JSON as text, so `JSON_ARRAYAGG` would re-quote each element into a string
+     * (`["\"a\""]`); `JSON_COMPACT` marks it back as JSON, keeping its type.
      */
-    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;
-    /** `VEC_DISTANCE_COSINE`/`VEC_DISTANCE_EUCLIDEAN`, 11.7+: the metric's own name, uppercased. */
+    protected jsonArrayOf(elem: string): string;
+    /** Text-backed JSON compares as text, so `JSON_EQUALS` compares it as JSON, key order aside. */
+    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
@@ -47,6 +49,9 @@ export declare class MariaDialect extends MysqlLikeSqlDialect {
     protected statementSettings<E>(entity: Type<E>, q: Query<E>): string[];
     /** `SET STATEMENT ... FOR`, which scopes a variable to the statement it prefixes. */
     protected applySettings(sql: string, settings: readonly string[]): string;
-    /** The reverse: selecting a `VECTOR` column raw yields that blob, so it is read back as text. */
+    /**
+     * The reverse: a `VECTOR` column reads back as its packed bytes in hex, which every driver hands over
+     * alike, and never through `VEC_ToText`, which keeps six of the nine digits a float32 needs.
+     */
     protected selectFieldExpr(escapedColumn: string, field: FieldOptions): string;
 }

package/dist/maria/mariaDialect.js

@@ -3,7 +3,6 @@ import { jsonPath } from '../dialect/jsonSql.js';
 import { MYSQL_FEATURES, MysqlLikeSqlDialect } from '../dialect/mysqlLikeSqlDialect.js';
 import { getMeta } from '../entity/index.js';
 import { columnFamily } from '../util/field.util.js';
-import { MARIA_VECTOR_METRICS } from './mariaVectorMetrics.js';
 export class MariaDialect extends MysqlLikeSqlDialect {
     dialectName = 'mariadb';
     // MariaDB 10.5+ has `INSERT ... RETURNING`, so ids come back exact per row - the upsert's too.
@@ -42,32 +41,34 @@ export class MariaDialect extends MysqlLikeSqlDialect {
         return returning ? ` ${returning}` : '';
     }
     /**
-     * MariaDB supports neither MySQL's `->`/`->>` shorthand nor the base's chained form. `JSON_VALUE`
-     * reads a scalar and `JSON_EXTRACT` the subtree that the array operators need.
+     * `JSON_EXTRACT` for the value and `JSON_VALUE` for its text, which every version has: MySQL's `->`/`->>`
+     * arrive only in 13.1.
      */
-    getJsonPathScalarExpr(escapedColumn, jsonPathStr) {
-        return `JSON_VALUE(${escapedColumn}, ${jsonPath(jsonPathStr)})`;
-    }
-    getJsonPathJsonbExpr(escapedColumn, jsonPathStr) {
-        return `JSON_EXTRACT(${escapedColumn}, ${jsonPath(jsonPathStr)})`;
+    jsonPathReading(escapedColumn, path, mode) {
+        return `${mode === 'json' ? 'JSON_EXTRACT' : 'JSON_VALUE'}(${escapedColumn}, ${jsonPath(path)})`;
     }
+    /** MariaDB orders JSON as the text it stores, so a number sorts by its value first. */
+    jsonSortModes = ['numeric', 'text'];
     /** MariaDB has no `CAST(val AS JSON)`; `JSON_EXTRACT` at the root reads a value as JSON. */
     jsonCast(operand) {
         return `JSON_EXTRACT(${operand}, '$')`;
     }
     /**
-     * MariaDB stores JSON as text, so JSON_ARRAYAGG would re-quote each element into a string
-     * (`["\"a\""]`). JSON_COMPACT marks it back as JSON, keeping element types intact.
+     * MariaDB stores JSON as text, so `JSON_ARRAYAGG` would re-quote each element into a string
+     * (`["\"a\""]`); `JSON_COMPACT` marks it back as JSON, keeping its type.
      */
-    jsonPullElem(alias) {
-        return `JSON_COMPACT(${alias}.v)`;
+    jsonArrayOf(elem) {
+        return super.jsonArrayOf(`JSON_COMPACT(${elem})`);
     }
-    /** Text-backed JSON compares as text, so use JSON_EQUALS for key-order-independent equality. */
-    jsonPullKeep(alias, operand) {
-        return `NOT JSON_EQUALS(${alias}.v, ${operand})`;
+    /** Text-backed JSON compares as text, so `JSON_EQUALS` compares it as JSON, key order aside. */
+    jsonDiffers(elem, operand) {
+        return `NOT JSON_EQUALS(${elem}, ${operand})`;
     }
-    /** `VEC_DISTANCE_COSINE`/`VEC_DISTANCE_EUCLIDEAN`, 11.7+: the metric's own name, uppercased. */
-    vectorMetrics = new Map([...MARIA_VECTOR_METRICS].map(([metric, name]) => [metric, { fn: `VEC_DISTANCE_${name.toUpperCase()}` }]));
+    /** `VEC_DISTANCE_COSINE`/`VEC_DISTANCE_EUCLIDEAN`, 11.7+, which the index's `DISTANCE=` names alike. */
+    vectorMetrics = new Map([
+        ['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
@@ -94,8 +95,11 @@ export class MariaDialect extends MysqlLikeSqlDialect {
     applySettings(sql, settings) {
         return `SET STATEMENT ${settings.join(', ')} FOR ${sql}`;
     }
-    /** The reverse: selecting a `VECTOR` column raw yields that blob, so it is read back as text. */
+    /**
+     * The reverse: a `VECTOR` column reads back as its packed bytes in hex, which every driver hands over
+     * alike, and never through `VEC_ToText`, which keeps six of the nine digits a float32 needs.
+     */
     selectFieldExpr(escapedColumn, field) {
-        return columnFamily(field.type) === 'vector' ? `VEC_ToText(${escapedColumn})` : escapedColumn;
+        return columnFamily(field.type) === 'vector' ? this.bytesAsText(escapedColumn) : escapedColumn;
     }
 }

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

@@ -1,6 +1,6 @@
 import type { AbstractSqlDialect } from '../../dialect/abstractSqlDialect.js';
 import { type IndexType } from '../../schema/types.js';
-import { type IndexColumnSchema, type IndexFeature, type IndexJsonArray, type IndexSchema } from '../../type/index.js';
+import { type IndexColumnSchema, type IndexFeature, type IndexJsonArray, type IndexJsonPath, type IndexSchema } from '../../type/index.js';
 /** Refuses an index of a type `types` lacks, `hints` naming what to declare instead. */
 export declare function assertIndexType(index: IndexSchema, types: ReadonlySet<IndexType>, dialectName: string, hints?: ReadonlyMap<IndexType, string>): void;
 /** Refuses an index asking for a feature `features` lacks. */
@@ -46,6 +46,8 @@ export declare class IndexDdl<D extends AbstractSqlDialect = AbstractSqlDialect>
      * expression compiled from the path rather than written out by the caller.
      */
     protected indexColumnTarget(entry: IndexColumnSchema): string;
+    /** The path read the way a query comparing it reads it, which is how the planner matches the two. */
+    protected jsonPathIndexExpr(escapedColumn: string, json: IndexJsonPath): string;
     /**
      * One key per *element* of the JSON array, which is MySQL's multi-valued index and nothing else's -
      * every other dialect refuses `jsonArray` in {@link assertIndexFeatures} and never reaches this.

package/dist/migrate/ddl/indexDdl.js

@@ -94,13 +94,17 @@ export class IndexDdl {
         }
         const column = this.dialect.escapeId(entry.column);
         if (entry.jsonPath) {
-            return `(${this.dialect.jsonPathExpr(column, entry.jsonPath.path, jsonTypeMode(entry.jsonPath.type))})`;
+            return `(${this.jsonPathIndexExpr(column, entry.jsonPath)})`;
         }
         if (entry.jsonArray) {
             return `(${this.jsonArrayIndexExpr(column, entry.jsonArray)})`;
         }
         return entry.length === undefined ? column : `${column}(${entry.length})`;
     }
+    /** The path read the way a query comparing it reads it, which is how the planner matches the two. */
+    jsonPathIndexExpr(escapedColumn, json) {
+        return this.dialect.jsonPathExpr(escapedColumn, json.path, jsonTypeMode(json.type));
+    }
     /**
      * One key per *element* of the JSON array, which is MySQL's multi-valued index and nothing else's -
      * every other dialect refuses `jsonArray` in {@link assertIndexFeatures} and never reaches this.

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

@@ -1,5 +1,5 @@
 import type { IndexType } from '../../schema/types.js';
-import type { IndexJsonArray, IndexSchema } from '../../type/index.js';
+import type { IndexJsonArray, IndexJsonPath, IndexSchema } from '../../type/index.js';
 import { IndexDdl } from './indexDdl.js';
 /** `CREATE INDEX ... (cols) USING btree`, plus the types this family spells as a keyword instead. */
 export declare class MysqlLikeIndexDdl extends IndexDdl {
@@ -10,8 +10,13 @@ export declare class MysqlLikeIndexDdl extends IndexDdl {
     protected indexTuning(index: IndexSchema): string;
 }
 export declare class MySqlIndexDdl extends MysqlLikeIndexDdl {
-    /** The multi-valued index is the only JSON index MySQL has - see `IndexFeature` for why. */
     protected readonly indexFeatures: Set<"expression" | "include" | "jsonArray" | "jsonPath" | "nullsOrder" | "opsClass" | "partial" | "prefixLength">;
+    /**
+     * A number as the query reads it. A string as `CHAR(n)` in the collation `->>` returns, which the
+     * planner strips back to the bare `->>` a query compares; any other collation leaves it unused. A
+     * boolean compares as JSON, which no key part can hold.
+     */
+    protected jsonPathIndexExpr(escapedColumn: string, json: IndexJsonPath): string;
     /**
      * `CAST(col AS CHAR(64) ARRAY)`, over the column itself where the array is the whole document -
      * which is what `$all` reads, and what its `JSON_CONTAINS(col, ?)` is matched against. A `path`

package/dist/migrate/ddl/mysqlIndexDdl.js

@@ -1,5 +1,4 @@
-import { jsonPath } from '../../dialect/jsonSql.js';
-import { MARIA_VECTOR_METRICS } from '../../maria/mariaVectorMetrics.js';
+import { jsonTypeMode } from '../../dialect/jsonSql.js';
 import { unsupportedVectorMetric, VECTOR_INDEX_TYPES } from '../../type/vector.js';
 import { IndexDdl } from './indexDdl.js';
 /**
@@ -18,15 +17,38 @@ export class MysqlLikeIndexDdl extends IndexDdl {
     }
 }
 export class MySqlIndexDdl extends MysqlLikeIndexDdl {
-    /** The multi-valued index is the only JSON index MySQL has - see `IndexFeature` for why. */
-    indexFeatures = new Set(['expression', 'prefixLength', 'jsonArray']);
+    indexFeatures = new Set([
+        'expression',
+        'prefixLength',
+        'jsonPath',
+        'jsonArray',
+    ]);
+    /**
+     * A number as the query reads it. A string as `CHAR(n)` in the collation `->>` returns, which the
+     * planner strips back to the bare `->>` a query compares; any other collation leaves it unused. A
+     * boolean compares as JSON, which no key part can hold.
+     */
+    jsonPathIndexExpr(escapedColumn, json) {
+        const mode = jsonTypeMode(json.type);
+        if (mode === 'json') {
+            throw new TypeError(`mysql cannot index the boolean JSON path '${json.path}', which compares as JSON`);
+        }
+        const expr = super.jsonPathIndexExpr(escapedColumn, json);
+        if (mode === 'numeric') {
+            return expr;
+        }
+        if (!json.length) {
+            throw new TypeError(`a MySQL index over the string JSON path '${json.path}' needs a length`);
+        }
+        return `CAST(${expr} AS CHAR(${json.length}) CHARACTER SET utf8mb4) COLLATE utf8mb4_bin`;
+    }
     /**
      * `CAST(col AS CHAR(64) ARRAY)`, over the column itself where the array is the whole document -
      * which is what `$all` reads, and what its `JSON_CONTAINS(col, ?)` is matched against. A `path`
      * indexes the array at that path instead, as `'tags.ids': { $all: [...] }` reads it.
      */
     jsonArrayIndexExpr(escapedColumn, json) {
-        const source = json.path ? `${escapedColumn}->${jsonPath(json.path)}` : escapedColumn;
+        const source = json.path ? this.dialect.jsonPathExpr(escapedColumn, json.path, 'json') : escapedColumn;
         return `CAST(${source} AS ${arrayCastType(json)} ARRAY)`;
     }
     /**
@@ -61,7 +83,7 @@ export class MariaIndexDdl extends MysqlLikeIndexDdl {
     indexTuning(index) {
         let tuning = super.indexTuning(index) + (index.m === undefined ? '' : ` M=${index.m}`);
         if (index.distance) {
-            const metric = MARIA_VECTOR_METRICS.get(index.distance);
+            const metric = this.dialect.vectorMetrics.get(index.distance)?.index;
             if (!metric) {
                 throw unsupportedVectorMetric(this.dialect.dialectName, index.distance, index.name);
             }

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

@@ -6,11 +6,6 @@ export declare class PgIndexDdl extends IndexDdl {
     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">;
-    /** The metrics its vector index takes, each naming the operator class it is built with. */
-    protected readonly vectorMetrics: ReadonlyMap<import("../../type/vector.js").VectorDistance, {
-        readonly op: string;
-        readonly opsSuffix: string;
-    }>;
     /** pgvector's own index types; CockroachDB's native one widens this. */
     protected isVectorIndex(index: IndexSchema): boolean;
     protected indexAccessMethod(index: IndexSchema): string;
@@ -28,10 +23,6 @@ export declare class CockroachIndexDdl extends PgIndexDdl {
     /** v26.3 answers `hash` and `brin` "unimplemented", `ivfflat` "unrecognized"; `hnsw` builds its vector index. */
     protected readonly indexTypes: Set<"brin" | "btree" | "fulltext" | "gin" | "gist" | "hash" | "hnsw" | "ivfflat" | "vector" | "vectorSearch">;
     protected readonly indexTypeHints: Map<"brin" | "btree" | "fulltext" | "gin" | "gist" | "hash" | "hnsw" | "ivfflat" | "vector" | "vectorSearch", string>;
-    protected readonly vectorMetrics: ReadonlyMap<import("../../type/vector.js").VectorDistance, {
-        readonly op: string;
-        readonly opsSuffix: string;
-    }>;
     private isNativeVectorIndex;
     protected isVectorIndex(index: IndexSchema): boolean;
     protected indexKeyword(index: IndexSchema): string;

package/dist/migrate/ddl/pgIndexDdl.js

@@ -1,4 +1,3 @@
-import { COCKROACH_VECTOR_METRICS, PG_VECTOR_METRICS } from '../../dialect/pgVectorMetrics.js';
 import { unsupportedVectorMetric } from '../../type/vector.js';
 import { IndexDdl } from './indexDdl.js';
 /** `$text` computes its `TO_TSVECTOR` per row, which no index over the raw columns serves. */
@@ -26,8 +25,6 @@ export class PgIndexDdl extends IndexDdl {
         'include',
         'jsonPath',
     ]);
-    /** The metrics its vector index takes, each naming the operator class it is built with. */
-    vectorMetrics = PG_VECTOR_METRICS;
     /** pgvector's own index types; CockroachDB's native one widens this. */
     isVectorIndex(index) {
         return index.type === 'hnsw' || index.type === 'ivfflat';
@@ -43,12 +40,12 @@ export class PgIndexDdl extends IndexDdl {
         if (!this.isVectorIndex(index) || !index.distance) {
             return entry.opsClass ? ` ${entry.opsClass}` : '';
         }
-        const metric = this.vectorMetrics.get(index.distance);
+        const metric = this.dialect.vectorMetrics.get(index.distance)?.index;
         if (!metric) {
             throw unsupportedVectorMetric(this.dialect.dialectName, index.distance, index.name);
         }
         const vectorType = this.dialect.supportedVectorType(index.vectorType ?? 'vector');
-        const opsClass = `${vectorType}_${metric.opsSuffix}_ops`;
+        const opsClass = `${vectorType}_${metric}_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`);
@@ -83,7 +80,6 @@ export class CockroachIndexDdl extends PgIndexDdl {
         ...PG_INDEX_TYPE_HINTS,
         ['ivfflat', "; declare type: 'vector' instead"],
     ]);
-    vectorMetrics = COCKROACH_VECTOR_METRICS;
     isNativeVectorIndex(index) {
         return index.type === 'vector';
     }

package/dist/migrate/introspection/abstractSqlSchemaIntrospector.d.ts

@@ -12,6 +12,15 @@ import { BaseSqlIntrospector } from './baseSqlIntrospector.js';
  * it is four avoidable ones.
  */
 export type TableRowReader = <T extends RawRow>(sql: string, params?: unknown[]) => Promise<T[]>;
+/** A foreign key as MySQL and SQL Server list one: a row, its column lists comma-joined. */
+export type JoinedForeignKeyRow = {
+    readonly constraint_name: string;
+    readonly columns: string;
+    readonly referenced_table: string;
+    readonly referenced_columns: string;
+    readonly delete_rule: string;
+    readonly update_rule: string;
+};
 /** A SQL introspector: an engine states its catalogue queries (`get*Query`) and how their rows map (`map*Result`). */
 export declare abstract class AbstractSqlSchemaIntrospector extends BaseSqlIntrospector implements SchemaIntrospector {
     protected readonly pool: QuerierPool;
@@ -48,8 +57,10 @@ export declare abstract class AbstractSqlSchemaIntrospector extends BaseSqlIntro
     protected getIndexesParams(tableName: string): unknown[];
     protected getForeignKeysParams(tableName: string): unknown[];
     protected getPrimaryKeyParams(tableName: string): unknown[];
-    /** The {@link ForeignKeyAction} a catalogue names, whatever its case. */
+    /** The {@link ForeignKeyAction} a catalogue names, whatever its case, and `SET_NULL` as SQL Server spells it. */
     protected normalizeReferentialAction(action: string): ForeignKeyAction | undefined;
+    /** Foreign keys read one row each, as {@link JoinedForeignKeyRow} lists them. */
+    protected joinedForeignKeys(rows: readonly JoinedForeignKeyRow[]): ForeignKeySchema[];
     /**
      * Convert bigint/null values to number safely.
      */