uql-orm 0.21.0 → 0.22.0

package/dist/migrate/schemaGenerator.js

@@ -4,11 +4,7 @@ import { areTypesEqual, canonicalToSql, fieldOptionsToCanonical, isVectorCategor
 import { SchemaASTBuilder } from '../schema/schemaASTBuilder.js';
 import { escapeSqlId, getKeys, isAutoIncrement } from '../util/index.js';
 import { formatDefaultValue } from './builder/expressions.js';
-/** Maps UQL distance metric names to inline DDL keywords (e.g. MariaDB `DISTANCE=euclidean`). */
-const INLINE_VECTOR_DISTANCE_MAP = new Map([
-    ['cosine', 'cosine'],
-    ['l2', 'euclidean'],
-]);
+import { indexNodeToSchema } from './generator/indexNodeToSchema.js';
 /**
  * Unified SQL schema generator.
  * Parameterized by dialect to handle Postgres, MySQL, MariaDB, and SQLite.
@@ -53,15 +49,7 @@ export class SqlSchemaGenerator {
     getCanonicalType(field, fieldType) {
         return fieldOptionsToCanonical(field, fieldType);
     }
-    /**
-     * Convert CanonicalType to SQL type string for this dialect.
-     * Also handles legacy string types for backward compatibility.
-     */
     canonicalTypeToSql(type) {
-        // Handle legacy string types
-        if (typeof type === 'string') {
-            return type;
-        }
         return canonicalToSql(type, this.dialect);
     }
     // ============================================================================
@@ -73,10 +61,10 @@ export class SqlSchemaGenerator {
         const tableNode = ast.getTables()[0];
         return this.generateCreateTableFromNode(tableNode, options);
     }
-    generateDropTable(entity) {
-        const meta = getMeta(entity);
-        const tableName = this.dialect.resolveTableName(entity, meta);
-        return `DROP TABLE IF EXISTS ${this.escapeId(tableName)};`;
+    generateDropTable(tableName, options = {}) {
+        const ifExists = options.ifExists ? 'IF EXISTS ' : '';
+        const cascade = options.cascade && this.features.dropTableCascade ? ' CASCADE' : '';
+        return `DROP TABLE ${ifExists}${this.escapeId(tableName)}${cascade};`;
     }
     generateAlterTable(diff) {
         const statements = [];
@@ -145,48 +133,7 @@ export class SqlSchemaGenerator {
         return statements;
     }
     generateCreateIndex(tableName, index, options = {}) {
-        const unique = index.unique ? 'UNIQUE ' : '';
-        const ifNotExists = (options.ifNotExists ?? this.features.indexIfNotExists) ? 'IF NOT EXISTS ' : '';
-        const opsClassMap = this.dialect.vectorOpsClass;
-        // CockroachDB's native vector index has one algorithm (no hnsw/ivfflat choice), so `type: 'vector'`
-        // is its trigger - same generic value MariaDB's inline style already uses (see `isInlineVectorIdx`).
-        const isNativeVectorIndex = this.features.vectorIndexStyle === 'native' && index.type === 'vector';
-        const hasOpsClass = opsClassMap && (isNativeVectorIndex || index.type === 'hnsw' || index.type === 'ivfflat');
-        // For pgvector/CockroachDB vector indexes: append operator class to the column. Throws rather
-        // than silently omitting the operator class for an unsupported distance - e.g. a bare
-        // `CREATE VECTOR INDEX ... (col)` on CockroachDB would build using its default distance
-        // metric instead of the one actually requested, with no error to signal the mismatch.
-        const columns = index.columns
-            .map((c) => {
-            const escaped = this.escapeId(c);
-            if (!opsClassMap || !hasOpsClass || !index.distance) {
-                return escaped;
-            }
-            const opsClass = opsClassMap.get(index.distance);
-            if (!opsClass) {
-                throw new TypeError(`${this.dialect.dialectName} does not support vector distance metric: ${index.distance} (index "${index.name}")`);
-            }
-            return `${escaped} ${opsClass}`;
-        })
-            .join(', ');
-        // CockroachDB has no access-method keyword: `CREATE VECTOR INDEX ... (col)`, not
-        // `CREATE INDEX ... USING vector (col)`.
-        const indexKeyword = isNativeVectorIndex ? 'VECTOR INDEX' : 'INDEX';
-        const using = !isNativeVectorIndex && index.type ? ` USING ${index.type}` : '';
-        // Build WITH params for pgvector indexes with operator class support. CockroachDB's native
-        // vector index has its own, differently-named tuning knobs - not generated here.
-        let withClause = '';
-        if (hasOpsClass && !isNativeVectorIndex) {
-            const withParams = [];
-            if (index.m !== undefined)
-                withParams.push(`m = ${index.m}`);
-            if (index.efConstruction !== undefined)
-                withParams.push(`ef_construction = ${index.efConstruction}`);
-            if (index.lists !== undefined)
-                withParams.push(`lists = ${index.lists}`);
-            withClause = withParams.length > 0 ? ` WITH (${withParams.join(', ')})` : '';
-        }
-        return `CREATE ${unique}${indexKeyword} ${ifNotExists}${this.escapeId(index.name)} ON ${this.escapeId(tableName)}${using} (${columns})${withClause};`;
+        return this.dialect.getCreateIndexStatement(tableName, index, options);
     }
     generateDropIndex(tableName, indexName) {
         if (this.dialect.dropIndexSyntax === 'on-table') {
@@ -195,19 +142,15 @@ export class SqlSchemaGenerator {
         return `DROP INDEX IF EXISTS ${this.escapeId(indexName)};`;
     }
     /**
-     * Generate column definition from a ColumnSchema object
+     * Generate a column definition from a {@link ColumnSchema}, whose type is the engine's own spelling
+     * and may already carry its precision (or even `PRIMARY KEY`, for a serial).
      */
     generateColumnDefinitionFromSchema(column, options = {}) {
         const { includePrimaryKey = true, includeUnique = true } = options;
         let type = column.type;
         if (!type.includes('(')) {
             if (column.precision !== undefined) {
-                if (column.scale !== undefined) {
-                    type += `(${column.precision}, ${column.scale})`;
-                }
-                else {
-                    type += `(${column.precision})`;
-                }
+                type += column.scale === undefined ? `(${column.precision})` : `(${column.precision}, ${column.scale})`;
             }
             else if (column.length !== undefined) {
                 type += `(${column.length})`;
@@ -216,23 +159,38 @@ export class SqlSchemaGenerator {
         if (!includePrimaryKey) {
             type = type.replace(/\s+PRIMARY\s+KEY/i, '');
         }
-        let definition = `${this.escapeId(column.name)} ${type}`;
-        if (includePrimaryKey && column.isPrimaryKey && !type.includes('PRIMARY KEY')) {
-            definition += ' PRIMARY KEY';
+        // `includePrimaryKey: false` suppresses the keyword, not the fact: the column is still the primary
+        // key, so it must not pick up `NOT NULL` (implied) or `UNIQUE` (redundant) on the way out.
+        return this.renderColumn({
+            ...column,
+            type,
+            isUnique: column.isUnique && includeUnique,
+            declaresPrimaryKey: includePrimaryKey && column.isPrimaryKey,
+        });
+    }
+    /**
+     * The one place a column definition is spelled. Both callers reach it - the `ColumnSchema` path above
+     * and the `ColumnNode` path below - because the clause order and the "no NOT NULL on a primary key"
+     * rules are the same everywhere, and having them written twice is how the two paths drifted.
+     */
+    renderColumn(column) {
+        let def = `${this.escapeId(column.name)} ${column.type}`;
+        if (column.declaresPrimaryKey && !column.type.includes('PRIMARY KEY')) {
+            def += ' PRIMARY KEY';
         }
         if (!column.nullable && !column.isPrimaryKey) {
-            definition += ' NOT NULL';
+            def += ' NOT NULL';
         }
-        if (includeUnique && column.isUnique && !column.isPrimaryKey) {
-            definition += ' UNIQUE';
+        if (column.isUnique && !column.isPrimaryKey) {
+            def += ' UNIQUE';
         }
         if (column.defaultValue !== undefined) {
-            definition += ` DEFAULT ${this.formatDefaultValue(column.defaultValue)}`;
+            def += ` DEFAULT ${this.formatDefaultValue(column.defaultValue)}`;
         }
         if (column.comment) {
-            definition += this.generateColumnComment(column.name, column.comment);
+            def += this.generateColumnComment(column.name, column.comment);
         }
-        return definition;
+        return def;
     }
     getSqlType(field, fieldType) {
         // If field has a reference, inherit type from the target primary key
@@ -250,12 +208,6 @@ export class SqlSchemaGenerator {
         }
         return this.canonicalTypeToSql(canonical);
     }
-    /**
-     * Get the boolean type for this database
-     */
-    getBooleanType() {
-        return this.canonicalTypeToSql({ category: 'boolean' });
-    }
     /**
      * Generate ALTER COLUMN statements (database-specific)
      */
@@ -286,12 +238,6 @@ export class SqlSchemaGenerator {
         }
         return [`ALTER TABLE ${table} ${this.dialect.alterColumnSyntax} ${newDefinition};`];
     }
-    /**
-     * Get table options (e.g., ENGINE for MySQL)
-     */
-    getTableOptions(_meta) {
-        return this.dialect.tableOptions ? ` ${this.dialect.tableOptions}` : '';
-    }
     /**
      * Generate column comment clause (if supported)
      */
@@ -372,7 +318,8 @@ export class SqlSchemaGenerator {
         };
     }
     /**
-     * Convert field options to ColumnSchema
+     * Convert field options to ColumnSchema. Both sides of a diff are the engine's SQL spelling: what it
+     * would create for this field, against what it reported for the existing column.
      */
     fieldToColumnSchema(fieldKey, field, meta) {
         const isPrimaryKey = field.isId === true && meta.id === fieldKey;
@@ -410,12 +357,16 @@ export class SqlSchemaGenerator {
         return false;
     }
     /**
-     * Compare two column types for equality using the canonical type system
+     * Whether two column types are the same *as this engine stores them*.
+     *
+     * Both sides are SQL spellings, parsed back to canonical so that `INT` and `INTEGER`, or `DATETIME`
+     * and `TIMESTAMP`, do not read as a change. Do not "simplify" this into comparing the entity's
+     * canonical type against the column's: several canonical types share one storage type per engine
+     * (`boolean` is `TINYINT(1)` on MySQL and `INTEGER` on SQLite), so that comparison reports an
+     * alteration for those columns on every single sync.
      */
     isTypeEqual(current, desired) {
-        const typeA = sqlToCanonical(current.type);
-        const typeB = sqlToCanonical(desired.type);
-        return areTypesEqual(typeA, typeB);
+        return areTypesEqual(sqlToCanonical(current.type), sqlToCanonical(desired.type));
     }
     /**
      * Compare two default values for equality
@@ -445,8 +396,14 @@ export class SqlSchemaGenerator {
     generateCreateTableFromNode(table, options = {}) {
         const columns = [];
         const constraints = [];
+        const isInlineVectorIdx = this.features.inlineVectorIndex;
+        const vectorIndexes = isInlineVectorIdx ? table.indexes.filter((idx) => idx.type === 'vector') : [];
+        const regularIndexes = isInlineVectorIdx ? table.indexes.filter((idx) => idx.type !== 'vector') : table.indexes;
+        // 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.columns.map((col) => col.name)));
         for (const col of table.columns.values()) {
-            const colDef = this.generateColumnFromNode(col);
+            const colDef = this.generateColumnFromNode(indexedVectorColumns.has(col.name) ? { ...col, nullable: false } : col);
             columns.push(colDef);
         }
         if (table.primaryKey.length > 1) {
@@ -469,12 +426,11 @@ export class SqlSchemaGenerator {
             createSql += ',\n';
             createSql += constraints.map((c) => `  ${c}`).join(',\n');
         }
-        const isInlineVectorIdx = this.features.vectorIndexStyle === 'inline';
-        const vectorIndexes = isInlineVectorIdx ? table.indexes.filter((idx) => idx.type === 'vector') : [];
-        const regularIndexes = isInlineVectorIdx ? table.indexes.filter((idx) => idx.type !== 'vector') : table.indexes;
         if (vectorIndexes.length > 0) {
             createSql += ',\n';
-            createSql += vectorIndexes.map((idx) => `  ${this.generateInlineVectorIndex(idx)}`).join(',\n');
+            createSql += vectorIndexes
+                .map((idx) => `  ${this.dialect.getInlineVectorIndexDeclaration(indexNodeToSchema(idx))}`)
+                .join(',\n');
         }
         createSql += '\n)';
         if (this.dialect.tableOptions) {
@@ -495,73 +451,22 @@ export class SqlSchemaGenerator {
         return statements;
     }
     /**
-     * Generate a column definition from a ColumnNode.
+     * Generate a column definition from a ColumnNode. A composite key is declared as a table constraint,
+     * so only a lone primary key column carries `PRIMARY KEY` inline.
      */
     generateColumnFromNode(col) {
-        const colName = this.escapeId(col.name);
-        let sqlType = this.canonicalTypeToSql(col.type);
-        if (col.isPrimaryKey && col.isAutoIncrement) {
-            sqlType = this.serialPrimaryKeyType;
-        }
-        let def = `${colName} ${sqlType}`;
-        if (!col.nullable && !col.isPrimaryKey) {
-            def += ' NOT NULL';
-        }
-        if (col.isPrimaryKey && col.table.primaryKey.length === 1 && !sqlType.includes('PRIMARY KEY')) {
-            def += ' PRIMARY KEY';
-        }
-        if (col.isUnique && !col.isPrimaryKey) {
-            def += ' UNIQUE';
-        }
-        if (col.defaultValue !== undefined) {
-            def += ` DEFAULT ${this.formatDefaultValue(col.defaultValue)}`;
-        }
-        if (col.comment) {
-            def += this.generateColumnComment(col.name, col.comment);
-        }
-        return def;
-    }
-    /**
-     * Generate an inline VECTOR INDEX clause for use inside CREATE TABLE.
-     * Syntax: `VECTOR INDEX (col) M=n DISTANCE=metric`
-     */
-    generateInlineVectorIndex(index) {
-        const columns = index.columns.map((c) => this.escapeId(c.name)).join(', ');
-        let clause = `VECTOR INDEX (${columns})`;
-        if (index.m !== undefined) {
-            clause += ` M=${index.m}`;
-        }
-        if (index.distance) {
-            const metric = INLINE_VECTOR_DISTANCE_MAP.get(index.distance);
-            if (!metric) {
-                throw new TypeError(`${this.dialect.dialectName} does not support vector distance metric: ${index.distance} (index "${index.name}")`);
-            }
-            clause += ` DISTANCE=${metric}`;
-        }
-        return clause;
+        return this.renderColumn({
+            ...col,
+            type: col.isPrimaryKey && col.isAutoIncrement ? this.serialPrimaryKeyType : this.canonicalTypeToSql(col.type),
+            declaresPrimaryKey: col.isPrimaryKey && col.table.primaryKey.length === 1,
+        });
     }
     /**
      * Generate CREATE INDEX SQL from an IndexNode.
      * Delegates to `generateCreateIndex` for unified SQL assembly.
      */
     generateCreateIndexFromNode(index, options = { ifNotExists: false }) {
-        return this.generateCreateIndex(index.table.name, {
-            name: index.name,
-            columns: index.columns.map((c) => c.name),
-            unique: index.unique,
-            type: index.type,
-            distance: index.distance,
-            m: index.m,
-            efConstruction: index.efConstruction,
-            lists: index.lists,
-        }, options);
-    }
-    /**
-     * Generate DROP TABLE SQL from a TableNode.
-     */
-    generateDropTableFromNode(table, options = {}) {
-        const ifExists = options.ifExists ? 'IF EXISTS ' : '';
-        return `DROP TABLE ${ifExists}${this.escapeId(table.name)};`;
+        return this.generateCreateIndex(index.table.name, indexNodeToSchema(index), options);
     }
     // ============================================================================
     // Phase 3: Builder Operation Methods (Moved forward for unification)
@@ -570,12 +475,6 @@ export class SqlSchemaGenerator {
         const tableNode = this.tableDefinitionToNode(table);
         return this.generateCreateTableFromNode(tableNode, options);
     }
-    generateDropTableSql(tableName, options) {
-        const ifExists = options?.ifExists ? 'IF EXISTS ' : '';
-        // Use dialect-specific cascade support from config
-        const cascade = options?.cascade && this.features.dropTableCascade ? ' CASCADE' : '';
-        return `DROP TABLE ${ifExists}${this.escapeId(tableName)}${cascade};`;
-    }
     generateRenameTableSql(oldName, newName) {
         if (this.dialect.renameTableSyntax === 'rename-table') {
             return `RENAME TABLE ${this.escapeId(oldName)} TO ${this.escapeId(newName)};`;
@@ -587,8 +486,8 @@ export class SqlSchemaGenerator {
         return `ALTER TABLE ${this.escapeId(tableName)} ADD COLUMN ${colSql};`;
     }
     generateAlterColumnSql(tableName, columnName, column) {
-        const colSql = this.generateColumnFromNode(this.fullColumnDefinitionToNode(column, tableName));
-        return this.generateAlterColumnStatements(tableName, { name: columnName, type: '' }, colSql).join('\n');
+        const node = this.fullColumnDefinitionToNode(column, tableName);
+        return this.generateAlterColumnStatements(tableName, { ...this.columnNodeToSchema(node), name: columnName }, this.generateColumnFromNode(node)).join('\n');
     }
     generateDropColumnSql(tableName, columnName) {
         return `ALTER TABLE ${this.escapeId(tableName)} DROP COLUMN ${this.escapeId(columnName)};`;
@@ -596,12 +495,6 @@ export class SqlSchemaGenerator {
     generateRenameColumnSql(tableName, oldName, newName) {
         return `ALTER TABLE ${this.escapeId(tableName)} RENAME COLUMN ${this.escapeId(oldName)} TO ${this.escapeId(newName)};`;
     }
-    generateCreateIndexSql(tableName, index) {
-        return this.generateCreateIndex(tableName, index);
-    }
-    generateDropIndexSql(tableName, indexName) {
-        return this.generateDropIndex(tableName, indexName);
-    }
     generateAddForeignKeySql(tableName, foreignKey) {
         const fkCols = foreignKey.columns.map((c) => this.escapeId(c)).join(', ');
         const refCols = foreignKey.referencesColumns.map((c) => this.escapeId(c)).join(', ');
@@ -645,10 +538,12 @@ export class SqlSchemaGenerator {
         table.primaryKey = finalPrimaryKey;
         for (const idxDef of def.indexes) {
             const indexNode = {
-                name: idxDef.name,
+                ...idxDef,
                 table,
-                columns: idxDef.columns.map((name) => columns.get(name)).filter((c) => c !== undefined),
-                unique: idxDef.unique,
+                columns: idxDef.columns
+                    .map((entry) => (entry.expression ? undefined : columns.get(entry.column)))
+                    .filter((c) => c !== undefined),
+                entries: idxDef.columns,
             };
             table.indexes.push(indexNode);
         }
@@ -703,7 +598,7 @@ export class SqlSchemaGenerator {
  * Synchronous factory for SQL schema generators only.
  * For MongoDB, use `createSchemaGeneratorAsync` from `./schemaGeneratorAsync.js` so the optional `mongodb` peer is not loaded at import time.
  */
-export function createSchemaGenerator(dialect, namingStrategy, defaultForeignKeyAction) {
+export function createSchemaGenerator(dialect, defaultForeignKeyAction) {
     if (!(dialect instanceof AbstractSqlDialect)) {
         return undefined;
     }

package/dist/migrate/schemaGeneratorAsync.d.ts

@@ -1,8 +1,8 @@
 import type { AbstractDialect } from '../dialect/abstractDialect.js';
 import type { ForeignKeyAction } from '../schema/types.js';
-import type { NamingStrategy, SchemaGenerator } from '../type/index.js';
+import type { SchemaGenerator } from '../type/index.js';
 /**
  * Async factory for schema generators. Use this for MongoDB so the optional peer
  * `mongodb` is only loaded when this path runs. SQL dialects delegate to {@link createSchemaGenerator}.
  */
-export declare function createSchemaGeneratorAsync(dialect: AbstractDialect, namingStrategy?: NamingStrategy, defaultForeignKeyAction?: ForeignKeyAction): Promise<SchemaGenerator | undefined>;
+export declare function createSchemaGeneratorAsync(dialect: AbstractDialect, defaultForeignKeyAction?: ForeignKeyAction): Promise<SchemaGenerator | undefined>;

package/dist/migrate/schemaGeneratorAsync.js

@@ -3,10 +3,10 @@ import { createSchemaGenerator } from './schemaGenerator.js';
  * Async factory for schema generators. Use this for MongoDB so the optional peer
  * `mongodb` is only loaded when this path runs. SQL dialects delegate to {@link createSchemaGenerator}.
  */
-export async function createSchemaGeneratorAsync(dialect, namingStrategy, defaultForeignKeyAction) {
+export async function createSchemaGeneratorAsync(dialect, defaultForeignKeyAction) {
     if (dialect.dialectName === 'mongodb') {
         const { MongoSchemaGenerator } = await import('./generator/mongoSchemaGenerator.js');
-        return new MongoSchemaGenerator(namingStrategy, defaultForeignKeyAction);
+        return new MongoSchemaGenerator(dialect.namingStrategy, defaultForeignKeyAction);
     }
-    return createSchemaGenerator(dialect, namingStrategy, defaultForeignKeyAction);
+    return createSchemaGenerator(dialect, defaultForeignKeyAction);
 }

package/dist/migrate/storage/databaseStorage.js

@@ -31,7 +31,7 @@ export class DatabaseMigrationStorage {
     }
     async createTableIfNotExists(querier) {
         const { dialect } = querier;
-        const sql = `
+        const sql = /*sql*/ `
       CREATE TABLE IF NOT EXISTS ${dialect.escapeId(this.tableName)} (
         ${dialect.escapeId('name')} VARCHAR(255) PRIMARY KEY,
         ${dialect.escapeId('executed_at')} TIMESTAMP DEFAULT CURRENT_TIMESTAMP
@@ -48,7 +48,7 @@ export class DatabaseMigrationStorage {
         }
         try {
             const { dialect } = querier;
-            const sql = `SELECT ${dialect.escapeId('name')} FROM ${dialect.escapeId(this.tableName)} ORDER BY ${dialect.escapeId('name')} ASC`;
+            const sql = /*sql*/ `SELECT ${dialect.escapeId('name')} FROM ${dialect.escapeId(this.tableName)} ORDER BY ${dialect.escapeId('name')} ASC`;
             const results = await querier.all(sql);
             return results.map((r) => r.name);
         }
@@ -62,7 +62,7 @@ export class DatabaseMigrationStorage {
     async logWithQuerier(querier, migrationName) {
         await this.ensureStorage();
         const { dialect } = querier;
-        const sql = `INSERT INTO ${dialect.escapeId(this.tableName)} (${dialect.escapeId('name')}) VALUES (${dialect.placeholder(1)})`;
+        const sql = /*sql*/ `INSERT INTO ${dialect.escapeId(this.tableName)} (${dialect.escapeId('name')}) VALUES (${dialect.placeholder(1)})`;
         await querier.run(sql, [migrationName]);
     }
     /**
@@ -71,7 +71,7 @@ export class DatabaseMigrationStorage {
     async unlogWithQuerier(querier, migrationName) {
         await this.ensureStorage();
         const { dialect } = querier;
-        const sql = `DELETE FROM ${dialect.escapeId(this.tableName)} WHERE ${dialect.escapeId('name')} = ${dialect.placeholder(1)}`;
+        const sql = /*sql*/ `DELETE FROM ${dialect.escapeId(this.tableName)} WHERE ${dialect.escapeId('name')} = ${dialect.placeholder(1)}`;
         await querier.run(sql, [migrationName]);
     }
 }

package/dist/mongo/mongoDialect.d.ts

@@ -15,6 +15,8 @@ export declare class MongoDialect extends AbstractDialect {
     private static readonly REL_COUNT_KEY;
     private static readonly REL_NESTED_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;
     /**
      * MongoDB stores the primary key as `_id`; everything else resolves as usual. Projections, sorts,

package/dist/mongo/mongoDialect.js

@@ -14,7 +14,7 @@ export const mongoDialectFeatures = {
     renameColumn: false,
     foreignKeyAlter: false,
     columnComment: false,
-    vectorIndexStyle: 'create',
+    inlineVectorIndex: false,
     vectorSupportsLength: false,
     supportsTimestamptz: false,
     defaultStringAsText: false,
@@ -30,6 +30,8 @@ export class MongoDialect extends AbstractDialect {
     static REL_COUNT_KEY = 'n';
     static REL_NESTED_KEY = '__uql_target';
     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
     // COUNT(field) differ), so it is not listed here.
     static AGGREGATE_OP_MAP = new Map([
@@ -98,6 +100,11 @@ export class MongoDialect extends AbstractDialect {
                     return this.renderFilter(entity, filterIt, opts, lookups);
                 });
             }
+            else if (key === '$text') {
+                // MongoDB's text index declares which fields it covers, so `$fields` cannot narrow the search
+                // the way it does elsewhere - the same shape as `$distance` being index-defined here.
+                filter['$text'] = { $search: val.$value };
+            }
             else if (meta.relations[key]) {
                 this.assertNoRaw(val);
                 if (!lookups) {
@@ -744,13 +751,17 @@ 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.includes(key) && MongoDialect.VECTOR_INDEX_TYPES.has(idx.type));
+        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`;
+        if (!limit) {
+            throw new TypeError(`$vectorSearch requires $limit (vector sort on '${key}' of '${meta.name}')`);
+        }
         const stage = {
             index: indexName,
             path: colName,
             queryVector: [...search.$vector],
-            numCandidates: limit * 10,
+            // Atlas caps `numCandidates` at 10000 and wants roughly 10x the limit below that.
+            numCandidates: Math.min(limit * 10, MongoDialect.MAX_NUM_CANDIDATES),
             limit,
         };
         // Pre-filter: merge $where into $vectorSearch.filter

package/dist/mysql/mysqlDialect.d.ts

@@ -1,4 +1,12 @@
 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.
+     */
+    protected indexAccessMethod(index: IndexSchema): string;
 }

package/dist/mysql/mysqlDialect.js

@@ -1,4 +1,17 @@
 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.
+     */
+    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);
+    }
 }

package/dist/schema/canonicalType.d.ts

@@ -7,15 +7,27 @@
  * - TypeScript types (for entity generation)
  */
 import type { AbstractDialect } from '../dialect/abstractDialect.js';
+import type { VectorCast } from '../dialect/vectorCast.js';
 import type { ColumnType, FieldOptions } from '../type/entity.js';
 import type { CanonicalType, TypeCategory } from './types.js';
-/** Type guard for all vector-family categories. */
-export declare function isVectorCategory(category: TypeCategory): boolean;
+/** Whether a category is one of the vector types, narrowing it to the cast pgvector names use. */
+export declare function isVectorCategory(category: TypeCategory | undefined): category is VectorCast;
 /**
  * Parse a SQL type string into a canonical type.
  * Handles complex types like VARCHAR(255), DECIMAL(10,2), etc.
  */
 export declare function sqlToCanonical(sqlType: string): CanonicalType;
+/**
+ * The canonical type for a column an engine reported, merging the metadata columns it reports beside
+ * the type name (`character_maximum_length` and friends) over whatever the name itself carried. This is
+ * the one place a SQL type string is parsed: everything downstream compares and renders canonical
+ * types, so no consumer has to know that `TINYINT(1)` means boolean on MySQL.
+ */
+export declare function canonicalColumnType(sqlType: string, reported?: {
+    length?: number;
+    precision?: number;
+    scale?: number;
+}): CanonicalType;
 /**
  * Convert a canonical type to a SQL type string for a specific dialect instance.
  */