uql-orm 0.67.1 → 0.68.1

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/http/query.d.ts

@@ -1,11 +1,19 @@
-import type { Query } from '../type/index.js';
+import type { WireQuery } from '../type/index.js';
 /**
  * Parse raw query-string entries (with JSON-stringified values) into a UQL query object.
  * Symmetric counterpart of {@link stringifyQuery}. Only {@link ALLOWED_QUERY_KEYS} are honored.
  */
-export declare function parseQueryParams(params?: Record<string, unknown>): Query<unknown>;
+export declare function parseQueryParams(params?: Record<string, unknown>): WireQuery<unknown>;
 /**
  * Serialize a UQL query object into a percent-encoded query string where object values
  * are JSON-stringified. Symmetric counterpart of {@link parseQueryParams}.
  */
 export declare function stringifyQuery(query?: Record<string, unknown>): string;
+/**
+ * What leaves the browser, as JSON, refusing what JSON keeps nothing of rather than letting the server
+ * build a statement around the remains. A `raw` fragment renders SQL against a dialect the client does not
+ * have and arrives as `{}`; binary arrives as an object keyed by index. A `Date` is not among them - it
+ * serializes to ISO 8601, which is what a date column reads. This is what a cast, or a JavaScript caller,
+ * hits where the client's types already refuse a fragment.
+ */
+export declare function wireJson(value: unknown): string;

package/dist/http/query.js

@@ -1,5 +1,8 @@
 // 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_NUMBER_CLAUSES, QUERY_ROOT_OBJECT_CLAUSES, } from '../type/query.js';
+// the brand alone, not the class: importing `QueryRaw` for an `instanceof` kept it, and `ColumnRef`
+// with it, in the browser bundle, which is on a size budget
+import { RAW_VALUE } from '../type/queryRaw.js';
 // the specific util module, not the barrel, so the browser bundle does not pull in entity metadata
 import { getKeys, isWhereMap } from '../util/object.util.js';
 /**
@@ -82,8 +85,30 @@ export function stringifyQuery(query) {
         if (value === undefined) {
             continue;
         }
-        params.append(key, typeof value === 'object' && value !== null ? JSON.stringify(value) : String(value));
+        params.append(key, typeof value === 'object' && value !== null ? wireJson(value) : String(value));
     }
     const qs = params.toString();
     return qs ? `?${qs}` : '';
 }
+/**
+ * What leaves the browser, as JSON, refusing what JSON keeps nothing of rather than letting the server
+ * build a statement around the remains. A `raw` fragment renders SQL against a dialect the client does not
+ * have and arrives as `{}`; binary arrives as an object keyed by index. A `Date` is not among them - it
+ * serializes to ISO 8601, which is what a date column reads. This is what a cast, or a JavaScript caller,
+ * hits where the client's types already refuse a fragment.
+ */
+export function wireJson(value) {
+    return JSON.stringify(value, (_key, held) => {
+        if (typeof held !== 'object' || held === null) {
+            return held;
+        }
+        if (RAW_VALUE in held) {
+            throw new TypeError('raw SQL cannot travel over HTTP: what leaves the browser is JSON');
+        }
+        // A blob is a field value, so no type parameter reaches it: this is the only place it is caught.
+        if (held instanceof ArrayBuffer || ArrayBuffer.isView(held)) {
+            throw new TypeError('binary cannot travel over HTTP: what leaves the browser is JSON');
+        }
+        return held;
+    });
+}

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;