uql-orm 0.67.1 → 0.68.0

package/dist/dialect/abstractSqlDialect.js

@@ -1,21 +1,17 @@
 import { fieldOf, getMeta, relationOf, soleIdOf } from '../entity/index.js';
 import { COUNT_RESULT_KEY, parseQueryLock, QueryRaw, RAW_ALIAS, VECTOR_QUERY_KEYS, } from '../type/index.js';
 import { isInlinedExpression } from '../util/field.util.js';
-import { asSelectMap, assertNonNegativeInteger, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, idOnlyQuery, columnFamily, countedRelations, isJsonUpdateOp, isOperatorMap, isOperatorObject, isOperatorOnlyObject, isVectorSearch, normalizeScalarFieldSelection, parentJoins, targetKeyColumns, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortByCount, populatesRelations, raw, someValue, throwUnknownAggregateColumn, withoutSoftDeleteFilter, } from '../util/index.js';
-import { escapeAnsiSqlLiteral, escapeSingleQuotes } from '../util/sqlLiteral.js';
-import { COUNT_ALIAS, COUNTED_ROWS_ALIAS, JSON_ELEM_ALIAS, relationSortColumn } from './aliases.js';
-import { buildElemMatchConditions } from './jsonArrayElemMatchUtils.js';
-import { isJsonbOp, jsonCompareMode, jsonElemExists } from './jsonSql.js';
+import { asSelectMap, assertNonNegativeInteger, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, idOnlyQuery, columnFamily, countedRelations, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorKey, isVectorSearch, normalizeScalarFieldSelection, parentJoins, targetKeyColumns, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortByCount, populatesRelations, raw, throwUnknownAggregateColumn, withoutSoftDeleteFilter, } from '../util/index.js';
+import { escapeAnsiSqlLiteral } from '../util/sqlLiteral.js';
+import { COUNT_ALIAS, COUNTED_ROWS_ALIAS, JSON_ELEM_ALIAS, JSON_PULL_ALIAS, relationSortColumn } from './aliases.js';
+import { holdsOperator, isJsonScalar, jsonCompareMode, jsonElemExists, jsonPath, } from './jsonSql.js';
 import { SqlQueryContext } from './queryContext.js';
 import { NO_JOINS, resolveQueryJoins, resolveSortableJoin, } from './queryJoins.js';
 import { resolveVectorCast } from './vectorCast.js';
 import { VectorSqlDialect } from './vectorSqlDialect.js';
 /** The key a term answers under in a populated relation's row, which a raw expression has only once aliased. */
 export function relationTermKey({ sql, key }) {
-    if (key === undefined) {
-        throw new TypeError(`a raw $select in a populated relation needs an alias, the key its value lands under: ${sql}`);
-    }
-    return key;
+    return orRefuse(key, `a raw $select in a populated relation needs an alias, the key its value lands under: ${sql}`);
 }
 /**
  * What a projection reads: its raw expressions, or its fields past any `$exclude`, and every field where
@@ -27,6 +23,13 @@ function projectedKeys(meta, select, exclude, json) {
         : normalizeScalarFieldSelection(meta, asSelectMap(select), exclude);
     return selected.length || !json ? selected : normalizeScalarFieldSelection(meta);
 }
+/** `value`, where there is one; a `TypeError` saying `refusal` where there is none. */
+function orRefuse(value, refusal) {
+    if (value === undefined) {
+        throw TypeError(refusal);
+    }
+    return value;
+}
 /** An `$in`/`$nin` operand, which the types require to be an array but `/http` hands over untyped. */
 function inOperands(op, value) {
     if (!Array.isArray(value)) {
@@ -206,8 +209,8 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     }
     /**
      * The expression a scalar field is read through in the statement's own rows, the plain column by
-     * default. MariaDB reads a vector column back with `VEC_ToText`, since selecting it raw yields its
-     * binary form. A related row's column crosses JSON through {@link carriedFields} instead.
+     * default. MariaDB reads a vector column back as hex, since selecting it raw yields its binary form.
+     * A related row's column crosses JSON through {@link carriedFields} instead.
      */
     selectFieldExpr(escapedColumn, _field) {
         return escapedColumn;
@@ -413,7 +416,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         // Detect JSONB dot-notation: 'column.path' where column is a registered JSON/JSONB field
         const jsonDot = this.resolveJsonDotPath(meta, key, opts.prefix);
         if (jsonDot) {
-            this.compareJsonPath(ctx, jsonDot, val);
+            ctx.append(this.jsonConditions(ctx, this.jsonPathTarget(jsonDot), val));
             return;
         }
         if (key.includes('.')) {
@@ -430,19 +433,12 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             return;
         }
         const value = this.normalizeWhereValue(val);
-        const operators = getKeys(value);
-        if (operators.length > 1) {
-            ctx.append('(');
-        }
-        operators.forEach((op, index) => {
-            if (index > 0) {
-                ctx.append(' AND ');
-            }
-            this.compareFieldOperator(ctx, entity, key, op, value[op], opts);
-        });
-        if (operators.length > 1) {
-            ctx.append(')');
-        }
+        const parts = getKeys(value).map((op) => this.fieldCondition(ctx, entity, key, op, value[op], opts));
+        ctx.append(AbstractSqlDialect.conjunction(parts));
+    }
+    /** Conditions joined by `AND`, parenthesized where there is more than one. */
+    static conjunction(parts) {
+        return parts.length > 1 ? `(${parts.join(' AND ')})` : parts.join('');
     }
     compareLogicalOperator(ctx, entity, key, val, opts) {
         const { join, negate } = AbstractSqlDialect.GROUP_OPS[key];
@@ -477,14 +473,16 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     /** 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.
+     * The ordered comparisons, `QueryOrderedOp` at runtime, derived from the map above rather than spelled
+     * again: {@link QueryVectorNear}'s bounds, so `$near` never accepts one the renderer has no operator
+     * for, and the operators that read a JSON path as a number.
      */
-    static NEAR_BOUND_OPS = new Set([
+    static ORDERED_OPS = new Set([
         ...AbstractSqlDialect.COMPARE_OP_MAP.keys(),
         '$between',
     ]);
+    /** The operators an equality compares by value, which a JSON path reads the way that value compares. */
+    static EQUALITY_OPS = new Set(['$eq', '$ne', '$in', '$nin']);
     /**
      * 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
@@ -546,42 +544,31 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         const inlined = field && isInlinedExpression(field) ? field.computed : undefined;
         return inlined ? this.rawFragment(ctx, inlined, prefix, entity) : undefined;
     }
-    /** One operator of a field's condition. Both come from the query as data, so neither is trusted. */
+    /** {@link fieldCondition}, appended. */
     compareFieldOperator(ctx, entity, key, op, val, opts = {}) {
-        const field = this.resolveOperandField(ctx, entity, key, opts);
-        if (this.appendOperatorCondition(ctx, field, op, val)) {
-            return;
+        ctx.append(this.fieldCondition(ctx, entity, key, op, val, opts));
+    }
+    /** One operator of a field's condition. Both come from the query as data, so neither is trusted. */
+    fieldCondition(ctx, entity, key, op, val, opts) {
+        if (op === '$not') {
+            return `NOT (${this.buildFragment(ctx, (fragmentCtx) => this.compare(fragmentCtx, entity, key, val, opts))})`;
         }
-        switch (op) {
-            case '$not':
-                ctx.append('NOT (');
-                this.compare(ctx, entity, key, val, opts);
-                ctx.append(')');
-                break;
-            case '$all':
-                ctx.append(this.jsonAll(ctx, field, val));
-                break;
-            case '$size':
-                ctx.append(this.jsonSize(ctx, field, val));
-                break;
-            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}`);
+        if (op === '$near') {
+            return this.vectorNearCondition(ctx, getMeta(entity), key, val);
         }
+        const field = this.resolveOperandField(ctx, entity, key, opts);
+        const condition = this.operatorCondition(ctx, field, op, val) ?? this.jsonArrayCondition(ctx, { base: field, path: '' }, op, val);
+        return orRefuse(condition, `unknown operator: ${op}`);
     }
     /**
      * `<operand> <op> <value>` for every operator that needs only its left-hand SQL, shared by a column, a
-     * `HAVING` expression and a `$size` count; `undefined` for the rest.
+     * JSON path, a `HAVING` expression, a count and a distance; `undefined` for the rest. `bind` renders
+     * each compared value, a plain placeholder unless a JSON path reads it otherwise.
      */
-    operatorCondition(ctx, operand, op, val) {
+    operatorCondition(ctx, operand, op, val, bind = (value) => this.addValue(ctx, value)) {
         const compareOp = AbstractSqlDialect.COMPARE_OP_MAP.get(op);
         if (compareOp) {
-            return `${operand}${compareOp}${this.addValue(ctx, val)}`;
+            return `${operand}${compareOp}${bind(val)}`;
         }
         const like = this.likeCondition(ctx, operand, op, val);
         if (like) {
@@ -589,17 +576,17 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         }
         switch (op) {
             case '$eq':
-                return val === null ? `${operand} IS NULL` : `${operand} = ${this.addValue(ctx, val)}`;
+                return val === null ? `${operand} IS NULL` : `${operand} = ${bind(val)}`;
             case '$ne':
-                return val === null ? `${operand} IS NOT NULL` : this.neExpr(operand, this.addValue(ctx, val));
+                return val === null ? `${operand} IS NOT NULL` : this.neExpr(operand, bind(val));
             case '$regex':
                 return this.regexCondition(operand, this.addValue(ctx, val));
             case '$in':
             case '$nin':
-                return this.formatIn(ctx, operand, inOperands(op, val), op === '$nin');
+                return this.formatIn(ctx, operand, inOperands(op, val), op === '$nin', bind);
             case '$between': {
                 const [min, max] = val;
-                return `${operand} BETWEEN ${this.addValue(ctx, min)} AND ${this.addValue(ctx, max)}`;
+                return `${operand} BETWEEN ${bind(min)} AND ${bind(max)}`;
             }
             case '$isNull':
                 return operand + (val ? ' IS NULL' : ' IS NOT NULL');
@@ -609,114 +596,147 @@ export class AbstractSqlDialect extends VectorSqlDialect {
                 return undefined;
         }
     }
-    /** {@link operatorCondition}, appended; `false` when `op` needs more than an operand. */
-    appendOperatorCondition(ctx, operand, op, val) {
-        const condition = this.operatorCondition(ctx, operand, op, val);
-        if (condition === undefined) {
-            return false;
-        }
-        ctx.append(condition);
-        return true;
-    }
-    /**
-     * Build a comparison condition for a JSON field.
-     * Used by both `$elemMatch` and dot-notation paths.
-     * All dialect-specific behavior comes from overridable methods on `this`.
-     */
-    buildJsonFieldCondition(ctx, fieldAccessor, jsonPath, op, value, asJson = false) {
-        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, value)}`;
-        }
+    /** `$all`, `$size` and `$elemMatch`, which read the JSON array at `slot`; `undefined` for the rest. */
+    jsonArrayCondition(ctx, slot, op, val) {
         switch (op) {
-            case '$eq':
-                if (value === null)
-                    return `${jsonField} IS NULL`;
-                return `${comparand(value)} = ${this.jsonOperand(ctx, value, asJson)}`;
-            case '$ne':
-                if (value === null)
-                    return `${jsonField} IS NOT NULL`;
-                return this.neExpr(comparand(value), this.jsonOperand(ctx, value, asJson));
-            case '$regex':
-                return this.regexCondition(jsonField, this.addValue(ctx, value));
-            case '$in':
-            case '$nin':
-                return this.jsonInNin(ctx, jsonField, comparand, op, value, asJson);
             case '$all':
-                return this.jsonAll(ctx, jsonField, value);
+                return this.jsonAll(ctx, slot, val);
             case '$size':
-                return this.jsonSize(ctx, jsonField, value);
+                return this.sizeCondition(ctx, (fragmentCtx) => fragmentCtx.append(this.jsonLength(slot)), val);
             case '$elemMatch':
-                return this.jsonElemMatch(ctx, jsonField, value);
+                return this.jsonElemMatch(ctx, slot, val);
             default:
-                throw TypeError(`unknown operator: ${op}`);
+                return undefined;
         }
     }
-    jsonInNin(ctx, jsonField, comparand, op, value, asJson) {
-        const values = inOperands(op, value);
-        const negate = op === '$nin';
-        if (!asJson) {
-            return this.formatIn(ctx, comparand(values), 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)}`);
-        return `(${comparisons.join(negate ? ' AND ' : ' OR ')})`;
+    /** A path of a JSON document, read the way each operator reads it. */
+    jsonPathTarget(slot) {
+        return { slot, read: (mode) => this.jsonPathExpr(slot.base, slot.path, mode) };
+    }
+    /** Every operator `target` is compared with, `AND`-joined. */
+    jsonConditions(ctx, target, val) {
+        const value = this.normalizeWhereValue(val);
+        return AbstractSqlDialect.conjunction(getKeys(value).map((op) => this.jsonCondition(ctx, target, op, value[op])));
     }
-    /** The bound operand of a JSON comparison: JSON-encoded when comparing against the JSON value. */
-    jsonOperand(ctx, value, asJson) {
-        return asJson ? this.jsonScalarParam(ctx, value) : this.addValue(ctx, value);
+    jsonCondition(ctx, target, op, value) {
+        if (op === '$not') {
+            return `NOT (${this.jsonConditions(ctx, target, value)})`;
+        }
+        const array = this.jsonArrayCondition(ctx, target.slot, op, value);
+        if (array !== undefined) {
+            return array;
+        }
+        const mode = AbstractSqlDialect.jsonOperatorMode(op, value);
+        const operand = target.read(mode);
+        // Only a boolean compares as a JSON value, so the set holds two at most, and MySQL documents `IN()`
+        // as unsupported on JSON values: the comparisons are spelled out.
+        if (mode === 'json' && (op === '$in' || op === '$nin')) {
+            const negate = op === '$nin';
+            const comparisons = inOperands(op, value).map((val) => `${operand} ${negate ? '<>' : '='} ${this.jsonScalarParam(ctx, val)}`);
+            return `(${comparisons.join(negate ? ' AND ' : ' OR ')})`;
+        }
+        const condition = this.operatorCondition(ctx, operand, op, value, (val) => this.jsonOperand(ctx, val, mode));
+        return orRefuse(condition, `unknown operator: ${op}`);
     }
     /**
-     * `$elemMatch`: an element satisfies `match`. Operator keys test a scalar element; a plain object is
-     * containment, which an index can serve; anything else tests each exploded object's fields.
+     * How `op` reads a JSON value: an ordered comparison as a number, an equality as its operand compares,
+     * and a pattern or a null check as text.
      */
-    jsonElemMatch(ctx, jsonField, match) {
-        // Conditions on the element itself. One `FROM` serves them all, so the element is read as JSON
-        // only when *every* operand needs it - the same all-operands rule the comparison classifier uses.
-        if (isOperatorOnlyObject(match)) {
-            const entries = Object.entries(match);
-            const asJson = !this.features.typedJsonElements && entries.every(([op, val]) => isJsonbOp(op, val));
-            const alias = ctx.claimAlias(JSON_ELEM_ALIAS);
-            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)) {
-            throw TypeError(`$elemMatch cannot mix operators with field names: ${Object.keys(match).join(', ')}`);
+    static jsonOperatorMode(op, value) {
+        if (AbstractSqlDialect.ORDERED_OPS.has(op)) {
+            return 'numeric';
         }
-        // A plain object with no nested operators is containment, which is also the only form an index
-        // can serve. SQLite compares elements exactly, so it always expands the per-field form below.
-        if (this.features.partialJsonContainment && !someValue(match, isOperatorObject)) {
-            return this.jsonAll(ctx, jsonField, [match]);
+        return AbstractSqlDialect.EQUALITY_OPS.has(op) ? jsonCompareMode(value) : 'text';
+    }
+    /** A bound operand of a JSON comparison, read the way `mode` reads the value it is compared with. */
+    jsonOperand(ctx, value, mode) {
+        if (mode === 'json') {
+            return this.jsonScalarParam(ctx, value);
         }
+        const placeholder = this.addValue(ctx, value);
+        return mode === 'numeric' ? this.numericCast(placeholder) : placeholder;
+    }
+    /** The JSON value at `slot`, as an array operator reads it. */
+    jsonValue(slot) {
+        return slot.path ? this.jsonPathExpr(slot.base, slot.path, 'json') : slot.base;
+    }
+    /**
+     * `$all`: the JSON array at `slot` has an element holding each value, as Postgres's `@>` and MySQL's
+     * `JSON_CONTAINS` read one: a scalar equal, an array each of its elements, an object each of its keys.
+     * Plain JSON goes to {@link jsonContains}; an operator anywhere in it is matched element by element.
+     */
+    jsonAll(ctx, slot, values) {
+        return holdsOperator(values) ? this.jsonElemsHold(ctx, slot, values) : this.jsonContains(ctx, slot, values);
+    }
+    /** `$all` over plain JSON, which an engine with containment of its own spells natively, for an index to serve. */
+    jsonContains(ctx, slot, values) {
+        return this.jsonElemsHold(ctx, slot, values);
+    }
+    /** One `EXISTS` per value, over the elements of the array at `slot`: a scalar equal, anything else held. */
+    jsonElemsHold(ctx, slot, values) {
         const alias = ctx.claimAlias(JSON_ELEM_ALIAS);
-        const conditions = buildElemMatchConditions(match, (field, op, opVal) => {
-            const asJson = isJsonbOp(op, opVal);
-            return this.buildJsonFieldCondition(ctx, this.elemAccessor(alias, asJson), field, op, opVal, asJson);
+        const from = this.jsonElemFrom(slot, alias);
+        const element = {
+            slot: { base: this.jsonElemDoc(alias), path: '' },
+            read: (mode) => this.jsonElemValue(slot, alias, mode),
+        };
+        const conditions = values.map((value) => {
+            const holds = isOperatorMap(value) || Array.isArray(value)
+                ? this.jsonHolds(ctx, element, value)
+                : [this.jsonElemEquals(ctx, slot, alias, value)];
+            return jsonElemExists(from, holds, this.jsonElemHint);
         });
-        return jsonElemExists(this.jsonElemFrom(jsonField, Object.keys(match), alias), conditions);
+        return AbstractSqlDialect.conjunction(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.
+     * What the JSON `target` reads satisfies to hold `value`: an array each of its elements, an object each
+     * of its keys as a path, and an operator map or a scalar compared as a path is.
      */
-    elemAccessor(alias, asJson) {
-        return (field, mode) => {
-            const ref = this.jsonElemRef(alias, field || undefined, asJson);
-            return mode === 'numeric' ? this.numericCast(ref) : ref;
-        };
+    jsonHolds(ctx, target, value) {
+        if (Array.isArray(value)) {
+            return [this.jsonAll(ctx, target.slot, value)];
+        }
+        if (!isJsonObject(value)) {
+            return [this.jsonConditions(ctx, target, value)];
+        }
+        const { base, path } = target.slot;
+        return Object.entries(value).flatMap(([key, item]) => this.jsonHolds(ctx, this.jsonPathTarget({ base, path: path ? `${path}.${key}` : key }), item));
+    }
+    /** An element of the array at `slot` equal to `value`, both read as JSON. */
+    jsonElemEquals(ctx, slot, alias, value) {
+        return `${this.jsonElemValue(slot, alias, 'json')} = ${this.jsonScalarParam(ctx, value)}`;
+    }
+    /** The JSON array at `slot` contains at least one of `values`, each as `$all` reads it. */
+    jsonAny(ctx, slot, values) {
+        return `(${values.map((value) => this.jsonAll(ctx, slot, [value])).join(' OR ')})`;
+    }
+    /** An element of the array at `slot` itself, read the way `mode` reads a path: its document, or its root. */
+    jsonElemValue(_slot, alias, mode) {
+        const doc = this.jsonElemDoc(alias);
+        return mode === 'json' ? doc : this.jsonPathExpr(doc, '', mode);
     }
+    /**
+     * `$elemMatch`: an element holds `match`, as `$all` reads one value, its operators testing the element
+     * itself. An element equal to one value, or to one of several, is containment whatever the operator
+     * says, which compares by JSON type and is what an array index serves.
+     */
+    jsonElemMatch(ctx, slot, match) {
+        const keys = Object.keys(match);
+        if (keys.some(isOperatorKey) && !keys.every(isOperatorKey)) {
+            throw TypeError(`$elemMatch cannot mix operators with field names: ${keys.join(', ')}`);
+        }
+        const single = keys.length === 1;
+        const { $eq: equal, $in: within } = match;
+        if (single && isJsonScalar(equal)) {
+            return this.jsonAll(ctx, slot, [equal]);
+        }
+        if (single && Array.isArray(within) && within.length > 0 && within.every(isJsonScalar)) {
+            return this.jsonAny(ctx, slot, within);
+        }
+        return this.jsonAll(ctx, slot, [match]);
+    }
+    /** The optimizer hint a `$elemMatch` subquery opens with, where the engine plans one wrong without it. */
+    jsonElemHint = '';
     /**
      * 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.
@@ -799,35 +819,45 @@ export class AbstractSqlDialect extends VectorSqlDialect {
                     ? { key: keyPath, expr: this.escapeId(value.$project), direction: '', output: true }
                     : {
                         key: keyPath,
-                        expr: this.buildFragment(ctx, (fragmentCtx) => this.appendVectorSort(fragmentCtx, meta, key, value)),
+                        expr: this.buildFragment(ctx, (fragmentCtx) => this.appendVectorDistance(fragmentCtx, meta, key, value)),
                         direction: '',
                         output: false,
                     });
                 continue;
             }
-            columns.push({
-                key: keyPath,
-                ...this.sortColumn(ctx, meta, key, prefix),
-                direction: this.resolveSortDirection(value),
+            const direction = this.resolveSortDirection(value);
+            // A JSON path can sort by more than one reading, each carried under a name of its own.
+            this.sortColumns(ctx, meta, key, prefix).forEach((column, index) => {
+                columns.push({ key: index ? `${keyPath}:${index}` : keyPath, ...column, direction });
             });
         }
     }
     /**
-     * The `ORDER BY` operand for one key. A key that is not a field of `meta` - a `raw()` projection, a
-     * `$select` alias - is an output alias, which is never table-qualified and needs no resolving.
+     * The `ORDER BY` operands for one key: a JSON path's in each of {@link jsonSortModes}. A key that is
+     * not a field of `meta` - a `raw()` projection, a `$select` alias - is an output alias, which is never
+     * table-qualified and needs no resolving.
      */
-    sortColumn(ctx, meta, key, prefix) {
+    sortColumns(ctx, meta, key, prefix) {
         const field = meta.fields[key];
         if (field) {
             const expr = this.inlinedOperand(ctx, field, prefix ?? this.resolveTableAlias(meta), meta.entity) ??
                 this.columnWithPrefix(key, field, prefix);
-            return { expr, output: false };
+            return [{ expr, output: false }];
         }
         const json = this.resolveJsonDotPath(meta, key, prefix);
-        return json
-            ? { expr: this.jsonPathExpr(json.column, json.jsonPath, 'text'), output: false }
-            : { expr: this.escapeId(key), output: true };
+        if (!json) {
+            return [{ expr: this.escapeId(key), output: true }];
+        }
+        return this.jsonSortModes.map((mode) => ({
+            expr: this.jsonPathExpr(json.base, json.path, mode),
+            output: false,
+        }));
     }
+    /**
+     * How a JSON path is sorted by: as the JSON value, which the engine orders by type and a number by its
+     * value. An engine that orders JSON as text reads a number first, then the text.
+     */
+    jsonSortModes = ['json'];
     /**
      * `LIMIT`/`OFFSET`. `sorted` says whether an `ORDER BY` was emitted just before, which
      * {@link MergeSqlDialect} needs: SQL Server refuses to page a statement that has none.
@@ -1007,21 +1037,13 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     ]);
     resolveSortDirection(sort) {
         const direction = AbstractSqlDialect.SORT_DIRECTION_MAP.get(sort);
-        if (direction === undefined) {
-            throw TypeError(`unknown sort direction: ${sort}`);
-        }
-        return direction;
+        return orRefuse(direction, `unknown sort direction: ${sort}`);
     }
-    /** Scalar comparison operators shared by `HAVING` conditions and `$size` comparisons. */
+    /** Every operator of one `HAVING` condition, `AND`-joined. */
     havingCondition(ctx, expr, condition) {
         const ops = this.normalizeWhereValue(condition);
-        getKeys(ops).forEach((op, i) => {
-            if (i > 0)
-                ctx.append(' AND ');
-            if (!this.appendOperatorCondition(ctx, expr, op, ops[op])) {
-                throw TypeError(`unsupported HAVING operator: ${op}`);
-            }
-        });
+        const parts = getKeys(ops).map((op) => orRefuse(this.operatorCondition(ctx, expr, op, ops[op]), `unsupported HAVING operator: ${op}`));
+        ctx.append(parts.join(' AND '));
     }
     /**
      * How many rows the filter matched, on every row of the page. A window function runs before
@@ -1386,6 +1408,27 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     jsonPull(ctx, expr, escapedCol, pull) {
         return Object.entries(pull).reduce((acc, [key, value]) => this.jsonPullKey(ctx, acc, escapedCol, key, value), expr);
     }
+    /**
+     * Wrap `expr` so the array at `key` no longer contains `value`: the array rebuilt from the elements that
+     * differ from it, and any other value put back as it is. `JSON_REPLACE` leaves an absent key, and a NULL
+     * column, untouched.
+     */
+    jsonPullKey(ctx, expr, escapedCol, key, value) {
+        const slot = { base: escapedCol, path: key };
+        const elem = this.jsonElemValue(slot, JSON_PULL_ALIAS, 'json');
+        const differs = this.jsonDiffers(elem, this.jsonScalarParam(ctx, value));
+        const kept = `SELECT ${this.jsonArrayOf(elem)} FROM ${this.jsonElemFrom(slot, JSON_PULL_ALIAS)} WHERE ${differs}`;
+        const pulled = `CASE WHEN ${this.jsonIsArray(slot)} THEN (${kept}) ELSE ${this.jsonValue(slot)} END`;
+        return `JSON_REPLACE(${expr}, ${jsonPath(key)}, ${pulled})`;
+    }
+    /** The elements a `$pull` keeps, back in one array, and an empty one where it keeps none. */
+    jsonArrayOf(elem) {
+        return `COALESCE(JSON_ARRAYAGG(${elem}), JSON_ARRAY())`;
+    }
+    /** Whether an element is not the pulled value, both read as JSON. */
+    jsonDiffers(elem, operand) {
+        return `${elem} <> ${operand}`;
+    }
     compileDdl(sql, entity) {
         const ctx = this.createContext({ inlineValues: true });
         if (sql instanceof QueryRaw) {
@@ -1412,12 +1455,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             escapedPrefix: escapedPrefix ?? this.escapeId(prefix, true, true),
         });
     }
-    /**
-     * Resolves a dot-notation key to its JSON field metadata.
-     * Shared by `where()` and `sort()` to detect 'column.path' keys where 'column' is a JSON/JSONB field.
-     *
-     * @returns resolved metadata or `undefined` if the key is not a JSON dot-notation path
-     */
+    /** A `column.path` key of `meta`'s JSON field as the path it names, shared by `where` and `sort`; else `undefined`. */
     resolveJsonDotPath(meta, key, prefix) {
         const dotIndex = key.indexOf('.');
         if (dotIndex <= 0) {
@@ -1430,66 +1468,17 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         }
         const colName = this.resolveColumnName(root, field);
         const prefixed = (prefix ? this.escapeId(prefix, true, true) : '') + this.escapeId(colName);
-        return { jsonPath: key.slice(dotIndex + 1), column: prefixed };
+        return { base: prefixed, path: key.slice(dotIndex + 1) };
     }
     /**
      * 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, column } = resolved;
-        const accessor = (path, mode) => this.jsonPathExpr(column, path, mode);
-        const value = this.normalizeWhereValue(val);
-        const operators = getKeys(value);
-        if (operators.length > 1) {
-            ctx.append('(');
-        }
-        operators.forEach((op, index) => {
-            if (index > 0)
-                ctx.append(' AND ');
-            const asJson = isJsonbOp(op, value[op]);
-            const sql = this.buildJsonFieldCondition(ctx, accessor, jsonPath, op, value[op], asJson);
-            if (sql) {
-                ctx.append(sql);
-            }
-        });
-        if (operators.length > 1) {
-            ctx.append(')');
-        }
-    }
-    /**
-     * Returns SQL that extracts a scalar value from a JSON path.
-     * Dialects can override this to customize path access syntax while preserving
-     * the shared comparison/operator pipeline.
-     */
-    getJsonPathScalarExpr(escapedColumn, jsonPath) {
-        const segments = jsonPath.split('.');
-        let expr = escapedColumn;
-        for (let i = 0; i < segments.length; i++) {
-            const op = i === segments.length - 1 ? '->>' : '->';
-            expr = `(${expr}${op}'${escapeSingleQuotes(segments[i])}')`;
-        }
-        return expr;
-    }
-    getJsonPathJsonbExpr(escapedColumn, jsonPath) {
-        const segments = jsonPath.split('.');
-        let expr = escapedColumn;
-        for (const segment of segments) {
-            expr = `(${expr}->'${escapeSingleQuotes(segment)}')`;
-        }
-        return expr;
+    jsonPathExpr(escapedColumn, path, mode) {
+        return mode === 'numeric'
+            ? this.numericCast(this.jsonPathReading(escapedColumn, path, 'text'))
+            : this.jsonPathReading(escapedColumn, path, mode);
     }
     /**
      * Normalizes a raw WHERE value into an operator map.
@@ -1685,57 +1674,47 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     }
     /** Filter by relation size: the same subquery, counting instead of testing for existence. */
     compareRelationSize(ctx, entity, relKey, sizeVal, rel, opts) {
-        this.buildSizeComparison(ctx, () => this.appendRelationSubquery(ctx, getMeta(entity), relKey, rel, opts, 'COUNT(*)', {}), sizeVal);
+        const count = (fragmentCtx) => this.appendRelationSubquery(fragmentCtx, getMeta(entity), relKey, rel, opts, 'COUNT(*)', {});
+        ctx.append(this.sizeCondition(ctx, count, sizeVal));
     }
     /**
-     * `<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.
+     * `<expr> <op> <value>` for each bound, `AND`-joined. `expr` is spelled once per bound because it is an
+     * expression, not a column: a `WHERE` has no output alias to refer back to. Shared by `$size`, which
+     * counts, and `$near`, which measures a distance.
      */
-    buildExprComparison(ctx, exprFn, ops, appendOp) {
-        const entries = Object.entries(ops).filter(([, v]) => v !== undefined);
-        if (entries.length > 1) {
-            ctx.append('(');
-        }
-        entries.forEach(([op, val], index) => {
-            if (index > 0) {
-                ctx.append(' AND ');
-            }
-            exprFn();
-            appendOp(op, val);
-        });
-        if (entries.length > 1) {
-            ctx.append(')');
-        }
+    boundConditions(ctx, expr, bounds, condition, refusal) {
+        const parts = Object.entries(bounds)
+            .filter(([, val]) => val !== undefined)
+            .map(([op, val]) => orRefuse(condition(this.buildFragment(ctx, expr), op, val), `${refusal}: ${op}`));
+        return AbstractSqlDialect.conjunction(parts);
     }
     /**
-     * Build a complete `$size` comparison expression.
-     * @param sizeExprFn - function that appends the size expression to ctx (e.g. `JSONB_ARRAY_LENGTH("col")`)
+     * A count compared with `size`, a number or its bounds. A count is never NULL, so its equality stays
+     * plain rather than the null-safe `$ne` (`IS DISTINCT FROM`, `IS NOT`): same rows, shorter SQL.
      */
-    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));
+    sizeCondition(ctx, count, size) {
+        const bounds = typeof size === 'number' ? { $eq: size } : size;
+        return this.boundConditions(ctx, count, bounds, (operand, op, val) => {
+            if (op === '$eq' || op === '$ne') {
+                return `${operand} ${op === '$eq' ? '=' : '<>'} ${this.addValue(ctx, val)}`;
+            }
+            return AbstractSqlDialect.ORDERED_OPS.has(op) ? this.operatorCondition(ctx, operand, op, val) : undefined;
+        }, 'unsupported $size comparison operator');
     }
     /** `<distance> <op> ?`, the `$where` half of a vector search, its bounds checked here since `/http` input is untyped. */
-    compareVectorNear(ctx, meta, key, near) {
+    vectorNearCondition(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)) {
+            if (!AbstractSqlDialect.ORDERED_OPS.has(op)) {
                 throw TypeError(`unsupported $near bound: ${op}`);
             }
             bounds[op] = val;
         }
         if (!hasKeys(bounds)) {
-            const boundOps = [...AbstractSqlDialect.NEAR_BOUND_OPS].join(', ');
+            const boundOps = [...AbstractSqlDialect.ORDERED_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
@@ -1746,30 +1725,8 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             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',
-        '$ne',
-        '$gt',
-        '$gte',
-        '$lt',
-        '$lte',
-        '$between',
-    ]);
-    /** ` <op> <value>` after a count already written, refusing any operator a count cannot be compared with. */
-    appendSizeOp(ctx, op, val) {
-        if (!AbstractSqlDialect.SIZE_COMPARE_OPS.has(op)) {
-            throw TypeError(`unsupported $size comparison operator: ${op}`);
-        }
-        // A COUNT is never NULL, so equality stays plain here instead of taking the shared renderer's
-        // null-safe `$ne` (`IS DISTINCT FROM` on Postgres, `IS NOT` on SQLite). Same rows, shorter SQL.
-        if (op === '$eq' || op === '$ne') {
-            ctx.append(` ${op === '$eq' ? '=' : '<>'} ${this.addValue(ctx, val)}`);
-            return;
-        }
-        this.appendOperatorCondition(ctx, '', op, val);
+        const distance = (fragmentCtx) => this.appendVectorDistance(fragmentCtx, meta, key, search);
+        return this.boundConditions(ctx, distance, bounds, (operand, op, val) => this.operatorCondition(ctx, operand, op, val), 'unsupported $near bound');
     }
     /** ANSI-style single-quote escaping. MySQL-family dialects override this for backslash escaping. */
     escape(value) {
@@ -1800,12 +1757,12 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     neExpr(field, ph) {
         return `${field} ${this.neOp} ${ph}`;
     }
-    /** `operand IN (...)` binding each value, or the constant an empty set reduces to: no value is in it. */
-    formatIn(ctx, operand, values, negate) {
+    /** `operand IN (...)` of each value as `bind` renders it, or the constant an empty set reduces to: no value is in it. */
+    formatIn(_ctx, operand, values, negate, bind) {
         if (!values.length) {
             return negate ? '1 = 1' : '1 = 0';
         }
-        const phs = values.map((v) => this.addValue(ctx, v)).join(', ');
+        const phs = values.map(bind).join(', ');
         return `${operand} ${negate ? 'NOT IN' : 'IN'} (${phs})`;
     }
     toString() {