uql-orm 0.21.0 → 0.22.0

package/dist/dialect/indexSqlDialect.d.ts

@@ -0,0 +1,57 @@
+import { type IndexColumnSchema, type IndexFeature, type IndexSchema } from '../type/index.js';
+import { VectorSqlDialect } from './vectorSqlDialect.js';
+/**
+ * `CREATE INDEX` for SQL dialects: the statement and the fragments each engine spells differently.
+ *
+ * A layer of its own for the same reason as {@link VectorSqlDialect} below it - it needs only
+ * `escapeId` and `features.indexIfNotExists` from the SQL dialect above, so keeping it here spares
+ * that 2000-line class thirteen more members. What each engine can express at all is data
+ * ({@link indexFeatures}), validated once, rather than a throw per feature per dialect.
+ */
+export declare abstract class IndexSqlDialect extends VectorSqlDialect {
+    /**
+     * The `CREATE INDEX` statement for this dialect. The form here is the portable one, which SQLite
+     * (and so libSQL, Turso and D1) takes verbatim: no access-method clause, no operator classes, no
+     * tuning parameters. Dialects that have those override the fragments below rather than this.
+     */
+    getCreateIndexStatement(tableName: string, index: IndexSchema, opts?: {
+        ifNotExists?: boolean;
+    }): string;
+    /**
+     * Index features this dialect can express. Everything here is supported by at least one engine and
+     * refused by at least one other, so an index asking for a missing one is rejected rather than
+     * emitted: each of them is a hard error at the server, not a slower plan.
+     */
+    protected readonly indexFeatures: ReadonlySet<IndexFeature>;
+    private assertIndexFeatures;
+    /**
+     * The column-level declaration for a vector index that lives inside `CREATE TABLE` rather than in
+     * its own statement, which the `inlineVectorIndex` feature flags. Only MariaDB has one.
+     */
+    getInlineVectorIndexDeclaration(index: IndexSchema): string;
+    /** Only CockroachDB's native vector index replaces the `INDEX` keyword. */
+    protected indexKeyword(_index: IndexSchema): string;
+    /** One index entry: what is indexed, its operator class if any, then its stored order. */
+    protected indexColumn(entry: IndexColumnSchema, index: IndexSchema): string;
+    /**
+     * A quoted column, optionally prefix-limited, or an expression in its own parentheses - the form
+     * `((lower("email")))` that MySQL requires and Postgres, CockroachDB and SQLite all accept, so one
+     * rendering serves every engine that has expression indexes.
+     */
+    protected indexColumnTarget(entry: IndexColumnSchema): string;
+    /** Postgres-wire dialects put a vector or user-declared operator class here. */
+    protected indexColumnOpsClass(_entry: IndexColumnSchema, _index: IndexSchema): string;
+    /** `ASC` is every engine's default, so only `DESC` is worth emitting. */
+    protected indexColumnOrder(entry: IndexColumnSchema): string;
+    /** ` INCLUDE (...)`: non-key columns stored for index-only scans. Postgres-wire only. */
+    protected indexInclude(_index: IndexSchema): string;
+    /** ` USING <method>`, which SQLite's grammar has no place for at all. */
+    protected indexAccessMethod(_index: IndexSchema): string;
+    /** pgvector's ` WITH (m = ..., ef_construction = ..., lists = ...)`. */
+    protected indexTuning(_index: IndexSchema): string;
+    /**
+     * The partial-index predicate. Dialects without partial indexes throw instead of dropping it:
+     * silently widening a partial unique index changes which rows the database accepts.
+     */
+    protected indexPredicate(index: IndexSchema): string;
+}

package/dist/dialect/indexSqlDialect.js

