@mikro-orm/sql 7.0.0-rc.2 → 7.0.0-rc.3

package/AbstractSqlConnection.js

@@ -181,7 +181,8 @@ export class AbstractSqlConnection extends Connection {
         try {
             const res = (ctx ?? this.getClient()).getExecutor().stream(compiled, 1);
             this.logQuery(sql, {
-                sql, params,
+                sql,
+                params,
                 ...loggerContext,
                 affected: Utils.isPlainObject(res) ? res.affectedRows : undefined,
             });

package/AbstractSqlDriver.d.ts

@@ -1,7 +1,7 @@
 import { type AnyEntity, type Collection, type Configuration, type ConnectionType, type Constructor, type CountOptions, DatabaseDriver, type DeleteOptions, type Dictionary, type DriverMethodOptions, type EntityData, type EntityDictionary, type EntityField, EntityManagerType, type EntityMetadata, type EntityName, type EntityProperty, type FilterQuery, type FindOneOptions, type FindOptions, type FormulaTable, type LockOptions, type LoggingOptions, type NativeInsertUpdateManyOptions, type NativeInsertUpdateOptions, type ObjectQuery, type Options, type OrderDefinition, type PopulateOptions, type PopulatePath, type Primary, type QueryOrderMap, type QueryResult, type Raw, RawQueryFragment, type StreamOptions, type Transaction, type UpsertManyOptions, type UpsertOptions } from '@mikro-orm/core';
 import type { AbstractSqlConnection } from './AbstractSqlConnection.js';
 import type { AbstractSqlPlatform } from './AbstractSqlPlatform.js';
-import { QueryBuilder } from './query/QueryBuilder.js';
+import { type AnyQueryBuilder } from './query/QueryBuilder.js';
 import { type NativeQueryBuilder } from './query/NativeQueryBuilder.js';
 import { QueryType } from './query/enums.js';
 import { SqlEntityManager } from './SqlEntityManager.js';
@@ -36,7 +36,7 @@ export declare abstract class AbstractSqlDriver<Connection extends AbstractSqlCo
      * Force balanced strategy to load to-many relations via separate queries.
      */
     private forceBalancedStrategy;
-    mapResult<T extends object>(result: EntityData<T>, meta: EntityMetadata<T>, populate?: PopulateOptions<T>[], qb?: QueryBuilder<T, any, any, any>, map?: Dictionary): EntityData<T> | null;
+    mapResult<T extends object>(result: EntityData<T>, meta: EntityMetadata<T>, populate?: PopulateOptions<T>[], qb?: AnyQueryBuilder<T>, map?: Dictionary): EntityData<T> | null;
     /**
      * Maps aliased columns from TPT parent tables back to their original field names.
      * TPT parent columns are selected with aliases like `parent_alias__column_name`,
@@ -99,17 +99,17 @@ export declare abstract class AbstractSqlDriver<Connection extends AbstractSqlCo
      */
     mergeJoinedResult<T extends object>(rawResults: EntityData<T>[], meta: EntityMetadata<T>, joinedProps: PopulateOptions<T>[]): EntityData<T>[];
     protected shouldHaveColumn<T, U>(meta: EntityMetadata<T>, prop: EntityProperty<U>, populate: readonly PopulateOptions<U>[], fields?: readonly InternalField<U>[], exclude?: readonly InternalField<U>[]): boolean;
-    protected getFieldsForJoinedLoad<T extends object>(qb: QueryBuilder<T, any, any, any>, meta: EntityMetadata<T>, options: FieldsForJoinedLoadOptions<T>): InternalField<T>[];
+    protected getFieldsForJoinedLoad<T extends object>(qb: AnyQueryBuilder<T>, meta: EntityMetadata<T>, options: FieldsForJoinedLoadOptions<T>): InternalField<T>[];
     /**
      * Adds LEFT JOINs and fields for TPT polymorphic loading when populating a relation to a TPT base class.
      * @internal
      */
-    protected addTPTPolymorphicJoinsForRelation<T extends object>(qb: QueryBuilder<T, any, any, any>, meta: EntityMetadata<T>, baseAlias: string, fields: InternalField<T>[]): void;
+    protected addTPTPolymorphicJoinsForRelation<T extends object>(qb: AnyQueryBuilder<T>, meta: EntityMetadata<T>, baseAlias: string, fields: InternalField<T>[]): void;
     /**
      * Find the alias for a TPT child table in the query builder.
      * @internal
      */
-    protected findTPTChildAlias<T extends object>(qb: QueryBuilder<T, any, any, any>, childMeta: EntityMetadata): string | undefined;
+    protected findTPTChildAlias<T extends object>(qb: AnyQueryBuilder<T>, childMeta: EntityMetadata): string | undefined;
     /**
      * Builds a CASE WHEN expression for TPT discriminator.
      * Determines concrete entity type based on which child table has a non-null PK.
@@ -122,13 +122,13 @@ export declare abstract class AbstractSqlDriver<Connection extends AbstractSqlCo
      * This method reads the discriminator to determine the concrete type and maps child-specific fields.
      * @internal
      */
-    protected mapTPTChildFields<T extends object>(relationPojo: EntityData<T>, meta: EntityMetadata<T>, relationAlias: string, qb: QueryBuilder<T, any, any, any>, root: EntityData<T>): void;
+    protected mapTPTChildFields<T extends object>(relationPojo: EntityData<T>, meta: EntityMetadata<T>, relationAlias: string, qb: AnyQueryBuilder<T>, root: EntityData<T>): void;
     /**
      * @internal
      */
-    mapPropToFieldNames<T extends object>(qb: QueryBuilder<T, any, any, any, any, any>, prop: EntityProperty<T>, tableAlias: string, meta: EntityMetadata<T>, schema?: string, explicitFields?: readonly InternalField<T>[]): InternalField<T>[];
+    mapPropToFieldNames<T extends object>(qb: AnyQueryBuilder<T>, prop: EntityProperty<T>, tableAlias: string, meta: EntityMetadata<T>, schema?: string, explicitFields?: readonly InternalField<T>[]): InternalField<T>[];
     /** @internal */
-    createQueryBuilder<T extends object>(entityName: EntityName<T> | QueryBuilder<T, any, any, any>, ctx?: Transaction, preferredConnectionType?: ConnectionType, convertCustomTypes?: boolean, loggerContext?: LoggingOptions, alias?: string, em?: SqlEntityManager): QueryBuilder<T, any, any, any>;
+    createQueryBuilder<T extends object>(entityName: EntityName<T> | AnyQueryBuilder<T>, ctx?: Transaction, preferredConnectionType?: ConnectionType, convertCustomTypes?: boolean, loggerContext?: LoggingOptions, alias?: string, em?: SqlEntityManager): AnyQueryBuilder<T>;
     protected resolveConnectionType(args: {
         ctx?: Transaction;
         connectionType?: ConnectionType;
@@ -137,13 +137,19 @@ export declare abstract class AbstractSqlDriver<Connection extends AbstractSqlCo
     protected processManyToMany<T extends object>(meta: EntityMetadata<T>, pks: Primary<T>[], collections: EntityData<T>, clear: boolean, options?: DriverMethodOptions): Promise<void>;
     lockPessimistic<T extends object>(entity: T, options: LockOptions): Promise<void>;
     protected buildPopulateWhere<T extends object>(meta: EntityMetadata<T>, joinedProps: PopulateOptions<T>[], options: Pick<FindOptions<any>, 'populateWhere'>): ObjectQuery<T>;
-    protected buildOrderBy<T extends object>(qb: QueryBuilder<T, any, any, any>, meta: EntityMetadata<T>, populate: PopulateOptions<T>[], options: Pick<FindOptions<any>, 'strategy' | 'orderBy' | 'populateOrderBy'>): QueryOrderMap<T>[];
-    protected buildPopulateOrderBy<T extends object>(qb: QueryBuilder<T, any, any, any>, meta: EntityMetadata<T>, populateOrderBy: QueryOrderMap<T>[], parentPath: string, explicit: boolean, parentAlias?: string): QueryOrderMap<T>[];
-    protected buildJoinedPropsOrderBy<T extends object>(qb: QueryBuilder<T, any, any, any>, meta: EntityMetadata<T>, populate: PopulateOptions<T>[], options?: Pick<FindOptions<any>, 'strategy' | 'orderBy' | 'populateOrderBy'>, parentPath?: string): QueryOrderMap<T>[];
+    /**
+     * Builds a UNION ALL (or UNION) subquery from `unionWhere` branches and merges it
+     * into the main WHERE as `pk IN (branch_1 UNION ALL branch_2 ...)`.
+     * Each branch is planned independently by the database, enabling per-table index usage.
+     */
+    protected applyUnionWhere<T extends object>(meta: EntityMetadata<T>, where: ObjectQuery<T>, options: FindOptions<T, any, any, any> | CountOptions<T> | NativeInsertUpdateOptions<T> | DeleteOptions<T>, forDml?: boolean): Promise<ObjectQuery<T>>;
+    protected buildOrderBy<T extends object>(qb: AnyQueryBuilder<T>, meta: EntityMetadata<T>, populate: PopulateOptions<T>[], options: Pick<FindOptions<any>, 'strategy' | 'orderBy' | 'populateOrderBy'>): QueryOrderMap<T>[];
+    protected buildPopulateOrderBy<T extends object>(qb: AnyQueryBuilder<T>, meta: EntityMetadata<T>, populateOrderBy: QueryOrderMap<T>[], parentPath: string, explicit: boolean, parentAlias?: string): QueryOrderMap<T>[];
+    protected buildJoinedPropsOrderBy<T extends object>(qb: AnyQueryBuilder<T>, meta: EntityMetadata<T>, populate: PopulateOptions<T>[], options?: Pick<FindOptions<any>, 'strategy' | 'orderBy' | 'populateOrderBy'>, parentPath?: string): QueryOrderMap<T>[];
     private buildToManyOrderBy;
     protected normalizeFields<T extends object>(fields: InternalField<T>[], prefix?: string): string[];
     protected processField<T extends object>(meta: EntityMetadata<T>, prop: EntityProperty<T> | undefined, field: string, ret: InternalField<T>[]): void;
-    protected buildFields<T extends object>(meta: EntityMetadata<T>, populate: PopulateOptions<T>[], joinedProps: PopulateOptions<T>[], qb: QueryBuilder<T, any, any, any>, alias: string, options: Pick<FindOptions<T, any, any, any>, 'strategy' | 'fields' | 'exclude'>, schema?: string): InternalField<T>[];
+    protected buildFields<T extends object>(meta: EntityMetadata<T>, populate: PopulateOptions<T>[], joinedProps: PopulateOptions<T>[], qb: AnyQueryBuilder<T>, alias: string, options: Pick<FindOptions<T, any, any, any>, 'strategy' | 'fields' | 'exclude'>, schema?: string): InternalField<T>[];
 }
 interface FieldsForJoinedLoadOptions<T extends object> {
     explicitFields?: readonly InternalField<T>[];

package/AbstractSqlDriver.js

@@ -37,7 +37,7 @@ export class AbstractSqlDriver extends DatabaseDriver {
             throw new Error('Collation option for SQL drivers must be a string (collation name). Use a CollationOptions object only with MongoDB.');
         }
         if (options.indexHint != null && typeof options.indexHint !== 'string') {
-            throw new Error('indexHint for SQL drivers must be a string (e.g. \'force index(my_index)\'). Use an object only with MongoDB.');
+            throw new Error("indexHint for SQL drivers must be a string (e.g. 'force index(my_index)'). Use an object only with MongoDB.");
         }
     }
     createEntityManager(useContext) {
@@ -95,6 +95,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
         if (meta.virtual) {
             return this.findVirtual(entityName, where, options);
         }
+        if (options.unionWhere?.length) {
+            where = await this.applyUnionWhere(meta, where, options);
+        }
         const qb = await this.createQueryBuilderFromOptions(meta, where, options);
         const result = await this.rethrow(qb.execute('all'));
         if (options.last && !options.first) {
@@ -297,7 +300,10 @@ export class AbstractSqlDriver extends DatabaseDriver {
             }
             // Polymorphic to-one: iterate targets, find the matching one, build entity from its columns.
             // Skip :ref hints — no JOINs were created, so the FK reference is already set by the result mapper.
-            if (prop.polymorphic && prop.polymorphTargets?.length && !ref && [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind)) {
+            if (prop.polymorphic &&
+                prop.polymorphTargets?.length &&
+                !ref &&
+                [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind)) {
                 const basePath = parentJoinPath ? `${parentJoinPath}.${prop.name}` : `${meta.name}.${prop.name}`;
                 const pathPrefix = !parentJoinPath ? '[populate]' : '';
                 let matched = false;
@@ -306,16 +312,22 @@ export class AbstractSqlDriver extends DatabaseDriver {
                     const relationAlias = qb.getAliasForJoinPath(targetPath, { matchPopulateJoins: true });
                     const meta2 = targetMeta;
                     const targetProps = meta2.props.filter(p => this.platform.shouldHaveColumn(p, hint.children || []));
-                    const hasPK = meta2.getPrimaryProps().every(pk => pk.fieldNames.every(name => root[`${relationAlias}__${name}`] != null));
+                    const hasPK = meta2
+                        .getPrimaryProps()
+                        .every(pk => pk.fieldNames.every(name => root[`${relationAlias}__${name}`] != null));
                     if (hasPK && !matched) {
                         matched = true;
-                        let relationPojo = {};
+                        const relationPojo = {};
                         const tz = this.platform.getTimezone();
                         for (const p of targetProps) {
                             this.mapJoinedProp(relationPojo, p, relationAlias, root, tz, meta2);
                         }
                         // Inject the entity class constructor so that the factory creates the correct type
-                        Object.defineProperty(relationPojo, 'constructor', { value: meta2.class, enumerable: false, configurable: true });
+                        Object.defineProperty(relationPojo, 'constructor', {
+                            value: meta2.class,
+                            enumerable: false,
+                            configurable: true,
+                        });
                         result[prop.name] = relationPojo;
                         const populateChildren = hint.children || [];
                         this.mapJoinedProps(relationPojo, meta2, populateChildren, qb, root, map, targetPath);
@@ -366,7 +378,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
                 return;
             }
             const mapToPk = !hint.dataOnly && !!(ref || prop.mapToPk);
-            const targetProps = mapToPk ? meta2.getPrimaryProps() : meta2.props.filter(prop => this.platform.shouldHaveColumn(prop, hint.children || []));
+            const targetProps = mapToPk
+                ? meta2.getPrimaryProps()
+                : meta2.props.filter(prop => this.platform.shouldHaveColumn(prop, hint.children || []));
             // If the primary key value for the relation is null, we know we haven't joined to anything
             // and therefore we don't return any record (since all values would be null)
             const hasPK = meta2.getPrimaryProps().every(pk => pk.fieldNames.every(name => {
@@ -459,7 +473,12 @@ export class AbstractSqlDriver extends DatabaseDriver {
         else if (prop.runtimeType === 'Date') {
             const alias = `${relationAlias}__${prop.fieldNames[0]}`;
             const value = root[alias];
-            if (tz && tz !== 'local' && typeof value === 'string' && !value.includes('+') && value.lastIndexOf('-') < 11 && !value.endsWith('Z')) {
+            if (tz &&
+                tz !== 'local' &&
+                typeof value === 'string' &&
+                !value.includes('+') &&
+                value.lastIndexOf('-') < 11 &&
+                !value.endsWith('Z')) {
                 relationPojo[prop.name] = this.platform.parseDate(value + tz);
             }
             else if (['string', 'number'].includes(typeof value)) {
@@ -475,10 +494,11 @@ export class AbstractSqlDriver extends DatabaseDriver {
             if (prop.kind === ReferenceKind.EMBEDDED && (prop.object || meta.embeddable)) {
                 const item = parseJsonSafe(relationPojo[prop.name]);
                 if (Array.isArray(item)) {
-                    relationPojo[prop.name] = item.map(row => (row == null ? row : this.comparator.mapResult(prop.targetMeta, row)));
+                    relationPojo[prop.name] = item.map(row => row == null ? row : this.comparator.mapResult(prop.targetMeta, row));
                 }
                 else {
-                    relationPojo[prop.name] = item == null ? item : this.comparator.mapResult(prop.targetMeta, item);
+                    relationPojo[prop.name] =
+                        item == null ? item : this.comparator.mapResult(prop.targetMeta, item);
                 }
             }
         }
@@ -493,6 +513,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
         if (meta.virtual) {
             return this.countVirtual(entityName, where, options);
         }
+        if (options.unionWhere?.length) {
+            where = await this.applyUnionWhere(meta, where, options);
+        }
         options = { populate: [], ...options };
         const populate = options.populate;
         const joinedProps = this.joinedProps(meta, populate, options);
@@ -557,13 +580,19 @@ export class AbstractSqlDriver extends DatabaseDriver {
         }
         const tableName = this.getTableName(meta, options);
         let sql = `insert into ${tableName} `;
-        sql += fields.length > 0 ? '(' + fields.map(k => this.platform.quoteIdentifier(k)).join(', ') + ')' : `(${this.platform.quoteIdentifier(pks[0])})`;
+        sql +=
+            fields.length > 0
+                ? '(' + fields.map(k => this.platform.quoteIdentifier(k)).join(', ') + ')'
+                : `(${this.platform.quoteIdentifier(pks[0])})`;
         if (this.platform.usesOutputStatement()) {
             const returningProps = this.getTableProps(meta)
                 .filter(prop => (prop.persist !== false && prop.defaultRaw) || prop.autoincrement || prop.generated)
                 .filter(prop => !(prop.name in data[0]) || isRaw(data[0][prop.name]));
             const returningFields = Utils.flatten(returningProps.map(prop => prop.fieldNames));
-            sql += returningFields.length > 0 ? ` output ${returningFields.map(field => 'inserted.' + this.platform.quoteIdentifier(field)).join(', ')}` : '';
+            sql +=
+                returningFields.length > 0
+                    ? ` output ${returningFields.map(field => 'inserted.' + this.platform.quoteIdentifier(field)).join(', ')}`
+                    : '';
         }
         if (fields.length > 0 || this.platform.usesDefaultKeyword()) {
             sql += ' values ';
@@ -650,7 +679,11 @@ export class AbstractSqlDriver extends DatabaseDriver {
                     else {
                         const field = prop.fieldNames[0];
                         if (!duplicates.includes(field) || !usedDups.includes(field)) {
-                            if (prop.customType && !prop.object && 'convertToDatabaseValueSQL' in prop.customType && row[prop.name] != null && !isRaw(row[prop.name])) {
+                            if (prop.customType &&
+                                !prop.object &&
+                                'convertToDatabaseValueSQL' in prop.customType &&
+                                row[prop.name] != null &&
+                                !isRaw(row[prop.name])) {
                                 keys.push(prop.customType.convertToDatabaseValueSQL('?', this.platform));
                             }
                             else {
@@ -671,7 +704,10 @@ export class AbstractSqlDriver extends DatabaseDriver {
                 .filter(prop => !(prop.name in data[0]) || isRaw(data[0][prop.name]));
             const returningFields = Utils.flatten(returningProps.map(prop => prop.fieldNames));
             /* v8 ignore next */
-            sql += returningFields.length > 0 ? ` returning ${returningFields.map(field => this.platform.quoteIdentifier(field)).join(', ')}` : '';
+            sql +=
+                returningFields.length > 0
+                    ? ` returning ${returningFields.map(field => this.platform.quoteIdentifier(field)).join(', ')}`
+                    : '';
         }
         if (transform) {
             sql = transform(sql);
@@ -704,11 +740,15 @@ export class AbstractSqlDriver extends DatabaseDriver {
             /* v8 ignore next */
             where = { [meta.primaryKeys[0] ?? pks[0]]: where };
         }
+        if (!options.upsert && options.unionWhere?.length) {
+            where = (await this.applyUnionWhere(meta, where, options, true));
+        }
         if (Utils.hasObjectKeys(data)) {
             const qb = this.createQueryBuilder(entityName, options.ctx, 'write', options.convertCustomTypes, options.loggerContext).withSchema(this.getSchemaName(meta, options));
             if (options.upsert) {
                 /* v8 ignore next */
-                const uniqueFields = options.onConflictFields ?? (Utils.isPlainObject(where) ? Utils.keys(where) : meta.primaryKeys);
+                const uniqueFields = options.onConflictFields ??
+                    (Utils.isPlainObject(where) ? Utils.keys(where) : meta.primaryKeys);
                 const returning = getOnConflictReturningFields(meta, data, uniqueFields, options);
                 qb.insert(data)
                     .onConflict(uniqueFields)
@@ -728,7 +768,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
                 qb.update(data).where(where);
                 // reload generated columns and version fields
                 const returning = [];
-                meta.props.filter(prop => (prop.generated && !prop.primary) || prop.version).forEach(prop => returning.push(prop.name));
+                meta.props
+                    .filter(prop => (prop.generated && !prop.primary) || prop.version)
+                    .forEach(prop => returning.push(prop.name));
                 qb.returning(returning);
             }
             res = await this.rethrow(qb.execute('run', false));
@@ -744,7 +786,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
         const meta = this.metadata.get(entityName);
         if (options.upsert) {
             const uniqueFields = options.onConflictFields ??
-                (Utils.isPlainObject(where[0]) ? Object.keys(where[0]).flatMap(key => Utils.splitPrimaryKeys(key)) : meta.primaryKeys);
+                (Utils.isPlainObject(where[0])
+                    ? Object.keys(where[0]).flatMap(key => Utils.splitPrimaryKeys(key))
+                    : meta.primaryKeys);
             const qb = this.createQueryBuilder(entityName, options.ctx, 'write', options.convertCustomTypes, options.loggerContext).withSchema(this.getSchemaName(meta, options));
             const returning = getOnConflictReturningFields(meta, data[0], uniqueFields, options);
             qb.insert(data)
@@ -815,7 +859,11 @@ export class AbstractSqlDriver extends DatabaseDriver {
                     if (key in data[idx]) {
                         const pks = Utils.getOrderedPrimaryKeys(cond, meta);
                         sql += ` when (${pkCond}) then `;
-                        if (prop.customType && !prop.object && 'convertToDatabaseValueSQL' in prop.customType && data[idx][prop.name] != null && !isRaw(data[idx][key])) {
+                        if (prop.customType &&
+                            !prop.object &&
+                            'convertToDatabaseValueSQL' in prop.customType &&
+                            data[idx][prop.name] != null &&
+                            !isRaw(data[idx][key])) {
                             sql += prop.customType.convertToDatabaseValueSQL('?', this.platform);
                         }
                         else {
@@ -844,7 +892,10 @@ export class AbstractSqlDriver extends DatabaseDriver {
         sql = sql.substring(0, sql.length - 2) + ' where ';
         const pkProps = meta.primaryKeys.concat(...meta.concurrencyCheckKeys);
         const pks = Utils.flatten(pkProps.map(pk => meta.properties[pk].fieldNames));
-        sql += pks.length > 1 ? `(${pks.map(pk => `${this.platform.quoteIdentifier(pk)}`).join(', ')})` : this.platform.quoteIdentifier(pks[0]);
+        sql +=
+            pks.length > 1
+                ? `(${pks.map(pk => `${this.platform.quoteIdentifier(pk)}`).join(', ')})`
+                : this.platform.quoteIdentifier(pks[0]);
         const conds = where.map(cond => {
             if (Utils.isPlainObject(cond) && Utils.getObjectKeysSize(cond) === 1) {
                 cond = Object.values(cond)[0];
@@ -867,7 +918,10 @@ export class AbstractSqlDriver extends DatabaseDriver {
         if (this.platform.usesReturningStatement() && returning.size > 0) {
             const returningFields = Utils.flatten([...returning].map(prop => meta.properties[prop].fieldNames));
             /* v8 ignore next */
-            sql += returningFields.length > 0 ? ` returning ${returningFields.map(field => this.platform.quoteIdentifier(field)).join(', ')}` : '';
+            sql +=
+                returningFields.length > 0
+                    ? ` returning ${returningFields.map(field => this.platform.quoteIdentifier(field)).join(', ')}`
+                    : '';
         }
         const res = await this.rethrow(this.execute(sql, params, 'run', options.ctx, options.loggerContext));
         for (let i = 0; i < collections.length; i++) {
@@ -881,6 +935,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
         if (Utils.isPrimaryKey(where) && pks.length === 1) {
             where = { [pks[0]]: where };
         }
+        if (options.unionWhere?.length) {
+            where = await this.applyUnionWhere(meta, where, options, true);
+        }
         const qb = this.createQueryBuilder(entityName, options.ctx, 'write', false, options.loggerContext)
             .delete(where)
             .withSchema(this.getSchemaName(meta, options));
@@ -935,7 +992,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
                 const qb = this.createQueryBuilder(coll.property.targetMeta.class, options?.ctx, 'write').withSchema(this.getSchemaName(meta, options));
                 if (coll.getSnapshot() === undefined) {
                     if (coll.property.orphanRemoval) {
-                        const query = qb.delete({ [coll.property.mappedBy]: pks }).andWhere({ [cols.join(Utils.PK_SEPARATOR)]: { $nin: insertDiff } });
+                        const query = qb
+                            .delete({ [coll.property.mappedBy]: pks })
+                            .andWhere({ [cols.join(Utils.PK_SEPARATOR)]: { $nin: insertDiff } });
                         await this.rethrow(query.execute());
                         continue;
                     }
@@ -947,7 +1006,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
                     continue;
                 }
                 /* v8 ignore next */
-                const query = qb.update({ [coll.property.mappedBy]: pks }).where({ [cols.join(Utils.PK_SEPARATOR)]: { $in: insertDiff } });
+                const query = qb
+                    .update({ [coll.property.mappedBy]: pks })
+                    .where({ [cols.join(Utils.PK_SEPARATOR)]: { $in: insertDiff } });
                 await this.rethrow(query.execute());
                 continue;
             }
@@ -960,7 +1021,10 @@ export class AbstractSqlDriver extends DatabaseDriver {
                 else {
                     const targetMeta = coll.property.targetMeta;
                     const targetSchema = (coll[0] ?? snap?.[0]) && helper(coll[0] ?? snap?.[0]).getSchema();
-                    schema = targetMeta.schema === '*' ? (options?.schema ?? targetSchema ?? this.config.get('schema')) : targetMeta.schema;
+                    schema =
+                        targetMeta.schema === '*'
+                            ? (options?.schema ?? targetSchema ?? this.config.get('schema'))
+                            : targetMeta.schema;
                 }
             }
             else if (schema == null) {
@@ -997,7 +1061,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
         const populate = this.autoJoinOneToOneOwner(prop.targetMeta, options?.populate ?? [], options?.fields);
         const childFields = !Utils.isEmpty(options?.fields) ? options.fields.map(f => `${pivotProp1.name}.${f}`) : [];
         const childExclude = !Utils.isEmpty(options?.exclude) ? options.exclude.map(f => `${pivotProp1.name}.${f}`) : [];
-        const fields = pivotJoin ? [pivotProp1.name, pivotProp2.name] : [pivotProp1.name, pivotProp2.name, ...childFields];
+        const fields = pivotJoin
+            ? [pivotProp1.name, pivotProp2.name]
+            : [pivotProp1.name, pivotProp2.name, ...childFields];
         const res = await this.find(pivotMeta.class, where, {
             ctx,
             ...options,
@@ -1050,7 +1116,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
         const populateField = pivotJoin ? `${inverseProp.name}:ref` : inverseProp.name;
         const populate = this.autoJoinOneToOneOwner(targetMeta, options?.populate ?? [], options?.fields);
         const childFields = !Utils.isEmpty(options?.fields) ? options.fields.map(f => `${inverseProp.name}.${f}`) : [];
-        const childExclude = !Utils.isEmpty(options?.exclude) ? options.exclude.map(f => `${inverseProp.name}.${f}`) : [];
+        const childExclude = !Utils.isEmpty(options?.exclude)
+            ? options.exclude.map(f => `${inverseProp.name}.${f}`)
+            : [];
         const fields = pivotJoin
             ? [inverseProp.name, prop.discriminator, prop.discriminatorColumn]
             : [inverseProp.name, prop.discriminator, prop.discriminatorColumn, ...childFields];
@@ -1060,7 +1128,15 @@ export class AbstractSqlDriver extends DatabaseDriver {
             fields,
             exclude: childExclude,
             orderBy: this.getPivotOrderBy(prop, inverseProp, orderBy, options?.orderBy),
-            populate: [{ field: populateField, strategy: LoadStrategy.JOINED, joinType: JoinType.innerJoin, children: populate, dataOnly: inverseProp.mapToPk && !pivotJoin }],
+            populate: [
+                {
+                    field: populateField,
+                    strategy: LoadStrategy.JOINED,
+                    joinType: JoinType.innerJoin,
+                    children: populate,
+                    dataOnly: inverseProp.mapToPk && !pivotJoin,
+                },
+            ],
             populateWhere: undefined,
             // @ts-ignore
             _populateWhere: 'infer',
@@ -1092,7 +1168,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
         const populateField = ownerRelationName;
         const populate = this.autoJoinOneToOneOwner(targetMeta, options?.populate ?? [], options?.fields);
         const childFields = !Utils.isEmpty(options?.fields) ? options.fields.map(f => `${ownerRelationName}.${f}`) : [];
-        const childExclude = !Utils.isEmpty(options?.exclude) ? options.exclude.map(f => `${ownerRelationName}.${f}`) : [];
+        const childExclude = !Utils.isEmpty(options?.exclude)
+            ? options.exclude.map(f => `${ownerRelationName}.${f}`)
+            : [];
         const fields = [ownerRelationName, tagProp.name, prop.discriminatorColumn, ...childFields];
         const res = await this.find(pivotMeta.class, cond, {
             ctx,
@@ -1100,7 +1178,14 @@ export class AbstractSqlDriver extends DatabaseDriver {
             fields,
             exclude: childExclude,
             orderBy: this.getPivotOrderBy(prop, ownerProp, orderBy, options?.orderBy),
-            populate: [{ field: populateField, strategy: LoadStrategy.JOINED, joinType: JoinType.innerJoin, children: populate }],
+            populate: [
+                {
+                    field: populateField,
+                    strategy: LoadStrategy.JOINED,
+                    joinType: JoinType.innerJoin,
+                    children: populate,
+                },
+            ],
             populateWhere: undefined,
             // @ts-ignore
             _populateWhere: 'infer',
@@ -1179,7 +1264,10 @@ export class AbstractSqlDriver extends DatabaseDriver {
         }
         const relationsToPopulate = populate.map(({ field }) => field.split(':')[0]);
         const toPopulate = meta.relations
-            .filter(prop => prop.kind === ReferenceKind.ONE_TO_ONE && !prop.owner && !prop.lazy && !relationsToPopulate.includes(prop.name))
+            .filter(prop => prop.kind === ReferenceKind.ONE_TO_ONE &&
+            !prop.owner &&
+            !prop.lazy &&
+            !relationsToPopulate.includes(prop.name))
             .filter(prop => fields.length === 0 || fields.some(f => prop.name === f || prop.name.startsWith(`${String(f)}.`)))
             .map(prop => ({ field: `${prop.name}:ref`, strategy: LoadStrategy.JOINED }));
         return [...populate, ...toPopulate];
@@ -1295,8 +1383,13 @@ export class AbstractSqlDriver extends DatabaseDriver {
             const prop = meta.properties[propName];
             // Polymorphic to-one: create a LEFT JOIN per target type
             // Skip :ref hints — polymorphic to-one already has FK + discriminator in the row
-            if (prop.polymorphic && prop.polymorphTargets?.length && !ref && [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind)) {
-                const basePath = options.parentJoinPath ? `${options.parentJoinPath}.${prop.name}` : `${meta.name}.${prop.name}`;
+            if (prop.polymorphic &&
+                prop.polymorphTargets?.length &&
+                !ref &&
+                [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind)) {
+                const basePath = options.parentJoinPath
+                    ? `${options.parentJoinPath}.${prop.name}`
+                    : `${meta.name}.${prop.name}`;
                 const pathPrefix = !options.parentJoinPath && populateWhereAll && !basePath.startsWith('[populate]') ? '[populate]' : '';
                 for (const targetMeta of prop.polymorphTargets) {
                     const tableAlias = qb.getNextAlias(targetMeta.className);
@@ -1314,7 +1407,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
                 continue;
             }
             // ignore ref joins of known FKs unless it's a filter hint
-            if (ref && !hint.filter && (prop.kind === ReferenceKind.MANY_TO_ONE || (prop.kind === ReferenceKind.ONE_TO_ONE && prop.owner))) {
+            if (ref &&
+                !hint.filter &&
+                (prop.kind === ReferenceKind.MANY_TO_ONE || (prop.kind === ReferenceKind.ONE_TO_ONE && prop.owner))) {
                 continue;
             }
             const meta2 = prop.targetMeta;
@@ -1360,7 +1455,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
                     childExplicitFields.push(f.substring(prop.name.length + 1));
                 }
             });
-            const childExclude = options.exclude ? Utils.extractChildElements(options.exclude, prop.name) : options.exclude;
+            const childExclude = options.exclude
+                ? Utils.extractChildElements(options.exclude, prop.name)
+                : options.exclude;
             if (!ref && (!prop.mapToPk || hint.dataOnly)) {
                 fields.push(...this.getFieldsForJoinedLoad(qb, meta2, {
                     ...options,
@@ -1371,7 +1468,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
                     parentJoinPath: path,
                 }));
             }
-            else if (hint.filter || (prop.mapToPk && !hint.dataOnly) || (ref && [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind))) {
+            else if (hint.filter ||
+                (prop.mapToPk && !hint.dataOnly) ||
+                (ref && [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind))) {
                 fields.push(...prop.referencedColumnNames.map(col => qb.helper.mapper(`${tableAlias}.${col}`, qb.type, undefined, `${tableAlias}__${col}`)));
             }
         }
@@ -1473,7 +1572,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
             if (childAlias) {
                 // Map fields using same filtering as joined loading, plus skip PKs
                 for (const prop of currentMeta.ownProps.filter(p => !p.primary && this.platform.shouldHaveColumn(p, []))) {
-                    this.mapJoinedProp(relationPojo, prop, childAlias, root, tz, currentMeta, { deleteFromRoot: true });
+                    this.mapJoinedProp(relationPojo, prop, childAlias, root, tz, currentMeta, {
+                        deleteFromRoot: true,
+                    });
                 }
             }
             currentMeta = currentMeta.tptParent;
@@ -1522,7 +1623,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
     /** @internal */
     createQueryBuilder(entityName, ctx, preferredConnectionType, convertCustomTypes, loggerContext, alias, em) {
         // do not compute the connectionType if EM is provided as it will be computed from it in the QB later on
-        const connectionType = em ? preferredConnectionType : this.resolveConnectionType({ ctx, connectionType: preferredConnectionType });
+        const connectionType = em
+            ? preferredConnectionType
+            : this.resolveConnectionType({ ctx, connectionType: preferredConnectionType });
         const qb = new QueryBuilder(entityName, this.metadata, this, ctx, alias, connectionType, em, loggerContext);
         if (!convertCustomTypes) {
             qb.unsetFlag(QueryFlag.CONVERT_CUSTOM_TYPES);
@@ -1598,6 +1701,47 @@ export class AbstractSqlDriver extends DatabaseDriver {
         /* v8 ignore next */
         return { $and: [options.populateWhere, where] };
     }
+    /**
+     * Builds a UNION ALL (or UNION) subquery from `unionWhere` branches and merges it
+     * into the main WHERE as `pk IN (branch_1 UNION ALL branch_2 ...)`.
+     * Each branch is planned independently by the database, enabling per-table index usage.
+     */
+    async applyUnionWhere(meta, where, options, forDml = false) {
+        const unionWhere = options.unionWhere;
+        const strategy = options.unionWhereStrategy ?? 'union-all';
+        const schema = this.getSchemaName(meta, options);
+        const connectionType = this.resolveConnectionType({
+            ctx: options.ctx,
+            connectionType: options.connectionType,
+        });
+        const branchQbs = [];
+        for (const branch of unionWhere) {
+            const qb = this.createQueryBuilder(meta.class, options.ctx, connectionType, false, options.logging).withSchema(schema);
+            const pkFields = meta.primaryKeys.map(pk => {
+                const prop = meta.properties[pk];
+                return `${qb.alias}.${prop.fieldNames[0]}`;
+            });
+            qb.select(pkFields).where(branch);
+            if (options.em) {
+                await qb.applyJoinedFilters(options.em, options.filters);
+            }
+            branchQbs.push(qb);
+        }
+        const [first, ...rest] = branchQbs;
+        const unionQb = strategy === 'union' ? first.union(...rest) : first.unionAll(...rest);
+        const pkHash = Utils.getPrimaryKeyHash(meta.primaryKeys);
+        // MySQL does not allow referencing the target table in a subquery
+        // for UPDATE/DELETE, so we wrap the union in a derived table.
+        if (forDml) {
+            const { sql, params } = unionQb.toQuery();
+            return {
+                $and: [where, { [pkHash]: { $in: raw(`select * from (${sql}) as __u`, params) } }],
+            };
+        }
+        return {
+            $and: [where, { [pkHash]: { $in: unionQb.toRaw() } }],
+        };
+    }
     buildOrderBy(qb, meta, populate, options) {
         const joinedProps = this.joinedProps(meta, populate, options);
         // `options._populateWhere` is a copy of the value provided by user with a fallback to the global config option
@@ -1628,7 +1772,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
                 let path = parentPath;
                 const meta2 = prop.targetMeta;
                 if (prop.kind !== ReferenceKind.SCALAR &&
-                    (![ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind) || !prop.owner || Utils.isPlainObject(childOrder))) {
+                    (![ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind) ||
+                        !prop.owner ||
+                        Utils.isPlainObject(childOrder))) {
                     path += `.${field}`;
                 }
                 if (prop.kind === ReferenceKind.MANY_TO_MANY && typeof childOrder !== 'object') {
@@ -1639,7 +1785,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
                 if (!join) {
                     continue;
                 }
-                if (join && ![ReferenceKind.SCALAR, ReferenceKind.EMBEDDED].includes(prop.kind) && typeof childOrder === 'object') {
+                if (join &&
+                    ![ReferenceKind.SCALAR, ReferenceKind.EMBEDDED].includes(prop.kind) &&
+                    typeof childOrder === 'object') {
                     const children = this.buildPopulateOrderBy(qb, meta2, Utils.asArray(childOrder), path, explicit, propAlias);
                     orderBy.push(...children);
                     continue;
@@ -1770,7 +1918,8 @@ export class AbstractSqlDriver extends DatabaseDriver {
             if (!options.fields.includes('*') && !options.fields.includes(`${qb.alias}.*`)) {
                 ret.unshift(...meta.primaryKeys.filter(pk => !options.fields.includes(pk)));
             }
-            if (meta.root.inheritanceType === 'sti' && !options.fields.includes(`${qb.alias}.${meta.root.discriminatorColumn}`)) {
+            if (meta.root.inheritanceType === 'sti' &&
+                !options.fields.includes(`${qb.alias}.${meta.root.discriminatorColumn}`)) {
                 ret.push(meta.root.discriminatorColumn);
             }
         }

package/AbstractSqlPlatform.d.ts

@@ -27,6 +27,7 @@ export declare abstract class AbstractSqlPlatform extends Platform {
     getSearchJsonPropertySQL(path: string, type: string, aliased: boolean): string | RawQueryFragment;
     getSearchJsonPropertyKey(path: string[], type: string, aliased: boolean, value?: unknown): string | RawQueryFragment;
     getJsonIndexDefinition(index: IndexDef): string[];
+    supportsUnionWhere(): boolean;
     supportsSchemas(): boolean;
     /** @inheritDoc */
     generateCustomOrder(escapedColumn: string, values: unknown[]): string;

package/AbstractSqlPlatform.js

@@ -64,15 +64,14 @@ export class AbstractSqlPlatform extends Platform {
     }
     getSearchJsonPropertyKey(path, type, aliased, value) {
         const [a, ...b] = path;
-        const quoteKey = (key) => key.match(/^[a-z]\w*$/i) ? key : `"${key}"`;
+        const quoteKey = (key) => (key.match(/^[a-z]\w*$/i) ? key : `"${key}"`);
         if (aliased) {
             return raw(alias => `json_extract(${this.quoteIdentifier(`${alias}.${a}`)}, '$.${b.map(quoteKey).join('.')}')`);
         }
         return raw(`json_extract(${this.quoteIdentifier(a)}, '$.${b.map(quoteKey).join('.')}')`);
     }
     getJsonIndexDefinition(index) {
-        return index.columnNames
-            .map(column => {
+        return index.columnNames.map(column => {
             if (!column.includes('.')) {
                 return column;
             }
@@ -80,6 +79,9 @@ export class AbstractSqlPlatform extends Platform {
             return `(json_extract(${root}, '$.${path.join('.')}'))`;
         });
     }
+    supportsUnionWhere() {
+        return true;
+    }
     supportsSchemas() {
         return false;
     }