uql-orm 0.79.0 → 0.81.0

package/dist/dialect/abstractSqlDialect.js

@@ -1,11 +1,12 @@
 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 { COUNT_RESULT_KEY, parseQueryLock, QueryRaw, RAW_ALIAS, } 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, fieldUpdateOf, fulltextIndexOver, fulltextWeights, isFieldUpdateOp, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorKey, isVectorSearch, normalizeScalarFieldSelection, parentJoins, rankedTextSearch, targetKeyColumns, textSearchFields, textSortOf, textWeightSteps, parseGroupMap, parseRelationAtKey, parseRelationSize, populatesRelations, aggregateOf, raw, refs, throwUnknownAggregateColumn, withoutSoftDeleteFilter, } from '../util/index.js';
 import { escapeAnsiSqlLiteral } from '../util/sqlLiteral.js';
-import { UqlUsageError } from '../util/uqlError.js';
+import { kindOf, UqlUsageError } from '../util/uqlError.js';
 import { AGGREGATE_PAGE_ALIAS, AGGREGATE_VALUE_ALIAS, ROWS_ALIAS, JSON_ELEM_ALIAS, JSON_PULL_ALIAS, relationSortColumn, } from './aliases.js';
 import { holdsOperator, isJsonScalar, jsonCompareMode, jsonElemExists, jsonPath, } from './jsonSql.js';
+import { betweenBounds, COMPARE_OPS, EQUALITY_OPS, GROUP_OPS, groupClauses, inOperands, isGroupOp, isOrderedOp, isVectorQuery, LIKE_OPS, ORDERED_OPS, VECTOR_QUERY_KEY_SET, whereOperators, } from './operators.js';
 import { SqlQueryContext } from './queryContext.js';
 import { groupPathField, NO_JOINS, aggregateColumnField, resolveGroupJoins, resolveQueryJoins, relationSortTerms, resolveSortableJoin, } from './queryJoins.js';
 import { resolveVectorCast } from './vectorCast.js';