@@ -0,0 +1,101 @@
+import { INDEX_FEATURE_LABELS } from '../type/index.js';
+import { VectorSqlDialect } from './vectorSqlDialect.js';
+/**
+ * `CREATE INDEX` for SQL dialects: the statement and the fragments each engine spells differently.
+ *
+ * A layer of its own for the same reason as {@link VectorSqlDialect} below it - it needs only
+ * `escapeId` and `features.indexIfNotExists` from the SQL dialect above, so keeping it here spares
+ * that 2000-line class thirteen more members. What each engine can express at all is data
+ * ({@link indexFeatures}), validated once, rather than a throw per feature per dialect.
+ */
+export class IndexSqlDialect extends VectorSqlDialect {
+    /**
+     * The `CREATE INDEX` statement for this dialect. The form here is the portable one, which SQLite
+     * (and so libSQL, Turso and D1) takes verbatim: no access-method clause, no operator classes, no
+     * tuning parameters. Dialects that have those override the fragments below rather than this.
+     */
+    getCreateIndexStatement(tableName, index, opts = {}) {
+        this.assertIndexFeatures(index);
+        const unique = index.unique ? 'UNIQUE ' : '';
+        const ifNotExists = (opts.ifNotExists ?? this.features.indexIfNotExists) ? 'IF NOT EXISTS ' : '';
+        const columns = index.columns.map((entry) => this.indexColumn(entry, index)).join(', ');
+        return (`CREATE ${unique}${this.indexKeyword(index)} ${ifNotExists}${this.escapeId(index.name)} ` +
+            `ON ${this.escapeId(tableName)}${this.indexAccessMethod(index)} (${columns})` +
+            `${this.indexInclude(index)}${this.indexTuning(index)}${this.indexPredicate(index)};`);
+    }
+    /**
+     * Index features this dialect can express. Everything here is supported by at least one engine and
+     * refused by at least one other, so an index asking for a missing one is rejected rather than
+     * emitted: each of them is a hard error at the server, not a slower plan.
+     */
+    indexFeatures = new Set(['expression']);
+    assertIndexFeatures(index) {
+        const requested = [
+            ['expression', index.columns.some((entry) => entry.expression)],
+            ['prefixLength', index.columns.some((entry) => entry.length !== undefined)],
+            ['nullsOrder', index.columns.some((entry) => entry.nulls !== undefined)],
+            ['opsClass', index.columns.some((entry) => entry.opsClass !== undefined)],
+            ['include', Boolean(index.include?.length)],
+        ];
+        for (const [feature, needed] of requested) {
+            if (needed && !this.indexFeatures.has(feature)) {
+                throw new TypeError(`${this.dialectName} does not support ${INDEX_FEATURE_LABELS[feature]} (index "${index.name}")`);
+            }
+        }
+    }
+    /**
+     * The column-level declaration for a vector index that lives inside `CREATE TABLE` rather than in
+     * its own statement, which the `inlineVectorIndex` feature flags. Only MariaDB has one.
+     */
+    getInlineVectorIndexDeclaration(index) {
+        throw new TypeError(`${this.dialectName} has no inline vector index (index "${index.name}")`);
+    }
+    /** Only CockroachDB's native vector index replaces the `INDEX` keyword. */
+    indexKeyword(_index) {
+        return 'INDEX';
+    }
+    /** One index entry: what is indexed, its operator class if any, then its stored order. */
+    indexColumn(entry, index) {
+        return `${this.indexColumnTarget(entry)}${this.indexColumnOpsClass(entry, index)}${this.indexColumnOrder(entry)}`;
+    }
+    /**
+     * A quoted column, optionally prefix-limited, or an expression in its own parentheses - the form
+     * `((lower("email")))` that MySQL requires and Postgres, CockroachDB and SQLite all accept, so one
+     * rendering serves every engine that has expression indexes.
+     */
+    indexColumnTarget(entry) {
+        if (entry.expression) {
+            return `(${entry.column})`;
+        }
+        const column = this.escapeId(entry.column);
+        return entry.length === undefined ? column : `${column}(${entry.length})`;
+    }
+    /** Postgres-wire dialects put a vector or user-declared operator class here. */
+    indexColumnOpsClass(_entry, _index) {
+        return '';
+    }
+    /** `ASC` is every engine's default, so only `DESC` is worth emitting. */
+    indexColumnOrder(entry) {
+        const order = entry.order === 'desc' ? ' DESC' : '';
+        return entry.nulls ? `${order} NULLS ${entry.nulls.toUpperCase()}` : order;
+    }
+    /** ` INCLUDE (...)`: non-key columns stored for index-only scans. Postgres-wire only. */
+    indexInclude(_index) {
+        return '';
+    }
+    /** ` USING <method>`, which SQLite's grammar has no place for at all. */
+    indexAccessMethod(_index) {
+        return '';
+    }
+    /** pgvector's ` WITH (m = ..., ef_construction = ..., lists = ...)`. */
+    indexTuning(_index) {
+        return '';
+    }
+    /**
+     * The partial-index predicate. Dialects without partial indexes throw instead of dropping it:
+     * silently widening a partial unique index changes which rows the database accepts.
+     */
+    indexPredicate(index) {
+        return index.where ? ` WHERE ${index.where}` : '';
+    }
+}

