uql-orm 0.72.0 → 0.72.1

package/dist/dialect/abstractSqlDialect.d.ts

@@ -183,10 +183,16 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      */
     protected appendTextSearch<E>(_ctx: QueryContext, _entity: Type<E>, _meta: EntityMeta<E>, _search: QueryTextSearchOptions<E>): void;
     /**
-     * A row's relevance to a `$text` search, higher for a better match: what `$sort: { $text }` orders by.
-     * Each engine that searches scores too, so a dialect overrides this beside {@link appendTextSearch}.
+     * A row's relevance to a `$text` search, what `$sort: { $text }` orders by. Where the fulltext index
+     * weighs its columns, a match counts its column's weight, as MongoDB's `textScore` counts it: the score
+     * over every column times the lightest weight, plus each heavier column's own times what it weighs more.
      */
-    protected appendTextRank<E>(_ctx: QueryContext, _meta: EntityMeta<E>, _search: QueryTextSearchOptions<E>): void;
+    private appendTextRank;
+    /**
+     * How relevant the `keys` of a row are to a `$text` search, higher for a better match. Each engine that
+     * searches scores too, so a dialect overrides this beside {@link appendTextSearch}.
+     */
+    protected appendTextScore<E>(_ctx: QueryContext, _meta: EntityMeta<E>, _search: QueryTextSearchOptions<E>, _keys: readonly string[]): void;
     /** Ranks by the root `$text` of `where`, which is looked up only once a `$sort` asks for it. */
     private textRanker;
     select<E>(ctx: QueryContext, entity: Type<E>, q: Query<E>, opts?: ReadOptions, joins?: QueryJoins, totalAlias?: string): ReadProjection;

package/dist/dialect/abstractSqlDialect.js

@@ -1,7 +1,7 @@
 import { fieldOf, getMeta, relationOf, soleIdOf } from '../entity/index.js';
 import { COUNT_RESULT_KEY, parseQueryLock, QueryRaw, RAW_ALIAS, VECTOR_QUERY_KEYS, } from '../type/index.js';
 import { isInlinedExpression } from '../util/field.util.js';
-import { asSelectMap, assertNonNegativeInteger, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, idOnlyQuery, columnFamily, countedRelations, fieldUpdateOf, isFieldUpdateOp, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorKey, isVectorSearch, normalizeScalarFieldSelection, parentJoins, rankedTextSearch, targetKeyColumns, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortByCount, populatesRelations, aggregateOf, raw, refs, throwUnknownAggregateColumn, withoutSoftDeleteFilter, } from '../util/index.js';
+import { asSelectMap, assertNonNegativeInteger, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, idOnlyQuery, columnFamily, countedRelations, fieldUpdateOf, fulltextIndexOver, fulltextWeights, isFieldUpdateOp, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorKey, isVectorSearch, normalizeScalarFieldSelection, parentJoins, rankedTextSearch, targetKeyColumns, textSearchFields, textWeightSteps, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortByCount, populatesRelations, aggregateOf, raw, refs, throwUnknownAggregateColumn, withoutSoftDeleteFilter, } from '../util/index.js';
 import { escapeAnsiSqlLiteral } from '../util/sqlLiteral.js';
 import { AGGREGATE_PAGE_ALIAS, AGGREGATE_VALUE_ALIAS, ROWS_ALIAS, JSON_ELEM_ALIAS, JSON_PULL_ALIAS, relationSortColumn, } from './aliases.js';
 import { holdsOperator, isJsonScalar, jsonCompareMode, jsonElemExists, jsonPath, } from './jsonSql.js';
@@ -225,10 +225,34 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         throw new TypeError(`${this.dialectName} does not support $text full-text search`);
     }
     /**
-     * A row's relevance to a `$text` search, higher for a better match: what `$sort: { $text }` orders by.
-     * Each engine that searches scores too, so a dialect overrides this beside {@link appendTextSearch}.
+     * A row's relevance to a `$text` search, what `$sort: { $text }` orders by. Where the fulltext index
+     * weighs its columns, a match counts its column's weight, as MongoDB's `textScore` counts it: the score
+     * over every column times the lightest weight, plus each heavier column's own times what it weighs more.
      */