@@ -33,14 +34,43 @@ function orRefuse(value, 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)) {
-        throw new UqlUsageError(`${op} expects an array, got ${value === null ? 'null' : typeof value}`);
+/** Conditions joined by `AND`, parenthesized where there is more than one. */
+function conjunction(parts) {
+    return parts.length > 1 ? `(${parts.join(' AND ')})` : parts.join('');
+}
+/**
+ * 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.
+ */
+function jsonOperatorMode(op, value) {
+    if (ORDERED_OPS.has(op)) {
+        return 'numeric';
     }
-    return value;
+    return EQUALITY_OPS.has(op) ? jsonCompareMode(value) : 'text';
 }
+/** `$group` aggregate operator to SQL function name, over ops `resolveAggregateOp` has already allowlisted. */
+const AGGREGATE_FN = {
+    $count: 'COUNT',
+    $sum: 'SUM',
+    $avg: 'AVG',
+    $min: 'MIN',
+    $max: 'MAX',
+};
+const SORT_DIRECTION_MAP = new Map([
+    [1, {}],
+    ['asc', {}],
+    ['desc', { direction: ' DESC' }],
+    [-1, { direction: ' DESC' }],
+    ['ascNullsFirst', { nulls: 'first' }],
+    ['ascNullsLast', { nulls: 'last' }],
+    ['descNullsFirst', { direction: ' DESC', nulls: 'first' }],
+    ['descNullsLast', { direction: ' DESC', nulls: 'last' }],
+]);
 export class AbstractSqlDialect extends VectorSqlDialect {
+    /** Itself, unless the engine is a fork running another's SQL, which is the only case that overrides. */
+    get dialectFamily() {
+        return this.dialectName;
+    }
     /**
      * How this engine declares a namespace, so a generated migration creates the schemas its tables
      * need before creating them. Only reached where {@link DialectFeatures.schemas} is on. MySQL and
@@ -142,10 +172,14 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         const expression = this.returningIdExpression(meta);
         return expression ? `RETURNING ${expression}` : '';
     }
+    /** What the returned row is read off, for an engine that names it: SQL Server's `INSERTED.`. */
+    returnedRowPrefix = '';
     /** `<id column> AS id` on its own, for a statement composing a `RETURNING` list of several items. */
     returningIdExpression(meta) {
         const [idKey] = meta.ids;
-        return meta.ids.length === 1 ? `${this.escapeId(this.columnOf(meta, idKey))} ${this.escapeId('id')}` : '';
+        return meta.ids.length === 1
+            ? `${this.returnedRowPrefix}${this.escapeId(this.columnOf(meta, idKey))} ${this.escapeId('id')}`
+            : '';
     }
     search(ctx, entity, q = {}, opts = {}, joins = NO_JOINS, order) {
         const meta = getMeta(entity);
@@ -258,7 +292,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     }
     /** The columns a `$text` over `keys` reads, qualified by `prefix` where the statement joins, as any column is. */
     textColumns(meta, keys, prefix) {
-        return keys.map((key) => this.columnWithPrefix(key, meta.fields[key], prefix));
+        return keys.map((key) => this.columnWithPrefix(key, meta.fields[key], { prefix }));
     }
     /** Ranks by the root `$text` of `where`, which is looked up only once a `$sort` asks for it. */
     textRanker(meta, where, prefix) {
@@ -447,14 +481,14 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             }
             this.getComparisonKey(ctx, entity, key, opts);
             ctx.append(' = ');
-            this.getRawValue(ctx, { value: val, prefix: opts.prefix });
+            this.getRawValue(ctx, { ...opts, value: val });
             return;
         }
         if (key === '$text') {
             this.appendTextSearch(ctx, meta, val, opts.prefix);
             return;
         }
-        if (AbstractSqlDialect.isGroupOp(key)) {
+        if (isGroupOp(key)) {
             this.compareLogicalOperator(ctx, entity, key, val, opts);
             return;
         }
@@ -477,27 +511,23 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             this.compareRelation(ctx, entity, key, val, rel, opts);
             return;
         }
-        const value = this.normalizeWhereValue(val);
-        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('');
+        const parts = whereOperators(val, 'unknown operator').map(([op, value]) => this.fieldCondition(ctx, entity, key, op, value, opts));
+        ctx.append(conjunction(parts));
     }
     compareLogicalOperator(ctx, entity, key, val, opts) {
-        const { join, negate } = AbstractSqlDialect.GROUP_OPS[key];
-        const items = AbstractSqlDialect.groupClauses(key, val);
+        const { join, negate } = GROUP_OPS[key];
+        const items = groupClauses(key, val);
         // With more than one item each is an operand of the operator joining them, so a compound item
         // parenthesizes itself and precedence never applies; a lone item is this group verbatim, so it
         // inherits the group's own position. A negation always makes its subject an operand.
         const childOperand = items.length > 1 || negate || opts.operand;
         const parts = this.renderOperands(ctx, items, (fragmentCtx, entry) => {
+            // The same scope as the group, so every render option carries over: a trigger's `NEW.` included.
             if (entry instanceof QueryRaw) {
-                this.getRawValue(fragmentCtx, { value: entry, prefix: opts.prefix });
+                this.getRawValue(fragmentCtx, { ...opts, value: entry });
             }
             else {
-                this.renderWhere(fragmentCtx, entity, entry, { prefix: opts.prefix, operand: childOperand, clause: false });
+                this.renderWhere(fragmentCtx, entity, entry, { ...opts, operand: childOperand, clause: false });
             }
         });
         if (!parts.length) {
@@ -509,40 +539,6 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     }
     /** Memoizes {@link escapedColumnName}; see there for why it is per dialect instance. */
     escapedColumns = new WeakMap();
-    static COMPARE_OP_MAP = new Map([
-        ['$gt', ' > '],
-        ['$gte', ' >= '],
-        ['$lt', ' < '],
-        ['$lte', ' <= '],
-    ]);
-    /** What a `$near` says about the search itself; everything else in it is a bound. */
-    static VECTOR_QUERY_KEYS = new Set(VECTOR_QUERY_KEYS);
-    /**
-     * The 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 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
-     * two can never drift apart - and neither one decides case folding, which is
-     * {@link caseInsensitiveMatch}'s single call.
-     */
-    static LIKE_OPS = new Map([
-        ['$like', '$ilike', (v) => v],
-        ['$startsWith', '$istartsWith', (v) => `${v}%`],
-        ['$endsWith', '$iendsWith', (v) => `%${v}`],
-        ['$includes', '$iincludes', (v) => `%${v}%`],
-    ].flatMap(([sensitive, insensitive, pattern]) => [
-        [sensitive, { pattern, insensitive: false }],
-        [insensitive, { pattern, insensitive: true }],
-    ]));
     /**
      * How the engine matches case-insensitively: `ilike` has the operator, `native` ignores case already
      * (SQLite, where folding in JS would break non-ASCII), and `fold` lowers both sides.
@@ -554,7 +550,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
      * compared against.
      */
     likeCondition(ctx, operand, op, val) {
-        const like = AbstractSqlDialect.LIKE_OPS.get(op);
+        const like = LIKE_OPS.get(op);
         if (!like) {
             return undefined;
         }
@@ -565,8 +561,8 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         return `${fold ? `LOWER(${operand})` : operand} ${matchOp} ${ph}`;
     }
     /** Builds `prefix.column` from an already-resolved field, through the same memo writes use. */
-    columnWithPrefix(key, field, prefix) {
-        return this.escapeId(prefix, true, true) + this.escapedColumnOf(key, field);
+    columnWithPrefix(key, field, opts) {
+        return (opts.escapedPrefix ?? this.escapeId(opts.prefix, true, true)) + this.escapedColumnOf(key, field);
     }
     /**
      * The SQL a field comparison reads its left-hand side from. An inlined field builds its expression
@@ -577,7 +573,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         const meta = getMeta(entity);
         const field = meta.fields[key];
         return (this.inlinedOperand(ctx, field, opts.prefix ?? this.resolveTableAlias(meta), entity) ??
-            this.columnWithPrefix(key, field, opts.prefix));
+            this.columnWithPrefix(key, field, opts));
     }
     /**
      * The expression an inlined computed field stands for, or nothing when the field is a real column.
@@ -608,10 +604,11 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     /**
      * `<operand> <op> <value>` for every operator that needs only its left-hand SQL, shared by a column, a
      * 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.
+     * each compared value, a plain placeholder unless a JSON path reads it otherwise. NULL compares as the
+     * engine compares it: `<>`, `NOT IN` and `NOT` are unknown on a NULL, which SQL drops.
      */
     operatorCondition(ctx, operand, op, val, bind = (value) => this.addValue(ctx, value)) {
-        const compareOp = AbstractSqlDialect.COMPARE_OP_MAP.get(op);
+        const compareOp = COMPARE_OPS.get(op);
         if (compareOp) {
             return `${operand}${compareOp}${bind(val)}`;
         }
@@ -623,14 +620,14 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             case '$eq':
                 return val === null ? `${operand} IS NULL` : `${operand} = ${bind(val)}`;
             case '$ne':
-                return val === null ? `${operand} IS NOT NULL` : this.neExpr(operand, bind(val));
+                return val === null ? `${operand} IS NOT NULL` : `${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', bind);
             case '$between': {
-                const [min, max] = val;
+                const [min, max] = betweenBounds(val);
                 return `${operand} BETWEEN ${bind(min)} AND ${bind(max)}`;
             }
             case '$isNull':
@@ -660,8 +657,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     }
     /** 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])));
+        return conjunction(whereOperators(val, 'unknown operator').map(([op, value]) => this.jsonCondition(ctx, target, op, value)));
     }
     jsonCondition(ctx, target, op, value) {
         if (op === '$not') {
@@ -671,7 +667,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         if (array !== undefined) {
             return array;
         }
-        const mode = AbstractSqlDialect.jsonOperatorMode(op, value);
+        const mode = 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.
@@ -683,16 +679,6 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         const condition = this.operatorCondition(ctx, operand, op, value, (val) => this.jsonOperand(ctx, val, mode));
         return orRefuse(condition, `unknown operator: ${op}`);
     }
-    /**
-     * 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.
-     */
-    static jsonOperatorMode(op, value) {
-        if (AbstractSqlDialect.ORDERED_OPS.has(op)) {
-            return 'numeric';
-        }
-        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') {
@@ -731,7 +717,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
                 : [this.jsonElemEquals(ctx, slot, alias, value)];
             return jsonElemExists(from, holds, this.jsonElemHint);
         });
-        return AbstractSqlDialect.conjunction(conditions);
+        return conjunction(conditions);
     }
     /**
      * What the JSON `target` reads satisfies to hold `value`: an array each of its elements, an object each
@@ -897,7 +883,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         const field = meta.fields[key];
         if (field) {
             const expr = this.inlinedOperand(ctx, field, prefix ?? this.resolveTableAlias(meta), meta.entity) ??
-                this.columnWithPrefix(key, field, prefix);
+                this.columnWithPrefix(key, field, { prefix });
             return [{ expr, output: false }];
         }
         const json = this.resolveJsonDotPath(meta, key, prefix);
@@ -1007,14 +993,6 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     estimatedCount(_ctx, _entity) {
         throw new UqlUsageError(`${this.dialectName} does not support estimatedCount`);
     }
-    /** `$group` aggregate operator to SQL function name, over ops `resolveAggregateOp` has already allowlisted. */
-    static AGGREGATE_FN = {
-        $count: 'COUNT',
-        $sum: 'SUM',
-        $avg: 'AVG',
-        $min: 'MIN',
-        $max: 'MAX',
-    };
     aggregate(ctx, entity, q, opts = {}) {
         const meta = getMeta(entity);
         const entries = parseGroupMap(q.$group, q.$select);
@@ -1121,18 +1099,8 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             this.havingCondition(ctx, this.aggregateRef(emittedColumns, alias, '$having'), condition);
         });
     }
-    static SORT_DIRECTION_MAP = new Map([
-        [1, {}],
-        ['asc', {}],
-        ['desc', { direction: ' DESC' }],
-        [-1, { direction: ' DESC' }],
-        ['ascNullsFirst', { nulls: 'first' }],
-        ['ascNullsLast', { nulls: 'last' }],
-        ['descNullsFirst', { direction: ' DESC', nulls: 'first' }],
-        ['descNullsLast', { direction: ' DESC', nulls: 'last' }],
-    ]);
     resolveSortDirection(sort) {
-        const order = AbstractSqlDialect.SORT_DIRECTION_MAP.get(sort);
+        const order = SORT_DIRECTION_MAP.get(sort);
         return orRefuse(order, `unknown sort direction: ${sort}`);
     }
     /**
@@ -1155,8 +1123,8 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     }
     /** Every operator of one `HAVING` condition, `AND`-joined. */
     havingCondition(ctx, expr, condition) {
-        const ops = this.normalizeWhereValue(condition);
-        const parts = getKeys(ops).map((op) => orRefuse(this.operatorCondition(ctx, expr, op, ops[op]), `unsupported HAVING operator: ${op}`));
+        const refusal = 'unsupported HAVING operator';
+        const parts = whereOperators(condition, refusal).map(([op, value]) => orRefuse(this.operatorCondition(ctx, expr, op, value), `${refusal}: ${op}`));
         ctx.append(parts.join(' AND '));
     }
     /**
@@ -1620,17 +1588,6 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             ? this.numericCast(this.jsonPathReading(escapedColumn, path, 'text'))
             : this.jsonPathReading(escapedColumn, path, mode);
     }
-    /**
-     * Normalizes a raw WHERE value into an operator map.
-     * Arrays become `$in`, operator maps pass through, everything else becomes `$eq`.
-     */
-    normalizeWhereValue(val) {
-        if (Array.isArray(val))
-            return { $in: val };
-        if (isOperatorMap(val))
-            return val;
-        return { $eq: val };
-    }
     /**
      * A field key's mapped column (`@Field({ name })`), escaped, memoized per dialect instance: field
      * metadata is shared between dialects while this result is not, since `escapeIdChar` and the naming
@@ -1759,7 +1716,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     }
     /** One aggregate function call, the one spelling every statement that aggregates writes. */
     aggregateFn(op, operand, distinct) {
-        return `${AbstractSqlDialect.AGGREGATE_FN[op]}(${distinct ? 'DISTINCT ' : ''}${operand})`;
+        return `${AGGREGATE_FN[op]}(${distinct ? 'DISTINCT ' : ''}${operand})`;
     }
     /**
      * One equality per key of the parent, anded: a composite correlates on every column, and matching on
@@ -1901,45 +1858,31 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         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);
+        return conjunction(parts);
     }
-    /**
-     * 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.
-     */
+    /** A count compared with `size`, a number or its bounds. */
     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');
+        return this.boundConditions(ctx, count, bounds, (operand, op, val) => op === '$eq' || op === '$ne' || isOrderedOp(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. */
     vectorNearCondition(ctx, meta, key, near, prefix) {
-        const bounds = {};
-        for (const [op, val] of Object.entries(near)) {
-            if (AbstractSqlDialect.VECTOR_QUERY_KEYS.has(op) || val === undefined) {
-                continue;
-            }
-            if (!AbstractSqlDialect.ORDERED_OPS.has(op)) {
-                throw new UqlUsageError(`unsupported $near bound: ${op}`);
-            }
-            bounds[op] = val;
+        if (!isOperatorMap(near)) {
+            throw new UqlUsageError(`$near on '${key}' expects an object of its $vector and bounds, got ${kindOf(near)}`);
         }
+        const bounds = Object.fromEntries(Object.entries(near).filter(([op, val]) => !VECTOR_QUERY_KEY_SET.has(op) && val !== undefined));
         if (!hasKeys(bounds)) {
-            const boundOps = [...AbstractSqlDialect.ORDERED_OPS].join(', ');
+            const boundOps = [...ORDERED_OPS].join(', ');
             throw new UqlUsageError(`$near on '${key}' needs a bound (${boundOps}); without one it filters nothing`);
         }
         // Required by the type, so this only fires for a query that never met it: `/http` casts client
         // JSON straight to `Query`. A `$near` never borrows the `$sort`'s vector, which is what keeps the
         // predicate meaning the same thing in a `count`, or in an entity filter merged into a `$where`.
-        if (!near.$vector) {
+        if (!isVectorQuery(near)) {
             throw new UqlUsageError(`$near on '${key}' needs its own $vector`);
         }
         const distance = (fragmentCtx) => this.appendVectorDistance(fragmentCtx, meta, key, near, prefix);
-        return this.boundConditions(ctx, distance, bounds, (operand, op, val) => this.operatorCondition(ctx, operand, op, val), 'unsupported $near bound');
+        return this.boundConditions(ctx, distance, bounds, (operand, op, val) => (isOrderedOp(op) ? this.operatorCondition(ctx, operand, op, val) : undefined), 'unsupported $near bound');
     }
     /** ANSI-style single-quote escaping. MySQL-family dialects override this for backslash escaping. */
     escape(value) {
@@ -1960,16 +1903,6 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     get likeFn() {
         return 'LIKE';
     }
-    /**
-     * Not-equal operator token for non-null comparisons.
-     * Postgres uses `IS DISTINCT FROM`; MySQL/Maria uses custom `neExpr`.
-     */
-    get neOp() {
-        return '<>';
-    }
-    neExpr(field, ph) {
-        return `${field} ${this.neOp} ${ph}`;
-    }
     /** `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) {

package/dist/dialect/aliases.d.ts

@@ -1,4 +1,9 @@
 import type { RelationAggregateSpec } from '../type/index.js';
+/**
+ * What every schema object uql creates is named from, so a hand-written trigger or function is never
+ * offered for dropping: ownership is the name, since no engine records who created one.
+ */
+export declare const OWNED_PREFIX = "_uql";
 /** The column a paged read carries its own unpaged total in, from `COUNT(*) OVER ()`. */
 export declare const TOTAL_ALIAS = "_uql_total";
 /**

package/dist/dialect/aliases.js

@@ -1,5 +1,10 @@
 // Every identifier UQL invents, `_uql`-prefixed to stay off a user's own, collected in one place:
 // the ends writing and reading one sit in different modules, and a drift between them fails silently.
+/**
+ * What every schema object uql creates is named from, so a hand-written trigger or function is never
+ * offered for dropping: ownership is the name, since no engine records who created one.
+ */
+export const OWNED_PREFIX = '_uql';
 /** The column a paged read carries its own unpaged total in, from `COUNT(*) OVER ()`. */
 export const TOTAL_ALIAS = '_uql_total';
 /**

package/dist/dialect/mysqlLikeSqlDialect.d.ts

@@ -1,4 +1,4 @@
-import type { EntityMeta, FieldOptions, InsertIdSource, Query, QueryConflictPaths, QueryContext, QueryOptions, QueryPager, QueryTextSearchOptions, RowLockFeatures, SqlDialectFeatures, Type } from '../type/index.js';
+import type { EntityMeta, FieldOptions, InsertIdSource, Query, QueryConflictPaths, QueryContext, QueryOptions, QueryPager, QueryTextSearchOptions, RowLockFeatures, SqlDialectFeatures, SqlDialectName, Type } from '../type/index.js';
 import { AbstractSqlDialect, type DerivedRelation, type RelationRows } from './abstractSqlDialect.js';
 import { type JsonSlot } from './jsonSql.js';
 /** What the MySQL-family engines have. */
@@ -7,6 +7,8 @@ export declare const MYSQL_ROW_LOCKS: RowLockFeatures;
 export declare const MYSQL_FEATURES: SqlDialectFeatures;
 /** What MySQL and MariaDB share, their JSON functions above all: `JSON_LENGTH`, `JSON_CONTAINS`, `JSON_TABLE`, `JSON_SET`. */
 export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
+    /** Every member of this family runs the same SQL, so a body written once serves them all. */
+    get dialectFamily(): SqlDialectName;
     readonly features: SqlDialectFeatures;
     /**
      * `information_schema` keeps InnoDB's own row estimate, which is live enough to answer before
@@ -89,7 +91,7 @@ export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
     protected appendTextScore<E>(ctx: QueryContext, meta: EntityMeta<E>, search: QueryTextSearchOptions<E>, keys: readonly string[], prefix: string | undefined): void;
     /** `DOUBLE`, never a bare `DECIMAL`, which is `DECIMAL(10,0)` and rounds `1.4` to `1`. */
     protected numericCast(expr: string): string;
-    protected neExpr(field: string, ph: string): string;
+    neExpr(field: string, ph: string): string;
     /**
      * Omitting the `COALESCE` on a NOT NULL column keeps MySQL's partial in-place JSON update
      * applicable: it requires the target column as the direct `JSON_SET` input.

package/dist/dialect/mysqlLikeSqlDialect.js

@@ -15,7 +15,6 @@ const MAX_LIMIT = BigInt.asUintN(64, -1n);
 /** Declared apart so MariaDB, which has no `FOR UPDATE OF`, can restate that one part of it. */
 export const MYSQL_ROW_LOCKS = { of: true, withWindow: true, placement: 'suffix' };
 export const MYSQL_FEATURES = {
-    ifNotExists: true,
     indexIfNotExists: false,
     schemas: true,
     dropTableCascade: false,
@@ -39,11 +38,25 @@ export const MYSQL_FEATURES = {
     narrowVectorTypes: false,
     vectorTuningNeedsTransaction: false,
     serialDeclaresPrimaryKey: false,
+    triggers: {
+        preamble: '',
+        assignsRow: true,
+        body: 'inline',
+        guards: 'thenEndIf',
+        layout: 'timingFirst',
+        rows: 'row',
+        scope: 'schema',
+        before: true,
+    },
 };
 /** The one `JSON_TABLE` column an exploded array reads each element through, as a JSON document. */
 const ELEM_COLUMN = 'v';
 /** What MySQL and MariaDB share, their JSON functions above all: `JSON_LENGTH`, `JSON_CONTAINS`, `JSON_TABLE`, `JSON_SET`. */
 export class MysqlLikeSqlDialect extends AbstractSqlDialect {
+    /** Every member of this family runs the same SQL, so a body written once serves them all. */
+    get dialectFamily() {
+        return 'mysql';
+    }
     features = MYSQL_FEATURES;
     /**
      * `information_schema` keeps InnoDB's own row estimate, which is live enough to answer before

package/dist/dialect/operators.d.ts

@@ -0,0 +1,66 @@
+import { type QueryGroupOp, type QueryOrderedOp, type QueryVectorQuery, type QueryWhereArray, type QueryWhereFieldOp } from '../type/index.js';
+/**
+ * How each grouping operator renders: the operator joining its clauses, and whether the group is
+ * negated (`$not` is `NOT (a AND b)`). Total over {@link QueryGroupOp}.
+ */
+export declare const GROUP_OPS: {
+    readonly $and: {
+        readonly join: '$and';
+        readonly negate: false;
+    };
+    readonly $or: {
+        readonly join: '$or';
+        readonly negate: false;
+    };
+    readonly $not: {
+        readonly join: '$and';
+        readonly negate: true;
+    };
+    readonly $nor: {
+        readonly join: '$or';
+        readonly negate: true;
+    };
+};
+/** Whether a `$where` key groups clauses, narrowing it for the renderers that read {@link GROUP_OPS}. */
+export declare function isGroupOp(key: string): key is QueryGroupOp;
+/**
+ * A group operator's clauses, rejecting what the types do not cover: `/http` casts client JSON
+ * straight to `Query`, so a scalar can arrive where an array belongs. Shared so both backends
+ * refuse the same payload rather than one throwing and the other failing further in.
+ */
+export declare function groupClauses<E>(key: QueryGroupOp, val: QueryWhereArray<E> | undefined): QueryWhereArray<E>;
+/**
+ * A WHERE value as the operators it applies: an array is `$in`, an operator map its own entries, and
+ * anything else `$eq`. Each key is checked here, once, refused as `refusal` where it is no operator.
+ */
+export declare function whereOperators(val: unknown, refusal: string): [QueryWhereFieldOp, unknown][];
+/** An `$in`/`$nin` operand, which the types require to be an array but `/http` hands over untyped. */
+export declare function inOperands(op: string, value: unknown): unknown[];
+/** A `$between`'s two bounds, which `/http` hands over untyped too; one missing would bind `undefined`. */
+export declare function betweenBounds(value: unknown): readonly [unknown, unknown];
+/** Whether a `$near` names the vector it measures from, which its type requires and `/http` does not. */
+export declare function isVectorQuery(near: Record<string, unknown>): near is Record<string, unknown> & QueryVectorQuery;
+/** One entry of {@link LIKE_OPS}: how the pattern is built, and whether it ignores case. */
+export type LikeOp = {
+    readonly pattern: (value: string) => string;
+    readonly insensitive: boolean;
+};
+export declare const COMPARE_OPS: ReadonlyMap<QueryWhereFieldOp, string>;
+/**
+ * The ordered comparisons, `QueryOrderedOp` at runtime, derived from {@link COMPARE_OPS} 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.
+ */
+export declare const ORDERED_OPS: ReadonlySet<string>;
+export declare function isOrderedOp(op: string): op is QueryOrderedOp;
+/** The operators an equality compares by value, which a JSON path reads the way that value compares. */
+export declare const EQUALITY_OPS: ReadonlySet<string>;
+/**
+ * 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
+ * two can never drift apart - and neither one decides case folding, which is
+ * `AbstractSqlDialect.caseInsensitiveMatch`'s single call.
+ */
+export declare const LIKE_OPS: ReadonlyMap<string, LikeOp>;
+/** What a `$near` says about the search itself; everything else in it is a bound. */
+export declare const VECTOR_QUERY_KEY_SET: ReadonlySet<string>;