@mikro-orm/sql 7.0.0-dev.99 → 7.0.0-rc.1

package/query/QueryBuilder.js

@@ -1,8 +1,10 @@
-import { helper, isRaw, LoadStrategy, LockMode, PopulateHint, QueryFlag, QueryHelper, raw, RawQueryFragment, Reference, ReferenceKind, serialize, Utils, ValidationError, inspect, } from '@mikro-orm/core';
+import { helper, inspect, isRaw, LoadStrategy, LockMode, PopulateHint, QueryFlag, QueryHelper, raw, RawQueryFragment, Reference, ReferenceKind, serialize, Utils, ValidationError, } from '@mikro-orm/core';
 import { JoinType, QueryType } from './enums.js';
 import { QueryBuilderHelper } from './QueryBuilderHelper.js';
 import { CriteriaNodeFactory } from './CriteriaNodeFactory.js';
 import { NativeQueryBuilder } from './NativeQueryBuilder.js';
+/** Matches 'path as alias' — safe because ORM property names are JS identifiers (no spaces). */
+const FIELD_ALIAS_RE = /^(.+?)\s+as\s+(\w+)$/i;
 /**
  * SQL query builder with fluent interface.
  *
@@ -47,8 +49,6 @@ export class QueryBuilder {
     _populate = [];
     /** @internal */
     _populateMap = {};
-    /** @internal */
-    rawFragments = new Set();
     aliasCounter = 0;
     flags = new Set([QueryFlag.CONVERT_CUSTOM_TYPES]);
     finalized = false;