package/dist/dialect/mysqlLikeSqlDialect.d.ts

@@ -1,4 +1,4 @@
-import type { DialectFeatures, FieldOptions, InsertIdSource, QueryContext, QuerySizeComparisonOps } from '../type/index.js';
+import type { DialectFeatures, EntityMeta, FieldOptions, IndexFeature, IndexSchema, InsertIdSource, QueryContext, QuerySizeComparisonOps, QueryTextSearchOptions, Type } from '../type/index.js';
 import { AbstractSqlDialect } from './abstractSqlDialect.js';
 /**
  * Shared JSON-array / JSON-object operator implementation between MySQL and MariaDB.
@@ -28,6 +28,21 @@ export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
     readonly insertIdSource: InsertIdSource;
     readonly maxBindValues: number;
     escape(value: unknown): string;
+    /**
+     * `MATCH(cols) AGAINST(?)`, which needs a `FULLTEXT` index over exactly those columns: without one
+     * the server answers "Can't find FULLTEXT index matching the column list". Declare it with
+     * `@Index([...], { type: 'fulltext' })`.
+     */
+    protected appendTextSearch<E>(ctx: QueryContext, _entity: Type<E>, meta: EntityMeta<E>, search: QueryTextSearchOptions<E>): void;
+    /**
+     * A full-text index is its own keyword here (`CREATE FULLTEXT INDEX ... (cols)`); `USING fulltext`
+     * is a syntax error, so it is the keyword that changes rather than the access method.
+     */
+    protected indexKeyword(index: IndexSchema): string;
+    protected readonly indexFeatures: Set<IndexFeature>;
+    protected indexAccessMethod(index: IndexSchema): string;
+    /** Neither MySQL nor MariaDB has partial indexes, and quietly widening one changes which rows it rejects. */
+    protected indexPredicate(index: IndexSchema): string;
     protected numericCast(expr: string): string;
     protected ilikeExpr(f: string, ph: string): string;
     protected neExpr(field: string, ph: string): string;

package/dist/dialect/mysqlLikeSqlDialect.js

@@ -1,3 +1,4 @@
+import { getFieldKeys } from '../util/index.js';
 import { escapeMysqlSqlLiteral, escapeSingleQuotes } from '../util/sqlLiteral.js';
 import { AbstractSqlDialect } from './abstractSqlDialect.js';
 import { JSON_PULL_ALIAS, jsonAssignCall, jsonPath, jsonRemoveCall, jsonSetTarget } from './jsonSql.js';
@@ -23,7 +24,7 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
         renameColumn: true,
         foreignKeyAlter: true,
         columnComment: true,
-        vectorIndexStyle: 'inline',
+        inlineVectorIndex: false,
         vectorSupportsLength: false,
         supportsTimestamptz: false,
         defaultStringAsText: false,
@@ -47,6 +48,36 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
     escape(value) {
         return escapeMysqlSqlLiteral(value);
     }
+    /**
+     * `MATCH(cols) AGAINST(?)`, which needs a `FULLTEXT` index over exactly those columns: without one
+     * the server answers "Can't find FULLTEXT index matching the column list". Declare it with
+     * `@Index([...], { type: 'fulltext' })`.
+     */
+    appendTextSearch(ctx, _entity, meta, search) {
+        const searchFields = search.$fields ?? getFieldKeys(meta.fields);
+        const columns = searchFields.map((key) => this.escapeId(this.resolveColumnName(key, meta.fields[key])));
+        ctx.append(`MATCH(${columns.join(', ')}) AGAINST(`);
+        ctx.addValue(search.$value);
+        ctx.append(')');
+    }
+    /**
+     * A full-text index is its own keyword here (`CREATE FULLTEXT INDEX ... (cols)`); `USING fulltext`
+     * is a syntax error, so it is the keyword that changes rather than the access method.
+     */
+    indexKeyword(index) {
+        return index.type === 'fulltext' ? 'FULLTEXT INDEX' : super.indexKeyword(index);
+    }
+    indexFeatures = new Set(['expression', 'prefixLength']);
+    indexAccessMethod(index) {
+        return index.type && index.type !== 'fulltext' ? ` USING ${index.type}` : '';
+    }
+    /** Neither MySQL nor MariaDB has partial indexes, and quietly widening one changes which rows it rejects. */
+    indexPredicate(index) {
+        if (index.where) {
+            throw new TypeError(`${this.dialectName} does not support partial indexes (index "${index.name}" declares a "where" condition)`);
+        }
+        return '';
+    }
     numericCast(expr) {
         return `CAST(${expr} AS DECIMAL)`;
     }