-    appendTextRank(_ctx, _meta, _search) {
+    appendTextRank(ctx, meta, search) {
+        const keys = textSearchFields(meta, search);
+        const index = fulltextIndexOver(meta, keys);
+        const weights = index && fulltextWeights({ type: index.type, entries: index.columns });
+        if (!weights) {
+            this.appendTextScore(ctx, meta, search, keys);
+            return;
+        }
+        const { lightest, extra } = textWeightSteps(weights);
+        ctx.append(`(${lightest} * `);
+        this.appendTextScore(ctx, meta, search, keys);
+        keys.forEach((key, at) => {
+            if (extra[at]) {
+                ctx.append(` + ${extra[at]} * `);
+                this.appendTextScore(ctx, meta, search, [key]);
+            }
+        });
+        ctx.append(')');
+    }
+    /**
+     * How relevant the `keys` of a row are to a `$text` search, higher for a better match. Each engine that
+     * searches scores too, so a dialect overrides this beside {@link appendTextSearch}.
+     */
+    appendTextScore(_ctx, _meta, _search, _keys) {
         throw new TypeError(`${this.dialectName} does not support $text full-text search`);
     }
     /** Ranks by the root `$text` of `where`, which is looked up only once a `$sort` asks for it. */

package/dist/dialect/mysqlLikeSqlDialect.d.ts

@@ -80,8 +80,11 @@ export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
      * `@Index((post) => [...], { type: 'fulltext' })`.
      */
     protected appendTextSearch<E>(ctx: QueryContext, _entity: Type<E>, meta: EntityMeta<E>, search: QueryTextSearchOptions<E>): void;
-    /** `MATCH ... AGAINST` is the relevance itself, a match being any row it scores above zero. */
-    protected appendTextRank<E>(ctx: QueryContext, meta: EntityMeta<E>, search: QueryTextSearchOptions<E>): void;
+    /**
+     * `MATCH ... AGAINST` is the relevance itself, a match being any row it scores above zero. Over `keys`
+     * alone, it needs a `FULLTEXT` index of exactly those: a weighted index declares one per heavier column.
+     */
+    protected appendTextScore<E>(ctx: QueryContext, meta: EntityMeta<E>, search: QueryTextSearchOptions<E>, keys: readonly string[]): void;
     /** `DOUBLE`, never a bare `DECIMAL`, which is `DECIMAL(10,0)` and rounds `1.4` to `1`. */
     protected numericCast(expr: string): string;
     protected neExpr(field: string, ph: string): string;

package/dist/dialect/mysqlLikeSqlDialect.js

@@ -32,6 +32,7 @@ export const MYSQL_FEATURES = {
     rowLocks: true,
     rowLockWithWindow: true,
     rowLockOf: true,
+    textScoreIndexes: true,
     orderedUpsertReturning: true,
     orderedJsonAggregates: true,
     narrowVectorTypes: false,
@@ -178,11 +179,14 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
      * `@Index((post) => [...], { type: 'fulltext' })`.
      */
     appendTextSearch(ctx, _entity, meta, search) {
-        this.appendTextRank(ctx, meta, search);
+        this.appendTextScore(ctx, meta, search, textSearchFields(meta, search));
     }
-    /** `MATCH ... AGAINST` is the relevance itself, a match being any row it scores above zero. */
-    appendTextRank(ctx, meta, search) {
-        const columns = textSearchFields(meta, search).map((key) => this.escapeId(this.resolveColumnName(key, meta.fields[key])));
+    /**
+     * `MATCH ... AGAINST` is the relevance itself, a match being any row it scores above zero. Over `keys`
+     * alone, it needs a `FULLTEXT` index of exactly those: a weighted index declares one per heavier column.
+     */
+    appendTextScore(ctx, meta, search, keys) {
+        const columns = keys.map((key) => this.escapeId(this.resolveColumnName(key, meta.fields[key])));
         ctx.append(`MATCH(${this.textSearchTarget(columns)}) AGAINST(`);
         ctx.addValue(search.$value);
         ctx.append(')');

package/dist/dialect/pgLikeSqlDialect.d.ts

@@ -64,9 +64,12 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
      * input (quoted phrases, `or`, `-negation`) and never raises a syntax error, unlike `TO_TSQUERY`.
      */
     protected appendTextSearch<E>(ctx: QueryContext, _entity: Type<E>, meta: EntityMeta<E>, search: QueryTextSearchOptions<E>): void;
-    /** `TS_RANK` of the document the predicate matches, against the same search. */
-    protected appendTextRank<E>(ctx: QueryContext, meta: EntityMeta<E>, search: QueryTextSearchOptions<E>): void;
-    /** The document a search reads and the search itself, open for its value. */
+    /** `TS_RANK` of the document over `keys` against the same search the match reads. */
+    protected appendTextScore<E>(ctx: QueryContext, meta: EntityMeta<E>, search: QueryTextSearchOptions<E>, keys: readonly string[]): void;
+    /**
+     * The document over `keys` and the search itself, open for its value, under the `$config` asked for,
+     * else that of the fulltext index over every field searched, which is what serves the match.
+     */
     private textSearchParts;
     /**
      * The document, `TO_TSVECTOR('english'::regconfig, COALESCE("a", '') || ' ' || COALESCE("b", ''))`, a

package/dist/dialect/pgLikeSqlDialect.js

@@ -36,6 +36,7 @@ export const PG_FEATURES = {
     rowLocks: true,
     rowLockWithWindow: false,
     rowLockOf: true,
+    textScoreIndexes: false,
     orderedUpsertReturning: true,
     orderedJsonAggregates: true,
     narrowVectorTypes: false,
@@ -134,19 +135,22 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
         ctx.addValue(search.$value);
         ctx.append(')');
     }
-    /** `TS_RANK` of the document the predicate matches, against the same search. */
-    appendTextRank(ctx, meta, search) {
-        const { document, query } = this.textSearchParts(meta, search);
+    /** `TS_RANK` of the document over `keys` against the same search the match reads. */
+    appendTextScore(ctx, meta, search, keys) {
+        const { document, query } = this.textSearchParts(meta, search, keys);
         ctx.append(`TS_RANK(${document}, ${query}`);
         ctx.addValue(search.$value);
         ctx.append('))');
     }
-    /** The document a search reads and the search itself, open for its value. */
-    textSearchParts(meta, search) {
-        const keys = textSearchFields(meta, search);
-        const index = fulltextIndexOver(meta, keys);
+    /**
+     * The document over `keys` and the search itself, open for its value, under the `$config` asked for,
+     * else that of the fulltext index over every field searched, which is what serves the match.
+     */
+    textSearchParts(meta, search, keys) {
+        const fields = textSearchFields(meta, search);
+        const index = fulltextIndexOver(meta, fields);
         const config = search.$config ?? (index && fulltextConfig(index));
-        const columns = keys.map((key) => this.escapeId(this.resolveColumnName(key, meta.fields[key])));
+        const columns = (keys ?? fields).map((key) => this.escapeId(this.resolveColumnName(key, meta.fields[key])));
         return {
             document: this.textSearchTarget(columns, config),
             query: `${this.textQueryFn}(${this.textConfigArg(config)}`,

package/dist/entity/metadata/definition.js

@@ -1,6 +1,6 @@
 import { RelationAggregate, SOFT_DELETE_FILTER } from '../../type/index.js';
 import { isInlinedExpression } from '../../util/field.util.js';
-import { entitySql, entityWhere, fieldOptionConflict, getKeys, hasKeys, isToManyRelation, memberRefs, normalizeIndexColumn, definedEntries, } from '../../util/index.js';
+import { entitySql, entityWhere, fieldOptionConflict, getKeys, hasKeys, isToManyRelation, memberRefs, fulltextWeights, normalizeIndexColumn, definedEntries, } from '../../util/index.js';
 import { ownRegistrations } from '../decorator/bag.js';
 /**
  * A map held on `globalThis` through the global symbol registry, so a single one survives multiple
@@ -101,11 +101,13 @@ export function defineHook(entity, methodName, event) {
 export function defineIndex(entity, index) {
     const meta = ensureWritableMeta(entity);
     const refs = memberRefs();
+    const columns = index.columns(refs).map(normalizeIndexColumn);
+    fulltextWeights({ type: index.type, entries: columns });
     (meta.indexes ??= []).push({
         ...index,
         unique: index.unique ?? false,
         where: index.where && entityWhere(index.where),
-        columns: index.columns(refs).map(normalizeIndexColumn),
+        columns,
         include: index.include?.(refs).map((ref) => ref.key),
     });
     return meta;

package/dist/migrate/cli.js

@@ -239,7 +239,8 @@ export async function runDriftCheck(migrator, config) {
     }
     else {
         console.log('\nChecking for schema drift...');
-        const expectedAST = buildEntityAST(await migrator.getSchemaGenerator(), config.entities);
+        const generator = await migrator.getSchemaGenerator();
+        const expectedAST = generator.buildAST?.(config.entities) ?? buildEntityAST(generator, config.entities);
         // Build actual schema from database
         const actualAST = await migrator.schemaIntrospector.introspect();
         // Detect drift. The dialect renders canonical types as SQL - without it every type formats as

package/dist/migrate/ddl/indexDdl.d.ts

@@ -15,6 +15,8 @@ export declare class IndexDdl<D extends AbstractSqlDialect = AbstractSqlDialect>
     getCreateIndexStatement(tableName: string, index: IndexSchema, opts?: {
         ifNotExists?: boolean;
     }): string;
+    /** What an index added to a table that has rows needs run after it to serve queries; nothing, mostly. */
+    settleStatements(_tableName: string, _index: IndexSchema): 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

package/dist/migrate/ddl/indexDdl.js

@@ -50,6 +50,10 @@ export class IndexDdl {
             `ON ${this.dialect.escapeId(tableName)}${this.indexAccessMethod(index)} (${columns})` +
             `${this.indexInclude(index)}${this.indexTuning(index)}${this.indexPredicate(index)};`);
     }
+    /** What an index added to a table that has rows needs run after it to serve queries; nothing, mostly. */
+    settleStatements(_tableName, _index) {
+        return [];
+    }
     /**
      * 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

package/dist/migrate/ddl/mysqlIndexDdl.d.ts

@@ -6,6 +6,11 @@ export declare class MysqlLikeIndexDdl extends IndexDdl {
     protected readonly indexFeatures: Set<"expression" | "include" | "jsonArray" | "jsonPath" | "nullsOrder" | "opsClass" | "partial" | "prefixLength">;
     protected readonly indexTypes: ReadonlySet<IndexType>;
     protected readonly indexTypeKeywords: ReadonlyMap<IndexType, string>;
+    /**
+     * InnoDB fills a fulltext index added beside another on a loaded table only once the table is optimized:
+     * until then MariaDB scores it 0 and MySQL can fail a `MATCH` over it (MySQL 26.7, MariaDB 12.3).
+     */
+    settleStatements(tableName: string, index: IndexSchema): string[];
     /** ` USING btree|hash` trails the columns: between the table and them, it is a syntax error here. */
     protected indexTuning(index: IndexSchema): string;
 }

package/dist/migrate/ddl/mysqlIndexDdl.js

@@ -11,6 +11,13 @@ export class MysqlLikeIndexDdl extends IndexDdl {
     indexFeatures = new Set(['expression', 'prefixLength']);
     indexTypes = new Set(['btree', 'hash', 'fulltext']);
     indexTypeKeywords = MYSQL_LIKE_INDEX_KEYWORDS;
+    /**
+     * InnoDB fills a fulltext index added beside another on a loaded table only once the table is optimized:
+     * until then MariaDB scores it 0 and MySQL can fail a `MATCH` over it (MySQL 26.7, MariaDB 12.3).
+     */
+    settleStatements(tableName, index) {
+        return index.type === 'fulltext' ? [`OPTIMIZE TABLE ${this.dialect.escapeId(tableName)};`] : [];
+    }
     /** ` USING btree|hash` trails the columns: between the table and them, it is a syntax error here. */
     indexTuning(index) {
         return index.type && !this.indexTypeKeywords.has(index.type) ? ` USING ${index.type}` : '';

package/dist/migrate/generator/mongoCommand.d.ts

@@ -5,6 +5,8 @@ export type MongoIndexOptions = {
     readonly unique: boolean;
     readonly name: string;
     readonly partialFilterExpression?: Readonly<Record<string, unknown>>;
+    /** A text index's weight per field, which `textScore` multiplies a match in it by. */
+    readonly weights?: Readonly<Record<string, number>>;
 };
 /** A field of an Atlas vector search index: the vector itself, or one its `filter` pre-filters on. */
 export type MongoVectorSearchField = {

package/dist/migrate/generator/mongoSchemaGenerator.js

@@ -3,6 +3,7 @@ import { MongoDialect } from '../../mongo/mongoDialect.js';
 import { QueryRaw, } from '../../type/index.js';
 import { indexDistance, unsupportedVectorMetric } from '../../type/vector.js';
 import { declaredIndexes, declaredIndexName, renderIndexColumn } from '../../util/ddlExpression.util.js';
+import { fulltextWeights } from '../../util/dialect.util.js';
 import { assertIndexFeatures, assertIndexType } from '../ddl/indexDdl.js';
 import { assertIndexPredicate, refusedIndexPredicate } from '../indexPredicate.js';
 import { renderIndexDefinition } from './definitionToNode.js';
@@ -121,6 +122,7 @@ export class MongoSchemaGenerator extends MongoDialect {
         for (const entry of index.entries) {
             key[entry.column] = index.type === 'fulltext' ? 'text' : entry.order === 'desc' ? -1 : 1;
         }
+        const weights = fulltextWeights(index);
         return serializeMongoCommand({
             action: 'createIndex',
             collection: tableName,
@@ -130,6 +132,7 @@ export class MongoSchemaGenerator extends MongoDialect {
                 unique: index.unique,
                 name: index.name,
                 partialFilterExpression: index.where && JSON.parse(index.where),
+                weights: weights && Object.fromEntries(index.entries.map((entry, at) => [entry.column, weights[at]])),
             },
         });
     }

package/dist/migrate/introspection/mongoIntrospector.d.ts

@@ -7,7 +7,7 @@ import { type QuerierPool, type SchemaIntrospector, type TableSchema } from '../
  */
 export declare class MongoSchemaIntrospector implements SchemaIntrospector {
     private readonly pool;
-    /** `listIndexes` reports keys and uniqueness; a `partialFilterExpression` is no SQL predicate. */
+    /** `listIndexes` reports keys, uniqueness and text weights; a `partialFilterExpression` is no SQL predicate. */
     readonly indexFacets: ReadonlySet<IndexFacet>;
     constructor(pool: QuerierPool);
     introspect(tables?: readonly string[]): Promise<SchemaAST>;

package/dist/migrate/introspection/mongoIntrospector.js

@@ -8,8 +8,8 @@ const SEARCH_NOT_ENABLED = 31082;
  */
 export class MongoSchemaIntrospector {
     pool;
-    /** `listIndexes` reports keys and uniqueness; a `partialFilterExpression` is no SQL predicate. */
-    indexFacets = new Set();
+    /** `listIndexes` reports keys, uniqueness and text weights; a `partialFilterExpression` is no SQL predicate. */
+    indexFacets = new Set(['textWeights']);
     constructor(pool) {
         this.pool = pool;
     }
@@ -38,10 +38,12 @@ export class MongoSchemaIntrospector {
                 name: tableName,
                 columns: [],
                 indexes: [
-                    ...indexes.map((idx) => ({
-                        name: idx.name ?? Object.keys(idx.key).join('_'),
-                        entries: Object.keys(idx.key).map((column) => ({ column })),
-                        unique: !!idx.unique,
+                    ...indexes.map(({ name, key, unique, weights }) => ({
+                        name: name ?? Object.keys(key).join('_'),
+                        unique: !!unique,
+                        ...(weights
+                            ? { entries: Object.entries(weights).map(textIndexEntry), type: 'fulltext' }
+                            : { entries: Object.keys(key).map((column) => ({ column })) }),
                     })),
                     ...searchIndexes
                         .filter((idx) => idx.type === 'vectorSearch')
@@ -75,6 +77,10 @@ export class MongoSchemaIntrospector {
         });
     }
 }
+/** A text index field as an entity declares it: its weight stated only where it is not the default 1. */
+function textIndexEntry([column, weight]) {
+    return weight === 1 ? { column } : { column, weight };
+}
 /** A collection's Atlas search indexes, none where the server has no Atlas Search. */
 async function listSearchIndexes(collection) {
     try {

package/dist/migrate/schemaGenerator.d.ts

@@ -1,5 +1,6 @@
 import type { AbstractSqlDialect } from '../dialect/index.js';
 import type { SchemaAST } from '../schema/schemaAST.js';
+import { type BuildSchemaASTOptions } from '../schema/schemaASTBuilder.js';
 import { type DiffOptions } from '../schema/schemaASTDiffer.js';
 import type { CanonicalType, ColumnNode, ForeignKeyAction, IndexNode, TableNode } from '../schema/types.js';
 import type { ColumnSchema, CreateSchemaOptions, DialectFeatures, DropSchemaOptions, EntityMeta, EntityWhereMeta, FieldMeta, FieldOptions, ForeignKeySchema, IndexSchema, NamingStrategy, SchemaDiff, SchemaGenerator, Type } from '../type/index.js';
@@ -65,6 +66,8 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
     generateCreateIndex(tableName: string, index: IndexSchema, options?: {
         ifNotExists?: boolean;
     }): string;
+    /** An index added to a table that may already have rows: its `CREATE`, then what the engine needs after. */
+    private addIndexStatements;
     /**
      * `schema` is the table's, because that is where its indexes live. MySQL takes it from the table
      * operand instead, which is already qualified.
@@ -175,4 +178,4 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
  * The entities as an AST, named by `generator`'s resolvers rather than a naming strategy, which would
  * also rename an explicit `@Entity({ name })` and so compare each table under another name.
  */
-export declare function buildEntityAST(generator: Pick<SchemaGenerator, 'resolveTableAlias' | 'resolveSchema' | 'resolveColumnName' | 'compileDdl' | 'compileIndexPredicate'>, entities: readonly Type<object>[], defaultForeignKeyAction?: ForeignKeyAction): SchemaAST;
+export declare function buildEntityAST(generator: Pick<SchemaGenerator, 'resolveTableAlias' | 'resolveSchema' | 'resolveColumnName' | 'compileDdl' | 'compileIndexPredicate'>, entities: readonly Type<object>[], options?: Pick<BuildSchemaASTOptions, 'defaultForeignKeyAction' | 'textScoreIndexes'>): SchemaAST;

package/dist/migrate/schemaGenerator.js

@@ -74,7 +74,10 @@ export class SqlSchemaGenerator {
     }
     /** The entity side as an AST, carrying this generator's default referential action. */
     buildAST(entities) {
-        return buildEntityAST(this, entities, this.defaultForeignKeyAction);
+        return buildEntityAST(this, entities, {
+            defaultForeignKeyAction: this.defaultForeignKeyAction,
+            textScoreIndexes: this.dialect.features.textScoreIndexes,
+        });
     }
     /**
      * Every `CREATE TABLE` for `entities`, then their foreign keys, since a relation graph is routinely
@@ -115,7 +118,7 @@ export class SqlSchemaGenerator {
      * resolves instead of being silently dropped.
      */
     orderedTables(entities, direction, only) {
-        const ast = buildEntityAST(this, entities, this.defaultForeignKeyAction);
+        const ast = this.buildAST(entities);
         const tables = direction === 'create' ? ast.getCreateOrder() : ast.getDropOrder();
         if (!only) {
             return tables;
@@ -166,7 +169,7 @@ export class SqlSchemaGenerator {
         // Add indexes
         if (diff.indexesToAdd?.length) {
             for (const index of diff.indexesToAdd) {
-                statements.push(this.generateCreateIndex(diff.tableName, index));
+                statements.push(...this.addIndexStatements(diff.tableName, index));
             }
         }
         // Drop indexes
@@ -243,6 +246,10 @@ export class SqlSchemaGenerator {
     generateCreateIndex(tableName, index, options = {}) {
         return this.indexDdl.getCreateIndexStatement(tableName, index, options);
     }
+    /** An index added to a table that may already have rows: its `CREATE`, then what the engine needs after. */
+    addIndexStatements(tableName, index) {
+        return [this.generateCreateIndex(tableName, index), ...this.indexDdl.settleStatements(tableName, index)];
+    }
     /**
      * `schema` is the table's, because that is where its indexes live. MySQL takes it from the table
      * operand instead, which is already qualified.
@@ -338,7 +345,7 @@ export class SqlSchemaGenerator {
         }
         // Keyed by the qualified name this generator resolves, which is the key the AST stores the table
         // under.
-        const desired = (desiredAst ?? buildEntityAST(this, [entity], this.defaultForeignKeyAction)).getTable(tableName);
+        const desired = (desiredAst ?? this.buildAST([entity])).getTable(tableName);
         if (!desired) {
             return undefined;
         }
@@ -556,7 +563,7 @@ export class SqlSchemaGenerator {
             case 'alterColumn':
                 return this.generateAlterColumnSql(operation.tableName, operation.columnName, operation.changes);
             case 'createIndex':
-                return [this.generateCreateIndexFromDefinition(operation.tableName, operation.index)];
+                return this.addIndexStatements(operation.tableName, renderIndexDefinition(operation.index, (sql) => this.dialect.compileDdl(sql)));
             case 'dropIndex':
                 return [this.generateDropIndex(operation.tableName, operation.indexName)];
             case 'addForeignKey':
@@ -693,7 +700,7 @@ function foreignKeyOf(relation) {
  * The entities as an AST, named by `generator`'s resolvers rather than a naming strategy, which would
  * also rename an explicit `@Entity({ name })` and so compare each table under another name.
  */
-export function buildEntityAST(generator, entities, defaultForeignKeyAction) {
+export function buildEntityAST(generator, entities, options = {}) {
     return buildSchemaAST(entities, {
         // The alias, not `resolveTableName`: a node holds its schema separately, so that a name derived
         // from it stays a single identifier.
@@ -702,6 +709,6 @@ export function buildEntityAST(generator, entities, defaultForeignKeyAction) {
         resolveColumnName: (key, field) => generator.resolveColumnName(key, field),
         compileDdl: (sql, entity) => generator.compileDdl(sql, entity),
         compileIndexPredicate: (where, entity, indexName) => generator.compileIndexPredicate(where, entity, indexName),
-        defaultForeignKeyAction,
+        ...options,
     });
 }

package/dist/mssql/mssqlDialect.js

@@ -34,6 +34,7 @@ const MSSQL_FEATURES = {
     rowLocks: true,
     rowLockWithWindow: true,
     rowLockOf: true,
+    textScoreIndexes: false,
     orderedUpsertReturning: false,
     orderedJsonAggregates: true,
     narrowVectorTypes: false,

package/dist/schema/indexDifferences.d.ts

@@ -2,8 +2,9 @@ import type { IndexNode } from './types.js';
 /**
  * What an introspector reports about an index, and so all a diff may compare; apart from `IndexFeature`, what an engine emits.
  * `vector` is whether it is a vector index at all, for an engine with one vector index whatever type declared it.
+ * `textWeights` is a text index's weights, kept by an engine that lists its fields in no declared order.
  */
-export type IndexFacet = 'order' | 'nulls' | 'opsClass' | 'accessMethod' | 'include' | 'vector';
+export type IndexFacet = 'order' | 'nulls' | 'opsClass' | 'accessMethod' | 'include' | 'vector' | 'textWeights';
 /**
  * Whether the table has this index already, by shape rather than name, uniqueness included. An index
  * over an expression, whose text the engine reprints, falls back to its name.

package/dist/schema/indexDifferences.js

@@ -35,7 +35,7 @@ export function describeIndexDifferences(source, target, facets) {
     const differences = [];
     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(', '));
+        const [sourceColumns, targetColumns] = [source, target].map((index) => textFieldOrder(index, facets, index.entries.map((entry) => entrySignature(entry, facets))).join(', '));
         if (sourceColumns !== targetColumns) {
             differences.push(`columns: (${targetColumns}) -> (${sourceColumns})`);
         }
@@ -59,6 +59,10 @@ export function describeIndexDifferences(source, target, facets) {
     }
     return differences;
 }
+/** A text index's fields as a set where the engine keeps its weights: MongoDB lists them alphabetically. */
+function textFieldOrder(index, facets, entries) {
+    return facets.has('textWeights') && index.type === 'fulltext' ? entries.toSorted() : entries;
+}
 function entrySignature(entry, facets) {
     const parts = [entry.column];
     if (facets.has('order')) {
@@ -72,5 +76,8 @@ function entrySignature(entry, facets) {
     if (facets.has('opsClass') && entry.opsClass) {
         parts.push(entry.opsClass);
     }
+    if (facets.has('textWeights') && (entry.weight ?? 1) !== 1) {
+        parts.push(`weight ${entry.weight}`);
+    }
     return parts.join(' ');
 }

package/dist/schema/schemaASTBuilder.d.ts

@@ -24,6 +24,8 @@ export interface BuildSchemaASTOptions {
     compileDdl?: (sql: EntityWhereMeta<object>, entity: Type<object>) => string;
     /** A partial index's predicate as the engine writes it, `compileDdl` where none is given. `buildEntityAST` supplies it. */
     compileIndexPredicate?: (where: EntityWhereMeta<object>, entity: Type<object>, indexName: string) => string;
+    /** Whether a weighted fulltext index declares one of its own for each heavier column, as MySQL scores through one. */
+    textScoreIndexes?: boolean;
 }
 /**
  * Build a SchemaAST from entity classes (decorated with `@Entity`, `@Field`, etc.).

package/dist/schema/schemaASTBuilder.js

@@ -1,5 +1,6 @@
 import { fieldOf, foreignKeysOf, getMeta, soleIdOf } from '../entity/metadata/definition.js';
 import { declaredIndexes, declaredIndexName, renderIndexColumn } from '../util/ddlExpression.util.js';
+import { fulltextWeights, textWeightSteps } from '../util/dialect.util.js';
 import { isInlinedExpression } from '../util/field.util.js';
 import { isSoleIdField } from '../util/field.util.js';
 import { isAutoIncrement } from '../util/field.util.js';
@@ -26,6 +27,7 @@ export function buildSchemaAST(entities, options = {}) {
         defaultForeignKeyAction: options.defaultForeignKeyAction ?? DEFAULT_FOREIGN_KEY_ACTION,
         compileDdl,
         compileIndexPredicate: options.compileIndexPredicate ?? compileDdl,
+        textScoreIndexes: options.textScoreIndexes ?? false,
     };
     for (const pass of [addTableFromEntity, addRelationshipsFromEntity, addIndexesFromEntity]) {
         for (const entity of entities) {
@@ -213,4 +215,25 @@ function addCompositeIndex(ctx, table, meta, idxMeta) {
         lists: idxMeta.lists,
         config: idxMeta.config,
     });
+    if (ctx.textScoreIndexes) {
+        addTextScoreIndexes(ctx, table, idxMeta.type, resolved);
+    }
+}
+/** A fulltext index of its own for each column heavier than the index's lightest, which its score reads. */
+function addTextScoreIndexes(ctx, table, type, entries) {
+    const weights = fulltextWeights({ type, entries });
+    if (!weights)
+        return;
+    const { extra } = textWeightSteps(weights);
+    entries.forEach((entry, at) => {
+        if (extra[at] && typeof entry.column === 'string') {
+            ctx.ast.addIndex({
+                name: derivedIndexName(table.name, [entry.column, 'score']),
+                table,
+                entries: [{ column: entry.column }],
+                unique: false,
+                type: 'fulltext',
+            });
+        }
+    });
 }

package/dist/sqlite/sqliteDialect.d.ts

@@ -68,7 +68,7 @@ export declare class SqliteDialect extends AbstractSqlDialect {
      */
     protected appendTextSearch<E>(ctx: QueryContext, entity: Type<E>, meta: EntityMeta<E>, search: QueryTextSearchOptions<E>): void;
     /** FTS5's `BM25` of the match, lower for a better one, so negated to rank as every other engine does. */
-    protected appendTextRank<E>(ctx: QueryContext, meta: EntityMeta<E>): void;
+    protected appendTextScore<E>(ctx: QueryContext, meta: EntityMeta<E>): void;
     protected jsonLength(slot: JsonSlot): string;
     /** `JSON_EACH` walks the array at the path itself, each element's `fullkey` naming it from the column. */
     protected jsonElemFrom(slot: JsonSlot, alias: string): string;

package/dist/sqlite/sqliteDialect.js

@@ -27,6 +27,7 @@ export const SQLITE_FEATURES = {
     rowLocks: false,
     rowLockWithWindow: true,
     rowLockOf: true,
+    textScoreIndexes: false,
     orderedUpsertReturning: true,
     orderedJsonAggregates: true,
     narrowVectorTypes: false,
@@ -164,7 +165,7 @@ export class SqliteDialect extends AbstractSqlDialect {
         ctx.addValue(search.$value);
     }
     /** FTS5's `BM25` of the match, lower for a better one, so negated to rank as every other engine does. */
-    appendTextRank(ctx, meta) {
+    appendTextScore(ctx, meta) {
         ctx.append(`-BM25(${this.escapedTableName(meta)})`);
     }
     jsonLength(slot) {

package/dist/type/dialect.d.ts

@@ -142,6 +142,11 @@ export interface SqlDialectFeatures extends DialectFeatures {
     readonly rowLockWithWindow: boolean;
     /** Whether a lock can be narrowed to one table of a join, `FOR UPDATE OF`, which MariaDB lacks. */
     readonly rowLockOf: boolean;
+    /**
+     * Whether a fulltext index's heavier column needs a fulltext index of its own to be scored by, as
+     * MySQL's `MATCH` does, which reads only an index over exactly its columns.
+     */
+    readonly textScoreIndexes: boolean;
     /** Whether a multi-row upsert's `RETURNING` lists its rows in payload order; where not, the ids are read back. */
     readonly orderedUpsertReturning: boolean;
     /** Whether a JSON aggregate takes an `ORDER BY` of its own; where not, a relation's rows keep their derived table's order. */

package/dist/type/entity.d.ts

@@ -563,6 +563,11 @@ export type IndexColumnModifiers = {
     readonly nulls?: 'first' | 'last';
     /** Operator class, e.g. `jsonb_path_ops` for a smaller GIN index. Postgres only. */
     readonly opsClass?: string;
+    /**
+     * How many times a match in this column of a fulltext index counts in `$sort: { $text }`, 1 by default:
+     * a whole number from 1 to 99999, the range MongoDB weighs by.
+     */
+    readonly weight?: number;
     /** Index a path inside a JSON column. See {@link IndexJsonPath}. */
     readonly jsonPath?: IndexJsonPath;
     /** Index every element of a JSON array. See {@link IndexJsonArray}. */

package/dist/util/dialect.util.d.ts

@@ -1,3 +1,4 @@
+import type { IndexType } from '../schema/types.js';
 import { type CascadeType, type EntityData, type EntityId, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type FieldUpdateOp, type JsonUpdateOp, type OnFieldCallback, type Query, type QueryAggMap, type QueryAggregateOp, type QueryExclude, type QueryGroupMap, type QueryOptions, QueryRaw, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorSearch, type QueryWhere, type RelationKey, type UpdatePayload } from '../type/index.js';
 export type CallbackKey = keyof Pick<FieldOptions, 'onInsert' | 'onUpdate'>;
 /** The keys of `payload` a write persists as columns. */
@@ -171,6 +172,24 @@ export declare function assertAggregateColumns(clauseMap: object, emitted: Reado
 export declare function fulltextConfig(index: {
     readonly config?: string;
 }): string;
+/**
+ * Each column's weight in a fulltext index, 1 where it states none, or none at all where they are alike.
+ * Checked wherever it is read, so the migration, the search and its rank refuse the same declaration.
+ */
+export declare function fulltextWeights(index: {
+    readonly type?: IndexType;
+    readonly entries: readonly {
+        readonly weight?: number;
+    }[];
+}): readonly number[] | undefined;
+/**
+ * A weighted fulltext index's lightest weight, and what each column weighs beyond it: the score over every
+ * column counts the lightest, and a column weighing more adds its own score times the rest.
+ */
+export declare function textWeightSteps(weights: readonly number[]): {
+    lightest: number;
+    extra: number[];
+};
 /** The fulltext index over exactly `fields`, in order, which a search of them is served by. */
 export declare function fulltextIndexOver<E>(meta: EntityMeta<E>, fields: readonly string[]): EntityIndexMeta<E> | undefined;
 /**

package/dist/util/dialect.util.js

@@ -456,6 +456,35 @@ const DEFAULT_TEXT_CONFIG = 'simple';
 export function fulltextConfig(index) {
     return index.config ?? DEFAULT_TEXT_CONFIG;
 }
+/** The largest weight MongoDB's text index takes, which truncates a fraction to the whole number below. */
+const MAX_TEXT_WEIGHT = 99_999;
+/**
+ * Each column's weight in a fulltext index, 1 where it states none, or none at all where they are alike.
+ * Checked wherever it is read, so the migration, the search and its rank refuse the same declaration.
+ */
+export function fulltextWeights(index) {
+    if (!index.entries.some((entry) => entry.weight !== undefined)) {
+        return undefined;
+    }
+    if (index.type !== 'fulltext') {
+        throw new TypeError(`a column weight ranks a fulltext index, and this one is ${index.type ?? 'btree'}`);
+    }
+    const weights = index.entries.map(({ weight = 1 }) => {
+        if (!Number.isInteger(weight) || weight < 1 || weight > MAX_TEXT_WEIGHT) {
+            throw new TypeError(`a column weight is a whole number from 1 to ${MAX_TEXT_WEIGHT}, not ${weight}`);
+        }
+        return weight;
+    });
+    return new Set(weights).size > 1 ? weights : undefined;
+}
+/**
+ * A weighted fulltext index's lightest weight, and what each column weighs beyond it: the score over every
+ * column counts the lightest, and a column weighing more adds its own score times the rest.
+ */
+export function textWeightSteps(weights) {
+    const lightest = Math.min(...weights);
+    return { lightest, extra: weights.map((weight) => weight - lightest) };
+}
 /** The fulltext index over exactly `fields`, in order, which a search of them is served by. */
 export function fulltextIndexOver(meta, fields) {
     return meta.indexes?.find((index) => index.type === 'fulltext' &&

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "The JSON-native TypeScript ORM for Bun, Browsers, Edge, Deno, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.72.0",
+  "version": "0.72.1",
   "type": "module",
   "engines": {
     "node": ">=24"