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

package/query/QueryBuilder.js

@@ -1,4 +1,5 @@
-import { helper, inspect, isRaw, LoadStrategy, LockMode, PopulateHint, QueryFlag, QueryHelper, raw, RawQueryFragment, Reference, ReferenceKind, serialize, Utils, ValidationError, } from '@mikro-orm/core';
+var _a;
+import { EntityMetadata, 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';
@@ -31,59 +32,54 @@ export class QueryBuilder {
     connectionType;
     em;
     loggerContext;
+    #state = _a.createDefaultState();
+    #helper;
+    #query;
+    /** @internal */
+    static createDefaultState() {
+        return {
+            aliasCounter: 0,
+            explicitAlias: false,
+            populateHintFinalized: false,
+            joins: {},
+            cond: {},
+            orderBy: [],
+            groupBy: [],
+            having: {},
+            comments: [],
+            hintComments: [],
+            subQueries: {},
+            aliases: {},
+            tptAlias: {},
+            ctes: [],
+            tptJoinsApplied: false,
+            autoJoinedPaths: [],
+            populate: [],
+            populateMap: {},
+            flags: new Set([QueryFlag.CONVERT_CUSTOM_TYPES]),
+            finalized: false,
+            joinedProps: new Map(),
+        };
+    }
     get mainAlias() {
         this.ensureFromClause();
-        return this._mainAlias;
+        return this.#state.mainAlias;
     }
     get alias() {
         return this.mainAlias.aliasName;
     }
     get helper() {
         this.ensureFromClause();
-        return this._helper;
+        return this.#helper;
     }
     get type() {
-        return this._type ?? QueryType.SELECT;
+        return this.#state.type ?? QueryType.SELECT;
     }
     /** @internal */
-    _populate = [];
-    /** @internal */
-    _populateMap = {};
-    aliasCounter = 0;
-    flags = new Set([QueryFlag.CONVERT_CUSTOM_TYPES]);
-    finalized = false;
-    populateHintFinalized = false;
-    _joins = {};
-    _explicitAlias = false;
-    _schema;
-    _cond = {};
-    _data;
-    _orderBy = [];
-    _groupBy = [];
-    _having = {};
-    _returning;
-    _onConflict;
-    _limit;
-    _offset;
-    _distinctOn;
-    _joinedProps = new Map();
-    _cache;
-    _indexHint;
-    _collation;
-    _comments = [];
-    _hintComments = [];
-    flushMode;
-    lockMode;
-    lockTables;
-    subQueries = {};
-    _mainAlias;
-    _aliases = {};
-    _tptAlias = {}; // maps entity className to alias for TPT parent tables
-    _helper;
-    _query;
+    get state() {
+        return this.#state;
+    }
     platform;
-    tptJoinsApplied = false;
-    autoJoinedPaths = [];
     /**
      * @internal
      */
@@ -96,15 +92,15 @@ export class QueryBuilder {
         this.loggerContext = loggerContext;
         this.platform = this.driver.getPlatform();
         if (alias) {
-            this.aliasCounter++;
-            this._explicitAlias = true;
+            this.#state.aliasCounter++;
+            this.#state.explicitAlias = true;
         }
         // @ts-expect-error union type does not match the overloaded method signature
         this.from(entityName, alias);
     }
     select(fields, distinct = false) {
         this.ensureNotFinalized();
-        this._fields = Utils.asArray(fields).flatMap(f => {
+        this.#state.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) {
@@ -115,14 +111,14 @@ export class QueryBuilder {
                 }
                 return f;
             }
-            const asMatch = f.match(FIELD_ALIAS_RE);
+            const asMatch = FIELD_ALIAS_RE.exec(f);
             if (asMatch) {
                 return `${this.resolveNestedPath(asMatch[1].trim())} as ${asMatch[2]}`;
             }
             return this.resolveNestedPath(f);
         });
         if (distinct) {
-            this.flags.add(QueryFlag.DISTINCT);
+            this.#state.flags.add(QueryFlag.DISTINCT);
         }
         return this.init(QueryType.SELECT);
     }
@@ -131,10 +127,10 @@ export class QueryBuilder {
      */
     addSelect(fields) {
         this.ensureNotFinalized();
-        if (this._type && this._type !== QueryType.SELECT) {
+        if (this.#state.type && this.#state.type !== QueryType.SELECT) {
             return this;
         }
-        return this.select([...Utils.asArray(this._fields), ...Utils.asArray(fields)]);
+        return this.select([...Utils.asArray(this.#state.fields), ...Utils.asArray(fields)]);
     }
     distinct() {
         this.ensureNotFinalized();
@@ -142,7 +138,7 @@ export class QueryBuilder {
     }
     distinctOn(fields) {
         this.ensureNotFinalized();
-        this._distinctOn = Utils.asArray(fields);
+        this.#state.distinctOn = Utils.asArray(fields);
         return this;
     }
     /**
@@ -217,16 +213,16 @@ export class QueryBuilder {
      */
     count(field, distinct = false) {
         if (field) {
-            this._fields = Utils.asArray(field);
+            this.#state.fields = Utils.asArray(field);
         }
         else if (distinct || this.hasToManyJoins()) {
-            this._fields = this.mainAlias.meta.primaryKeys;
+            this.#state.fields = this.mainAlias.meta.primaryKeys;
         }
         else {
-            this._fields = [raw('*')];
+            this.#state.fields = [raw('*')];
         }
         if (distinct) {
-            this.flags.add(QueryFlag.DISTINCT);
+            this.#state.flags.add(QueryFlag.DISTINCT);
         }
         return this.init(QueryType.COUNT);
     }
@@ -260,29 +256,30 @@ export class QueryBuilder {
      * ```
      */
     joinAndSelect(field, alias, cond = {}, type = JoinType.innerJoin, path, fields, schema) {
-        if (!this._type) {
+        if (!this.#state.type) {
             this.select('*');
         }
         let subquery;
         if (Array.isArray(field)) {
-            const rawFragment = field[1] instanceof QueryBuilder ? field[1].toRaw() : field[1];
+            const rawFragment = field[1] instanceof _a ? field[1].toRaw() : field[1];
             subquery = this.platform.formatQuery(rawFragment.sql, rawFragment.params);
             field = field[0];
         }
         const { prop, key } = this.joinReference(field, alias, cond, type, path, schema, subquery);
         const [fromAlias] = this.helper.splitField(field);
         if (subquery) {
-            this._joins[key].subquery = subquery;
+            this.#state.joins[key].subquery = subquery;
         }
-        const populate = this._joinedProps.get(fromAlias);
+        const populate = this.#state.joinedProps.get(fromAlias);
         const item = { field: prop.name, strategy: LoadStrategy.JOINED, children: [] };
         if (populate) {
             populate.children.push(item);
         }
-        else { // root entity
-            this._populate.push(item);
+        else {
+            // root entity
+            this.#state.populate.push(item);
         }
-        this._joinedProps.set(alias, item);
+        this.#state.joinedProps.set(alias, item);
         this.addSelect(this.getFieldsForJoinedLoad(prop, alias, fields));
         return this;
     }
@@ -303,12 +300,12 @@ export class QueryBuilder {
     getFieldsForJoinedLoad(prop, alias, explicitFields) {
         const fields = [];
         const populate = [];
-        const joinKey = Object.keys(this._joins).find(join => join.endsWith(`#${alias}`));
+        const joinKey = Object.keys(this.#state.joins).find(join => join.endsWith(`#${alias}`));
         const targetMeta = prop.targetMeta;
-        const schema = this._schema ?? (targetMeta.schema !== '*' ? targetMeta.schema : undefined);
+        const schema = this.#state.schema ?? (targetMeta.schema !== '*' ? targetMeta.schema : undefined);
         if (joinKey) {
-            const path = this._joins[joinKey].path.split('.').slice(1);
-            let children = this._populate;
+            const path = this.#state.joins[joinKey].path.split('.').slice(1);
+            let children = this.#state.populate;
             for (let i = 0; i < path.length; i++) {
                 const child = children.filter(hint => {
                     const [propName] = hint.field.split(':', 2);
@@ -358,13 +355,13 @@ export class QueryBuilder {
      * @internal
      */
     scheduleFilterCheck(path) {
-        this.autoJoinedPaths.push(path);
+        this.#state.autoJoinedPaths.push(path);
     }
     /**
      * @internal
      */
     async applyJoinedFilters(em, filterOptions) {
-        for (const path of this.autoJoinedPaths) {
+        for (const path of this.#state.autoJoinedPaths) {
             const join = this.getJoinForPath(path);
             if (join.type === JoinType.pivotJoin) {
                 continue;
@@ -382,7 +379,8 @@ export class QueryBuilder {
             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', '$size'].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];
                     }
                 }
@@ -399,10 +397,10 @@ export class QueryBuilder {
     withSubQuery(subQuery, alias) {
         this.ensureNotFinalized();
         if (isRaw(subQuery)) {
-            this.subQueries[alias] = this.platform.formatQuery(subQuery.sql, subQuery.params);
+            this.#state.subQueries[alias] = this.platform.formatQuery(subQuery.sql, subQuery.params);
         }
         else {
-            this.subQueries[alias] = subQuery.toString();
+            this.#state.subQueries[alias] = subQuery.toString();
         }
         return this;
     }
@@ -426,31 +424,32 @@ export class QueryBuilder {
                 platform: this.platform,
                 aliasMap: this.getAliasMap(),
                 aliased: [QueryType.SELECT, QueryType.COUNT].includes(this.type),
-                convertCustomTypes: this.flags.has(QueryFlag.CONVERT_CUSTOM_TYPES),
+                convertCustomTypes: this.#state.flags.has(QueryFlag.CONVERT_CUSTOM_TYPES),
             });
         }
         const op = operator || params;
-        const topLevel = !op || !(Utils.hasObjectKeys(this._cond) || RawQueryFragment.hasObjectFragments(this._cond));
+        const topLevel = !op || !(Utils.hasObjectKeys(this.#state.cond) || RawQueryFragment.hasObjectFragments(this.#state.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 })) {
+        const ignoreBranching = this.#state.resolvedPopulateWhere === '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.meta.primaryKeys, true);
         }
         if (topLevel) {
-            this._cond = criteriaNode.process(this, { ignoreBranching });
+            this.#state.cond = criteriaNode.process(this, { ignoreBranching });
         }
-        else if (Array.isArray(this._cond[op])) {
-            this._cond[op].push(criteriaNode.process(this, { ignoreBranching }));
+        else if (Array.isArray(this.#state.cond[op])) {
+            this.#state.cond[op].push(criteriaNode.process(this, { ignoreBranching }));
         }
         else {
-            const cond1 = [this._cond, criteriaNode.process(this, { ignoreBranching })];
-            this._cond = { [op]: cond1 };
+            const cond1 = [this.#state.cond, criteriaNode.process(this, { ignoreBranching })];
+            this.#state.cond = { [op]: cond1 };
         }
-        if (this._onConflict) {
-            this._onConflict[this._onConflict.length - 1].where = this.helper.processOnConflictCondition(this._cond, this._schema);
-            this._cond = {};
+        if (this.#state.onConflict) {
+            this.#state.onConflict[this.#state.onConflict.length - 1].where = this.helper.processOnConflictCondition(this.#state.cond, this.#state.schema);
+            this.#state.cond = {};
         }
         return this;
     }
@@ -469,7 +468,7 @@ export class QueryBuilder {
     processOrderBy(orderBy, reset = true) {
         this.ensureNotFinalized();
         if (reset) {
-            this._orderBy = [];
+            this.#state.orderBy = [];
         }
         const selectAliases = this.getSelectAliases();
         Utils.asArray(orderBy).forEach(orig => {
@@ -494,7 +493,7 @@ export class QueryBuilder {
                 convertCustomTypes: false,
                 type: 'orderBy',
             });
-            this._orderBy.push(CriteriaNodeFactory.createNode(this.metadata, this.mainAlias.entityName, processed).process(this, {
+            this.#state.orderBy.push(CriteriaNodeFactory.createNode(this.metadata, this.mainAlias.entityName, processed).process(this, {
                 matchPopulateJoins: true,
                 type: 'orderBy',
             }));
@@ -504,9 +503,9 @@ export class QueryBuilder {
     /** 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 ?? []) {
+        for (const field of this.#state.fields ?? []) {
             if (typeof field === 'string') {
-                const m = field.match(FIELD_ALIAS_RE);
+                const m = FIELD_ALIAS_RE.exec(field);
                 if (m) {
                     aliases.add(m[2]);
                 }
@@ -516,7 +515,7 @@ export class QueryBuilder {
     }
     groupBy(fields) {
         this.ensureNotFinalized();
-        this._groupBy = Utils.asArray(fields).flatMap(f => {
+        this.#state.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) {
@@ -544,12 +543,12 @@ export class QueryBuilder {
             cond = { [raw(`(${cond})`, params)]: [] };
         }
         const processed = CriteriaNodeFactory.createNode(this.metadata, this.mainAlias.entityName, cond, undefined, undefined, false).process(this, { type: 'having' });
-        if (!this._having || !operator) {
-            this._having = processed;
+        if (!this.#state.having || !operator) {
+            this.#state.having = processed;
         }
         else {
-            const cond1 = [this._having, processed];
-            this._having = { [operator]: cond1 };
+            const cond1 = [this.#state.having, processed];
+            this.#state.having = { [operator]: cond1 };
         }
         return this;
     }
@@ -562,8 +561,8 @@ export class QueryBuilder {
     onConflict(fields = []) {
         const meta = this.mainAlias.meta;
         this.ensureNotFinalized();
-        this._onConflict ??= [];
-        this._onConflict.push({
+        this.#state.onConflict ??= [];
+        this.#state.onConflict.push({
             fields: isRaw(fields)
                 ? fields
                 : Utils.asArray(fields).flatMap(f => {
@@ -575,24 +574,24 @@ export class QueryBuilder {
         return this;
     }
     ignore() {
-        if (!this._onConflict) {
+        if (!this.#state.onConflict) {
             throw new Error('You need to call `qb.onConflict()` first to use `qb.ignore()`');
         }
-        this._onConflict[this._onConflict.length - 1].ignore = true;
+        this.#state.onConflict[this.#state.onConflict.length - 1].ignore = true;
         return this;
     }
     merge(data) {
-        if (!this._onConflict) {
+        if (!this.#state.onConflict) {
             throw new Error('You need to call `qb.onConflict()` first to use `qb.merge()`');
         }
         if (Array.isArray(data) && data.length === 0) {
             return this.ignore();
         }
-        this._onConflict[this._onConflict.length - 1].merge = data;
+        this.#state.onConflict[this.#state.onConflict.length - 1].merge = data;
         return this;
     }
     returning(fields) {
-        this._returning = Utils.asArray(fields);
+        this.#state.returning = Utils.asArray(fields);
         return this;
     }
     /**
@@ -600,9 +599,9 @@ export class QueryBuilder {
      */
     populate(populate, populateWhere, populateFilter) {
         this.ensureNotFinalized();
-        this._populate = populate;
-        this._populateWhere = populateWhere;
-        this._populateFilter = populateFilter;
+        this.#state.populate = populate;
+        this.#state.populateWhere = populateWhere;
+        this.#state.populateFilter = populateFilter;
         return this;
     }
     /**
@@ -616,7 +615,7 @@ export class QueryBuilder {
      */
     limit(limit, offset = 0) {
         this.ensureNotFinalized();
-        this._limit = limit;
+        this.#state.limit = limit;
         if (offset) {
             this.offset(offset);
         }
@@ -632,12 +631,12 @@ export class QueryBuilder {
      */
     offset(offset) {
         this.ensureNotFinalized();
-        this._offset = offset;
+        this.#state.offset = offset;
         return this;
     }
     withSchema(schema) {
         this.ensureNotFinalized();
-        this._schema = schema;
+        this.#state.schema = schema;
         return this;
     }
     setLockMode(mode, tables) {
@@ -645,31 +644,31 @@ export class QueryBuilder {
         if (mode != null && ![LockMode.OPTIMISTIC, LockMode.NONE].includes(mode) && !this.context) {
             throw ValidationError.transactionRequired();
         }
-        this.lockMode = mode;
-        this.lockTables = tables;
+        this.#state.lockMode = mode;
+        this.#state.lockTables = tables;
         return this;
     }
     setFlushMode(flushMode) {
         this.ensureNotFinalized();
-        this.flushMode = flushMode;
+        this.#state.flushMode = flushMode;
         return this;
     }
     setFlag(flag) {
         this.ensureNotFinalized();
-        this.flags.add(flag);
+        this.#state.flags.add(flag);
         return this;
     }
     unsetFlag(flag) {
         this.ensureNotFinalized();
-        this.flags.delete(flag);
+        this.#state.flags.delete(flag);
         return this;
     }
     hasFlag(flag) {
-        return this.flags.has(flag);
+        return this.#state.flags.has(flag);
     }
     cache(config = true) {
         this.ensureNotFinalized();
-        this._cache = config;
+        this.#state.cache = config;
         return this;
     }
     /**
@@ -677,7 +676,7 @@ export class QueryBuilder {
      */
     indexHint(sql) {
         this.ensureNotFinalized();
-        this._indexHint = sql;
+        this.#state.indexHint = sql;
         return this;
     }
     /**
@@ -685,7 +684,7 @@ export class QueryBuilder {
      */
     collation(collation) {
         this.ensureNotFinalized();
-        this._collation = collation;
+        this.#state.collation = collation;
         return this;
     }
     /**
@@ -693,7 +692,7 @@ export class QueryBuilder {
      */
     comment(comment) {
         this.ensureNotFinalized();
-        this._comments.push(...Utils.asArray(comment));
+        this.#state.comments.push(...Utils.asArray(comment));
         return this;
     }
     /**
@@ -703,52 +702,110 @@ export class QueryBuilder {
      */
     hintComment(comment) {
         this.ensureNotFinalized();
-        this._hintComments.push(...Utils.asArray(comment));
+        this.#state.hintComments.push(...Utils.asArray(comment));
         return this;
     }
     from(target, aliasName) {
         this.ensureNotFinalized();
-        if (target instanceof QueryBuilder) {
+        if (target instanceof _a) {
             this.fromSubQuery(target, aliasName);
         }
+        else if (typeof target === 'string' && !this.metadata.find(target)) {
+            this.fromRawTable(target, aliasName);
+        }
         else {
-            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}'`);
+            if (aliasName && this.#state.mainAlias && Utils.className(target) !== this.#state.mainAlias.aliasName) {
+                throw new Error(`Cannot override the alias to '${aliasName}' since a query already contains references to '${this.#state.mainAlias.aliasName}'`);
             }
             this.fromEntityName(target, aliasName);
         }
         return this;
     }
     getNativeQuery(processVirtualEntity = true) {
-        if (this._query?.qb) {
-            return this._query.qb;
+        if (this.#state.unionQuery) {
+            if (!this.#query?.qb) {
+                this.#query = {};
+                const nqb = this.platform.createNativeQueryBuilder();
+                nqb.select('*');
+                nqb.from(raw(`(${this.#state.unionQuery.sql})`, this.#state.unionQuery.params));
+                this.#query.qb = nqb;
+            }
+            return this.#query.qb;
         }
-        this._query = {};
+        if (this.#query?.qb) {
+            return this.#query.qb;
+        }
+        this.#query = {};
         this.finalize();
         const qb = this.getQueryBase(processVirtualEntity);
+        for (const cte of this.#state.ctes) {
+            const query = cte.query;
+            const opts = { columns: cte.columns, materialized: cte.materialized };
+            if (cte.recursive) {
+                qb.withRecursive(cte.name, query, opts);
+            }
+            else {
+                qb.with(cte.name, query, opts);
+            }
+        }
         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', schema)), isNotEmptyObject(this._groupBy));
-        Utils.runIfNotEmpty(() => this.helper.appendQueryCondition(this.type, this._having, qb, undefined, 'having'), isNotEmptyObject(this._having));
+        Utils.runIfNotEmpty(() => this.helper.appendQueryCondition(this.type, this.#state.cond, qb), this.#state.cond && !this.#state.onConflict);
+        Utils.runIfNotEmpty(() => qb.groupBy(this.prepareFields(this.#state.groupBy, 'groupBy', schema)), isNotEmptyObject(this.#state.groupBy));
+        Utils.runIfNotEmpty(() => this.helper.appendQueryCondition(this.type, this.#state.having, qb, undefined, 'having'), isNotEmptyObject(this.#state.having));
         Utils.runIfNotEmpty(() => {
-            const queryOrder = this.helper.getQueryOrder(this.type, this._orderBy, this._populateMap, this._collation);
+            const queryOrder = this.helper.getQueryOrder(this.type, this.#state.orderBy, this.#state.populateMap, this.#state.collation);
             if (queryOrder.length > 0) {
                 const sql = Utils.unique(queryOrder).join(', ');
                 qb.orderBy(sql);
                 return;
             }
-        }, 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);
-        Utils.runIfNotEmpty(() => qb.hintComment(this._hintComments), this._hintComments);
-        Utils.runIfNotEmpty(() => this.helper.appendOnConflictClause(QueryType.UPSERT, this._onConflict, qb), this._onConflict);
-        if (this.lockMode) {
-            this.helper.getLockSQL(qb, this.lockMode, this.lockTables, this._joins);
-        }
-        this.helper.finalize(this.type, qb, this.mainAlias.meta, this._data, this._returning);
-        return this._query.qb = qb;
+        }, isNotEmptyObject(this.#state.orderBy));
+        Utils.runIfNotEmpty(() => qb.limit(this.#state.limit), this.#state.limit != null);
+        Utils.runIfNotEmpty(() => qb.offset(this.#state.offset), this.#state.offset);
+        Utils.runIfNotEmpty(() => qb.comment(this.#state.comments), this.#state.comments);
+        Utils.runIfNotEmpty(() => qb.hintComment(this.#state.hintComments), this.#state.hintComments);
+        Utils.runIfNotEmpty(() => this.helper.appendOnConflictClause(QueryType.UPSERT, this.#state.onConflict, qb), this.#state.onConflict);
+        if (this.#state.lockMode) {
+            this.helper.getLockSQL(qb, this.#state.lockMode, this.#state.lockTables, this.#state.joins);
+        }
+        this.processReturningStatement(qb, this.mainAlias.meta, this.#state.data, this.#state.returning);
+        return (this.#query.qb = qb);
+    }
+    processReturningStatement(qb, meta, data, returning) {
+        const usesReturningStatement = this.platform.usesReturningStatement() || this.platform.usesOutputStatement();
+        if (!meta || !data || !usesReturningStatement) {
+            return;
+        }
+        // always respect explicit returning hint
+        if (returning && returning.length > 0) {
+            qb.returning(returning.map(field => this.helper.mapper(field, this.type)));
+            return;
+        }
+        if (this.type === QueryType.INSERT) {
+            const returningProps = meta.hydrateProps
+                .filter(prop => prop.returning || (prop.persist !== false && ((prop.primary && prop.autoincrement) || prop.defaultRaw)))
+                .filter(prop => !(prop.name in data));
+            if (returningProps.length > 0) {
+                qb.returning(Utils.flatten(returningProps.map(prop => prop.fieldNames)));
+            }
+            return;
+        }
+        if (this.type === QueryType.UPDATE) {
+            const returningProps = meta.hydrateProps.filter(prop => prop.fieldNames && isRaw(data[prop.fieldNames[0]]));
+            if (returningProps.length > 0) {
+                qb.returning(returningProps.flatMap((prop) => {
+                    if (prop.hasConvertToJSValueSQL) {
+                        const aliased = this.platform.quoteIdentifier(prop.fieldNames[0]);
+                        const sql = prop.customType.convertToJSValueSQL(aliased, this.platform) +
+                            ' as ' +
+                            this.platform.quoteIdentifier(prop.fieldNames[0]);
+                        return [raw(sql)];
+                    }
+                    return prop.fieldNames;
+                }));
+            }
+        }
     }
     /**
      * Returns the query with parameters as wildcards.
@@ -764,13 +821,16 @@ export class QueryBuilder {
         return raw(sql, params);
     }
     toQuery() {
-        if (this._query?.sql) {
-            return { sql: this._query.sql, params: this._query.params };
+        if (this.#state.unionQuery) {
+            return this.#state.unionQuery;
+        }
+        if (this.#query?.sql) {
+            return { sql: this.#query.sql, params: this.#query.params };
         }
         const query = this.getNativeQuery().compile();
-        this._query.sql = query.sql;
-        this._query.params = query.params;
-        return { sql: this._query.sql, params: this._query.params };
+        this.#query.sql = query.sql;
+        this.#query.params = query.params;
+        return { sql: this.#query.sql, params: this.#query.params };
     }
     /**
      * Returns the list of all parameters for this query.
@@ -802,7 +862,7 @@ export class QueryBuilder {
      * @internal
      */
     getJoinForPath(path, options) {
-        const joins = Object.values(this._joins);
+        const joins = Object.values(this.#state.joins);
         if (joins.length === 0) {
             return undefined;
         }
@@ -834,7 +894,7 @@ export class QueryBuilder {
      */
     getNextAlias(entityName = 'e') {
         entityName = Utils.className(entityName);
-        return this.driver.config.getNamingStrategy().aliasName(entityName, this.aliasCounter++);
+        return this.driver.config.getNamingStrategy().aliasName(entityName, this.#state.aliasCounter++);
     }
     /**
      * Registers a join for a specific polymorphic target type.
@@ -847,15 +907,15 @@ export class QueryBuilder {
         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.#state.joins[aliasedName] = this.helper.joinManyToOneReference(targetProp, ownerAlias, alias, type, {}, schema);
+        this.#state.joins[aliasedName].path = path;
         this.createAlias(targetMeta.class, alias);
     }
     /**
      * @internal
      */
     getAliasMap() {
-        return Object.fromEntries(Object.entries(this._aliases).map(([key, value]) => [key, value.entityName]));
+        return Object.fromEntries(Object.entries(this.#state.aliases).map(([key, value]) => [key, value.entityName]));
     }
     /**
      * Executes this QB and returns the raw results, mapped to the property names (unless disabled via last parameter).
@@ -870,11 +930,16 @@ export class QueryBuilder {
         if (!this.connectionType && (isRunType || this.context)) {
             this.connectionType = 'write';
         }
-        if (!this.finalized && method === 'get' && this.type === QueryType.SELECT) {
+        if (!this.#state.finalized && method === 'get' && this.type === QueryType.SELECT) {
             this.limit(1);
         }
         const query = this.toQuery();
-        const cached = await this.em?.tryCache(this.mainAlias.entityName, this._cache, ['qb.execute', query.sql, query.params, method]);
+        const cached = await this.em?.tryCache(this.mainAlias.entityName, this.#state.cache, [
+            'qb.execute',
+            query.sql,
+            query.params,
+            method,
+        ]);
         if (cached?.data !== undefined) {
             return cached.data;
         }
@@ -882,17 +947,17 @@ export class QueryBuilder {
         const res = await this.getConnection().execute(query.sql, query.params, method, this.context, loggerContext);
         const meta = this.mainAlias.meta;
         if (!options.mapResults || !meta) {
-            await this.em?.storeCache(this._cache, cached, res);
+            await this.em?.storeCache(this.#state.cache, cached, res);
             return res;
         }
         if (method === 'run') {
             return res;
         }
-        const joinedProps = this.driver.joinedProps(meta, this._populate);
+        const joinedProps = this.driver.joinedProps(meta, this.#state.populate);
         let mapped;
         if (Array.isArray(res)) {
             const map = {};
-            mapped = res.map(r => this.driver.mapResult(r, meta, this._populate, this, map));
+            mapped = res.map(r => this.driver.mapResult(r, meta, this.#state.populate, this, map));
             if (options.mergeResults && joinedProps.length > 0) {
                 mapped = this.driver.mergeJoinedResult(mapped, this.mainAlias.meta, joinedProps);
             }
@@ -901,10 +966,10 @@ export class QueryBuilder {
             mapped = [this.driver.mapResult(res, meta, joinedProps, this)];
         }
         if (method === 'get') {
-            await this.em?.storeCache(this._cache, cached, mapped[0]);
+            await this.em?.storeCache(this.#state.cache, cached, mapped[0]);
             return mapped[0];
         }
-        await this.em?.storeCache(this._cache, cached, mapped);
+        await this.em?.storeCache(this.#state.cache, cached, mapped);
         return mapped;
     }
     getConnection() {
@@ -940,13 +1005,13 @@ export class QueryBuilder {
             yield* res;
             return;
         }
-        const joinedProps = this.driver.joinedProps(meta, this._populate);
+        const joinedProps = this.driver.joinedProps(meta, this.#state.populate);
         const stack = [];
         const hash = (data) => {
             return Utils.getPrimaryKeyHash(meta.primaryKeys.map(pk => data[pk]));
         };
         for await (const row of res) {
-            const mapped = this.driver.mapResult(row, meta, this._populate, this);
+            const mapped = this.driver.mapResult(row, meta, this.#state.populate, this);
             if (!options.mergeResults || joinedProps.length === 0) {
                 yield this.mapResult(mapped, options.mapResults);
                 continue;
@@ -975,7 +1040,7 @@ export class QueryBuilder {
      * Executes the query, returning array of results mapped to entity instances.
      */
     async getResultList(limit) {
-        await this.em.tryFlush(this.mainAlias.entityName, { flushMode: this.flushMode });
+        await this.em.tryFlush(this.mainAlias.entityName, { flushMode: this.#state.flushMode });
         const res = await this.execute('all', true);
         return this.mapResults(res, limit);
     }
@@ -997,15 +1062,15 @@ export class QueryBuilder {
         if (!map) {
             return row;
         }
-        const entity = this.em.map(this.mainAlias.entityName, row, { schema: this._schema });
-        this.propagatePopulateHint(entity, this._populate);
+        const entity = this.em.map(this.mainAlias.entityName, row, { schema: this.#state.schema });
+        this.propagatePopulateHint(entity, this.#state.populate);
         return entity;
     }
     mapResults(res, limit) {
         const entities = [];
         for (const row of res) {
             const entity = this.mapResult(row);
-            this.propagatePopulateHint(entity, this._populate);
+            this.propagatePopulateHint(entity, this.#state.populate);
             entities.push(entity);
             if (limit != null && --limit === 0) {
                 break;
@@ -1017,7 +1082,7 @@ export class QueryBuilder {
      * Executes the query, returning the first result or null
      */
     async getSingleResult() {
-        if (!this.finalized) {
+        if (!this.#state.finalized) {
             this.limit(1);
         }
         const [res] = await this.getResultList(1);
@@ -1029,9 +1094,12 @@ export class QueryBuilder {
             res = await this.execute('get', false);
         }
         else {
-            const qb = (this._type === undefined ? this : this.clone());
+            const qb = (this.#state.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([]);
+            qb.count(field, distinct ?? qb.hasToManyJoins())
+                .limit(undefined)
+                .offset(undefined)
+                .orderBy([]);
             res = await qb.execute('get', false);
         }
         return res ? +res.count : 0;
@@ -1059,28 +1127,97 @@ export class QueryBuilder {
         Object.defineProperty(qb, '__as', { enumerable: false, value: finalAlias });
         return qb;
     }
+    /**
+     * Combines the current query with one or more other queries using `UNION ALL`.
+     * All queries must select the same columns. Returns a `QueryBuilder` that
+     * can be used with `$in`, passed to `qb.from()`, or converted via `.getQuery()`,
+     * `.getParams()`, `.toQuery()`, `.toRaw()`, etc.
+     *
+     * ```ts
+     * const qb1 = em.createQueryBuilder(Employee).select('id').where(condition1);
+     * const qb2 = em.createQueryBuilder(Employee).select('id').where(condition2);
+     * const qb3 = em.createQueryBuilder(Employee).select('id').where(condition3);
+     * const subquery = qb1.unionAll(qb2, qb3);
+     *
+     * const results = await em.find(Employee, { id: { $in: subquery } });
+     * ```
+     */
+    unionAll(...others) {
+        return this.buildUnionQuery('union all', others);
+    }
+    /**
+     * Combines the current query with one or more other queries using `UNION` (with deduplication).
+     * All queries must select the same columns. Returns a `QueryBuilder` that
+     * can be used with `$in`, passed to `qb.from()`, or converted via `.getQuery()`,
+     * `.getParams()`, `.toQuery()`, `.toRaw()`, etc.
+     *
+     * ```ts
+     * const qb1 = em.createQueryBuilder(Employee).select('id').where(condition1);
+     * const qb2 = em.createQueryBuilder(Employee).select('id').where(condition2);
+     * const subquery = qb1.union(qb2);
+     *
+     * const results = await em.find(Employee, { id: { $in: subquery } });
+     * ```
+     */
+    union(...others) {
+        return this.buildUnionQuery('union', others);
+    }
+    buildUnionQuery(separator, others) {
+        const all = [this, ...others];
+        const parts = [];
+        const params = [];
+        for (const qb of all) {
+            const compiled = qb instanceof _a ? qb.toQuery() : qb.compile();
+            parts.push(`(${compiled.sql})`);
+            params.push(...compiled.params);
+        }
+        const result = this.clone(true);
+        result.#state.unionQuery = { sql: parts.join(` ${separator} `), params };
+        return result;
+    }
+    with(name, query, options) {
+        return this.addCte(name, query, options);
+    }
+    withRecursive(name, query, options) {
+        return this.addCte(name, query, options, true);
+    }
+    addCte(name, query, options, recursive) {
+        this.ensureNotFinalized();
+        if (this.#state.ctes.some(cte => cte.name === name)) {
+            throw new Error(`CTE with name '${name}' already exists`);
+        }
+        // Eagerly compile QueryBuilder to RawQueryFragment — later mutations to the sub-query won't be reflected
+        const compiled = query instanceof _a ? query.toRaw() : query;
+        this.#state.ctes.push({
+            name,
+            query: compiled,
+            recursive,
+            columns: options?.columns,
+            materialized: options?.materialized,
+        });
+        return this;
+    }
     clone(reset, preserve) {
-        const qb = new QueryBuilder(this.mainAlias.entityName, this.metadata, this.driver, this.context, this.mainAlias.aliasName, this.connectionType, this.em);
-        reset = reset || [];
-        // clone array/object properties
-        const properties = [
-            'flags', '_populate', '_populateWhere', '_populateFilter', '__populateWhere', '_populateMap', '_joins', '_joinedProps', '_cond', '_data', '_orderBy',
-            '_schema', '_indexHint', '_collation', '_cache', 'subQueries', 'lockMode', 'lockTables', '_groupBy', '_having', '_returning',
-            '_comments', '_hintComments', 'aliasCounter',
-        ];
-        for (const prop of Object.keys(this)) {
-            if (!preserve?.includes(prop) && (reset === true || reset.includes(prop) || ['_helper', '_query'].includes(prop))) {
-                continue;
+        const qb = new _a(this.#state.mainAlias.entityName, this.metadata, this.driver, this.context, this.#state.mainAlias.aliasName, this.connectionType, this.em);
+        if (reset !== true) {
+            qb.#state = Utils.copy(this.#state);
+            // CTEs contain NativeQueryBuilder instances that should not be deep-cloned
+            qb.#state.ctes = this.#state.ctes.map(cte => ({ ...cte }));
+            if (Array.isArray(reset)) {
+                const fresh = _a.createDefaultState();
+                for (const key of reset) {
+                    qb.#state[key] = fresh[key];
+                }
             }
-            qb[prop] = properties.includes(prop) ? Utils.copy(this[prop]) : this[prop];
         }
-        /* v8 ignore next */
-        if (this._fields && reset !== true && !reset.includes('_fields')) {
-            qb._fields = [...this._fields];
+        else if (preserve) {
+            for (const key of preserve) {
+                qb.#state[key] = Utils.copy(this.#state[key]);
+            }
         }
-        qb._aliases = { ...this._aliases };
-        qb._helper.aliasMap = qb._aliases;
-        qb.finalized = false;
+        qb.#state.finalized = false;
+        qb.#query = undefined;
+        qb.#helper = qb.createQueryBuilderHelper();
         return qb;
     }
     /**
@@ -1100,11 +1237,11 @@ export class QueryBuilder {
         if (typeof meta.expression === 'string') {
             return `(${meta.expression}) as ${this.platform.quoteIdentifier(this.alias)}`;
         }
-        const res = meta.expression(this.em, this._cond, {});
+        const res = meta.expression(this.em, this.#state.cond, {});
         if (typeof res === 'string') {
             return `(${res}) as ${this.platform.quoteIdentifier(this.alias)}`;
         }
-        if (res instanceof QueryBuilder) {
+        if (res instanceof _a) {
             return `(${res.getFormattedQuery()}) as ${this.platform.quoteIdentifier(this.alias)}`;
         }
         if (isRaw(res)) {
@@ -1123,10 +1260,11 @@ export class QueryBuilder {
     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;
+        this.#state.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.#state.joins[key].path = path;
         return key;
     }
     joinReference(field, alias, cond, type, path, schema, subquery) {
@@ -1136,7 +1274,7 @@ export class QueryBuilder {
                 name: '__subquery__',
                 kind: ReferenceKind.MANY_TO_ONE,
             };
-            if (field instanceof QueryBuilder) {
+            if (field instanceof _a) {
                 prop.type = Utils.className(field.mainAlias.entityName);
                 prop.targetMeta = field.mainAlias.meta;
                 field = field.getNativeQuery();
@@ -1145,7 +1283,7 @@ export class QueryBuilder {
                 field = this.platform.formatQuery(field.sql, field.params);
             }
             const key = `${this.alias}.${prop.name}#${alias}`;
-            this._joins[key] = {
+            this.#state.joins[key] = {
                 prop,
                 alias,
                 type,
@@ -1161,10 +1299,10 @@ export class QueryBuilder {
         }
         const [fromAlias, fromField] = this.helper.splitField(field);
         const q = (str) => `'${str}'`;
-        if (!this._aliases[fromAlias]) {
-            throw new Error(`Trying to join ${q(fromField)} with alias ${q(fromAlias)}, but ${q(fromAlias)} is not a known alias. Available aliases are: ${Object.keys(this._aliases).map(q).join(', ')}.`);
+        if (!this.#state.aliases[fromAlias]) {
+            throw new Error(`Trying to join ${q(fromField)} with alias ${q(fromAlias)}, but ${q(fromAlias)} is not a known alias. Available aliases are: ${Object.keys(this.#state.aliases).map(q).join(', ')}.`);
         }
-        const entityName = this._aliases[fromAlias].entityName;
+        const entityName = this.#state.aliases[fromAlias].entityName;
         const meta = this.metadata.get(entityName);
         const prop = meta.properties[fromField];
         if (!prop) {
@@ -1172,7 +1310,7 @@ export class QueryBuilder {
         }
         // 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))
+        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);
@@ -1187,10 +1325,10 @@ export class QueryBuilder {
         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 ?? Utils.className(entityName))}.${prop.name}`;
+        path ??= `${Object.values(this.#state.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;
+            this.#state.joins[aliasedName] = this.helper.joinOneToReference(prop, fromAlias, alias, type, cond, schema);
+            this.#state.joins[aliasedName].path ??= path;
         }
         else if (prop.kind === ReferenceKind.MANY_TO_MANY) {
             let pivotAlias = alias;
@@ -1200,18 +1338,19 @@ export class QueryBuilder {
                 aliasedName = `${fromAlias}.${prop.name}#${pivotAlias}`;
             }
             const joins = this.helper.joinManyToManyReference(prop, fromAlias, alias, pivotAlias, type, cond, path, schema);
-            Object.assign(this._joins, joins);
+            Object.assign(this.#state.joins, joins);
             this.createAlias(prop.pivotEntity, pivotAlias);
-            this._joins[aliasedName].path ??= path;
+            this.#state.joins[aliasedName].path ??= path;
             aliasedName = Object.keys(joins)[1];
         }
         else if (prop.kind === ReferenceKind.ONE_TO_ONE) {
-            this._joins[aliasedName] = this.helper.joinOneToReference(prop, ownerAlias, alias, type, cond, schema);
-            this._joins[aliasedName].path ??= path;
+            this.#state.joins[aliasedName] = this.helper.joinOneToReference(prop, ownerAlias, alias, type, cond, schema);
+            this.#state.joins[aliasedName].path ??= path;
         }
-        else { // MANY_TO_ONE
-            this._joins[aliasedName] = this.helper.joinManyToOneReference(prop, ownerAlias, alias, type, cond, schema);
-            this._joins[aliasedName].path ??= path;
+        else {
+            // MANY_TO_ONE
+            this.#state.joins[aliasedName] = this.helper.joinManyToOneReference(prop, ownerAlias, alias, type, cond, schema);
+            this.#state.joins[aliasedName].path ??= path;
         }
         return { prop, key: aliasedName };
     }
@@ -1229,14 +1368,14 @@ export class QueryBuilder {
             // 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);
+            const asMatch = FIELD_ALIAS_RE.exec(originalField);
             if (asMatch) {
                 field = asMatch[1].trim();
                 customAlias = asMatch[2];
             }
-            const join = Object.keys(this._joins).find(k => field === k.substring(0, k.indexOf('#')));
+            const join = Object.keys(this.#state.joins).find(k => field === k.substring(0, k.indexOf('#')));
             if (join && type === 'where') {
-                ret.push(...this.helper.mapJoinColumns(this.type, this._joins[join]));
+                ret.push(...this.helper.mapJoinColumns(this.type, this.#state.joins[join]));
                 return;
             }
             const [a, f] = this.helper.splitField(field);
@@ -1250,7 +1389,7 @@ 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;
+                const aliased = this.#state.aliases[a] ? `${a}.${name}` : name;
                 ret.push(getFieldName(aliased, customAlias));
                 return;
             }
@@ -1260,7 +1399,9 @@ export class QueryBuilder {
                 }
                 const nest = (prop) => {
                     for (const childProp of Object.values(prop.embeddedProps)) {
-                        if (childProp.fieldNames && (childProp.kind !== ReferenceKind.EMBEDDED || childProp.object) && childProp.persist !== false) {
+                        if (childProp.fieldNames &&
+                            (childProp.kind !== ReferenceKind.EMBEDDED || childProp.object) &&
+                            childProp.persist !== false) {
                             ret.push(getFieldName(childProp.fieldNames[0]));
                         }
                         else {
@@ -1281,16 +1422,16 @@ export class QueryBuilder {
             ret.push(getFieldName(field, customAlias));
         });
         const requiresSQLConversion = this.mainAlias.meta.props.filter(p => p.hasConvertToJSValueSQL && p.persist !== false);
-        if (this.flags.has(QueryFlag.CONVERT_CUSTOM_TYPES) &&
+        if (this.#state.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]) {
-                ret.push(...this.helper.mapJoinColumns(this.type, this._joins[f]));
+        for (const f of Object.keys(this.#state.populateMap)) {
+            if (type === 'where' && this.#state.joins[f]) {
+                ret.push(...this.helper.mapJoinColumns(this.type, this.#state.joins[f]));
             }
         }
         return Utils.unique(ret);
@@ -1306,14 +1447,16 @@ export class QueryBuilder {
         }
         const parts = field.split('.');
         // Simple alias.property case - let prepareFields handle it
-        if (parts.length === 2 && this._aliases[parts[0]]) {
+        if (parts.length === 2 && this.#state.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;
+        let currentMeta = this.#state.aliases[currentAlias]
+            ? this.metadata.get(this.#state.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]) {
+        if (!this.#state.aliases[currentAlias]) {
             currentAlias = this.mainAlias.aliasName;
             parts.unshift(currentAlias);
         }
@@ -1351,14 +1494,14 @@ export class QueryBuilder {
                 }
                 // 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];
+                const existingJoinKey = Object.keys(this.#state.joins).find(k => {
+                    const join = this.#state.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;
+                    joinAlias = this.#state.joins[existingJoinKey].alias;
                 }
                 else {
                     joinAlias = this.getNextAlias(prop.targetMeta?.className ?? propName);
@@ -1375,18 +1518,18 @@ export class QueryBuilder {
     }
     init(type, data, cond) {
         this.ensureNotFinalized();
-        this._type = type;
-        if ([QueryType.UPDATE, QueryType.DELETE].includes(type) && Utils.hasObjectKeys(this._cond)) {
+        this.#state.type = type;
+        if ([QueryType.UPDATE, QueryType.DELETE].includes(type) && Utils.hasObjectKeys(this.#state.cond)) {
             throw new Error(`You are trying to call \`qb.where().${type.toLowerCase()}()\`. Calling \`qb.${type.toLowerCase()}()\` before \`qb.where()\` is required.`);
         }
         if (!this.helper.isTableNameAliasRequired(type)) {
-            delete this._fields;
+            this.#state.fields = undefined;
         }
         if (data) {
             if (Utils.isEntity(data)) {
                 data = this.em?.getComparator().prepareEntity(data) ?? serialize(data);
             }
-            this._data = this.helper.processData(data, this.flags.has(QueryFlag.CONVERT_CUSTOM_TYPES), false);
+            this.#state.data = this.helper.processData(data, this.#state.flags.has(QueryFlag.CONVERT_CUSTOM_TYPES), false);
         }
         if (cond) {
             this.where(cond);
@@ -1394,47 +1537,54 @@ export class QueryBuilder {
         return this;
     }
     getQueryBase(processVirtualEntity) {
-        const qb = this.platform.createNativeQueryBuilder().setFlags(this.flags);
-        const { subQuery, aliasName, entityName, meta } = this.mainAlias;
-        const requiresAlias = this.finalized && (this._explicitAlias || this.helper.isTableNameAliasRequired(this.type));
+        const qb = this.platform.createNativeQueryBuilder().setFlags(this.#state.flags);
+        const { subQuery, aliasName, entityName, meta, rawTableName } = this.mainAlias;
+        const requiresAlias = this.#state.finalized && (this.#state.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;
+        const tableName = rawTableName
+            ? rawTableName
+            : subQuery instanceof NativeQueryBuilder
+                ? subQuery.as(aliasName)
+                : subQuery
+                    ? raw(`(${subQuery.sql}) as ${this.platform.quoteIdentifier(aliasName)}`, subQuery.params)
+                    : this.helper.getTableName(entityName);
+        const joinSchema = this.#state.schema ?? this.em?.schema ?? schema;
+        const schemaOverride = this.#state.schema ?? this.em?.schema;
         if (meta.virtual && processVirtualEntity) {
-            qb.from(raw(this.fromVirtual(meta)), { indexHint: this._indexHint });
+            qb.from(raw(this.fromVirtual(meta)), { indexHint: this.#state.indexHint });
         }
         else {
             qb.from(tableName, {
-                schema,
+                schema: rawTableName ? undefined : schema,
                 alias,
-                indexHint: this._indexHint,
+                indexHint: this.#state.indexHint,
             });
         }
         switch (this.type) {
             case QueryType.SELECT:
-                qb.select(this.prepareFields(this._fields, 'where', schema));
-                if (this._distinctOn) {
-                    qb.distinctOn(this.prepareFields(this._distinctOn, 'where', schema));
+                qb.select(this.prepareFields(this.#state.fields, 'where', schema));
+                if (this.#state.distinctOn) {
+                    qb.distinctOn(this.prepareFields(this.#state.distinctOn, 'where', schema));
                 }
-                else if (this.flags.has(QueryFlag.DISTINCT)) {
+                else if (this.#state.flags.has(QueryFlag.DISTINCT)) {
                     qb.distinct();
                 }
-                this.helper.processJoins(qb, this._joins, joinSchema);
+                this.helper.processJoins(qb, this.#state.joins, joinSchema, schemaOverride);
                 break;
             case QueryType.COUNT: {
-                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);
+                const fields = this.#state.fields.map(f => this.helper.mapper(f, this.type, undefined, undefined, schema));
+                qb.count(fields, this.#state.flags.has(QueryFlag.DISTINCT));
+                this.helper.processJoins(qb, this.#state.joins, joinSchema, schemaOverride);
                 break;
             }
             case QueryType.INSERT:
-                qb.insert(this._data);
+                qb.insert(this.#state.data);
                 break;
             case QueryType.UPDATE:
-                qb.update(this._data);
-                this.helper.processJoins(qb, this._joins, joinSchema);
-                this.helper.updateVersionProperty(qb, this._data);
+                qb.update(this.#state.data);
+                this.helper.processJoins(qb, this.#state.joins, joinSchema, schemaOverride);
+                this.helper.updateVersionProperty(qb, this.#state.data);
                 break;
             case QueryType.DELETE:
                 qb.delete();
@@ -1460,7 +1610,9 @@ export class QueryBuilder {
         };
         lookUpChildren(children, meta.class);
         this.andWhere({
-            [meta.root.discriminatorColumn]: children.length > 0 ? { $in: [meta.discriminatorValue, ...children.map(c => c.discriminatorValue)] } : meta.discriminatorValue,
+            [meta.root.discriminatorColumn]: children.length > 0
+                ? { $in: [meta.discriminatorValue, ...children.map(c => c.discriminatorValue)] }
+                : meta.discriminatorValue,
         });
     }
     /**
@@ -1478,20 +1630,22 @@ export class QueryBuilder {
      */
     applyTPTJoins() {
         const meta = this.mainAlias.meta;
-        if (meta?.inheritanceType !== 'tpt' || !meta.tptParent || ![QueryType.SELECT, QueryType.COUNT].includes(this.type)) {
+        if (meta?.inheritanceType !== 'tpt' ||
+            !meta.tptParent ||
+            ![QueryType.SELECT, QueryType.COUNT].includes(this.type)) {
             return;
         }
-        if (this.tptJoinsApplied) {
+        if (this.#state.tptJoinsApplied) {
             return;
         }
-        this.tptJoinsApplied = true;
+        this.#state.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.#state.tptAlias[parentMeta.className] = parentAlias;
             this.addPropertyJoin(childMeta.tptParentProp, childAlias, parentAlias, JoinType.innerJoin, `[tpt]${childMeta.className}`);
             childMeta = parentMeta;
             childAlias = parentAlias;
@@ -1502,20 +1656,22 @@ export class QueryBuilder {
      */
     addTPTParentFields() {
         const meta = this.mainAlias.meta;
-        if (meta?.inheritanceType !== 'tpt' || !meta.tptParent || ![QueryType.SELECT, QueryType.COUNT].includes(this.type)) {
+        if (meta?.inheritanceType !== 'tpt' ||
+            !meta.tptParent ||
+            ![QueryType.SELECT, QueryType.COUNT].includes(this.type)) {
             return;
         }
-        if (!this._fields?.includes('*') && !this._fields?.includes(`${this.mainAlias.aliasName}.*`)) {
+        if (!this.#state.fields?.includes('*') && !this.#state.fields?.includes(`${this.mainAlias.aliasName}.*`)) {
             return;
         }
         let parentMeta = meta.tptParent;
         while (parentMeta) {
-            const parentAlias = this._tptAlias[parentMeta.className];
+            const parentAlias = this.#state.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
+                    .ownProps.filter(prop => this.platform.shouldHaveColumn(prop, []))
+                    .forEach(prop => this.#state.fields.push(...this.driver.mapPropToFieldNames(this, prop, parentAlias, parentMeta, schema)));
             }
             parentMeta = parentMeta.tptParent;
         }
@@ -1530,32 +1686,32 @@ export class QueryBuilder {
         if (!descendants?.length || ![QueryType.SELECT, QueryType.COUNT].includes(this.type)) {
             return;
         }
-        if (!this._fields?.includes('*') && !this._fields?.includes(`${this.mainAlias.aliasName}.*`)) {
+        if (!this.#state.fields?.includes('*') && !this.#state.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.#state.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)));
+            childMeta
+                .ownProps.filter(prop => !prop.primary && this.platform.shouldHaveColumn(prop, []))
+                .forEach(prop => this.#state.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));
+            this.#state.fields.push(this.driver.buildTPTDiscriminatorExpression(meta, descendants, this.#state.tptAlias, this.mainAlias.aliasName));
         }
     }
     finalize() {
-        if (this.finalized) {
+        if (this.#state.finalized) {
             return;
         }
-        if (!this._type) {
+        if (!this.#state.type) {
             this.select('*');
         }
         const meta = this.mainAlias.meta;
@@ -1565,93 +1721,102 @@ export class QueryBuilder {
         this.applyTPTPolymorphicJoins();
         this.processPopulateHint();
         this.processNestedJoins();
-        if (meta && (this._fields?.includes('*') || this._fields?.includes(`${this.mainAlias.aliasName}.*`))) {
+        if (meta && (this.#state.fields?.includes('*') || this.#state.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)))
+                .filter(prop => prop.formula && (!prop.lazy || this.#state.flags.has(QueryFlag.INCLUDE_LAZY_FORMULAS)))
                 .map(prop => {
                 const aliased = this.platform.quoteIdentifier(prop.fieldNames[0]);
                 const table = this.helper.createFormulaTable(quotedMainAlias, meta, schema);
                 return `${this.driver.evaluateFormula(prop.formula, columns, table)} as ${aliased}`;
             })
-                .filter(field => !this._fields.some(f => {
+                .filter(field => !this.#state.fields.some(f => {
                 if (isRaw(f)) {
                     return f.sql === field && f.params.length === 0;
                 }
                 return f === field;
             }))
-                .forEach(field => this._fields.push(raw(field)));
+                .forEach(field => this.#state.fields.push(raw(field)));
         }
-        QueryHelper.processObjectParams(this._data);
-        QueryHelper.processObjectParams(this._cond);
-        QueryHelper.processObjectParams(this._having);
+        QueryHelper.processObjectParams(this.#state.data);
+        QueryHelper.processObjectParams(this.#state.cond);
+        QueryHelper.processObjectParams(this.#state.having);
         // automatically enable paginate flag when we detect to-many joins, but only if there is no `group by` clause
-        if (!this.flags.has(QueryFlag.DISABLE_PAGINATE) && this._groupBy.length === 0 && this.hasToManyJoins()) {
-            this.flags.add(QueryFlag.PAGINATE);
-        }
-        if (meta && !meta.virtual && this.flags.has(QueryFlag.PAGINATE) && !this.flags.has(QueryFlag.DISABLE_PAGINATE) && (this._limit > 0 || this._offset > 0)) {
+        if (!this.#state.flags.has(QueryFlag.DISABLE_PAGINATE) &&
+            this.#state.groupBy.length === 0 &&
+            this.hasToManyJoins()) {
+            this.#state.flags.add(QueryFlag.PAGINATE);
+        }
+        if (meta &&
+            !meta.virtual &&
+            this.#state.flags.has(QueryFlag.PAGINATE) &&
+            !this.#state.flags.has(QueryFlag.DISABLE_PAGINATE) &&
+            (this.#state.limit > 0 || this.#state.offset > 0)) {
             this.wrapPaginateSubQuery(meta);
         }
-        if (meta && (this.flags.has(QueryFlag.UPDATE_SUB_QUERY) || this.flags.has(QueryFlag.DELETE_SUB_QUERY))) {
+        if (meta &&
+            (this.#state.flags.has(QueryFlag.UPDATE_SUB_QUERY) || this.#state.flags.has(QueryFlag.DELETE_SUB_QUERY))) {
             this.wrapModifySubQuery(meta);
         }
-        this.finalized = true;
+        this.#state.finalized = true;
     }
     /** @internal */
     processPopulateHint() {
-        if (this.populateHintFinalized) {
+        if (this.#state.populateHintFinalized) {
             return;
         }
         const meta = this.mainAlias.meta;
-        if (meta && this.flags.has(QueryFlag.AUTO_JOIN_ONE_TO_ONE_OWNER)) {
-            const relationsToPopulate = this._populate.map(({ field }) => field);
+        if (meta && this.#state.flags.has(QueryFlag.AUTO_JOIN_ONE_TO_ONE_OWNER)) {
+            const relationsToPopulate = this.#state.populate.map(({ field }) => field);
             meta.relations
-                .filter(prop => prop.kind === ReferenceKind.ONE_TO_ONE && !prop.owner && !relationsToPopulate.includes(prop.name) && !relationsToPopulate.includes(`${prop.name}:ref`))
+                .filter(prop => prop.kind === ReferenceKind.ONE_TO_ONE &&
+                !prop.owner &&
+                !relationsToPopulate.includes(prop.name) &&
+                !relationsToPopulate.includes(`${prop.name}:ref`))
                 .map(prop => ({ field: `${prop.name}:ref` }))
-                .forEach(item => this._populate.push(item));
+                .forEach(item => this.#state.populate.push(item));
         }
-        this._populate.forEach(({ field }) => {
+        this.#state.populate.forEach(({ field }) => {
             const [fromAlias, fromField] = this.helper.splitField(field);
             const aliasedField = `${fromAlias}.${fromField}`;
-            const join = Object.keys(this._joins).find(k => `${aliasedField}#${this._joins[k].alias}` === k);
-            if (join && this._joins[join] && this.helper.isOneToOneInverse(fromField)) {
-                this._populateMap[join] = this._joins[join].alias;
+            const join = Object.keys(this.#state.joins).find(k => `${aliasedField}#${this.#state.joins[k].alias}` === k);
+            if (join && this.#state.joins[join] && this.helper.isOneToOneInverse(fromField)) {
+                this.#state.populateMap[join] = this.#state.joins[join].alias;
                 return;
             }
             if (meta && this.helper.isOneToOneInverse(fromField)) {
                 const prop = meta.properties[fromField];
                 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.#state.joins[aliasedName] = this.helper.joinOneToReference(prop, this.mainAlias.aliasName, alias, JoinType.leftJoin);
+                this.#state.joins[aliasedName].path =
+                    `${Object.values(this.#state.joins).find(j => j.alias === fromAlias)?.path ?? meta.className}.${prop.name}`;
+                this.#state.populateMap[aliasedName] = this.#state.joins[aliasedName].alias;
                 this.createAlias(prop.targetMeta.class, alias);
             }
         });
         this.processPopulateWhere(false);
         this.processPopulateWhere(true);
-        this.populateHintFinalized = true;
+        this.#state.populateHintFinalized = true;
     }
     processPopulateWhere(filter) {
-        const key = filter ? '_populateFilter' : '_populateWhere';
-        if (this[key] == null || this[key] === PopulateHint.ALL) {
+        const value = filter ? this.#state.populateFilter : this.#state.populateWhere;
+        if (value == null || value === PopulateHint.ALL) {
             return;
         }
-        let joins = Object.values(this._joins);
+        let joins = Object.values(this.#state.joins);
         for (const join of joins) {
             join.cond_ ??= join.cond;
             join.cond = { ...join.cond };
         }
-        if (typeof this[key] === 'object') {
-            const cond = CriteriaNodeFactory
-                .createNode(this.metadata, this.mainAlias.entityName, this[key])
-                .process(this, { matchPopulateJoins: true, ignoreBranching: true, preferNoBranch: true, filter });
+        if (typeof value === 'object') {
+            const cond = CriteriaNodeFactory.createNode(this.metadata, this.mainAlias.entityName, value).process(this, { matchPopulateJoins: true, ignoreBranching: true, preferNoBranch: true, filter });
             // there might be new joins created by processing the `populateWhere` object
-            joins = Object.values(this._joins);
+            joins = Object.values(this.#state.joins);
             this.mergeOnConditions(joins, cond, filter);
         }
     }
@@ -1671,9 +1836,11 @@ export class QueryBuilder {
                 // https://stackoverflow.com/a/56815807/3665878
                 if (parentJoin && !filter) {
                     const nested = (parentJoin.nested ??= new Set());
-                    join.type = join.type === JoinType.innerJoin || ([ReferenceKind.ONE_TO_MANY, ReferenceKind.MANY_TO_MANY].includes(parentJoin.prop.kind))
-                        ? JoinType.nestedInnerJoin
-                        : JoinType.nestedLeftJoin;
+                    join.type =
+                        join.type === JoinType.innerJoin ||
+                            [ReferenceKind.ONE_TO_MANY, ReferenceKind.MANY_TO_MANY].includes(parentJoin.prop.kind)
+                            ? JoinType.nestedInnerJoin
+                            : JoinType.nestedLeftJoin;
                     nested.add(join);
                 }
                 if (join.cond[k]) {
@@ -1695,10 +1862,10 @@ export class QueryBuilder {
      * otherwise the inner join could discard rows of the root table.
      */
     processNestedJoins() {
-        if (this.flags.has(QueryFlag.DISABLE_NESTED_INNER_JOIN)) {
+        if (this.#state.flags.has(QueryFlag.DISABLE_NESTED_INNER_JOIN)) {
             return;
         }
-        const joins = Object.values(this._joins);
+        const joins = Object.values(this.#state.joins);
         const lookupParentGroup = (j) => {
             return j.nested ?? (j.parent ? lookupParentGroup(j.parent) : undefined);
         };
@@ -1707,48 +1874,44 @@ export class QueryBuilder {
                 join.parent = joins.find(j => j.alias === join.ownerAlias);
                 // https://stackoverflow.com/a/56815807/3665878
                 if (join.parent?.type === JoinType.leftJoin || join.parent?.type === JoinType.nestedLeftJoin) {
-                    const nested = ((join.parent).nested ??= new Set());
-                    join.type = join.type === JoinType.innerJoin
-                        ? JoinType.nestedInnerJoin
-                        : JoinType.nestedLeftJoin;
+                    const nested = (join.parent.nested ??= new Set());
+                    join.type = join.type === JoinType.innerJoin ? JoinType.nestedInnerJoin : JoinType.nestedLeftJoin;
                     nested.add(join);
                 }
                 else if (join.parent?.type === JoinType.nestedInnerJoin) {
                     const group = lookupParentGroup(join.parent);
-                    const nested = group ?? ((join.parent).nested ??= new Set());
-                    join.type = join.type === JoinType.innerJoin
-                        ? JoinType.nestedInnerJoin
-                        : JoinType.nestedLeftJoin;
+                    const nested = group ?? (join.parent.nested ??= new Set());
+                    join.type = join.type === JoinType.innerJoin ? JoinType.nestedInnerJoin : JoinType.nestedLeftJoin;
                     nested.add(join);
                 }
             }
         }
     }
     hasToManyJoins() {
-        return Object.values(this._joins).some(join => {
+        return Object.values(this.#state.joins).some(join => {
             return [ReferenceKind.ONE_TO_MANY, ReferenceKind.MANY_TO_MANY].includes(join.prop.kind);
         });
     }
     wrapPaginateSubQuery(meta) {
         const schema = this.getSchema(this.mainAlias);
         const pks = this.prepareFields(meta.primaryKeys, 'sub-query', schema);
-        const subQuery = this.clone(['_orderBy', '_fields', 'lockMode', 'lockTableAliases'])
+        const subQuery = this.clone(['orderBy', 'fields', 'lockMode', 'lockTables'])
             .select(pks)
             .groupBy(pks)
-            .limit(this._limit);
+            .limit(this.#state.limit);
         // revert the on conditions added via populateWhere, we want to apply those only once
-        for (const join of Object.values(subQuery._joins)) {
+        for (const join of Object.values(subQuery.#state.joins)) {
             if (join.cond_) {
                 join.cond = join.cond_;
             }
         }
-        if (this._offset) {
-            subQuery.offset(this._offset);
+        if (this.#state.offset) {
+            subQuery.offset(this.#state.offset);
         }
         const addToSelect = [];
-        if (this._orderBy.length > 0) {
+        if (this.#state.orderBy.length > 0) {
             const orderBy = [];
-            for (const orderMap of this._orderBy) {
+            for (const orderMap of this.#state.orderBy) {
                 for (const field of Utils.getObjectQueryKeys(orderMap)) {
                     const direction = orderMap[field];
                     if (RawQueryFragment.isKnownFragmentSymbol(field)) {
@@ -1769,11 +1932,11 @@ export class QueryBuilder {
             }
             subQuery.orderBy(orderBy);
         }
-        subQuery.finalized = true;
+        subQuery.#state.finalized = true;
         const innerQuery = subQuery.as(this.mainAlias.aliasName).clear('select').select(pks);
         if (addToSelect.length > 0) {
             addToSelect.forEach(prop => {
-                const field = this._fields.find(field => {
+                const field = this.#state.fields.find(field => {
                     if (typeof field === 'object' && field && '__as' in field) {
                         return field.__as === prop;
                     }
@@ -1799,18 +1962,20 @@ export class QueryBuilder {
         // https://stackoverflow.com/questions/17892762/mysql-this-version-of-mysql-doesnt-yet-support-limit-in-all-any-some-subqu
         const subSubQuery = this.platform.createNativeQueryBuilder();
         subSubQuery.select(pks).from(innerQuery);
-        this._limit = undefined;
-        this._offset = undefined;
+        this.#state.limit = undefined;
+        this.#state.offset = undefined;
         // Save the original WHERE conditions before pruning joins
-        const originalCond = this._cond;
+        const originalCond = this.#state.cond;
         const populatePaths = this.getPopulatePaths();
-        if (!this._fields.some(field => isRaw(field))) {
+        if (!this.#state.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) } });
+        this.select(this.#state.fields).where({
+            [Utils.getPrimaryKeyHash(meta.primaryKeys)]: { $in: raw(sql, params) },
+        });
     }
     /**
      * Computes the set of populate paths from the _populate hints.
@@ -1827,7 +1992,7 @@ export class QueryBuilder {
                 }
             }
         }
-        addPath(this._populate);
+        addPath(this.#state.populate);
         return paths;
     }
     normalizeJoinPath(join, meta) {
@@ -1839,14 +2004,14 @@ export class QueryBuilder {
      * GH #6160
      */
     transferConditionsForOrderByJoins(meta, cond, populatePaths) {
-        if (!cond || this._orderBy.length === 0) {
+        if (!cond || this.#state.orderBy.length === 0) {
             return;
         }
-        const orderByAliases = new Set(this._orderBy
+        const orderByAliases = new Set(this.#state.orderBy
             .flatMap(hint => Object.keys(hint))
             .filter(k => !RawQueryFragment.isKnownFragmentSymbol(k))
             .map(k => k.split('.')[0]));
-        for (const join of Object.values(this._joins)) {
+        for (const join of Object.values(this.#state.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
@@ -1859,10 +2024,8 @@ export class QueryBuilder {
      * 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 orderByAliases = this.#state.orderBy.flatMap(hint => Object.keys(hint)).map(k => k.split('.')[0]);
+        const joins = Object.entries(this.#state.joins);
         const rootAlias = this.alias;
         function addParentAlias(alias) {
             const join = joins.find(j => j[1].alias === alias);
@@ -1877,7 +2040,7 @@ export class QueryBuilder {
         for (const [key, join] of joins) {
             const path = this.normalizeJoinPath(join, meta);
             if (!populatePaths.has(path) && !orderByAliases.includes(join.alias)) {
-                delete this._joins[key];
+                delete this.#state.joins[key];
             }
         }
     }
@@ -1909,25 +2072,25 @@ export class QueryBuilder {
     }
     wrapModifySubQuery(meta) {
         const subQuery = this.clone();
-        subQuery.finalized = true;
+        subQuery.#state.finalized = true;
         // wrap one more time to get around MySQL limitations
         // 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 method = this.#state.flags.has(QueryFlag.UPDATE_SUB_QUERY) ? 'update' : 'delete';
         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
+        this.#state.cond = {}; // otherwise we would trigger validation error
+        this.#state.joins = {}; // included in the subquery
         subSubQuery.select(pks).from(subQuery.as(this.mainAlias.aliasName));
         const { sql, params } = subSubQuery.compile();
-        this[method](this._data).where({
+        this[method](this.#state.data).where({
             [Utils.getPrimaryKeyHash(meta.primaryKeys)]: { $in: raw(sql, params) },
         });
     }
     getSchema(alias) {
         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);
+        const schema = this.#state.schema ?? metaSchema ?? this.em?.schema ?? this.em?.config.getSchema(true);
         if (schema === this.platform.getDefaultSchemaName()) {
             return undefined;
         }
@@ -1937,35 +2100,51 @@ export class QueryBuilder {
     createAlias(entityName, aliasName, subQuery) {
         const meta = this.metadata.find(entityName);
         const alias = { aliasName, entityName, meta, subQuery };
-        this._aliases[aliasName] = alias;
+        this.#state.aliases[aliasName] = alias;
         return alias;
     }
     createMainAlias(entityName, aliasName, subQuery) {
-        this._mainAlias = this.createAlias(entityName, aliasName, subQuery);
-        this._helper = this.createQueryBuilderHelper();
-        return this._mainAlias;
+        this.#state.mainAlias = this.createAlias(entityName, aliasName, subQuery);
+        this.#helper = this.createQueryBuilderHelper();
+        return this.#state.mainAlias;
     }
     fromSubQuery(target, aliasName) {
-        const subQuery = target.getNativeQuery();
         const { entityName } = target.mainAlias;
         aliasName ??= this.getNextAlias(entityName);
+        const subQuery = target.#state.unionQuery ? target.toRaw() : target.getNativeQuery();
         this.createMainAlias(entityName, aliasName, subQuery);
     }
     fromEntityName(entityName, aliasName) {
-        aliasName ??= this._mainAlias?.aliasName ?? this.getNextAlias(entityName);
+        aliasName ??= this.#state.mainAlias?.aliasName ?? this.getNextAlias(entityName);
         this.createMainAlias(entityName, aliasName);
     }
+    fromRawTable(tableName, aliasName) {
+        aliasName ??= this.#state.mainAlias?.aliasName ?? this.getNextAlias(tableName);
+        const meta = new EntityMetadata({
+            className: tableName,
+            collection: tableName,
+        });
+        meta.root = meta;
+        this.#state.mainAlias = {
+            aliasName,
+            entityName: tableName,
+            meta,
+            rawTableName: tableName,
+        };
+        this.#state.aliases[aliasName] = this.#state.mainAlias;
+        this.#helper = this.createQueryBuilderHelper();
+    }
     createQueryBuilderHelper() {
-        return new QueryBuilderHelper(this.mainAlias.entityName, this.mainAlias.aliasName, this._aliases, this.subQueries, this.driver, this._tptAlias);
+        return new QueryBuilderHelper(this.mainAlias.entityName, this.mainAlias.aliasName, this.#state.aliases, this.#state.subQueries, this.driver, this.#state.tptAlias);
     }
     ensureFromClause() {
         /* v8 ignore next */
-        if (!this._mainAlias) {
+        if (!this.#state.mainAlias) {
             throw new Error(`Cannot proceed to build a query because the main alias is not set.`);
         }
     }
     ensureNotFinalized() {
-        if (this.finalized) {
+        if (this.#state.finalized) {
             throw new Error('This QueryBuilder instance is already finalized, clone it first if you want to modify it.');
         }
     }
@@ -1974,28 +2153,35 @@ export class QueryBuilder {
     [Symbol.for('nodejs.util.inspect.custom')](depth = 2) {
         const object = { ...this };
         const hidden = ['metadata', 'driver', 'context', 'platform', 'type'];
-        Object.keys(object).filter(k => k.startsWith('_')).forEach(k => delete object[k]);
-        Object.keys(object).filter(k => object[k] == null).forEach(k => delete object[k]);
+        Object.keys(object)
+            .filter(k => k.startsWith('_'))
+            .forEach(k => delete object[k]);
+        Object.keys(object)
+            .filter(k => object[k] == null)
+            .forEach(k => delete object[k]);
         hidden.forEach(k => delete object[k]);
         let prefix = this.type ? this.type.substring(0, 1) + this.type.toLowerCase().substring(1) : '';
-        if (this._data) {
-            object.data = this._data;
+        if (this.#state.data) {
+            object.data = this.#state.data;
         }
-        if (this._schema) {
-            object.schema = this._schema;
+        if (this.#state.schema) {
+            object.schema = this.#state.schema;
         }
-        if (!Utils.isEmpty(this._cond)) {
-            object.where = this._cond;
+        if (!Utils.isEmpty(this.#state.cond)) {
+            object.where = this.#state.cond;
         }
-        if (this._onConflict?.[0]) {
+        if (this.#state.onConflict?.[0]) {
             prefix = 'Upsert';
-            object.onConflict = this._onConflict[0];
+            object.onConflict = this.#state.onConflict[0];
         }
-        if (!Utils.isEmpty(this._orderBy)) {
-            object.orderBy = this._orderBy;
+        if (!Utils.isEmpty(this.#state.orderBy)) {
+            object.orderBy = this.#state.orderBy;
         }
-        const name = this._mainAlias ? `${prefix}QueryBuilder<${Utils.className(this._mainAlias?.entityName)}>` : 'QueryBuilder';
+        const name = this.#state.mainAlias
+            ? `${prefix}QueryBuilder<${Utils.className(this.#state.mainAlias?.entityName)}>`
+            : 'QueryBuilder';
         const ret = inspect(object, { depth });
         return ret === '[Object]' ? `[${name}]` : name + ' ' + ret;
     }
 }
+_a = QueryBuilder;