uql-orm 0.37.1 → 0.39.0

package/dist/migrate/schemaGenerator.js

@@ -5,6 +5,7 @@ import { buildSchemaAST } from '../schema/schemaASTBuilder.js';
 import { getKeys, isAutoIncrement, qualifyName } from '../util/index.js';
 import { derivedForeignKeyName } from '../util/sql.util.js';
 import { formatDefaultValue, SqlExpression } from './builder/expressions.js';
+import { indexDdlFor } from './ddl/index.js';
 import { fullColumnDefinitionToNode, tableDefinitionToNode } from './generator/definitionToNode.js';
 import { indexNodeToSchema } from './generator/indexNodeToSchema.js';
 /**
@@ -14,9 +15,12 @@ import { indexNodeToSchema } from './generator/indexNodeToSchema.js';
 export class SqlSchemaGenerator {
     dialect;
     defaultForeignKeyAction;
+    /** `CREATE INDEX` for this dialect: the migrator's, so a runtime import carries none of it. */
+    indexDdl;
     constructor(dialect, defaultForeignKeyAction = 'NO ACTION') {
         this.dialect = dialect;
         this.defaultForeignKeyAction = defaultForeignKeyAction;
+        this.indexDdl = indexDdlFor(dialect);
     }
     get namingStrategy() {
         return this.dialect.namingStrategy;
@@ -188,7 +192,7 @@ export class SqlSchemaGenerator {
         return statements;
     }
     generateCreateIndex(tableName, index, options = {}) {
-        return this.dialect.getCreateIndexStatement(tableName, index, options);
+        return this.indexDdl.getCreateIndexStatement(tableName, index, options);
     }
     /**
      * `schema` is the table's, because that is where its indexes live. MySQL takes it from the table
@@ -374,23 +378,16 @@ export class SqlSchemaGenerator {
      *
      * Only ever additive. An index the entity does not name is left alone: it may well have been
      * created deliberately outside the ORM, and dropping it is a decision for a reviewed migration.
+     *
+     * A vector index is one of these like any other: MariaDB's `CREATE VECTOR INDEX ... ON t (col)`
+     * adds one to a table that already exists, which the inline `CREATE TABLE` form it also has cannot.
      */
     missingIndexes(entity, currentTable) {
         // Keyed by the qualified name, so a table in a schema finds itself rather than reporting that
         // the entity declares no indexes at all.
         const desired = buildEntityAST(this, [entity]).getTable(qualifyName(currentTable.name, currentTable.schema))?.indexes ?? [];
         const present = new Set(currentTable.indexes.map((index) => index.name));
-        return desired
-            .filter((index) => !present.has(index.name) && !this.isInlineVectorIndex(index))
-            .map(indexNodeToSchema);
-    }
-    /**
-     * A vector index this dialect declares inside `CREATE TABLE` rather than as a statement of its own,
-     * which MariaDB is alone in doing. It has no `CREATE INDEX` form, so it can only ever be created
-     * with its table, never added to one.
-     */
-    isInlineVectorIndex(index) {
-        return this.features.inlineVectorIndex && index.type === 'vector';
+        return desired.filter((index) => !present.has(index.name)).map(indexNodeToSchema);
     }
     columnNodeToSchema(col) {
         return {
@@ -483,11 +480,11 @@ export class SqlSchemaGenerator {
     generateCreateTableFromNode(table, options = {}) {
         const columns = [];
         const constraints = [];
-        const vectorIndexes = table.indexes.filter((index) => this.isInlineVectorIndex(index));
-        const regularIndexes = table.indexes.filter((index) => !this.isInlineVectorIndex(index));
         // MariaDB rejects a `VECTOR INDEX` whose column is nullable ("All parts of a VECTOR index must
         // be NOT NULL"), so being indexed decides it rather than the entity's own nullability.
-        const indexedVectorColumns = new Set(vectorIndexes.flatMap((idx) => idx.entries.map((entry) => entry.column)));
+        const indexedVectorColumns = new Set(this.features.vectorIndexRequiresNotNull
+            ? table.indexes.filter((index) => index.type === 'vector').flatMap((idx) => idx.entries.map((e) => e.column))
+            : []);
         for (const col of table.columns.values()) {
             const colDef = this.generateColumnFromNode(indexedVectorColumns.has(col.name) ? { ...col, nullable: false } : col);
             columns.push(colDef);
@@ -512,12 +509,6 @@ export class SqlSchemaGenerator {
             createSql += ',\n';
             createSql += constraints.map((c) => `  ${c}`).join(',\n');
         }
-        if (vectorIndexes.length > 0) {
-            createSql += ',\n';
-            createSql += vectorIndexes
-                .map((idx) => `  ${this.dialect.getInlineVectorIndexDeclaration(indexNodeToSchema(idx))}`)
-                .join(',\n');
-        }
         createSql += '\n)';
         if (this.dialect.tableOptions) {
             createSql += ` ${this.dialect.tableOptions}`;
@@ -531,7 +522,7 @@ export class SqlSchemaGenerator {
             }
         }
         statements.push(createSql);
-        for (const idx of regularIndexes) {
+        for (const idx of table.indexes) {
             statements.push(this.generateCreateIndexFromNode(idx));
         }
         return statements;

package/dist/mongo/mongoDialect.d.ts

@@ -18,7 +18,6 @@ export declare class MongoDialect extends AbstractDialect {
     readonly dialectName = "mongodb";
     readonly insertIdSource = "returning";
     private static readonly ID_KEY;
-    private static readonly VECTOR_INDEX_TYPES;
     /** Atlas rejects a `$vectorSearch` asking for more candidates than this. */
     private static readonly MAX_NUM_CANDIDATES;
     private static readonly AGGREGATE_OP_MAP;
@@ -223,7 +222,7 @@ export declare class MongoDialect extends AbstractDialect {
      * Build a `$vectorSearch` aggregation pipeline stage.
      * Merges `$where` into `$vectorSearch.filter` for optimal pre-filtering.
      */
-    buildVectorSearchStage<E extends Document>(entity: Type<E>, key: string, search: QueryVectorSearch, where: QueryWhere<E> | undefined, limit: number, opts?: QueryOptions): Record<string, unknown>;
+    buildVectorSearchStage<E extends Document>(entity: Type<E>, key: string, search: QueryVectorSearch, where: QueryWhere<E> | undefined, limit: number, opts?: QueryOptions, candidates?: number): Record<string, unknown>;
 }
 export type MongoAggregationPipelineEntry<E extends Document> = {
     $lookup?: MongoAggregationLookup<E>;

package/dist/mongo/mongoDialect.js

@@ -4,7 +4,7 @@ import { COUNT_ALIAS, REL_NESTED_KEY, REL_TEMP_PREFIX, sortCountField } from '..
 import { resolveQueryJoins, resolveSortableJoin } from '../dialect/queryJoins.js';
 import { getMeta } from '../entity/index.js';
 import { QueryRaw } from '../type/queryRaw.js';
-import { asSelectMap, assertAggregateColumns, assertNonNegativeInteger, buildQueryWhereAsMap, fillOnFields, filterFieldKeys, getKeys, getRelationRequestSummary, hasKeys, isJsonUpdateOp, isOperatorMap, isOperatorObject, isVectorSearch, normalizeScalarFieldSelection, parseGroupMap, parseRelationSize, parseSortByCount, someKey, } from '../util/index.js';
+import { asSelectMap, assertAggregateColumns, assertNonNegativeInteger, buildQueryWhereAsMap, entityName, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, getKeys, getRelationRequestSummary, hasKeys, isJsonUpdateOp, isOperatorMap, isOperatorObject, isVectorSearch, normalizeScalarFieldSelection, parseGroupMap, parseRelationSize, parseSortByCount, someKey, } from '../util/index.js';
 /** Default {@link DialectFeatures} for MongoDB; shared by {@link MongoDialect} and its schema generator. */
 export const mongoDialectFeatures = {
     explicitJsonCast: false,
@@ -17,7 +17,7 @@ export const mongoDialectFeatures = {
     renameColumn: false,
     foreignKeyAlter: false,
     columnComment: false,
-    inlineVectorIndex: false,
+    vectorIndexRequiresNotNull: false,
     vectorSupportsLength: false,
     supportsTimestamptz: false,
     defaultStringAsText: false,
@@ -28,7 +28,6 @@ export class MongoDialect extends AbstractDialect {
     // The MongoDB driver reports the exact `_id` of every inserted document (`insertedIds`).
     insertIdSource = 'returning';
     static ID_KEY = '_id';
-    static VECTOR_INDEX_TYPES = new Set(['vectorSearch', 'hnsw', 'ivfflat', 'vector']);
     /** Atlas rejects a `$vectorSearch` asking for more candidates than this. */
     static MAX_NUM_CANDIDATES = 10_000;
     // Direct field aggregates → MongoDB accumulator. `$count` is handled separately (COUNT(*) vs
@@ -254,7 +253,7 @@ export class MongoDialect extends AbstractDialect {
         if (root === MongoDialect.ID_KEY || root === meta.id || meta.fields[root]) {
             return;
         }
-        throw new TypeError(`path ${key} does not exist in ${meta.name ?? ''}`);
+        throw new TypeError(`path ${key} does not exist in ${entityName(meta)}`);
     }
     mapTableNameRow(row) {
         return row.table_name;
@@ -329,6 +328,16 @@ export class MongoDialect extends AbstractDialect {
                 case '$text':
                     result['$text'] = { $search: val };
                     break;
+                case '$near':
+                    // Atlas has no distance operator. The only threshold it offers is a `$match` on
+                    // `{$meta:'vectorSearchScore'}`, which is a *similarity* on a scale set by the index's own
+                    // `similarity` - and that lives in the Atlas index definition, which UQL neither emits nor
+                    // reads (the same reason `$distance` is index-defined for `$text` above). Converting a
+                    // distance to that scale would mean guessing which metric produced the score, and guessing
+                    // wrong filters the wrong rows silently. So this refuses, the way an unsupported
+                    // `DISTANCE=` does rather than defaulting.
+                    throw new TypeError('$near is not supported on MongoDB: Atlas scores by index-defined similarity, not distance. ' +
+                        "Project the score with $sort's $project and filter on it instead.");
                 default:
                     result[op] = val;
                     break;
@@ -912,29 +921,27 @@ export class MongoDialect extends AbstractDialect {
      * Returns `undefined` if no vector sort is present.
      */
     extractVectorSort(sort) {
-        if (!sort)
+        const found = sort && findVectorSort(sort);
+        if (!found) {
             return undefined;
-        let vectorKey;
-        let vectorSearch;
+        }
+        // The remaining entries order the rows the vector stage already picked, so they stay a `$sort`.
+        // Copied in one pass rather than `entries().filter().fromEntries()`, which walks the map three
+        // times over. Every key of the map is optional, so dropping one leaves a valid map - which
+        // neither `Omit` nor a computed-key rest can say over a mapped type with no index signature.
         const regularSort = {};
-        for (const [key, value] of Object.entries(sort)) {
-            if (isVectorSearch(value)) {
-                vectorKey = key;
-                vectorSearch = value;
-            }
-            else {
-                regularSort[key] = value;
+        for (const key of getKeys(sort)) {
+            if (key !== found.key) {
+                regularSort[key] = sort[key];
             }
         }
-        if (!vectorKey || !vectorSearch)
-            return undefined;
-        return { vectorKey, vectorSearch, regularSort };
+        return { vectorKey: found.key, vectorSearch: found.search, regularSort: regularSort };
     }
     /**
      * Build a `$vectorSearch` aggregation pipeline stage.
      * Merges `$where` into `$vectorSearch.filter` for optimal pre-filtering.
      */
-    buildVectorSearchStage(entity, key, search, where, limit, opts) {
+    buildVectorSearchStage(entity, key, search, where, limit, opts, candidates) {
         const meta = getMeta(entity);
         const field = meta.fields[key];
         if (!field) {
@@ -942,8 +949,7 @@ export class MongoDialect extends AbstractDialect {
         }
         const colName = this.resolveColumnName(key, field);
         // Resolve index name from @Index metadata, or fall back to convention
-        const indexMeta = meta.indexes?.find((idx) => idx.columns.some((entry) => entry.column === key) && MongoDialect.VECTOR_INDEX_TYPES.has(idx.type));
-        const indexName = indexMeta?.name ?? `${colName}_index`;
+        const indexName = findVectorIndex(meta, key)?.name ?? `${colName}_index`;
         if (!limit) {
             throw new TypeError(`$vectorSearch requires $limit (vector sort on '${key}' of '${meta.name}')`);
         }
@@ -951,8 +957,9 @@ export class MongoDialect extends AbstractDialect {
             index: indexName,
             path: colName,
             queryVector: [...search.$vector],
-            // Atlas caps `numCandidates` at 10000 and wants roughly 10x the limit below that.
-            numCandidates: Math.min(limit * 10, MongoDialect.MAX_NUM_CANDIDATES),
+            // `$candidates` is the caller's own budget; the fallback is 10x the limit, which is what Atlas
+            // suggests as a floor. Either way it is clamped: Atlas rejects a stage asking for more.
+            numCandidates: Math.min(candidates ?? limit * 10, MongoDialect.MAX_NUM_CANDIDATES),
             limit,
         };
         // Pre-filter: merge $where into $vectorSearch.filter

package/dist/mongo/mongodbQuerier.js

@@ -133,7 +133,7 @@ export class MongodbQuerier extends AbstractQuerier {
     buildVectorPipeline(entity, q, vectorSort, opts) {
         const scoreAlias = vectorSort.vectorSearch.$project;
         return [
-            this.dialect.buildVectorSearchStage(entity, vectorSort.vectorKey, vectorSort.vectorSearch, q.$where, q.$limit ?? 10, opts),
+            this.dialect.buildVectorSearchStage(entity, vectorSort.vectorKey, vectorSort.vectorSearch, q.$where, q.$limit ?? 10, opts, q.$candidates),
             // The score becomes a real field before anything reads it, so the lookups and the projection
             // that follow treat it like any other - and a query with no projection keeps its own columns.
             ...(scoreAlias ? [{ $addFields: { [scoreAlias]: { $meta: 'vectorSearchScore' } } }] : []),

package/dist/mysql/mysqlDialect.d.ts

@@ -1,12 +1,9 @@
 import { MysqlLikeSqlDialect } from '../dialect/mysqlLikeSqlDialect.js';
-import type { IndexSchema } from '../type/index.js';
 export declare class MySqlDialect extends MysqlLikeSqlDialect {
     readonly dialectName = "mysql";
     /**
-     * MySQL has no vector index of any kind, so one is refused here rather than compiled to DDL the
-     * server rejects: `USING hnsw` is a syntax error, and MariaDB's inline `VECTOR INDEX` is not MySQL
-     * syntax either. Verified against MySQL 9.7, which does have `VECTOR` columns and
-     * `STRING_TO_VECTOR`, but no distance function outside HeatWave - hence nothing to index for.
+     * `VALUES(col)` inside `ON DUPLICATE KEY UPDATE` has been deprecated since MySQL 8.0.20 and is
+     * "subject to removal in a future version"; aliasing the inserted row (8.0.19+) is its replacement.
      */
-    protected indexAccessMethod(index: IndexSchema): string;
+    protected readonly upsertNewRowAlias = "_uql_new";
 }

package/dist/mysql/mysqlDialect.js

@@ -1,17 +1,10 @@
+import { UPSERT_NEW_ROW_ALIAS } from '../dialect/aliases.js';
 import { MysqlLikeSqlDialect } from '../dialect/mysqlLikeSqlDialect.js';
 export class MySqlDialect extends MysqlLikeSqlDialect {
     dialectName = 'mysql';
     /**
-     * MySQL has no vector index of any kind, so one is refused here rather than compiled to DDL the
-     * server rejects: `USING hnsw` is a syntax error, and MariaDB's inline `VECTOR INDEX` is not MySQL
-     * syntax either. Verified against MySQL 9.7, which does have `VECTOR` columns and
-     * `STRING_TO_VECTOR`, but no distance function outside HeatWave - hence nothing to index for.
+     * `VALUES(col)` inside `ON DUPLICATE KEY UPDATE` has been deprecated since MySQL 8.0.20 and is
+     * "subject to removal in a future version"; aliasing the inserted row (8.0.19+) is its replacement.
      */
-    indexAccessMethod(index) {
-        if (index.type === 'vector' || index.type === 'hnsw' || index.type === 'ivfflat') {
-            throw new TypeError(`${this.dialectName} has no vector index (index "${index.name}" declares type "${index.type}"). ` +
-                'Vector search on MySQL needs HeatWave.');
-        }
-        return super.indexAccessMethod(index);
-    }
+    upsertNewRowAlias = UPSERT_NEW_ROW_ALIAS;
 }

package/dist/postgres/postgresDialect.d.ts

@@ -10,6 +10,8 @@ import type { QueryConflictPaths, QueryContext, SqlDialectName, Type } from '../
 export declare class PostgresDialect extends PgLikeSqlDialect {
     readonly dialectName: SqlDialectName;
     readonly vectorExtension: string | undefined;
+    /** pgvector is the only engine with `halfvec` and `sparsevec`; every other maps them onto `vector`. */
+    protected readonly hasNarrowVectorTypes = true;
     upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[]): void;
     /**
      * `to_regclass` rather than a `::regclass` cast: it answers `NULL` for a table that does not exist

package/dist/postgres/postgresDialect.js

@@ -11,6 +11,8 @@ import { getMeta } from '../entity/index.js';
 export class PostgresDialect extends PgLikeSqlDialect {
     dialectName = 'postgres';
     vectorExtension = 'vector';
+    /** pgvector is the only engine with `halfvec` and `sparsevec`; every other maps them onto `vector`. */
+    hasNarrowVectorTypes = true;
     upsert(ctx, entity, conflictPaths, payload) {
         // The xmax system column is 0 for a newly inserted row and non-zero for an updated one (MVCC).
         super.upsert(ctx, entity, conflictPaths, payload, `, (xmax = 0) AS ${this.escapeId('_created')}`);

package/dist/querier/abstractSqlQuerier.d.ts

@@ -45,6 +45,17 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
      * actionable answer, and on SQLite it is the answer either way.
      */
     protected assertLockable<E>(entity: Type<E>, q: Query<E>): void;
+    /**
+     * Run the `SET`s that tune an ANN index for this query, and refuse the ones that would not apply.
+     *
+     * Same shape as {@link assertLockable} and for the same reason: a `SET LOCAL` outside a transaction
+     * is accepted, applies to nothing, and leaves the query running at the engine's default recall -
+     * correct SQL, silently untuned. Only the querier knows whether a transaction is open.
+     *
+     * The statements go through `internalRun`, sharing this querier's single connection with the query
+     * they precede; `SET LOCAL` then expires with the transaction, so nothing is left behind.
+     */
+    private applyVectorTuning;
     protected internalFindMany<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<E[]>;
     /**
      * One statement for both: the page carries its own unpaged total in an extra column. An empty page

package/dist/querier/abstractSqlQuerier.js

@@ -76,6 +76,31 @@ export class AbstractSqlQuerier extends AbstractQuerier {
             throw new TypeError('$lock requires an open transaction');
         }
     }
+    /**
+     * Run the `SET`s that tune an ANN index for this query, and refuse the ones that would not apply.
+     *
+     * Same shape as {@link assertLockable} and for the same reason: a `SET LOCAL` outside a transaction
+     * is accepted, applies to nothing, and leaves the query running at the engine's default recall -
+     * correct SQL, silently untuned. Only the querier knows whether a transaction is open.
+     *
+     * The statements go through `internalRun`, sharing this querier's single connection with the query
+     * they precede; `SET LOCAL` then expires with the transaction, so nothing is left behind.
+     */
+    async applyVectorTuning(entity, q) {
+        // Resolved before the transaction check, so the refusal fires only where the tuning would have
+        // meant something: a query with no vector search, or on a field carrying no ANN index, has
+        // nothing to set and no reason to demand a transaction for it.
+        const statements = this.dialect.vectorTuningStatements(getMeta(entity), q);
+        if (!statements.length) {
+            return;
+        }
+        if (this.dialect.vectorTuningNeedsTransaction && !this.hasOpenTransaction) {
+            throw new TypeError(`$candidates requires an open transaction on ${this.dialect.dialectName}; run the query inside pool.transaction(...)`);
+        }
+        for (const statement of statements) {
+            await this.internalRun(statement);
+        }
+    }
     async internalFindMany(entity, q, opts) {
         return this.hydrateRows(entity, q, await this.selectRows(entity, q, opts));
     }
@@ -119,6 +144,12 @@ export class AbstractSqlQuerier extends AbstractQuerier {
     }
     async selectRows(entity, q, opts, totalAlias) {
         this.assertLockable(entity, q);
+        // Guarded rather than awaited unconditionally, here and in the stream below: an `await` on this
+        // path defers a microtask on every read, which reorders the two statements `findManyAndCount`
+        // issues concurrently. Keep the guard at any new call site.
+        if (q.$candidates !== undefined) {
+            await this.applyVectorTuning(entity, q);
+        }
         const ctx = this.dialect.createContext();
         this.dialect.find(ctx, entity, q, opts, totalAlias);
         return this.all(ctx.sql, ctx.values);
@@ -130,6 +161,10 @@ export class AbstractSqlQuerier extends AbstractQuerier {
     }
     async *internalFindManyStream(entity, q, opts) {
         this.assertLockable(entity, q);
+        // Guarded for the reason `selectRows` above spells out.
+        if (q.$candidates !== undefined) {
+            await this.applyVectorTuning(entity, q);
+        }
         const meta = getMeta(entity);
         const { toManyKeys } = getRelationRequestSummary(meta, q.$populate);
         if (toManyKeys.length) {

package/dist/schema/canonicalType.js

@@ -83,7 +83,7 @@ const SQL_TO_CANONICAL = {
 };
 /**
  * pgvector is the only engine with three vector column types, so every other dialect maps all three
- * canonical categories onto the single type it does have (see {@link MULTI_VECTOR_TYPE_DIALECTS}, the
+ * canonical categories onto the single type it does have (see `hasNarrowVectorTypes` on the dialect, the
  * dialect-side half of the same fact).
  */
 function withVectorType(scalars, vector) {
@@ -125,7 +125,7 @@ const CANONICAL_TO_SQL = {
         uuid: 'CHAR(36)',
         blob: 'BLOB',
     }, 
-    // MySQL 9.x does have a `VECTOR` type, but no distance function outside HeatWave and no vector
+    // MySQL does have a `VECTOR` type (26.7), but no distance function outside HeatWave and no vector
     // index, so JSON keeps the column queryable with the JSON operators and needs no conversion.
     'JSON'),
     sqlite: withVectorType({
@@ -186,44 +186,43 @@ const PG_SIZE_MODIFIERS = {
         big: 'DOUBLE PRECISION',
     },
 };
+/**
+ * MariaDB is a MySQL fork and spells every one of these the same way, so both take the one map.
+ * Listed per-dialect, MariaDB's had only `integer`: a `double` column was created `FLOAT` there, four
+ * bytes where the entity asked for eight, and a `big` string or blob lost its `LONG` prefix.
+ */
+const MYSQL_SIZE_MODIFIERS = {
+    integer: {
+        tiny: 'TINYINT',
+        small: 'SMALLINT',
+        medium: 'MEDIUMINT',
+        big: 'BIGINT',
+    },
+    float: {
+        tiny: 'FLOAT',
+        small: 'FLOAT',
+        medium: 'DOUBLE',
+        big: 'DOUBLE',
+    },
+    string: {
+        tiny: 'TINYTEXT',
+        small: 'TEXT',
+        medium: 'MEDIUMTEXT',
+        big: 'LONGTEXT',
+    },
+    blob: {
+        tiny: 'TINYBLOB',
+        small: 'BLOB',
+        medium: 'MEDIUMBLOB',
+        big: 'LONGBLOB',
+    },
+};
 const SIZE_MODIFIERS = {
     postgres: PG_SIZE_MODIFIERS,
     cockroachdb: PG_SIZE_MODIFIERS,
-    mysql: {
-        integer: {
-            tiny: 'TINYINT',
-            small: 'SMALLINT',
-            medium: 'MEDIUMINT',
-            big: 'BIGINT',
-        },
-        float: {
-            tiny: 'FLOAT',
-            small: 'FLOAT',
-            medium: 'DOUBLE',
-            big: 'DOUBLE',
-        },
-        string: {
-            tiny: 'TINYTEXT',
-            small: 'TEXT',
-            medium: 'MEDIUMTEXT',
-            big: 'LONGTEXT',
-        },
-        blob: {
-            tiny: 'TINYBLOB',
-            small: 'BLOB',
-            medium: 'MEDIUMBLOB',
-            big: 'LONGBLOB',
-        },
-    },
+    mysql: MYSQL_SIZE_MODIFIERS,
     sqlite: {}, // SQLite uses affinity, no size modifiers
-    mariadb: {
-        integer: {
-            tiny: 'TINYINT',
-            small: 'SMALLINT',
-            medium: 'MEDIUMINT',
-            big: 'BIGINT',
-        },
-    },
+    mariadb: MYSQL_SIZE_MODIFIERS,
     mongodb: {},
 };
 /**

package/dist/schema/indexDifferences.d.ts

@@ -17,6 +17,7 @@ export type IndexFacet = 'order' | 'nulls' | 'opsClass' | 'accessMethod' | 'incl
  * `status = ANY (ARRAY['a'::text, 'b'::text])`, `LIKE` as `~~`, and a date literal with its time zone
  * spelled out. Folding that back needs a SQL parser, and every near-miss reports drift that no
  * migration can settle. So a partial index's predicate is never compared, and an index over an
- * expression has its entries left alone while the rest of it still compares.
+ * expression - a `raw()` one, or a JSON path, which the engines report as an expression too - has
+ * its entries left alone while the rest of it still compares.
  */
 export declare function describeIndexDifferences(source: IndexNode, target: IndexNode, facets: ReadonlySet<IndexFacet>): string[];

package/dist/schema/indexDifferences.js

@@ -6,11 +6,12 @@
  * `status = ANY (ARRAY['a'::text, 'b'::text])`, `LIKE` as `~~`, and a date literal with its time zone
  * spelled out. Folding that back needs a SQL parser, and every near-miss reports drift that no
  * migration can settle. So a partial index's predicate is never compared, and an index over an
- * expression has its entries left alone while the rest of it still compares.
+ * expression - a `raw()` one, or a JSON path, which the engines report as an expression too - has
+ * its entries left alone while the rest of it still compares.
  */
 export function describeIndexDifferences(source, target, facets) {
     const differences = [];
-    const comparableEntries = ![...source.entries, ...target.entries].some((entry) => entry.expression);
+    const comparableEntries = ![...source.entries, ...target.entries].some((entry) => entry.expression || entry.jsonPath || entry.jsonArray);
     if (comparableEntries) {
         const [sourceColumns, targetColumns] = [source.entries, target.entries].map((entries) => entries.map((entry) => entrySignature(entry, facets)).join(', '));
         if (sourceColumns !== targetColumns) {

package/dist/sqlite/sqliteDialect.d.ts

@@ -1,5 +1,5 @@
 import { AbstractSqlDialect } from '../dialect/abstractSqlDialect.js';
-import type { DialectFeatures, EntityMeta, FieldOptions, QueryContext, QueryPager, QuerySizeComparisonOps, QueryTextSearchOptions, Type, VectorDistance } from '../type/index.js';
+import type { DialectFeatures, EntityMeta, FieldOptions, QueryContext, QueryPager, QuerySizeComparisonOps, QueryTextSearchOptions, Type, VectorDistance, VectorMetric } from '../type/index.js';
 export declare class SqliteDialect extends AbstractSqlDialect {
     /** Default {@link DialectFeatures} for SQLite and SQLite-derived dialects. */
     protected readonly featureDefaults: DialectFeatures;
@@ -21,7 +21,7 @@ export declare class SqliteDialect extends AbstractSqlDialect {
      * loaded on the connection (see `Sqlite3QuerierPool`'s `extensions` option). libSQL and Turso ship
      * their own vector functions instead, so `LibsqlDialect` overrides this.
      */
-    protected readonly vectorDistanceFns: ReadonlyMap<VectorDistance, string>;
+    readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
     /**
      * SQLite does not support the `DEFAULT` keyword inside `VALUES`. Inline the metadata default
      * when declared, else `NULL` (which is also how SQLite auto-generates INTEGER PRIMARY KEYs).

package/dist/sqlite/sqliteDialect.js

@@ -14,7 +14,7 @@ export class SqliteDialect extends AbstractSqlDialect {
         renameColumn: true,
         foreignKeyAlter: false, // SQLite does not support adding FKs to existing tables
         columnComment: false, // SQLite does not support column comments
-        inlineVectorIndex: false,
+        vectorIndexRequiresNotNull: false,
         vectorSupportsLength: false,
         supportsTimestamptz: false,
         defaultStringAsText: true,
@@ -38,10 +38,10 @@ export class SqliteDialect extends AbstractSqlDialect {
      * loaded on the connection (see `Sqlite3QuerierPool`'s `extensions` option). libSQL and Turso ship
      * their own vector functions instead, so `LibsqlDialect` overrides this.
      */
-    vectorDistanceFns = new Map([
-        ['cosine', 'vec_distance_cosine'],
-        ['l2', 'vec_distance_L2'],
-        ['l1', 'vec_distance_L1'],
+    vectorMetrics = new Map([
+        ['cosine', { fn: 'vec_distance_cosine' }],
+        ['l2', { fn: 'vec_distance_L2' }],
+        ['l1', { fn: 'vec_distance_L1' }],
     ]);
     /**
      * SQLite does not support the `DEFAULT` keyword inside `VALUES`. Inline the metadata default

package/dist/turso/tursoDialect.d.ts

@@ -1,5 +1,5 @@
 import { LibsqlDialect } from '../libsql/libsqlDialect.js';
-import type { VectorDistance } from '../type/index.js';
+import type { VectorDistance, VectorMetric } from '../type/index.js';
 /**
  * SQLite Dialect specialization for Turso Database.
  *
@@ -11,5 +11,5 @@ import type { VectorDistance } from '../type/index.js';
  */
 export declare class TursoDialect extends LibsqlDialect {
     /** The Rust engine adds a dot-product distance to libSQL's cosine and L2. */
-    protected readonly vectorDistanceFns: ReadonlyMap<VectorDistance, string>;
+    readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
 }

package/dist/turso/tursoDialect.js

@@ -10,9 +10,9 @@ import { LibsqlDialect } from '../libsql/libsqlDialect.js';
  */
 export class TursoDialect extends LibsqlDialect {
     /** The Rust engine adds a dot-product distance to libSQL's cosine and L2. */
-    vectorDistanceFns = new Map([
-        ['cosine', 'vector_distance_cos'],
-        ['l2', 'vector_distance_l2'],
-        ['inner', 'vector_distance_dot'],
+    vectorMetrics = new Map([
+        ['cosine', { fn: 'vector_distance_cos' }],
+        ['l2', { fn: 'vector_distance_l2' }],
+        ['inner', { fn: 'vector_distance_dot' }],
     ]);
 }

package/dist/type/dialect.d.ts

@@ -94,11 +94,11 @@ export interface EngineFeatures {
     /** Whether the dialect supports inline COMMENT on columns (MySQL/MariaDB). */
     readonly columnComment: boolean;
     /**
-     * Whether a vector index is declared inline in `CREATE TABLE` (MySQL/MariaDB) rather than as its own
-     * `CREATE INDEX` statement. The statement's shape itself is the dialect's business, see
-     * `AbstractSqlDialect.getCreateIndexStatement`.
+     * Whether every column of a vector index has to be `NOT NULL`, which MariaDB 12.3 enforces ("All
+     * parts of a VECTOR index must be NOT NULL") and CockroachDB 26.3 does not - so being indexed, not
+     * the entity, decides the column's nullability there.
      */
-    readonly inlineVectorIndex: boolean;
+    readonly vectorIndexRequiresNotNull: boolean;
     /** Whether the dialect requires/allows (n) length constraints on vector types. */
     readonly vectorSupportsLength: boolean;
     /** Whether the dialect natively supports the TIMESTAMPTZ alias/type. */
@@ -222,11 +222,25 @@ export interface SqlQueryDialect extends QueryDialect {
  * indexes exist everywhere but MariaDB 12.3 (which needs a generated column); prefix lengths are
  * MySQL-family only and *required* there to index `TEXT`; `NULLS FIRST/LAST` and operator classes are
  * Postgres-only (CockroachDB 26.2 answers "unimplemented"); `INCLUDE` is Postgres-wire only; the
- * MySQL family is alone in having no partial indexes.
+ * MySQL family is alone in having no partial indexes. The two JSON ones split the other way: the
+ * engines that index a path inside a document are the ones whose planner matches the query's own
+ * extraction back to it (Postgres, CockroachDB, SQLite - MySQL matches neither
+ * `CAST(col->>'$.x' AS CHAR(n))` nor `JSON_VALUE(... RETURNING ...)`, verified on 26.7, and needs a
+ * generated column instead), while MySQL alone has the multi-valued index a JSON array needs.
  *
  * Introspectors reuse the vocabulary for what they can read *back*, which is what diffing may
  * compare. The two sets are deliberately not the same object and must not be unified: Postgres can
  * emit an expression index and read one back, but MySQL emits one it cannot describe afterwards.
  */
-export type IndexFeature = 'expression' | 'partial' | 'prefixLength' | 'nullsOrder' | 'opsClass' | 'include';
-export declare const INDEX_FEATURE_LABELS: Record<IndexFeature, string>;
+export declare const INDEX_FEATURE_LABELS: {
+    readonly expression: 'expression indexes';
+    readonly partial: 'partial indexes';
+    readonly prefixLength: 'index prefix lengths';
+    readonly nullsOrder: 'NULLS FIRST/LAST in an index';
+    readonly opsClass: 'index operator classes';
+    readonly include: 'covering indexes (INCLUDE)';
+    readonly jsonPath: 'indexes over a path inside a JSON column';
+    readonly jsonArray: 'multi-valued indexes over a JSON array';
+};
+/** Derived from the labels, so a feature cannot be added without the words an error reports it in. */
+export type IndexFeature = keyof typeof INDEX_FEATURE_LABELS;