package/dist/dialect/pgLikeSqlDialect.d.ts

@@ -1,4 +1,4 @@
-import { type DialectFeatures, type EntityMeta, type FieldOptions, type JsonColumnType, type QueryComparisonOptions, type QueryConflictPaths, type QueryContext, type QueryOptions, type QuerySizeComparisonOps, type QueryVectorSearch, type Type, type VectorDistance } from '../type/index.js';
+import { type DialectFeatures, type EntityMeta, type FieldOptions, type IndexColumnSchema, type IndexFeature, type IndexSchema, type JsonColumnType, type QueryConflictPaths, type QueryContext, type QuerySizeComparisonOps, type QueryTextSearchOptions, type QueryVectorSearch, type Type, type VectorDistance } from '../type/index.js';
 import { AbstractSqlDialect } from './abstractSqlDialect.js';
 /**
  * Shared AST/quoting/JSONB/full-text-search/vector-search implementation between Postgres and
@@ -21,10 +21,31 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
     readonly alterColumnStrategy = "separate-clauses";
     readonly insertIdSource = "returning";
     readonly maxBindValues: number;
-    readonly vectorOpsClass: ReadonlyMap<VectorDistance, string> | undefined;
+    /**
+     * Each metric's pgvector distance operator and the operator-class suffix its index takes, in one
+     * place so a dialect cannot end up with the operator but not the opclass. The key set is the single
+     * source of truth for which metrics the dialect supports at all: CockroachDB narrows it to three.
+     */
+    readonly vectorMetrics: ReadonlyMap<VectorDistance, {
+        op: string;
+        opsSuffix: string;
+    }>;
     normalizeValue(value: unknown): unknown;
+    /** pgvector's own index types; CockroachDB's native one widens this. */
+    protected isVectorIndex(index: IndexSchema): boolean;
+    protected indexAccessMethod(index: IndexSchema): string;
+    protected readonly indexFeatures: Set<IndexFeature>;
+    /**
+     * A vector index's operator class is named `{type}_{metric}_ops`: an index on a `halfvec` column
+     * needs `halfvec_cosine_ops`, and `vector_cosine_ops` there is rejected outright. An unsupported
+     * distance throws rather than being omitted, since a bare `USING hnsw ("embedding")` would build
+     * with the dialect's default metric instead of the one requested, with nothing signalling it.
+     * Everything else takes the operator class the entry declares, e.g. `jsonb_path_ops` for GIN.
+     */
+    protected indexColumnOpsClass(entry: IndexColumnSchema, index: IndexSchema): string;
+    protected indexInclude(index: IndexSchema): string;
+    protected indexTuning(index: IndexSchema): string;
     placeholder(index: number): string;
-    insert<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[], opts?: QueryOptions): void;
     upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[]): void;
     /**
      * Shared `INSERT ... ON CONFLICT (...) DO UPDATE/NOTHING RETURNING ...` builder, assembling
@@ -35,11 +56,11 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
      */
     protected buildUpsertOnConflict<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[], extraReturning?: string): void;
     /**
-     * Full-text search: `to_tsvector(...) @@ websearch_to_tsquery(...)`. `websearch_to_tsquery` takes
-     * free-form user input (quoted phrases, `or`, `-negation`) and never raises a syntax error, unlike
-     * `to_tsquery`, which rejects anything unparseable - including a plain two-word search.
+     * `to_tsvector(...) @@ websearch_to_tsquery(...)`. `websearch_to_tsquery` takes free-form user input
+     * (quoted phrases, `or`, `-negation`) and never raises a syntax error, unlike `to_tsquery`, which
+     * rejects anything unparseable - including a plain two-word search.
      */