@@ -69,6 +69,7 @@ export class QueryBuilder {
     _joinedProps = new Map();
     _cache;
     _indexHint;
+    _collation;
     _comments = [];
     _hintComments = [];
     flushMode;
@@ -77,9 +78,12 @@ export class QueryBuilder {
     subQueries = {};
     _mainAlias;
     _aliases = {};
+    _tptAlias = {}; // maps entity className to alias for TPT parent tables
     _helper;
     _query;
     platform;
+    tptJoinsApplied = false;
+    autoJoinedPaths = [];
     /**
      * @internal
      */
@@ -100,12 +104,31 @@ export class QueryBuilder {
     }
     select(fields, distinct = false) {
         this.ensureNotFinalized();
-        this._fields = Utils.asArray(fields);
+        this._fields = Utils.asArray(fields).flatMap(f => {
+            if (typeof f !== 'string') {
+                // Normalize sql.ref('prop') and sql.ref('prop').as('alias') to string form
+                if (isRaw(f) && f.sql === '??' && f.params.length === 1) {
+                    return this.resolveNestedPath(String(f.params[0]));
+                }
+                if (isRaw(f) && f.sql === '?? as ??' && f.params.length === 2) {
+                    return `${this.resolveNestedPath(String(f.params[0]))} as ${String(f.params[1])}`;
+                }
+                return f;
+            }
+            const asMatch = f.match(FIELD_ALIAS_RE);
+            if (asMatch) {
+                return `${this.resolveNestedPath(asMatch[1].trim())} as ${asMatch[2]}`;
+            }
+            return this.resolveNestedPath(f);
+        });
         if (distinct) {
             this.flags.add(QueryFlag.DISTINCT);
         }
         return this.init(QueryType.SELECT);
     }
+    /**
+     * Adds fields to an existing SELECT query.
+     */
     addSelect(fields) {
         this.ensureNotFinalized();
         if (this._type && this._type !== QueryType.SELECT) {
@@ -117,30 +140,87 @@ export class QueryBuilder {
         this.ensureNotFinalized();
         return this.setFlag(QueryFlag.DISTINCT);
     }
-    /** postgres only */
     distinctOn(fields) {
         this.ensureNotFinalized();
         this._distinctOn = Utils.asArray(fields);
         return this;
     }
+    /**
+     * Creates an INSERT query with the given data.
+     *
+     * @example
+     * ```ts
+     * await em.createQueryBuilder(User)
+     *   .insert({ name: 'John', email: 'john@example.com' })
+     *   .execute();
+     *
+     * // Bulk insert
+     * await em.createQueryBuilder(User)
+     *   .insert([{ name: 'John' }, { name: 'Jane' }])
+     *   .execute();
+     * ```
+     */
     insert(data) {
         return this.init(QueryType.INSERT, data);
     }
+    /**
+     * Creates an UPDATE query with the given data.
+     * Use `where()` to specify which rows to update.
+     *
+     * @example
+     * ```ts
+     * await em.createQueryBuilder(User)
+     *   .update({ name: 'John Doe' })
+     *   .where({ id: 1 })
+     *   .execute();
+     * ```
+     */
     update(data) {
         return this.init(QueryType.UPDATE, data);
     }
+    /**
+     * Creates a DELETE query.
+     * Use `where()` to specify which rows to delete.
+     *
+     * @example
+     * ```ts
+     * await em.createQueryBuilder(User)
+     *   .delete()
+     *   .where({ id: 1 })
+     *   .execute();
+     *
+     * // Or pass the condition directly
+     * await em.createQueryBuilder(User)
+     *   .delete({ isActive: false })
+     *   .execute();
+     * ```
+     */
     delete(cond) {
         return this.init(QueryType.DELETE, undefined, cond);
     }
+    /**
+     * Creates a TRUNCATE query to remove all rows from the table.
+     */
     truncate() {
         return this.init(QueryType.TRUNCATE);
     }
+    /**
+     * Creates a COUNT query to count matching rows.
+     *
+     * @example
+     * ```ts
+     * const count = await em.createQueryBuilder(User)
+     *   .count()
+     *   .where({ isActive: true })
+     *   .execute('get');
+     * ```
+     */
     count(field, distinct = false) {
         if (field) {
             this._fields = Utils.asArray(field);
         }
         else if (distinct || this.hasToManyJoins()) {
-            this._fields = this.mainAlias.metadata.primaryKeys;
+            this._fields = this.mainAlias.meta.primaryKeys;
         }
         else {
             this._fields = [raw('*')];
@@ -158,16 +238,27 @@ export class QueryBuilder {
         this.join(field, alias, cond, JoinType.innerJoin, undefined, schema);
         return this;
     }
-    innerJoinLateral(field, alias, cond, schema) {
-        this.join(field, alias, cond, JoinType.innerJoinLateral, undefined, schema);
-        return this;
+    innerJoinLateral(field, alias, cond = {}, schema) {
+        return this.join(field, alias, cond, JoinType.innerJoinLateral, undefined, schema);
     }
     leftJoin(field, alias, cond = {}, schema) {
         return this.join(field, alias, cond, JoinType.leftJoin, undefined, schema);
     }
-    leftJoinLateral(field, alias, cond, schema) {
+    leftJoinLateral(field, alias, cond = {}, schema) {
         return this.join(field, alias, cond, JoinType.leftJoinLateral, undefined, schema);
     }
+    /**
+     * Adds a JOIN clause and automatically selects the joined entity's fields.
+     * This is useful for eager loading related entities.
+     *
+     * @example
+     * ```ts
+     * const qb = em.createQueryBuilder(Book, 'b');
+     * qb.select('*')
+     *   .joinAndSelect('b.author', 'a')
+     *   .where({ 'a.name': 'John' });
+     * ```
+     */
     joinAndSelect(field, alias, cond = {}, type = JoinType.innerJoin, path, fields, schema) {
         if (!this._type) {
             this.select('*');
@@ -199,18 +290,22 @@ export class QueryBuilder {
         return this.joinAndSelect(field, alias, cond, JoinType.leftJoin, undefined, fields, schema);
     }
     leftJoinLateralAndSelect(field, alias, cond = {}, fields, schema) {
-        return this.joinAndSelect(field, alias, cond, JoinType.leftJoinLateral, undefined, fields, schema);
+        this.joinAndSelect(field, alias, cond, JoinType.leftJoinLateral, undefined, fields, schema);
+        return this;
     }
     innerJoinAndSelect(field, alias, cond = {}, fields, schema) {
         return this.joinAndSelect(field, alias, cond, JoinType.innerJoin, undefined, fields, schema);
     }
     innerJoinLateralAndSelect(field, alias, cond = {}, fields, schema) {
-        return this.joinAndSelect(field, alias, cond, JoinType.innerJoinLateral, undefined, fields, schema);
+        this.joinAndSelect(field, alias, cond, JoinType.innerJoinLateral, undefined, fields, schema);
+        return this;
     }
     getFieldsForJoinedLoad(prop, alias, explicitFields) {
         const fields = [];
         const populate = [];
         const joinKey = Object.keys(this._joins).find(join => join.endsWith(`#${alias}`));
+        const targetMeta = prop.targetMeta;
+        const schema = this._schema ?? (targetMeta.schema !== '*' ? targetMeta.schema : undefined);
         if (joinKey) {
             const path = this._joins[joinKey].path.split('.').slice(1);
             let children = this._populate;
@@ -223,29 +318,29 @@ export class QueryBuilder {
             }
             populate.push(...children);
         }
-        for (const p of prop.targetMeta.getPrimaryProps()) {
-            fields.push(...this.driver.mapPropToFieldNames(this, p, alias));
+        for (const p of targetMeta.getPrimaryProps()) {
+            fields.push(...this.driver.mapPropToFieldNames(this, p, alias, targetMeta, schema));
         }
-        if (explicitFields) {
+        if (explicitFields && explicitFields.length > 0) {
             for (const field of explicitFields) {
                 const [a, f] = this.helper.splitField(field);
-                const p = prop.targetMeta.properties[f];
+                const p = targetMeta.properties[f];
                 if (p) {
-                    fields.push(...this.driver.mapPropToFieldNames(this, p, alias));
+                    fields.push(...this.driver.mapPropToFieldNames(this, p, alias, targetMeta, schema));
                 }
                 else {
                     fields.push(`${a}.${f} as ${a}__${f}`);
                 }
             }
         }
-        prop.targetMeta.props
+        targetMeta.props
             .filter(prop => {
-            if (!explicitFields) {
+            if (!explicitFields || explicitFields.length === 0) {
                 return this.platform.shouldHaveColumn(prop, populate);
             }
             return prop.primary && !explicitFields.includes(prop.name) && !explicitFields.includes(`${alias}.${prop.name}`);
         })
-            .forEach(prop => fields.push(...this.driver.mapPropToFieldNames(this, prop, alias)));
+            .forEach(prop => fields.push(...this.driver.mapPropToFieldNames(this, prop, alias, targetMeta, schema)));
         return fields;
     }
     /**
@@ -259,7 +354,6 @@ export class QueryBuilder {
         const cond = await this.em.applyFilters(this.mainAlias.entityName, {}, filterOptions, 'read');
         this.andWhere(cond);
     }
-    autoJoinedPaths = [];
     /**
      * @internal
      */
@@ -276,15 +370,23 @@ export class QueryBuilder {
                 continue;
             }
             filterOptions = QueryHelper.mergePropertyFilters(join.prop.filters, filterOptions);
-            const cond = await em.applyFilters(join.prop.type, join.cond, filterOptions, 'read');
-            if (Utils.hasObjectKeys(cond)) {
+            let cond = await em.applyFilters(join.prop.targetMeta.class, join.cond, filterOptions, 'read');
+            const criteriaNode = CriteriaNodeFactory.createNode(this.metadata, join.prop.targetMeta.class, cond);
+            cond = criteriaNode.process(this, {
+                matchPopulateJoins: true,
+                filter: true,
+                alias: join.alias,
+                ignoreBranching: true,
+                parentPath: join.path,
+            });
+            if (Utils.hasObjectKeys(cond) || RawQueryFragment.hasObjectFragments(cond)) {
                 // remove nested filters, we only care about scalars here, nesting would require another join branch
                 for (const key of Object.keys(cond)) {
-                    if (Utils.isPlainObject(cond[key]) && Object.keys(cond[key]).every(k => !(Utils.isOperator(k) && !['$some', '$none', '$every'].includes(k)))) {
+                    if (Utils.isPlainObject(cond[key]) && Object.keys(cond[key]).every(k => !(Utils.isOperator(k) && !['$some', '$none', '$every', '$size'].includes(k)))) {
                         delete cond[key];
                     }
                 }
-                if (Utils.hasObjectKeys(join.cond)) {
+                if (Utils.hasObjectKeys(join.cond) || RawQueryFragment.hasObjectFragments(join.cond)) {
                     /* v8 ignore next */
                     join.cond = { $and: [join.cond, cond] };
                 }
@@ -296,7 +398,7 @@ export class QueryBuilder {
     }
     withSubQuery(subQuery, alias) {
         this.ensureNotFinalized();
-        if (subQuery instanceof RawQueryFragment) {
+        if (isRaw(subQuery)) {
             this.subQueries[alias] = this.platform.formatQuery(subQuery.sql, subQuery.params);
         }
         else {
@@ -306,18 +408,18 @@ export class QueryBuilder {
     }
     where(cond, params, operator) {
         this.ensureNotFinalized();
-        const rawField = RawQueryFragment.getKnownFragment(cond);
-        if (rawField) {
-            const sql = this.platform.formatQuery(rawField.sql, rawField.params);
-            cond = { [raw(`(${sql})`)]: Utils.asArray(params) };
+        let processedCond;
+        if (isRaw(cond)) {
+            const sql = this.platform.formatQuery(cond.sql, cond.params);
+            processedCond = { [raw(`(${sql})`)]: Utils.asArray(params) };
             operator ??= '$and';
         }
         else if (typeof cond === 'string') {
-            cond = { [raw(`(${cond})`, Utils.asArray(params))]: [] };
+            processedCond = { [raw(`(${cond})`, Utils.asArray(params))]: [] };
             operator ??= '$and';
         }
         else {
-            cond = QueryHelper.processWhere({
+            processedCond = QueryHelper.processWhere({
                 where: cond,
                 entityName: this.mainAlias.entityName,
                 metadata: this.metadata,
@@ -328,13 +430,13 @@ export class QueryBuilder {
             });
         }
         const op = operator || params;
-        const topLevel = !op || !Utils.hasObjectKeys(this._cond);
-        const criteriaNode = CriteriaNodeFactory.createNode(this.metadata, this.mainAlias.entityName, cond);
+        const topLevel = !op || !(Utils.hasObjectKeys(this._cond) || RawQueryFragment.hasObjectFragments(this._cond));
+        const criteriaNode = CriteriaNodeFactory.createNode(this.metadata, this.mainAlias.entityName, processedCond);
         const ignoreBranching = this.__populateWhere === 'infer';
         if ([QueryType.UPDATE, QueryType.DELETE].includes(this.type) && criteriaNode.willAutoJoin(this, undefined, { ignoreBranching })) {
             // use sub-query to support joining
             this.setFlag(this.type === QueryType.UPDATE ? QueryFlag.UPDATE_SUB_QUERY : QueryFlag.DELETE_SUB_QUERY);
-            this.select(this.mainAlias.metadata.primaryKeys, true);
+            this.select(this.mainAlias.meta.primaryKeys, true);
         }
         if (topLevel) {
             this._cond = criteriaNode.process(this, { ignoreBranching });
@@ -369,7 +471,19 @@ export class QueryBuilder {
         if (reset) {
             this._orderBy = [];
         }
-        Utils.asArray(orderBy).forEach(o => {
+        const selectAliases = this.getSelectAliases();
+        Utils.asArray(orderBy).forEach(orig => {
+            // Shallow clone to avoid mutating the caller's object — safe because the clone
+            // is only used within this loop iteration and `orig` is not referenced afterward.
+            const o = { ...orig };
+            // Wrap known select aliases in raw() so they bypass property validation and alias prefixing
+            for (const key of Object.keys(o)) {
+                if (selectAliases.has(key)) {
+                    o[raw('??', [key])] = o[key];
+                    delete o[key];
+                }
+            }
+            this.helper.validateQueryOrder(o);
             const processed = QueryHelper.processWhere({
                 where: o,
                 entityName: this.mainAlias.entityName,
@@ -380,26 +494,61 @@ export class QueryBuilder {
                 convertCustomTypes: false,
                 type: 'orderBy',
             });
-            this._orderBy.push(CriteriaNodeFactory.createNode(this.metadata, this.mainAlias.entityName, processed).process(this, { matchPopulateJoins: true, type: 'orderBy' }));
+            this._orderBy.push(CriteriaNodeFactory.createNode(this.metadata, this.mainAlias.entityName, processed).process(this, {
+                matchPopulateJoins: true,
+                type: 'orderBy',
+            }));
         });
         return this;
     }
+    /** Collect custom aliases from select fields (stored as 'resolved as alias' strings by select()). */
+    getSelectAliases() {
+        const aliases = new Set();
+        for (const field of this._fields ?? []) {
+            if (typeof field === 'string') {
+                const m = field.match(FIELD_ALIAS_RE);
+                if (m) {
+                    aliases.add(m[2]);
+                }
+            }
+        }
+        return aliases;
+    }
     groupBy(fields) {
         this.ensureNotFinalized();
-        this._groupBy = Utils.asArray(fields);
+        this._groupBy = Utils.asArray(fields).flatMap(f => {
+            if (typeof f !== 'string') {
+                // Normalize sql.ref('prop') to string for proper formula resolution
+                if (isRaw(f) && f.sql === '??' && f.params.length === 1) {
+                    return this.resolveNestedPath(String(f.params[0]));
+                }
+                return f;
+            }
+            return this.resolveNestedPath(f);
+        });
         return this;
     }
+    /**
+     * Adds a HAVING clause to the query, typically used with GROUP BY.
+     *
+     * @example
+     * ```ts
+     * qb.select([raw('count(*) as count'), 'status'])
+     *   .groupBy('status')
+     *   .having({ count: { $gt: 5 } });
+     * ```
+     */
     having(cond = {}, params, operator) {
         this.ensureNotFinalized();
         if (typeof cond === 'string') {
             cond = { [raw(`(${cond})`, params)]: [] };
         }
-        cond = CriteriaNodeFactory.createNode(this.metadata, this.mainAlias.entityName, cond).process(this);
+        const processed = CriteriaNodeFactory.createNode(this.metadata, this.mainAlias.entityName, cond, undefined, undefined, false).process(this, { type: 'having' });
         if (!this._having || !operator) {
-            this._having = cond;
+            this._having = processed;
         }
         else {
-            const cond1 = [this._having, cond];
+            const cond1 = [this._having, processed];
             this._having = { [operator]: cond1 };
         }
         return this;
@@ -411,7 +560,7 @@ export class QueryBuilder {
         return this.having(cond, params, '$or');
     }
     onConflict(fields = []) {
-        const meta = this.mainAlias.metadata;
+        const meta = this.mainAlias.meta;
         this.ensureNotFinalized();
         this._onConflict ??= [];
         this._onConflict.push({
@@ -456,6 +605,15 @@ export class QueryBuilder {
         this._populateFilter = populateFilter;
         return this;
     }
+    /**
+     * Sets a LIMIT clause to restrict the number of results.
+     *
+     * @example
+     * ```ts
+     * qb.select('*').limit(10);        // First 10 results
+     * qb.select('*').limit(10, 20);    // 10 results starting from offset 20
+     * ```
+     */
     limit(limit, offset = 0) {
         this.ensureNotFinalized();
         this._limit = limit;
@@ -464,6 +622,14 @@ export class QueryBuilder {
         }
         return this;
     }
+    /**
+     * Sets an OFFSET clause to skip a number of results.
+     *
+     * @example
+     * ```ts
+     * qb.select('*').limit(10).offset(20);  // Results 21-30
+     * ```
+     */
     offset(offset) {
         this.ensureNotFinalized();
         this._offset = offset;
@@ -514,6 +680,14 @@ export class QueryBuilder {
         this._indexHint = sql;
         return this;
     }
+    /**
+     * Adds COLLATE clause to ORDER BY expressions.
+     */
+    collation(collation) {
+        this.ensureNotFinalized();
+        this._collation = collation;
+        return this;
+    }
     /**
      * Prepend comment to the sql query using the syntax `/* ... *‍/`. Some characters are forbidden such as `/*, *‍/` and `?`.
      */
@@ -538,11 +712,10 @@ export class QueryBuilder {
             this.fromSubQuery(target, aliasName);
         }
         else {
-            const entityName = Utils.className(target);
-            if (aliasName && this._mainAlias && entityName !== this._mainAlias.aliasName) {
+            if (aliasName && this._mainAlias && Utils.className(target) !== this._mainAlias.aliasName) {
                 throw new Error(`Cannot override the alias to '${aliasName}' since a query already contains references to '${this._mainAlias.aliasName}'`);
             }
-            this.fromEntityName(entityName, aliasName);
+            this.fromEntityName(target, aliasName);
         }
         return this;
     }
@@ -553,17 +726,19 @@ export class QueryBuilder {
         this._query = {};
         this.finalize();
         const qb = this.getQueryBase(processVirtualEntity);
+        const schema = this.getSchema(this.mainAlias);
+        const isNotEmptyObject = (obj) => Utils.hasObjectKeys(obj) || RawQueryFragment.hasObjectFragments(obj);
         Utils.runIfNotEmpty(() => this.helper.appendQueryCondition(this.type, this._cond, qb), this._cond && !this._onConflict);
-        Utils.runIfNotEmpty(() => qb.groupBy(this.prepareFields(this._groupBy, 'groupBy')), this._groupBy);
-        Utils.runIfNotEmpty(() => this.helper.appendQueryCondition(this.type, this._having, qb, undefined, 'having'), this._having);
+        Utils.runIfNotEmpty(() => qb.groupBy(this.prepareFields(this._groupBy, 'groupBy', schema)), isNotEmptyObject(this._groupBy));
+        Utils.runIfNotEmpty(() => this.helper.appendQueryCondition(this.type, this._having, qb, undefined, 'having'), isNotEmptyObject(this._having));
         Utils.runIfNotEmpty(() => {
-            const queryOrder = this.helper.getQueryOrder(this.type, this._orderBy, this._populateMap);
+            const queryOrder = this.helper.getQueryOrder(this.type, this._orderBy, this._populateMap, this._collation);
             if (queryOrder.length > 0) {
                 const sql = Utils.unique(queryOrder).join(', ');
                 qb.orderBy(sql);
                 return;
             }
-        }, this._orderBy);
+        }, isNotEmptyObject(this._orderBy));
         Utils.runIfNotEmpty(() => qb.limit(this._limit), this._limit != null);
         Utils.runIfNotEmpty(() => qb.offset(this._offset), this._offset);
         Utils.runIfNotEmpty(() => qb.comment(this._comments), this._comments);
@@ -572,17 +747,9 @@ export class QueryBuilder {
         if (this.lockMode) {
             this.helper.getLockSQL(qb, this.lockMode, this.lockTables, this._joins);
         }
-        this.helper.finalize(this.type, qb, this.mainAlias.metadata, this._data, this._returning);
-        this.clearRawFragmentsCache();
+        this.helper.finalize(this.type, qb, this.mainAlias.meta, this._data, this._returning);
         return this._query.qb = qb;
     }
-    /**
-     * @internal
-     */
-    clearRawFragmentsCache() {
-        this.rawFragments.forEach(key => RawQueryFragment.remove(key));
-        this.rawFragments.clear();
-    }
     /**
      * Returns the query with parameters as wildcards.
      */
@@ -622,7 +789,7 @@ export class QueryBuilder {
      * @internal
      */
     getAliasForJoinPath(path, options) {
-        if (!path || path === this.mainAlias.entityName) {
+        if (!path || path === Utils.className(this.mainAlias.entityName)) {
             return this.mainAlias.aliasName;
         }
         const join = typeof path === 'string' ? this.getJoinForPath(path, options) : path;
@@ -666,8 +833,24 @@ export class QueryBuilder {
      * @internal
      */
     getNextAlias(entityName = 'e') {
+        entityName = Utils.className(entityName);
         return this.driver.config.getNamingStrategy().aliasName(entityName, this.aliasCounter++);
     }
+    /**
+     * Registers a join for a specific polymorphic target type.
+     * Used by the driver to create per-target LEFT JOINs for JOINED loading.
+     * @internal
+     */
+    addPolymorphicJoin(prop, targetMeta, ownerAlias, alias, type, path, schema) {
+        // Override referencedColumnNames to use the specific target's PK columns
+        // (polymorphic targets may have different PK column names, e.g. org_id vs user_id)
+        const referencedColumnNames = targetMeta.getPrimaryProps().flatMap(pk => pk.fieldNames);
+        const targetProp = { ...prop, targetMeta, referencedColumnNames };
+        const aliasedName = `${ownerAlias}.${prop.name}[${targetMeta.className}]#${alias}`;
+        this._joins[aliasedName] = this.helper.joinManyToOneReference(targetProp, ownerAlias, alias, type, {}, schema);
+        this._joins[aliasedName].path = path;
+        this.createAlias(targetMeta.class, alias);
+    }
     /**
      * @internal
      */
@@ -697,7 +880,7 @@ export class QueryBuilder {
         }
         const loggerContext = { id: this.em?.id, ...this.loggerContext };
         const res = await this.getConnection().execute(query.sql, query.params, method, this.context, loggerContext);
-        const meta = this.mainAlias.metadata;
+        const meta = this.mainAlias.meta;
         if (!options.mapResults || !meta) {
             await this.em?.storeCache(this._cache, cached, res);
             return res;
@@ -711,7 +894,7 @@ export class QueryBuilder {
             const map = {};
             mapped = res.map(r => this.driver.mapResult(r, meta, this._populate, this, map));
             if (options.mergeResults && joinedProps.length > 0) {
-                mapped = this.driver.mergeJoinedResult(mapped, this.mainAlias.metadata, joinedProps);
+                mapped = this.driver.mergeJoinedResult(mapped, this.mainAlias.meta, joinedProps);
             }
         }
         else {
@@ -752,7 +935,7 @@ export class QueryBuilder {
         const query = this.toQuery();
         const loggerContext = { id: this.em?.id, ...this.loggerContext };
         const res = this.getConnection().stream(query.sql, query.params, this.context, loggerContext);
-        const meta = this.mainAlias.metadata;
+        const meta = this.mainAlias.meta;
         if (options.rawResults || !meta) {
             yield* res;
             return;
@@ -769,7 +952,7 @@ export class QueryBuilder {
                 continue;
             }
             if (stack.length > 0 && hash(stack[stack.length - 1]) !== hash(mapped)) {
-                const res = this.driver.mergeJoinedResult(stack, this.mainAlias.metadata, joinedProps);
+                const res = this.driver.mergeJoinedResult(stack, this.mainAlias.meta, joinedProps);
                 for (const row of res) {
                     yield this.mapResult(row, options.mapResults);
                 }
@@ -778,7 +961,7 @@ export class QueryBuilder {
             stack.push(mapped);
         }
         if (stack.length > 0) {
-            const merged = this.driver.mergeJoinedResult(stack, this.mainAlias.metadata, joinedProps);
+            const merged = this.driver.mergeJoinedResult(stack, this.mainAlias.meta, joinedProps);
             yield this.mapResult(merged[0], options.mapResults);
         }
     }
@@ -840,16 +1023,13 @@ export class QueryBuilder {
         const [res] = await this.getResultList(1);
         return res || null;
     }
-    /**
-     * Executes count query (without offset and limit), returning total count of results
-     */
     async getCount(field, distinct) {
         let res;
         if (this.type === QueryType.COUNT) {
             res = await this.execute('get', false);
         }
         else {
-            const qb = this._type === undefined ? this : this.clone();
+            const qb = (this._type === undefined ? this : this.clone());
             qb.processPopulateHint(); // needs to happen sooner so `qb.hasToManyJoins()` reports correctly
             qb.count(field, distinct ?? qb.hasToManyJoins()).limit(undefined).offset(undefined).orderBy([]);
             res = await qb.execute('get', false);
@@ -860,50 +1040,42 @@ export class QueryBuilder {
      * Executes the query, returning both array of results and total count query (without offset and limit).
      */
     async getResultAndCount() {
-        return [
-            await this.clone().getResultList(),
-            await this.clone().getCount(),
-        ];
+        return [await this.clone().getResultList(), await this.clone().getCount()];
     }
-    /**
-     * Returns native query builder instance with sub-query aliased with given alias.
-     * You can provide `EntityName.propName` as alias, then the field name will be used based on the metadata
-     */
-    as(alias) {
+    as(aliasOrTargetEntity, alias) {
         const qb = this.getNativeQuery();
-        if (alias.includes('.')) {
-            const [a, f] = alias.split('.');
-            const meta = this.metadata.find(a);
+        let finalAlias = aliasOrTargetEntity;
+        /* v8 ignore next */
+        if (typeof aliasOrTargetEntity === 'string' && aliasOrTargetEntity.includes('.')) {
+            throw new Error('qb.as(alias) no longer supports target entity name prefix, use qb.as(TargetEntity, key) signature instead');
+        }
+        if (alias) {
+            const meta = this.metadata.get(aliasOrTargetEntity);
             /* v8 ignore next */
-            alias = meta?.properties[f]?.fieldNames[0] ?? alias;
+            finalAlias = meta.properties[alias]?.fieldNames[0] ?? alias;
         }
-        qb.as(alias);
+        qb.as(finalAlias);
         // tag the instance, so it is possible to detect it easily
-        Object.defineProperty(qb, '__as', { enumerable: false, value: alias });
+        Object.defineProperty(qb, '__as', { enumerable: false, value: finalAlias });
         return qb;
     }
-    clone(reset) {
+    clone(reset, preserve) {
         const qb = new QueryBuilder(this.mainAlias.entityName, this.metadata, this.driver, this.context, this.mainAlias.aliasName, this.connectionType, this.em);
-        if (reset === true) {
-            return qb;
-        }
         reset = reset || [];
         // clone array/object properties
         const properties = [
             'flags', '_populate', '_populateWhere', '_populateFilter', '__populateWhere', '_populateMap', '_joins', '_joinedProps', '_cond', '_data', '_orderBy',
-            '_schema', '_indexHint', '_cache', 'subQueries', 'lockMode', 'lockTables', '_groupBy', '_having', '_returning',
-            '_comments', '_hintComments', 'rawFragments', 'aliasCounter',
+            '_schema', '_indexHint', '_collation', '_cache', 'subQueries', 'lockMode', 'lockTables', '_groupBy', '_having', '_returning',
+            '_comments', '_hintComments', 'aliasCounter',
         ];
-        RawQueryFragment.cloneRegistry = this.rawFragments;
         for (const prop of Object.keys(this)) {
-            if (reset.includes(prop) || ['_helper', '_query'].includes(prop)) {
+            if (!preserve?.includes(prop) && (reset === true || reset.includes(prop) || ['_helper', '_query'].includes(prop))) {
                 continue;
             }
             qb[prop] = properties.includes(prop) ? Utils.copy(this[prop]) : this[prop];
         }
-        delete RawQueryFragment.cloneRegistry;
         /* v8 ignore next */
-        if (this._fields && !reset.includes('_fields')) {
+        if (this._fields && reset !== true && !reset.includes('_fields')) {
             qb._fields = [...this._fields];
         }
         qb._aliases = { ...this._aliases };
@@ -935,13 +1107,28 @@ export class QueryBuilder {
         if (res instanceof QueryBuilder) {
             return `(${res.getFormattedQuery()}) as ${this.platform.quoteIdentifier(this.alias)}`;
         }
-        if (res instanceof RawQueryFragment) {
+        if (isRaw(res)) {
             const query = this.platform.formatQuery(res.sql, res.params);
             return `(${query}) as ${this.platform.quoteIdentifier(this.alias)}`;
         }
         /* v8 ignore next */
         return res;
     }
+    /**
+     * Adds a join from a property object. Used internally for TPT joins where the property
+     * is synthetic (not in entity.properties) but defined on metadata (e.g., tptParentProp).
+     * The caller must create the alias first via createAlias().
+     * @internal
+     */
+    addPropertyJoin(prop, ownerAlias, alias, type, path, schema) {
+        schema ??= prop.targetMeta?.schema === '*' ? '*' : this.driver.getSchemaName(prop.targetMeta);
+        const key = `[tpt]${ownerAlias}#${alias}`;
+        this._joins[key] = prop.kind === ReferenceKind.MANY_TO_ONE
+            ? this.helper.joinManyToOneReference(prop, ownerAlias, alias, type, {}, schema)
+            : this.helper.joinOneToReference(prop, ownerAlias, alias, type, {}, schema);
+        this._joins[key].path = path;
+        return key;
+    }
     joinReference(field, alias, cond, type, path, schema, subquery) {
         this.ensureNotFinalized();
         if (typeof field === 'object') {
@@ -950,11 +1137,11 @@ export class QueryBuilder {
                 kind: ReferenceKind.MANY_TO_ONE,
             };
             if (field instanceof QueryBuilder) {
-                prop.type = field.mainAlias.entityName;
-                prop.targetMeta = field.mainAlias.metadata;
+                prop.type = Utils.className(field.mainAlias.entityName);
+                prop.targetMeta = field.mainAlias.meta;
                 field = field.getNativeQuery();
             }
-            if (field instanceof RawQueryFragment) {
+            if (isRaw(field)) {
                 field = this.platform.formatQuery(field.sql, field.params);
             }
             const key = `${this.alias}.${prop.name}#${alias}`;
@@ -983,7 +1170,12 @@ export class QueryBuilder {
         if (!prop) {
             throw new Error(`Trying to join ${q(field)}, but ${q(fromField)} is not a defined relation on ${meta.className}.`);
         }
-        this.createAlias(prop.type, alias);
+        // For TPT inheritance, owning relations (M:1 and owning 1:1) may have FK columns in a parent table
+        // Resolve the correct alias for the table that owns the FK column
+        const ownerAlias = (prop.kind === ReferenceKind.MANY_TO_ONE || (prop.kind === ReferenceKind.ONE_TO_ONE && prop.owner))
+            ? this.helper.getTPTAliasForProperty(fromField, fromAlias)
+            : fromAlias;
+        this.createAlias(prop.targetMeta.class, alias);
         cond = QueryHelper.processWhere({
             where: cond,
             entityName: this.mainAlias.entityName,
@@ -992,10 +1184,10 @@ export class QueryBuilder {
             aliasMap: this.getAliasMap(),
             aliased: [QueryType.SELECT, QueryType.COUNT].includes(this.type),
         });
-        const criteriaNode = CriteriaNodeFactory.createNode(this.metadata, prop.targetMeta.className, cond);
+        const criteriaNode = CriteriaNodeFactory.createNode(this.metadata, prop.targetMeta.class, cond);
         cond = criteriaNode.process(this, { ignoreBranching: true, alias });
         let aliasedName = `${fromAlias}.${prop.name}#${alias}`;
-        path ??= `${(Object.values(this._joins).find(j => j.alias === fromAlias)?.path ?? entityName)}.${prop.name}`;
+        path ??= `${(Object.values(this._joins).find(j => j.alias === fromAlias)?.path ?? Utils.className(entityName))}.${prop.name}`;
         if (prop.kind === ReferenceKind.ONE_TO_MANY) {
             this._joins[aliasedName] = this.helper.joinOneToReference(prop, fromAlias, alias, type, cond, schema);
             this._joins[aliasedName].path ??= path;
@@ -1014,29 +1206,33 @@ export class QueryBuilder {
             aliasedName = Object.keys(joins)[1];
         }
         else if (prop.kind === ReferenceKind.ONE_TO_ONE) {
-            this._joins[aliasedName] = this.helper.joinOneToReference(prop, fromAlias, alias, type, cond, schema);
+            this._joins[aliasedName] = this.helper.joinOneToReference(prop, ownerAlias, alias, type, cond, schema);
             this._joins[aliasedName].path ??= path;
         }
         else { // MANY_TO_ONE
-            this._joins[aliasedName] = this.helper.joinManyToOneReference(prop, fromAlias, alias, type, cond, schema);
+            this._joins[aliasedName] = this.helper.joinManyToOneReference(prop, ownerAlias, alias, type, cond, schema);
             this._joins[aliasedName].path ??= path;
         }
         return { prop, key: aliasedName };
     }
-    prepareFields(fields, type = 'where') {
+    prepareFields(fields, type = 'where', schema) {
         const ret = [];
-        const getFieldName = (name) => {
-            return this.helper.mapper(name, this.type, undefined, type === 'groupBy' ? null : undefined);
+        const getFieldName = (name, customAlias) => {
+            const alias = customAlias ?? (type === 'groupBy' ? null : undefined);
+            return this.helper.mapper(name, this.type, undefined, alias, schema);
         };
-        fields.forEach(field => {
-            const rawField = RawQueryFragment.getKnownFragment(field, false);
-            if (rawField) {
-                ret.push(rawField);
+        fields.forEach(originalField => {
+            if (typeof originalField !== 'string') {
+                ret.push(originalField);
                 return;
             }
-            if (typeof field !== 'string') {
-                ret.push(field);
-                return;
+            // Strip 'as alias' suffix if present — the alias is passed to mapper at the end
+            let field = originalField;
+            let customAlias;
+            const asMatch = originalField.match(FIELD_ALIAS_RE);
+            if (asMatch) {
+                field = asMatch[1].trim();
+                customAlias = asMatch[2];
             }
             const join = Object.keys(this._joins).find(k => field === k.substring(0, k.indexOf('#')));
             if (join && type === 'where') {
@@ -1055,10 +1251,13 @@ export class QueryBuilder {
             if (prop?.embedded || (prop?.kind === ReferenceKind.EMBEDDED && prop.object)) {
                 const name = prop.embeddedPath?.join('.') ?? prop.fieldNames[0];
                 const aliased = this._aliases[a] ? `${a}.${name}` : name;
-                ret.push(getFieldName(aliased));
+                ret.push(getFieldName(aliased, customAlias));
                 return;
             }
             if (prop?.kind === ReferenceKind.EMBEDDED) {
+                if (customAlias) {
+                    throw new Error(`Cannot use 'as ${customAlias}' alias on embedded property '${field}' because it expands to multiple columns. Alias individual fields instead (e.g. '${field}.propertyName as ${customAlias}').`);
+                }
                 const nest = (prop) => {
                     for (const childProp of Object.values(prop.embeddedProps)) {
                         if (childProp.fieldNames && (childProp.kind !== ReferenceKind.EMBEDDED || childProp.object) && childProp.persist !== false) {
@@ -1072,30 +1271,108 @@ export class QueryBuilder {
                 nest(prop);
                 return;
             }
-            if (prop && prop.fieldNames.length > 1) {
+            if (prop && prop.fieldNames.length > 1 && !prop.fieldNames.includes(f)) {
+                if (customAlias) {
+                    throw new Error(`Cannot use 'as ${customAlias}' alias on '${field}' because it expands to multiple columns (${prop.fieldNames.join(', ')}).`);
+                }
                 ret.push(...prop.fieldNames.map(f => getFieldName(f)));
                 return;
             }
-            ret.push(getFieldName(field));
+            ret.push(getFieldName(field, customAlias));
         });
-        const meta = this.mainAlias.metadata;
-        /* v8 ignore next */
-        const requiresSQLConversion = meta?.props.filter(p => p.hasConvertToJSValueSQL && p.persist !== false) ?? [];
-        if (this.flags.has(QueryFlag.CONVERT_CUSTOM_TYPES) && (fields.includes('*') || fields.includes(`${this.mainAlias.aliasName}.*`)) && requiresSQLConversion.length > 0) {
+        const requiresSQLConversion = this.mainAlias.meta.props.filter(p => p.hasConvertToJSValueSQL && p.persist !== false);
+        if (this.flags.has(QueryFlag.CONVERT_CUSTOM_TYPES) &&
+            (fields.includes('*') || fields.includes(`${this.mainAlias.aliasName}.*`)) &&
+            requiresSQLConversion.length > 0) {
             for (const p of requiresSQLConversion) {
                 ret.push(this.helper.mapper(p.name, this.type));
             }
         }
         for (const f of Object.keys(this._populateMap)) {
             if (type === 'where' && this._joins[f]) {
-                const cols = this.helper.mapJoinColumns(this.type, this._joins[f]);
-                for (const col of cols) {
-                    ret.push(col);
-                }
+                ret.push(...this.helper.mapJoinColumns(this.type, this._joins[f]));
             }
         }
         return Utils.unique(ret);
     }
+    /**
+     * Resolves nested paths like `a.books.title` to their actual field references.
+     * Auto-joins relations as needed and returns `{alias}.{field}`.
+     * For embeddeds: navigates into flattened embeddeds to return the correct field name.
+     */
+    resolveNestedPath(field) {
+        if (typeof field !== 'string' || !field.includes('.')) {
+            return field;
+        }
+        const parts = field.split('.');
+        // Simple alias.property case - let prepareFields handle it
+        if (parts.length === 2 && this._aliases[parts[0]]) {
+            return field;
+        }
+        // Start with root alias
+        let currentAlias = parts[0];
+        let currentMeta = this._aliases[currentAlias] ? this.metadata.get(this._aliases[currentAlias].entityName) : this.mainAlias.meta;
+        // If first part is not an alias, it's a property of the main entity
+        if (!this._aliases[currentAlias]) {
+            currentAlias = this.mainAlias.aliasName;
+            parts.unshift(currentAlias);
+        }
+        // Walk through the path parts (skip the alias)
+        for (let i = 1; i < parts.length; i++) {
+            const propName = parts[i];
+            const prop = currentMeta.properties[propName];
+            if (!prop) {
+                return field; // Unknown property, return as-is for raw SQL support
+            }
+            const isLastPart = i === parts.length - 1;
+            // Handle embedded properties - navigate into flattened embeddeds
+            if (prop.kind === ReferenceKind.EMBEDDED) {
+                if (prop.object) {
+                    return `${currentAlias}.${propName}`;
+                }
+                // Navigate through remaining path to find the leaf property
+                const remainingPath = parts.slice(i + 1);
+                let embeddedProp = prop;
+                for (const part of remainingPath) {
+                    embeddedProp = embeddedProp?.embeddedProps?.[part];
+                    if (embeddedProp?.object && embeddedProp.fieldNames?.[0]) {
+                        return `${currentAlias}.${embeddedProp.fieldNames[0]}`;
+                    }
+                }
+                return `${currentAlias}.${embeddedProp?.fieldNames?.[0] ?? propName}`;
+            }
+            // Handle relations - auto-join if not the last part
+            if (prop.kind === ReferenceKind.MANY_TO_ONE ||
+                prop.kind === ReferenceKind.ONE_TO_ONE ||
+                prop.kind === ReferenceKind.ONE_TO_MANY ||
+                prop.kind === ReferenceKind.MANY_TO_MANY) {
+                if (isLastPart) {
+                    return `${currentAlias}.${propName}`;
+                }
+                // Find existing join or create new one
+                const joinPath = parts.slice(0, i + 1).join('.');
+                const existingJoinKey = Object.keys(this._joins).find(k => {
+                    const join = this._joins[k];
+                    // Check by path or by key prefix (key format is `alias.field#joinAlias`)
+                    return join.path === joinPath || k.startsWith(`${currentAlias}.${propName}#`);
+                });
+                let joinAlias;
+                if (existingJoinKey) {
+                    joinAlias = this._joins[existingJoinKey].alias;
+                }
+                else {
+                    joinAlias = this.getNextAlias(prop.targetMeta?.className ?? propName);
+                    this.join(`${currentAlias}.${propName}`, joinAlias, {}, JoinType.leftJoin);
+                }
+                currentAlias = joinAlias;
+                currentMeta = prop.targetMeta;
+                continue;
+            }
+            // Scalar property - return it (if not last part, it's an invalid path but let SQL handle it)
+            return `${currentAlias}.${propName}`;
+        }
+        return field;
+    }
     init(type, data, cond) {
         this.ensureNotFinalized();
         this._type = type;
@@ -1118,14 +1395,14 @@ export class QueryBuilder {
     }
     getQueryBase(processVirtualEntity) {
         const qb = this.platform.createNativeQueryBuilder().setFlags(this.flags);
-        const { subQuery, aliasName, entityName, metadata } = this.mainAlias;
+        const { subQuery, aliasName, entityName, meta } = this.mainAlias;
         const requiresAlias = this.finalized && (this._explicitAlias || this.helper.isTableNameAliasRequired(this.type));
         const alias = requiresAlias ? aliasName : undefined;
         const schema = this.getSchema(this.mainAlias);
         const tableName = subQuery ? subQuery.as(aliasName) : this.helper.getTableName(entityName);
         const joinSchema = this._schema ?? this.em?.schema ?? schema;
-        if (metadata?.virtual && processVirtualEntity) {
-            qb.from(raw(this.fromVirtual(metadata)), { indexHint: this._indexHint });
+        if (meta.virtual && processVirtualEntity) {
+            qb.from(raw(this.fromVirtual(meta)), { indexHint: this._indexHint });
         }
         else {
             qb.from(tableName, {
@@ -1136,9 +1413,9 @@ export class QueryBuilder {
         }
         switch (this.type) {
             case QueryType.SELECT:
-                qb.select(this.prepareFields(this._fields));
+                qb.select(this.prepareFields(this._fields, 'where', schema));
                 if (this._distinctOn) {
-                    qb.distinctOn(this.prepareFields(this._distinctOn));
+                    qb.distinctOn(this.prepareFields(this._distinctOn, 'where', schema));
                 }
                 else if (this.flags.has(QueryFlag.DISTINCT)) {
                     qb.distinct();
@@ -1146,7 +1423,7 @@ export class QueryBuilder {
                 this.helper.processJoins(qb, this._joins, joinSchema);
                 break;
             case QueryType.COUNT: {
-                const fields = this._fields.map(f => this.helper.mapper(f, this.type));
+                const fields = this._fields.map(f => this.helper.mapper(f, this.type, undefined, undefined, schema));
                 qb.count(fields, this.flags.has(QueryFlag.DISTINCT));
                 this.helper.processJoins(qb, this._joins, joinSchema);
                 break;
@@ -1169,23 +1446,111 @@ export class QueryBuilder {
         return qb;
     }
     applyDiscriminatorCondition() {
-        const meta = this.mainAlias.metadata;
-        if (!meta?.discriminatorValue) {
+        const meta = this.mainAlias.meta;
+        if (meta.root.inheritanceType !== 'sti' || !meta.discriminatorValue) {
             return;
         }
-        const types = Object.values(meta.root.discriminatorMap).map(cls => this.metadata.find(cls));
+        const types = Object.values(meta.root.discriminatorMap).map(cls => this.metadata.get(cls));
         const children = [];
         const lookUpChildren = (ret, type) => {
             const children = types.filter(meta2 => meta2.extends === type);
-            children.forEach(m => lookUpChildren(ret, m.className));
+            children.forEach(m => lookUpChildren(ret, m.class));
             ret.push(...children.filter(c => c.discriminatorValue));
             return children;
         };
-        lookUpChildren(children, meta.className);
+        lookUpChildren(children, meta.class);
         this.andWhere({
             [meta.root.discriminatorColumn]: children.length > 0 ? { $in: [meta.discriminatorValue, ...children.map(c => c.discriminatorValue)] } : meta.discriminatorValue,
         });
     }
+    /**
+     * Ensures TPT joins are applied. Can be called early before finalize() to populate
+     * the _tptAlias map for use in join resolution. Safe to call multiple times.
+     * @internal
+     */
+    ensureTPTJoins() {
+        this.applyTPTJoins();
+    }
+    /**
+     * For TPT (Table-Per-Type) inheritance: INNER JOINs parent tables.
+     * When querying a child entity, we need to join all parent tables.
+     * Field selection is handled separately in addTPTParentFields().
+     */
+    applyTPTJoins() {
+        const meta = this.mainAlias.meta;
+        if (meta?.inheritanceType !== 'tpt' || !meta.tptParent || ![QueryType.SELECT, QueryType.COUNT].includes(this.type)) {
+            return;
+        }
+        if (this.tptJoinsApplied) {
+            return;
+        }
+        this.tptJoinsApplied = true;
+        let childMeta = meta;
+        let childAlias = this.mainAlias.aliasName;
+        while (childMeta.tptParent) {
+            const parentMeta = childMeta.tptParent;
+            const parentAlias = this.getNextAlias(parentMeta.className);
+            this.createAlias(parentMeta.class, parentAlias);
+            this._tptAlias[parentMeta.className] = parentAlias;
+            this.addPropertyJoin(childMeta.tptParentProp, childAlias, parentAlias, JoinType.innerJoin, `[tpt]${childMeta.className}`);
+            childMeta = parentMeta;
+            childAlias = parentAlias;
+        }
+    }
+    /**
+     * For TPT inheritance: adds field selections from parent tables.
+     */
+    addTPTParentFields() {
+        const meta = this.mainAlias.meta;
+        if (meta?.inheritanceType !== 'tpt' || !meta.tptParent || ![QueryType.SELECT, QueryType.COUNT].includes(this.type)) {
+            return;
+        }
+        if (!this._fields?.includes('*') && !this._fields?.includes(`${this.mainAlias.aliasName}.*`)) {
+            return;
+        }
+        let parentMeta = meta.tptParent;
+        while (parentMeta) {
+            const parentAlias = this._tptAlias[parentMeta.className];
+            if (parentAlias) {
+                const schema = parentMeta.schema === '*' ? '*' : this.driver.getSchemaName(parentMeta);
+                parentMeta.ownProps
+                    .filter(prop => this.platform.shouldHaveColumn(prop, []))
+                    .forEach(prop => this._fields.push(...this.driver.mapPropToFieldNames(this, prop, parentAlias, parentMeta, schema)));
+            }
+            parentMeta = parentMeta.tptParent;
+        }
+    }
+    /**
+     * For TPT polymorphic queries: LEFT JOINs all child tables when querying a TPT base class.
+     * Adds discriminator and child fields to determine and load the concrete type.
+     */
+    applyTPTPolymorphicJoins() {
+        const meta = this.mainAlias.meta;
+        const descendants = meta?.allTPTDescendants;
+        if (!descendants?.length || ![QueryType.SELECT, QueryType.COUNT].includes(this.type)) {
+            return;
+        }
+        if (!this._fields?.includes('*') && !this._fields?.includes(`${this.mainAlias.aliasName}.*`)) {
+            return;
+        }
+        // LEFT JOIN each descendant table and add their fields
+        for (const childMeta of descendants) {
+            const childAlias = this.getNextAlias(childMeta.className);
+            this.createAlias(childMeta.class, childAlias);
+            this._tptAlias[childMeta.className] = childAlias;
+            this.addPropertyJoin(childMeta.tptInverseProp, this.mainAlias.aliasName, childAlias, JoinType.leftJoin, `[tpt]${meta.className}`);
+            // Add child fields
+            const schema = childMeta.schema === '*' ? '*' : this.driver.getSchemaName(childMeta);
+            childMeta.ownProps
+                .filter(prop => !prop.primary && this.platform.shouldHaveColumn(prop, []))
+                .forEach(prop => this._fields.push(...this.driver.mapPropToFieldNames(this, prop, childAlias, childMeta, schema)));
+        }
+        // Add computed discriminator (CASE WHEN to determine concrete type)
+        // descendants is pre-sorted by depth (deepest first) during discovery
+        if (meta.tptDiscriminatorColumn) {
+            this._fields.push(this.driver.buildTPTDiscriminatorExpression(meta, descendants, this._tptAlias, this.mainAlias.aliasName));
+        }
+    }
     finalize() {
         if (this.finalized) {
             return;
@@ -1193,20 +1558,28 @@ export class QueryBuilder {
         if (!this._type) {
             this.select('*');
         }
-        const meta = this.mainAlias.metadata;
+        const meta = this.mainAlias.meta;
         this.applyDiscriminatorCondition();
+        this.applyTPTJoins();
+        this.addTPTParentFields();
+        this.applyTPTPolymorphicJoins();
         this.processPopulateHint();
         this.processNestedJoins();
         if (meta && (this._fields?.includes('*') || this._fields?.includes(`${this.mainAlias.aliasName}.*`))) {
+            const schema = this.getSchema(this.mainAlias);
+            // Create a column mapping with unquoted aliases - quoting should be handled by the user via `quote` helper
+            // For TPT, use helper to resolve correct alias per property (inherited props use parent alias)
+            const quotedMainAlias = this.platform.quoteIdentifier(this.mainAlias.aliasName).toString();
+            const columns = meta.createColumnMappingObject(prop => this.helper.getTPTAliasForProperty(prop.name, this.mainAlias.aliasName), quotedMainAlias);
             meta.props
                 .filter(prop => prop.formula && (!prop.lazy || this.flags.has(QueryFlag.INCLUDE_LAZY_FORMULAS)))
                 .map(prop => {
-                const alias = this.platform.quoteIdentifier(this.mainAlias.aliasName);
                 const aliased = this.platform.quoteIdentifier(prop.fieldNames[0]);
-                return `${prop.formula(alias)} as ${aliased}`;
+                const table = this.helper.createFormulaTable(quotedMainAlias, meta, schema);
+                return `${this.driver.evaluateFormula(prop.formula, columns, table)} as ${aliased}`;
             })
                 .filter(field => !this._fields.some(f => {
-                if (f instanceof RawQueryFragment) {
+                if (isRaw(f)) {
                     return f.sql === field && f.params.length === 0;
                 }
                 return f === field;
@@ -1220,7 +1593,7 @@ export class QueryBuilder {
         if (!this.flags.has(QueryFlag.DISABLE_PAGINATE) && this._groupBy.length === 0 && this.hasToManyJoins()) {
             this.flags.add(QueryFlag.PAGINATE);
         }
-        if (meta && this.flags.has(QueryFlag.PAGINATE) && !this.flags.has(QueryFlag.DISABLE_PAGINATE) && (this._limit > 0 || this._offset > 0)) {
+        if (meta && !meta.virtual && this.flags.has(QueryFlag.PAGINATE) && !this.flags.has(QueryFlag.DISABLE_PAGINATE) && (this._limit > 0 || this._offset > 0)) {
             this.wrapPaginateSubQuery(meta);
         }
         if (meta && (this.flags.has(QueryFlag.UPDATE_SUB_QUERY) || this.flags.has(QueryFlag.DELETE_SUB_QUERY))) {
@@ -1233,7 +1606,7 @@ export class QueryBuilder {
         if (this.populateHintFinalized) {
             return;
         }
-        const meta = this.mainAlias.metadata;
+        const meta = this.mainAlias.meta;
         if (meta && this.flags.has(QueryFlag.AUTO_JOIN_ONE_TO_ONE_OWNER)) {
             const relationsToPopulate = this._populate.map(({ field }) => field);
             meta.relations
@@ -1251,12 +1624,12 @@ export class QueryBuilder {
             }
             if (meta && this.helper.isOneToOneInverse(fromField)) {
                 const prop = meta.properties[fromField];
-                const alias = this.getNextAlias(prop.pivotEntity ?? prop.type);
+                const alias = this.getNextAlias(prop.pivotEntity ?? prop.targetMeta.class);
                 const aliasedName = `${fromAlias}.${prop.name}#${alias}`;
                 this._joins[aliasedName] = this.helper.joinOneToReference(prop, this.mainAlias.aliasName, alias, JoinType.leftJoin);
                 this._joins[aliasedName].path = `${(Object.values(this._joins).find(j => j.alias === fromAlias)?.path ?? meta.className)}.${prop.name}`;
                 this._populateMap[aliasedName] = this._joins[aliasedName].alias;
-                this.createAlias(prop.type, alias);
+                this.createAlias(prop.targetMeta.class, alias);
             }
         });
         this.processPopulateWhere(false);
@@ -1357,8 +1730,12 @@ export class QueryBuilder {
         });
     }
     wrapPaginateSubQuery(meta) {
-        const pks = this.prepareFields(meta.primaryKeys, 'sub-query');
-        const subQuery = this.clone(['_orderBy', '_fields', 'lockMode', 'lockTableAliases']).select(pks).groupBy(pks).limit(this._limit);
+        const schema = this.getSchema(this.mainAlias);
+        const pks = this.prepareFields(meta.primaryKeys, 'sub-query', schema);
+        const subQuery = this.clone(['_orderBy', '_fields', 'lockMode', 'lockTableAliases'])
+            .select(pks)
+            .groupBy(pks)
+            .limit(this._limit);
         // revert the on conditions added via populateWhere, we want to apply those only once
         for (const join of Object.values(subQuery._joins)) {
             if (join.cond_) {
@@ -1372,11 +1749,10 @@ export class QueryBuilder {
         if (this._orderBy.length > 0) {
             const orderBy = [];
             for (const orderMap of this._orderBy) {
-                for (const [field, direction] of Object.entries(orderMap)) {
-                    if (RawQueryFragment.isKnownFragment(field)) {
-                        const rawField = RawQueryFragment.getKnownFragment(field, false);
-                        this.rawFragments.add(field);
-                        orderBy.push({ [rawField.clone()]: direction });
+                for (const field of Utils.getObjectQueryKeys(orderMap)) {
+                    const direction = orderMap[field];
+                    if (RawQueryFragment.isKnownFragmentSymbol(field)) {
+                        orderBy.push({ [field]: direction });
                         continue;
                     }
                     const [a, f] = this.helper.splitField(field);
@@ -1401,14 +1777,14 @@ export class QueryBuilder {
                     if (typeof field === 'object' && field && '__as' in field) {
                         return field.__as === prop;
                     }
-                    if (field instanceof RawQueryFragment) {
+                    if (isRaw(field)) {
                         // not perfect, but should work most of the time, ideally we should check only the alias (`... as alias`)
                         return field.sql.includes(prop);
                     }
                     return false;
                 });
                 /* v8 ignore next */
-                if (field instanceof RawQueryFragment) {
+                if (isRaw(field)) {
                     innerQuery.select(field);
                 }
                 else if (field instanceof NativeQueryBuilder) {
@@ -1425,28 +1801,67 @@ export class QueryBuilder {
         subSubQuery.select(pks).from(innerQuery);
         this._limit = undefined;
         this._offset = undefined;
-        if (!this._fields.some(f => RawQueryFragment.isKnownFragment(f))) {
-            this.pruneExtraJoins(meta);
-        }
+        // Save the original WHERE conditions before pruning joins
+        const originalCond = this._cond;
+        const populatePaths = this.getPopulatePaths();
+        if (!this._fields.some(field => isRaw(field))) {
+            this.pruneJoinsForPagination(meta, populatePaths);
+        }
+        // Transfer WHERE conditions to ORDER BY joins (GH #6160)
+        this.transferConditionsForOrderByJoins(meta, originalCond, populatePaths);
         const { sql, params } = subSubQuery.compile();
         this.select(this._fields).where({ [Utils.getPrimaryKeyHash(meta.primaryKeys)]: { $in: raw(sql, params) } });
     }
-    pruneExtraJoins(meta) {
-        // remove joins that are not used for population or ordering to improve performance
-        const populate = new Set();
-        const orderByAliases = this._orderBy
-            .flatMap(hint => Object.keys(hint))
-            .map(k => k.split('.')[0]);
+    /**
+     * Computes the set of populate paths from the _populate hints.
+     */
+    getPopulatePaths() {
+        const paths = new Set();
         function addPath(hints, prefix = '') {
             for (const hint of hints) {
                 const field = hint.field.split(':')[0];
-                populate.add((prefix ? prefix + '.' : '') + field);
+                const fullPath = prefix ? prefix + '.' + field : field;
+                paths.add(fullPath);
                 if (hint.children) {
-                    addPath(hint.children, (prefix ? prefix + '.' : '') + field);
+                    addPath(hint.children, fullPath);
                 }
             }
         }
         addPath(this._populate);
+        return paths;
+    }
+    normalizeJoinPath(join, meta) {
+        return join.path?.replace(/\[populate]|\[pivot]|:ref/g, '').replace(new RegExp(`^${meta.className}.`), '') ?? '';
+    }
+    /**
+     * Transfers WHERE conditions to ORDER BY joins that are not used for population.
+     * This ensures the outer query's ORDER BY uses the same filtered rows as the subquery.
+     * GH #6160
+     */
+    transferConditionsForOrderByJoins(meta, cond, populatePaths) {
+        if (!cond || this._orderBy.length === 0) {
+            return;
+        }
+        const orderByAliases = new Set(this._orderBy
+            .flatMap(hint => Object.keys(hint))
+            .filter(k => !RawQueryFragment.isKnownFragmentSymbol(k))
+            .map(k => k.split('.')[0]));
+        for (const join of Object.values(this._joins)) {
+            const joinPath = this.normalizeJoinPath(join, meta);
+            const isPopulateJoin = populatePaths.has(joinPath);
+            // Only transfer conditions for joins used for ORDER BY but not for population
+            if (orderByAliases.has(join.alias) && !isPopulateJoin) {
+                this.transferConditionsToJoin(cond, join);
+            }
+        }
+    }
+    /**
+     * Removes joins that are not used for population or ordering to improve performance.
+     */
+    pruneJoinsForPagination(meta, populatePaths) {
+        const orderByAliases = this._orderBy
+            .flatMap(hint => Object.keys(hint))
+            .map(k => k.split('.')[0]);
         const joins = Object.entries(this._joins);
         const rootAlias = this.alias;
         function addParentAlias(alias) {
@@ -1460,12 +1875,38 @@ export class QueryBuilder {
             addParentAlias(orderByAlias);
         }
         for (const [key, join] of joins) {
-            const path = join.path?.replace(/\[populate]|\[pivot]|:ref/g, '').replace(new RegExp(`^${meta.className}.`), '');
-            if (!populate.has(path ?? '') && !orderByAliases.includes(join.alias)) {
+            const path = this.normalizeJoinPath(join, meta);
+            if (!populatePaths.has(path) && !orderByAliases.includes(join.alias)) {
                 delete this._joins[key];
             }
         }
     }
+    /**
+     * Transfers WHERE conditions that reference a join alias to the join's ON clause.
+     * This is needed when a join is kept for ORDER BY after pagination wrapping,
+     * so the outer query orders by the same filtered rows as the subquery.
+     * @internal
+     */
+    transferConditionsToJoin(cond, join, path = '') {
+        const aliasPrefix = join.alias + '.';
+        for (const key of Object.keys(cond)) {
+            const value = cond[key];
+            // Handle $and/$or operators - recurse into nested conditions
+            if (key === '$and' || key === '$or') {
+                if (Array.isArray(value)) {
+                    for (const item of value) {
+                        this.transferConditionsToJoin(item, join, path);
+                    }
+                }
+                continue;
+            }
+            // Check if this condition references the join alias
+            if (key.startsWith(aliasPrefix)) {
+                // Add condition to the join's ON clause
+                join.cond[key] = value;
+            }
+        }
+    }
     wrapModifySubQuery(meta) {
         const subQuery = this.clone();
         subQuery.finalized = true;
@@ -1473,7 +1914,8 @@ export class QueryBuilder {
         // https://stackoverflow.com/questions/45494/mysql-error-1093-cant-specify-target-table-for-update-in-from-clause
         const subSubQuery = this.platform.createNativeQueryBuilder();
         const method = this.flags.has(QueryFlag.UPDATE_SUB_QUERY) ? 'update' : 'delete';
-        const pks = this.prepareFields(meta.primaryKeys, 'sub-query');
+        const schema = this.getSchema(this.mainAlias);
+        const pks = this.prepareFields(meta.primaryKeys, 'sub-query', schema);
         this._cond = {}; // otherwise we would trigger validation error
         this._joins = {}; // included in the subquery
         subSubQuery.select(pks).from(subQuery.as(this.mainAlias.aliasName));
@@ -1483,17 +1925,18 @@ export class QueryBuilder {
         });
     }
     getSchema(alias) {
-        const { metadata } = alias;
-        const metaSchema = metadata?.schema && metadata.schema !== '*' ? metadata.schema : undefined;
+        const { meta } = alias;
+        const metaSchema = meta.schema && meta.schema !== '*' ? meta.schema : undefined;
         const schema = this._schema ?? metaSchema ?? this.em?.schema ?? this.em?.config.getSchema(true);
         if (schema === this.platform.getDefaultSchemaName()) {
             return undefined;
         }
         return schema;
     }
+    /** @internal */
     createAlias(entityName, aliasName, subQuery) {
-        const metadata = this.metadata.find(entityName);
-        const alias = { aliasName, entityName, metadata, subQuery };
+        const meta = this.metadata.find(entityName);
+        const alias = { aliasName, entityName, meta, subQuery };
         this._aliases[aliasName] = alias;
         return alias;
     }
@@ -1513,7 +1956,7 @@ export class QueryBuilder {
         this.createMainAlias(entityName, aliasName);
     }
     createQueryBuilderHelper() {
-        return new QueryBuilderHelper(this.mainAlias.entityName, this.mainAlias.aliasName, this._aliases, this.subQueries, this.driver);
+        return new QueryBuilderHelper(this.mainAlias.entityName, this.mainAlias.aliasName, this._aliases, this.subQueries, this.driver, this._tptAlias);
     }
     ensureFromClause() {
         /* v8 ignore next */
@@ -1551,7 +1994,7 @@ export class QueryBuilder {
         if (!Utils.isEmpty(this._orderBy)) {
             object.orderBy = this._orderBy;
         }
-        const name = this._mainAlias ? `${prefix}QueryBuilder<${this._mainAlias?.entityName}>` : 'QueryBuilder';
+        const name = this._mainAlias ? `${prefix}QueryBuilder<${Utils.className(this._mainAlias?.entityName)}>` : 'QueryBuilder';
         const ret = inspect(object, { depth });
         return ret === '[Object]' ? `[${name}]` : name + ' ' + ret;
     }