-    compare<E>(ctx: QueryContext, entity: Type<E>, key: string, val: unknown, opts?: QueryComparisonOptions): void;
+    protected appendTextSearch<E>(ctx: QueryContext, _entity: Type<E>, meta: EntityMeta<E>, search: QueryTextSearchOptions<E>): void;
     protected jsonAll(ctx: QueryContext, jsonField: string, value: unknown): string;
     protected jsonSize(ctx: QueryContext, jsonField: string, value: number | QuerySizeComparisonOps): string;
     /**
@@ -54,7 +75,11 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
     protected formatIn(ctx: QueryContext, values: unknown[], negate: boolean): string;
     protected numericCast(expr: string): string;
     protected appendJsonValue(ctx: QueryContext, value: unknown, type: JsonColumnType): void;
-    protected appendVectorValue(ctx: QueryContext, value: readonly unknown[]): void;
+    /**
+     * pgvector needs the cast to pick the right type, and `sparsevec` needs its own literal: the dense
+     * `[1,0,2]` every other type takes is rejected as "invalid input syntax for type sparsevec".
+     */
+    protected appendVectorValue(ctx: QueryContext, value: readonly unknown[], field?: FieldOptions): void;
     /**
      * `create_if_missing => false` keeps an absent key (and a NULL column) untouched; `WITH
      * ORDINALITY` keeps the surviving elements in their original order.
@@ -70,13 +95,6 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
      * Helper to add a JSON value to context with appropriate stringification and cast.
      */
     private jsonVal;
-    /**
-     * pgvector distance operators. Not every dialect supports every metric - see
-     * {@link CockroachDialect.vectorOpsClass} for which ones each dialect actually has; the
-     * `vectorOpsClass` key set (checked in `appendVectorSort` below via `vectorOpsClass.get`)
-     * is the single source of truth for that, not this map.
-     */
-    private static readonly VECTOR_OPS;
     /** Emit a pgvector-style distance expression: `"col" <op> $N::<vectorType>`. */
     protected appendVectorSort<E>(ctx: QueryContext, meta: EntityMeta<E>, key: string, search: QueryVectorSearch): void;
 }

package/dist/dialect/pgLikeSqlDialect.js

@@ -3,6 +3,7 @@ import { QueryRaw, } from '../type/index.js';
 import { escapeSingleQuotes } from '../util/sqlLiteral.js';
 import { AbstractSqlDialect } from './abstractSqlDialect.js';
 import { JSON_PULL_ALIAS, jsonSetTarget } from './jsonSql.js';
+import { resolveVectorCast, toSparsevecLiteral } from './vectorCast.js';
 /**
  * Shared AST/quoting/JSONB/full-text-search/vector-search implementation between Postgres and
  * CockroachDB (wire- and SQL-compatible for everything below, including `to_tsvector`/`to_tsquery`
@@ -24,7 +25,7 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
         renameColumn: true,
         foreignKeyAlter: true,
         columnComment: false,
-        vectorIndexStyle: 'create',
+        inlineVectorIndex: false,
         vectorSupportsLength: true,
         supportsTimestamptz: true,
         defaultStringAsText: true,
@@ -42,12 +43,16 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
     alterColumnStrategy = 'separate-clauses';
     insertIdSource = 'returning';
     maxBindValues = 65535;
-    vectorOpsClass = new Map([
-        ['cosine', 'vector_cosine_ops'],
-        ['l2', 'vector_l2_ops'],
-        ['inner', 'vector_ip_ops'],
-        ['l1', 'vector_l1_ops'],
-        ['hamming', 'bit_hamming_ops'],
+    /**
+     * Each metric's pgvector distance operator and the operator-class suffix its index takes, in one
+     * place so a dialect cannot end up with the operator but not the opclass. The key set is the single
+     * source of truth for which metrics the dialect supports at all: CockroachDB narrows it to three.
+     */
+    vectorMetrics = new Map([
+        ['cosine', { op: '<=>', opsSuffix: 'cosine' }],
+        ['l2', { op: '<->', opsSuffix: 'l2' }],
+        ['inner', { op: '<#>', opsSuffix: 'ip' }],
+        ['l1', { op: '<+>', opsSuffix: 'l1' }],
     ]);
     normalizeValue(value) {
         if (value != null && typeof value === 'object' && Array.isArray(value)) {
@@ -55,13 +60,61 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
         }
         return super.normalizeValue(value);
     }
+    /** pgvector's own index types; CockroachDB's native one widens this. */
+    isVectorIndex(index) {
+        return index.type === 'hnsw' || index.type === 'ivfflat';
+    }
+    indexAccessMethod(index) {
+        return index.type ? ` USING ${index.type}` : '';
+    }
+    indexFeatures = new Set([
+        'expression',
+        'nullsOrder',
+        'opsClass',
+        'include',
+    ]);
+    /**
+     * A vector index's operator class is named `{type}_{metric}_ops`: an index on a `halfvec` column
+     * needs `halfvec_cosine_ops`, and `vector_cosine_ops` there is rejected outright. An unsupported
+     * distance throws rather than being omitted, since a bare `USING hnsw ("embedding")` would build
+     * with the dialect's default metric instead of the one requested, with nothing signalling it.
+     * Everything else takes the operator class the entry declares, e.g. `jsonb_path_ops` for GIN.
+     */
+    indexColumnOpsClass(entry, index) {
+        if (!this.isVectorIndex(index) || !index.distance) {
+            return entry.opsClass ? ` ${entry.opsClass}` : '';
+        }
+        const metric = this.vectorMetrics.get(index.distance);
+        if (!metric) {
+            throw new TypeError(`${this.dialectName} does not support vector distance metric: ${index.distance} (index "${index.name}")`);
+        }
+        const vectorType = this.supportedVectorType(index.vectorType ?? 'vector');
+        const opsClass = `${vectorType}_${metric.opsSuffix}_ops`;
+        // IVFFlat has neither a sparsevec nor an L1 operator class; HNSW has all of them (pgvector 0.8.2).
+        if (index.type === 'ivfflat' && (vectorType === 'sparsevec' || index.distance === 'l1')) {
+            throw new TypeError(`ivfflat has no ${opsClass} operator class (index "${index.name}"); use hnsw`);
+        }
+        return ` ${opsClass}`;
+    }
+    indexInclude(index) {
+        return index.include?.length ? ` INCLUDE (${index.include.map((column) => this.escapeId(column)).join(', ')})` : '';
+    }
+    indexTuning(index) {
+        if (!this.isVectorIndex(index)) {
+            return '';
+        }
+        const params = [];
+        if (index.m !== undefined)
+            params.push(`m = ${index.m}`);
+        if (index.efConstruction !== undefined)
+            params.push(`ef_construction = ${index.efConstruction}`);
+        if (index.lists !== undefined)
+            params.push(`lists = ${index.lists}`);
+        return params.length > 0 ? ` WITH (${params.join(', ')})` : '';
+    }
     placeholder(index) {
         return `$${index}`;
     }
-    insert(ctx, entity, payload, opts) {
-        super.insert(ctx, entity, payload, opts);
-        ctx.append(' ' + this.returningId(entity));
-    }
     upsert(ctx, entity, conflictPaths, payload) {
         this.buildUpsertOnConflict(ctx, entity, conflictPaths, payload);
     }
@@ -77,33 +130,23 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
         const update = this.getUpsertUpdateAssignments(ctx, meta, conflictPaths, payload, (name) => `EXCLUDED.${name}`);
         const keysStr = this.getUpsertConflictPathsStr(meta, conflictPaths);
         const onConflict = update ? `DO UPDATE SET ${update}` : 'DO NOTHING';
-        super.insert(ctx, entity, payload);
+        this.appendInsertValues(ctx, entity, payload);
         ctx.append(` ON CONFLICT (${keysStr}) ${onConflict} ${this.returningId(entity)}${extraReturning}`);
     }
     /**
-     * Full-text search: `to_tsvector(...) @@ websearch_to_tsquery(...)`. `websearch_to_tsquery` takes
-     * free-form user input (quoted phrases, `or`, `-negation`) and never raises a syntax error, unlike
-     * `to_tsquery`, which rejects anything unparseable - including a plain two-word search.
+     * `to_tsvector(...) @@ websearch_to_tsquery(...)`. `websearch_to_tsquery` takes free-form user input
+     * (quoted phrases, `or`, `-negation`) and never raises a syntax error, unlike `to_tsquery`, which
+     * rejects anything unparseable - including a plain two-word search.
      */
-    compare(ctx, entity, key, val, opts = {}) {
-        if (key === '$text') {
-            const meta = getMeta(entity);
-            const search = val;
-            const fields = (search.$fields ?? [])
-                .map((fKey) => {
-                const field = meta.fields[fKey];
-                const columnName = this.resolveColumnName(fKey, field);
-                return this.escapeId(columnName);
-            })
-                .join(` || ' ' || `);
-            // The config is bound once and its numbered placeholder reused by both calls.
-            const config = search.$config ? `${this.addValue(ctx.values, search.$config)}::regconfig, ` : '';
-            ctx.append(`to_tsvector(${config}${fields}) @@ websearch_to_tsquery(${config}`);
-            ctx.addValue(search.$value);
-            ctx.append(')');
-            return;
-        }
-        super.compare(ctx, entity, key, val, opts);
+    appendTextSearch(ctx, _entity, meta, search) {
+        const fields = (search.$fields ?? [])
+            .map((key) => this.escapeId(this.resolveColumnName(key, meta.fields[key])))
+            .join(` || ' ' || `);
+        // The config is bound once and its numbered placeholder reused by both calls.
+        const config = search.$config ? `${this.addValue(ctx.values, search.$config)}::regconfig, ` : '';
+        ctx.append(`to_tsvector(${config}${fields}) @@ websearch_to_tsquery(${config}`);
+        ctx.addValue(search.$value);
+        ctx.append(')');
     }
     jsonAll(ctx, jsonField, value) {
         return `${jsonField} @> ${this.jsonVal(ctx, value)}`;
@@ -146,9 +189,14 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
     appendJsonValue(ctx, value, type) {
         ctx.append(this.jsonVal(ctx, value, type));
     }
-    appendVectorValue(ctx, value) {
-        ctx.addValue(`[${value.join(',')}]`);
-        ctx.append('::vector');
+    /**
+     * pgvector needs the cast to pick the right type, and `sparsevec` needs its own literal: the dense
+     * `[1,0,2]` every other type takes is rejected as "invalid input syntax for type sparsevec".
+     */
+    appendVectorValue(ctx, value, field) {
+        const vectorType = this.supportedVectorType(resolveVectorCast(field));
+        ctx.addValue(vectorType === 'sparsevec' ? toSparsevecLiteral(value) : `[${value.join(',')}]`);
+        ctx.append(`::${vectorType}`);
     }
     /**
      * `create_if_missing => false` keeps an absent key (and a NULL column) untouched; `WITH
@@ -189,29 +237,15 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
         const ph = this.addValue(ctx.values, json);
         return this.features.explicitJsonCast ? `(${ph}::text)::${type}` : `${ph}::${type}`;
     }
-    /**
-     * pgvector distance operators. Not every dialect supports every metric - see
-     * {@link CockroachDialect.vectorOpsClass} for which ones each dialect actually has; the
-     * `vectorOpsClass` key set (checked in `appendVectorSort` below via `vectorOpsClass.get`)
-     * is the single source of truth for that, not this map.
-     */
-    static VECTOR_OPS = {
-        cosine: '<=>',
-        l2: '<->',
-        inner: '<#>',
-        l1: '<+>',
-        hamming: '<~>',
-    };
     /** Emit a pgvector-style distance expression: `"col" <op> $N::<vectorType>`. */
     appendVectorSort(ctx, meta, key, search) {
-        const { colName, distance, vectorCast } = this.resolveVectorSortParams(meta, key, search);
-        if (!this.vectorOpsClass.get(distance)) {
+        const { colName, distance, field } = this.resolveVectorSortParams(meta, key, search);
+        const metric = this.vectorMetrics.get(distance);
+        if (!metric) {
             throw new TypeError(`${this.dialectName} does not support vector distance metric: ${distance}`);
         }
-        const op = PgLikeSqlDialect.VECTOR_OPS[distance];
-        ctx.append(`${this.escapeId(colName)} ${op} `);
-        ctx.addValue(`[${search.$vector.join(',')}]`);
-        ctx.append(`::${vectorCast}`);
+        ctx.append(`${this.escapeId(colName)} ${metric.op} `);
+        this.appendVectorValue(ctx, search.$vector, field);
     }
 }
 /**

package/dist/dialect/vectorCast.d.ts

@@ -2,10 +2,31 @@
  * Kept out of `schema/canonicalType.ts`: importing one function from that migration/codegen module
  * pulled all ~18 KB of its type-mapping tables into every consumer's bundle.
  */
+import type { DialectName } from '../type/querier.js';
 /** Vector cast types supported by pgvector. */
 export type VectorCast = 'vector' | 'halfvec' | 'sparsevec';
+/**
+ * The dialects that have more than one vector column type. pgvector is the only one: `halfvec` and
+ * `sparsevec` exist nowhere else (`HALFVEC(3)` is a syntax error on CockroachDB 26.2 and MariaDB 12.3,
+ * not merely unsupported at runtime), so a field declaring one is stored - and therefore cast - as
+ * plain `vector`. Both halves of that used to be stated separately, in this dialect layer and in the
+ * migration type maps.
+ */
+export declare const MULTI_VECTOR_TYPE_DIALECTS: ReadonlySet<DialectName>;
+/**
+ * Whether a declared field type is a vector of any width. Every dialect that treats vectors specially
+ * has to answer this for all three, not just `vector`: matching that one alone left `halfvec` and
+ * `sparsevec` fields binding as plain arrays on insert and reading back raw.
+ */
+export declare function isVectorFieldType(type: unknown): boolean;
 /** Resolves the effective cast from field options, `columnType` taking priority over `type`. */
 export declare function resolveVectorCast(field: {
     type?: unknown;
     columnType?: unknown;
 } | undefined): VectorCast;
+/**
+ * pgvector's `sparsevec` literal: 1-based `index:value` pairs of the non-zero elements, then the
+ * dimension count (`{1:1,3:2}/3`). A dense `[1,0,2]` is rejected outright by that type, so an entity
+ * declaring `type: 'sparsevec'` still hands UQL the dense array its field type promises.
+ */
+export declare function toSparsevecLiteral(values: readonly unknown[]): string;

package/dist/dialect/vectorCast.js

@@ -2,6 +2,22 @@
  * Kept out of `schema/canonicalType.ts`: importing one function from that migration/codegen module
  * pulled all ~18 KB of its type-mapping tables into every consumer's bundle.
  */
+/**
+ * The dialects that have more than one vector column type. pgvector is the only one: `halfvec` and
+ * `sparsevec` exist nowhere else (`HALFVEC(3)` is a syntax error on CockroachDB 26.2 and MariaDB 12.3,
+ * not merely unsupported at runtime), so a field declaring one is stored - and therefore cast - as
+ * plain `vector`. Both halves of that used to be stated separately, in this dialect layer and in the
+ * migration type maps.
+ */
+export const MULTI_VECTOR_TYPE_DIALECTS = new Set(['postgres']);
+/**
+ * Whether a declared field type is a vector of any width. Every dialect that treats vectors specially
+ * has to answer this for all three, not just `vector`: matching that one alone left `halfvec` and
+ * `sparsevec` fields binding as plain arrays on insert and reading back raw.
+ */
+export function isVectorFieldType(type) {
+    return type === 'vector' || type === 'halfvec' || type === 'sparsevec';
+}
 /** Resolves the effective cast from field options, `columnType` taking priority over `type`. */
 export function resolveVectorCast(field) {
     const raw = field?.columnType ?? field?.type;
@@ -11,3 +27,15 @@ export function resolveVectorCast(field) {
         return 'sparsevec';
     return 'vector';
 }
+/**
+ * pgvector's `sparsevec` literal: 1-based `index:value` pairs of the non-zero elements, then the
+ * dimension count (`{1:1,3:2}/3`). A dense `[1,0,2]` is rejected outright by that type, so an entity
+ * 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}`;
+}

package/dist/dialect/vectorSqlDialect.d.ts

@@ -14,8 +14,6 @@ import { type VectorCast } from './vectorCast.js';
  * {@link appendVectorSort} or filling {@link vectorDistanceFns}.
  */
 export declare abstract class VectorSqlDialect extends AbstractDialect {
-    /** Vector index operator classes, keyed by distance metric. Partial: not every dialect supports every metric. */
-    readonly vectorOpsClass: ReadonlyMap<VectorDistance, string> | undefined;
     readonly vectorExtension: string | undefined;
     /**
      * Mapping of UQL vector distance metrics to native SQL functions.
@@ -33,8 +31,17 @@ export declare abstract class VectorSqlDialect extends AbstractDialect {
         colName: string;
         distance: VectorDistance;
         field: FieldOptions | undefined;
-        vectorCast: VectorCast;
     };
+    /**
+     * Binds a vector, both as a persisted value and as the query vector of a distance expression, so a
+     * dialect needing a conversion around it (`$1::vector`, `VEC_FromText(?)`) declares it once.
+     */
+    protected appendVectorValue(ctx: QueryContext, value: readonly unknown[], _field?: FieldOptions): void;
+    /**
+     * The vector type this dialect actually has for a declared one, so the cast follows the column
+     * rather than naming a type the engine does not define. See {@link MULTI_VECTOR_TYPE_DIALECTS}.
+     */
+    protected supportedVectorType(cast: VectorCast): VectorCast;
     /**
      * Append a vector similarity function call: `fn(col, ?)`.
      * Used by dialects that express vector distance via SQL functions (SQLite, MariaDB).