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

package/query/ObjectCriteriaNode.js

@@ -7,7 +7,8 @@ const COLLECTION_OPERATORS = ['$some', '$none', '$every', '$size'];
  */
 export class ObjectCriteriaNode extends CriteriaNode {
     process(qb, options) {
-        const matchPopulateJoins = options?.matchPopulateJoins || (this.prop && [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(this.prop.kind));
+        const matchPopulateJoins = options?.matchPopulateJoins ||
+            (this.prop && [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(this.prop.kind));
         const nestedAlias = qb.getAliasForJoinPath(this.getPath(options), { ...options, matchPopulateJoins });
         const ownerAlias = options?.alias || qb.alias;
         const keys = Utils.getObjectQueryKeys(this.payload);
@@ -20,13 +21,15 @@ export class ObjectCriteriaNode extends CriteriaNode {
                 if (![ReferenceKind.MANY_TO_MANY, ReferenceKind.ONE_TO_MANY].includes(this.prop.kind)) {
                     // ignore collection operators when used on a non-relational property - this can happen when they get into
                     // populateWhere via `infer` on m:n properties with select-in strategy
-                    if (this.parent?.parent) { // we validate only usage on top level
+                    if (this.parent?.parent) {
+                        // we validate only usage on top level
                         return {};
                     }
                     throw new Error(`Collection operators can be used only inside a collection property context, but it was used for ${this.getPath()}.`);
                 }
                 const $and = [];
-                const knownKey = [ReferenceKind.SCALAR, ReferenceKind.MANY_TO_ONE, ReferenceKind.EMBEDDED].includes(this.prop.kind) || (this.prop.kind === ReferenceKind.ONE_TO_ONE && this.prop.owner);
+                const knownKey = [ReferenceKind.SCALAR, ReferenceKind.MANY_TO_ONE, ReferenceKind.EMBEDDED].includes(this.prop.kind) ||
+                    (this.prop.kind === ReferenceKind.ONE_TO_ONE && this.prop.owner);
                 const parentMeta = this.metadata.find(this.parent.entityName);
                 const primaryKeys = parentMeta.primaryKeys.map(pk => {
                     return [QueryType.SELECT, QueryType.COUNT].includes(qb.type) ? `${knownKey ? alias : ownerAlias}.${pk}` : pk;
@@ -48,7 +51,9 @@ export class ObjectCriteriaNode extends CriteriaNode {
                         const pks = this.prop.referencedColumnNames;
                         const countExpr = raw(`count(${pks.map(() => '??').join(', ')})`, pks.map(pk => `${joinAlias}.${pk}`));
                         sub.groupBy(parentMeta.primaryKeys);
-                        sub.having({ $and: Object.keys(sizeCondition).map(op => ({ [countExpr]: { [op]: sizeCondition[op] } })) });
+                        sub.having({
+                            $and: Object.keys(sizeCondition).map(op => ({ [countExpr]: { [op]: sizeCondition[op] } })),
+                        });
                     }
                     else if (key === '$every') {
                         sub.where({ $not: { [this.key]: payload } });
@@ -111,7 +116,11 @@ export class ObjectCriteriaNode extends CriteriaNode {
                 // use '??' placeholder to properly quote the identifier
                 o[raw('??', [field])] = payload;
             }
-            else if (primaryKey || virtual || operator || field.includes('.') || ![QueryType.SELECT, QueryType.COUNT].includes(qb.type)) {
+            else if (primaryKey ||
+                virtual ||
+                operator ||
+                field.includes('.') ||
+                ![QueryType.SELECT, QueryType.COUNT].includes(qb.type)) {
                 this.inlineCondition(field.replaceAll(ALIAS_REPLACEMENT, alias), o, payload);
             }
             else {
@@ -121,9 +130,10 @@ export class ObjectCriteriaNode extends CriteriaNode {
         }, {});
     }
     isStrict() {
-        return this.strict || Utils.getObjectQueryKeys(this.payload).some(key => {
-            return this.payload[key].isStrict();
-        });
+        return (this.strict ||
+            Utils.getObjectQueryKeys(this.payload).some(key => {
+                return this.payload[key].isStrict();
+            }));
     }
     unwrap() {
         return Utils.getObjectQueryKeys(this.payload).reduce((o, field) => {
@@ -148,8 +158,18 @@ export class ObjectCriteriaNode extends CriteriaNode {
     }
     shouldInline(payload) {
         const rawField = RawQueryFragment.isKnownFragmentSymbol(this.key);
-        const scalar = Utils.isPrimaryKey(payload) || payload instanceof RegExp || payload instanceof Date || rawField;
-        const operator = Utils.isObject(payload) && Utils.getObjectQueryKeys(payload).every(k => Utils.isOperator(k, false));
+        const scalar = Utils.isPrimaryKey(payload) ||
+            payload instanceof RegExp ||
+            payload instanceof Date ||
+            rawField;
+        const operator = Utils.isObject(payload) &&
+            Utils.getObjectQueryKeys(payload).every(k => {
+                if (k === '$not' && Utils.isPlainObject(payload[k])) {
+                    // $not wrapping non-operator conditions (entity props) should be inlined
+                    return Utils.getObjectQueryKeys(payload[k]).every(ik => Utils.isOperator(ik, false));
+                }
+                return Utils.isOperator(k, false);
+            });
         return !!this.prop && this.prop.kind !== ReferenceKind.SCALAR && !scalar && !operator;
     }
     getChildKey(k, prop, childAlias, alias) {
@@ -161,7 +181,9 @@ export class ObjectCriteriaNode extends CriteriaNode {
     inlineArrayChildPayload(obj, payload, k, prop, childAlias, alias) {
         const key = this.getChildKey(k, prop, childAlias);
         const value = payload.map((child) => Utils.getObjectQueryKeys(child).reduce((inner, childKey) => {
-            const key = (RawQueryFragment.isKnownFragmentSymbol(childKey) || this.isPrefixed(childKey) || Utils.isOperator(childKey)) ? childKey : this.aliased(childKey, childAlias);
+            const key = RawQueryFragment.isKnownFragmentSymbol(childKey) || this.isPrefixed(childKey) || Utils.isOperator(childKey)
+                ? childKey
+                : this.aliased(childKey, childAlias);
             inner[key] = child[childKey];
             return inner;
         }, {}));
@@ -173,6 +195,12 @@ export class ObjectCriteriaNode extends CriteriaNode {
             if (RawQueryFragment.isKnownFragmentSymbol(k)) {
                 o[k] = payload[k];
             }
+            else if (k === '$not' &&
+                Utils.isPlainObject(payload[k]) &&
+                Utils.getObjectQueryKeys(payload[k]).some(ik => !Utils.isOperator(ik, false))) {
+                // $not wraps entity conditions (from auto-join), inline at current level
+                this.inlineCondition(k, o, payload[k]);
+            }
             else if (Utils.isOperator(k, false)) {
                 const tmp = payload[k];
                 delete payload[k];
@@ -218,24 +246,42 @@ export class ObjectCriteriaNode extends CriteriaNode {
         }
         const meta = this.metadata.find(this.entityName);
         const embeddable = this.prop.kind === ReferenceKind.EMBEDDED;
-        const knownKey = [ReferenceKind.SCALAR, ReferenceKind.MANY_TO_ONE, ReferenceKind.EMBEDDED].includes(this.prop.kind) || (this.prop.kind === ReferenceKind.ONE_TO_ONE && this.prop.owner);
-        const operatorKeys = knownKey && keys.every(key => Utils.isOperator(key, false));
-        const primaryKeys = knownKey && keys.every(key => {
-            if (typeof key !== 'string' || !meta.primaryKeys.includes(key)) {
-                return false;
-            }
-            if (!Utils.isPlainObject(this.payload[key].payload) || ![ReferenceKind.ONE_TO_ONE, ReferenceKind.MANY_TO_ONE].includes(meta.properties[key].kind)) {
-                return true;
-            }
-            return Utils.getObjectQueryKeys(this.payload[key].payload).every(k => typeof k === 'string' && meta.properties[key].targetMeta.primaryKeys.includes(k));
-        });
+        const knownKey = [ReferenceKind.SCALAR, ReferenceKind.MANY_TO_ONE, ReferenceKind.EMBEDDED].includes(this.prop.kind) ||
+            (this.prop.kind === ReferenceKind.ONE_TO_ONE && this.prop.owner);
+        const operatorKeys = knownKey &&
+            keys.every(key => {
+                if (key === '$not') {
+                    // $not wraps conditions like $and/$or, check if it wraps entity property conditions (needs auto-join)
+                    // vs simple operator conditions on the FK (doesn't need auto-join)
+                    const childPayload = this.payload[key].payload;
+                    if (Utils.isPlainObject(childPayload)) {
+                        return Utils.getObjectQueryKeys(childPayload).every(k => Utils.isOperator(k, false));
+                    }
+                }
+                return Utils.isOperator(key, false);
+            });
+        const primaryKeys = knownKey &&
+            keys.every(key => {
+                if (typeof key !== 'string' || !meta.primaryKeys.includes(key)) {
+                    return false;
+                }
+                if (!Utils.isPlainObject(this.payload[key].payload) ||
+                    ![ReferenceKind.ONE_TO_ONE, ReferenceKind.MANY_TO_ONE].includes(meta.properties[key].kind)) {
+                    return true;
+                }
+                return Utils.getObjectQueryKeys(this.payload[key].payload).every(k => typeof k === 'string' && meta.properties[key].targetMeta.primaryKeys.includes(k));
+            });
         return !primaryKeys && !nestedAlias && !operatorKeys && !embeddable;
     }
     autoJoin(qb, alias, options) {
         const nestedAlias = qb.getNextAlias(this.prop?.pivotEntity ?? this.entityName);
         const rawField = RawQueryFragment.isKnownFragmentSymbol(this.key);
-        const scalar = Utils.isPrimaryKey(this.payload) || this.payload instanceof RegExp || this.payload instanceof Date || rawField;
-        const operator = Utils.isPlainObject(this.payload) && Utils.getObjectQueryKeys(this.payload).every(k => Utils.isOperator(k, false));
+        const scalar = Utils.isPrimaryKey(this.payload) ||
+            this.payload instanceof RegExp ||
+            this.payload instanceof Date ||
+            rawField;
+        const operator = Utils.isPlainObject(this.payload) &&
+            Utils.getObjectQueryKeys(this.payload).every(k => Utils.isOperator(k, false));
         const field = `${alias}.${this.prop.name}`;
         const method = qb.hasFlag(QueryFlag.INFER_POPULATE) ? 'joinAndSelect' : 'join';
         const path = this.getPath();
@@ -245,9 +291,7 @@ export class ObjectCriteriaNode extends CriteriaNode {
         else {
             const prev = qb._fields?.slice();
             const toOneProperty = [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(this.prop.kind);
-            const joinType = toOneProperty && !this.prop.nullable
-                ? JoinType.innerJoin
-                : JoinType.leftJoin;
+            const joinType = toOneProperty && !this.prop.nullable ? JoinType.innerJoin : JoinType.leftJoin;
             qb[method](field, nestedAlias, undefined, joinType, path);
             if (!qb.hasFlag(QueryFlag.INFER_POPULATE)) {
                 qb._fields = prev;

package/query/QueryBuilder.d.ts

@@ -1,11 +1,11 @@
-import { type AnyEntity, type AutoPath, type ConnectionType, type Dictionary, type EntityData, type EntityKey, type EntityManager, type EntityMetadata, type EntityName, type EntityProperty, type ExpandProperty, type FilterObject, type FilterOptions, type FilterValue, type FlushMode, type GroupOperator, type Loaded, LockMode, type LoggingOptions, type MetadataStorage, type ObjectQuery, PopulateHint, type PopulateOptions, type PopulatePath, QueryFlag, type QueryOrderKeysFlat, type QueryOrderMap, type QueryResult, RawQueryFragment, type Raw, type RequiredEntityData, type Scalar, type Subquery, type Transaction } from '@mikro-orm/core';
+import { type AnyEntity, type AutoPath, type Collection, type ConnectionType, type Dictionary, type EntityData, type EntityDTOFlat, type EntityDTOProp, type EntityKey, type EntityManager, EntityMetadata, type EntityName, type EntityProperty, type ExpandProperty, type FilterObject, type FilterOptions, type FilterValue, type FlushMode, type GroupOperator, type Loaded, LockMode, type LoggingOptions, type MetadataStorage, type PrimaryProperty, type ObjectQuery, PopulateHint, type PopulateOptions, type PopulatePath, QueryFlag, type QueryOrderKeysFlat, type QueryOrderMap, type QueryResult, RawQueryFragment, type Raw, type RequiredEntityData, type Scalar, type SerializeDTO, type Subquery, type Transaction } from '@mikro-orm/core';
 import { JoinType, QueryType } from './enums.js';
 import type { AbstractSqlDriver } from '../AbstractSqlDriver.js';
 import { type Alias, type OnConflictClause, QueryBuilderHelper } from './QueryBuilderHelper.js';
 import type { SqlEntityManager } from '../SqlEntityManager.js';
 import type { ICriteriaNodeProcessOptions, InternalField, JoinOptions } from '../typings.js';
 import type { AbstractSqlPlatform } from '../AbstractSqlPlatform.js';
-import { NativeQueryBuilder } from './NativeQueryBuilder.js';
+import { type CteOptions, NativeQueryBuilder } from './NativeQueryBuilder.js';
 export interface ExecuteOptions {
     mapResults?: boolean;
     mergeResults?: boolean;
@@ -84,7 +84,7 @@ type RawOrderKeys<RawAliases extends string> = {
 export type ContextOrderByMap<Entity, RootAlias extends string = never, Context = never, RawAliases extends string = never> = QueryOrderMap<Entity> | ((IsNever<RootAlias> extends true ? {} : RootAliasOrderKeys<RootAlias, Entity>) & ([Context] extends [never] ? {} : ContextOrderKeys<Context>) & (IsNever<RawAliases> extends true ? {} : string extends RawAliases ? {} : RawOrderKeys<RawAliases>));
 type AliasedPath<Alias extends string, Type, P extends string> = P extends `${Alias}.*` ? P : P extends `${Alias}.${infer Rest}` ? `${Alias}.${AutoPath<Type & object, Rest, `${PopulatePath.ALL}`>}` : never;
 type ContextAliasedPath<Context, P extends string> = Context[keyof Context] extends infer Join ? Join extends any ? Join extends [string, infer Alias, infer Type, any] ? AliasedPath<Alias & string, Type, P> : never : never : never;
-type NestedAutoPath<Entity, RootAlias extends string, Context, P extends string> = P extends `${string}:ref` ? never : P extends `${infer Path} as ${string}` ? (AliasedPath<RootAlias, Entity, Path> | ContextAliasedPath<Context, Path> | AutoPath<Entity, Path, `${PopulatePath.ALL}`>) extends never ? never : P : AliasedPath<RootAlias, Entity, P> | ContextAliasedPath<Context, P> | AutoPath<Entity, P, `${PopulatePath.ALL}`>;
+type NestedAutoPath<Entity, RootAlias extends string, Context, P extends string> = P extends `${string}:ref` ? never : P extends `${infer Path} as ${string}` ? AliasedPath<RootAlias, Entity, Path> | ContextAliasedPath<Context, Path> | AutoPath<Entity, Path, `${PopulatePath.ALL}`> extends never ? never : P : AliasedPath<RootAlias, Entity, P> | ContextAliasedPath<Context, P> | AutoPath<Entity, P, `${PopulatePath.ALL}`>;
 type AliasedObjectQuery<Entity extends object, Alias extends string> = {
     [K in EntityKey<Entity> as `${Alias}.${K}`]?: ObjectQuery<Entity>[K];
 };
@@ -96,7 +96,7 @@ type JoinCondition<JoinedEntity extends object, Alias extends string> = (ObjectQ
 type RawJoinCondition = {
     [key: string]: FilterValue<Scalar> | RawQueryFragment;
 };
-type ExtractRawAliasFromField<F> = F extends RawQueryFragment<infer A> ? (A extends string ? A : never) : F extends `${string} as ${infer A}` ? A : never;
+type ExtractRawAliasFromField<F> = F extends RawQueryFragment<infer A> ? A extends string ? A : never : F extends `${string} as ${infer A}` ? A : never;
 type ExtractRawAliasesFromTuple<T extends readonly unknown[]> = T extends readonly [infer Head, ...infer Tail] ? ExtractRawAliasFromField<Head> | ExtractRawAliasesFromTuple<Tail> : never;
 type ExtractRawAliases<Fields> = Fields extends readonly unknown[] ? ExtractRawAliasesFromTuple<Fields> : ExtractRawAliasFromField<Fields>;
 type FlatOperatorMap = {
@@ -158,7 +158,7 @@ export type QBFilterQuery<Entity, RootAlias extends string = never, Context = ne
  * const publisher = await qb.getSingleResult();
  * ```
  */
-export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias extends string = never, Hint extends string = never, Context extends object = never, RawAliases extends string = never, Fields extends string = '*'> implements Subquery {
+export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias extends string = never, Hint extends string = never, Context extends object = never, RawAliases extends string = never, Fields extends string = '*', CTEs extends Record<string, object> = {}> implements Subquery {
     protected readonly metadata: MetadataStorage;
     protected readonly driver: AbstractSqlDriver;
     protected readonly context?: Transaction | undefined;
@@ -220,6 +220,15 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
         params?: readonly unknown[];
         qb: NativeQueryBuilder;
     };
+    protected _unionQuery?: {
+        sql: string;
+        params: readonly unknown[];
+    };
+    protected _ctes: (CteOptions & {
+        name: string;
+        query: NativeQueryBuilder | RawQueryFragment;
+        recursive?: boolean;
+    })[];
     protected readonly platform: AbstractSqlPlatform;
     private tptJoinsApplied;
     private readonly autoJoinedPaths;
@@ -247,7 +256,7 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      * qb.select('*', true);
      * ```
      */
-    select<const F extends readonly Field<Entity, RootAlias, Context>[]>(fields: F, distinct?: boolean): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases | ExtractRawAliases<F>, ExtractRootFields<F[number] & string, RootAlias, Context>>;
+    select<const F extends readonly Field<Entity, RootAlias, Context>[]>(fields: F, distinct?: boolean): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases | ExtractRawAliases<F>, ExtractRootFields<F[number] & string, RootAlias, Context>, CTEs>;
     /**
      * Creates a SELECT query, specifying the fields to retrieve.
      *
@@ -264,7 +273,7 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      * qb.select('*', true);
      * ```
      */
-    select<const P extends string>(fields: readonly NestedAutoPath<Entity, RootAlias, Context, P>[], distinct?: boolean): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, ExtractRootFields<P, RootAlias, Context>>;
+    select<const P extends string>(fields: readonly NestedAutoPath<Entity, RootAlias, Context, P>[], distinct?: boolean): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, ExtractRootFields<P, RootAlias, Context>, CTEs>;
     /**
      * Creates a SELECT query, specifying the fields to retrieve.
      *
@@ -275,7 +284,7 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      * qb.select('address.city');
      * ```
      */
-    select<const P extends string>(fields: NestedAutoPath<Entity, RootAlias, Context, P>, distinct?: boolean): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, ExtractRootFields<P, RootAlias, Context>>;
+    select<const P extends string>(fields: NestedAutoPath<Entity, RootAlias, Context, P>, distinct?: boolean): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, ExtractRootFields<P, RootAlias, Context>, CTEs>;
     /**
      * Creates a SELECT query, specifying the fields to retrieve.
      *
@@ -292,16 +301,16 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      * qb.select('*', true);
      * ```
      */
-    select<const F extends Field<Entity, RootAlias, Context>>(fields: F, distinct?: boolean): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases | ExtractRawAliases<readonly [F]>, ExtractRootFields<F & string, RootAlias, Context>>;
+    select<const F extends Field<Entity, RootAlias, Context>>(fields: F, distinct?: boolean): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases | ExtractRawAliases<readonly [F]>, ExtractRootFields<F & string, RootAlias, Context>, CTEs>;
     /**
      * Adds fields to an existing SELECT query.
      */
-    addSelect<const F extends Field<Entity, RootAlias, Context> | readonly Field<Entity, RootAlias, Context>[]>(fields: F): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases | ExtractRawAliases<F extends readonly unknown[] ? F : [F]>, Fields | ExtractRootFields<F extends readonly (infer U)[] ? U & string : F & string, RootAlias, Context>>;
-    distinct(): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>;
+    addSelect<const F extends Field<Entity, RootAlias, Context> | readonly Field<Entity, RootAlias, Context>[]>(fields: F): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases | ExtractRawAliases<F extends readonly unknown[] ? F : [F]>, Fields | ExtractRootFields<F extends readonly (infer U)[] ? U & string : F & string, RootAlias, Context>, CTEs>;
+    distinct(): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields, CTEs>;
     /** postgres only */
-    distinctOn<const F extends readonly Field<Entity, RootAlias, Context>[]>(fields: F): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>;
+    distinctOn<const F extends readonly Field<Entity, RootAlias, Context>[]>(fields: F): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields, CTEs>;
     /** postgres only */
-    distinctOn<F extends Field<Entity, RootAlias, Context>>(fields: F): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>;
+    distinctOn<F extends Field<Entity, RootAlias, Context>>(fields: F): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields, CTEs>;
     /**
      * Creates an INSERT query with the given data.
      *
@@ -376,29 +385,29 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      *   .where({ 'a.name': 'John' });
      * ```
      */
-    join<Field extends QBField<Entity, RootAlias, Context>, Alias extends string>(field: Field, alias: Alias, cond?: JoinCondition<JoinedEntityType<Entity, Context, Field & string>, Alias>, type?: JoinType, path?: string, schema?: string): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field> & {}, ModifyContext<Entity, Context, Field, Alias>, RawAliases>;
+    join<Field extends QBField<Entity, RootAlias, Context>, Alias extends string>(field: Field, alias: Alias, cond?: JoinCondition<JoinedEntityType<Entity, Context, Field & string>, Alias>, type?: JoinType, path?: string, schema?: string): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field> & {}, ModifyContext<Entity, Context, Field, Alias>, RawAliases, '*', CTEs>;
     /**
      * Adds a JOIN clause to the query for a subquery.
      */
-    join<Alias extends string>(field: RawQueryFragment | QueryBuilder<any>, alias: Alias, cond?: RawJoinCondition, type?: JoinType, path?: string, schema?: string): SelectQueryBuilder<Entity, RootAlias, Hint, ModifyContext<Entity, Context, string, Alias>, RawAliases>;
+    join<Alias extends string>(field: RawQueryFragment | QueryBuilder<any>, alias: Alias, cond?: RawJoinCondition, type?: JoinType, path?: string, schema?: string): SelectQueryBuilder<Entity, RootAlias, Hint, ModifyContext<Entity, Context, string, Alias>, RawAliases, '*', CTEs>;
     /**
      * Adds an INNER JOIN clause to the query for an entity relation.
      */
-    innerJoin<Field extends QBField<Entity, RootAlias, Context>, Alias extends string>(field: Field, alias: Alias, cond?: JoinCondition<JoinedEntityType<Entity, Context, Field & string>, Alias>, schema?: string): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field> & {}, ModifyContext<Entity, Context, Field, Alias>, RawAliases>;
+    innerJoin<Field extends QBField<Entity, RootAlias, Context>, Alias extends string>(field: Field, alias: Alias, cond?: JoinCondition<JoinedEntityType<Entity, Context, Field & string>, Alias>, schema?: string): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field> & {}, ModifyContext<Entity, Context, Field, Alias>, RawAliases, '*', CTEs>;
     /**
      * Adds an INNER JOIN clause to the query for a subquery.
      */
-    innerJoin<Alias extends string>(field: RawQueryFragment | QueryBuilder<any>, alias: Alias, cond?: RawJoinCondition, schema?: string): SelectQueryBuilder<Entity, RootAlias, Hint, ModifyContext<Entity, Context, string, Alias>, RawAliases>;
-    innerJoinLateral<Alias extends string>(field: RawQueryFragment | QueryBuilder<any>, alias: Alias, cond?: RawJoinCondition, schema?: string): SelectQueryBuilder<Entity, RootAlias, Hint, ModifyContext<Entity, Context, string, Alias>, RawAliases>;
+    innerJoin<Alias extends string>(field: RawQueryFragment | QueryBuilder<any>, alias: Alias, cond?: RawJoinCondition, schema?: string): SelectQueryBuilder<Entity, RootAlias, Hint, ModifyContext<Entity, Context, string, Alias>, RawAliases, '*', CTEs>;
+    innerJoinLateral<Alias extends string>(field: RawQueryFragment | QueryBuilder<any>, alias: Alias, cond?: RawJoinCondition, schema?: string): SelectQueryBuilder<Entity, RootAlias, Hint, ModifyContext<Entity, Context, string, Alias>, RawAliases, '*', CTEs>;
     /**
      * Adds a LEFT JOIN clause to the query for an entity relation.
      */
-    leftJoin<Field extends QBField<Entity, RootAlias, Context>, Alias extends string>(field: Field, alias: Alias, cond?: JoinCondition<JoinedEntityType<Entity, Context, Field & string>, Alias>, schema?: string): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field> & {}, ModifyContext<Entity, Context, Field, Alias>, RawAliases>;
+    leftJoin<Field extends QBField<Entity, RootAlias, Context>, Alias extends string>(field: Field, alias: Alias, cond?: JoinCondition<JoinedEntityType<Entity, Context, Field & string>, Alias>, schema?: string): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field> & {}, ModifyContext<Entity, Context, Field, Alias>, RawAliases, '*', CTEs>;
     /**
      * Adds a LEFT JOIN clause to the query for a subquery.
      */
-    leftJoin<Alias extends string>(field: RawQueryFragment | QueryBuilder<any>, alias: Alias, cond?: RawJoinCondition, schema?: string): SelectQueryBuilder<Entity, RootAlias, Hint, ModifyContext<Entity, Context, string, Alias>, RawAliases>;
-    leftJoinLateral<Alias extends string>(field: RawQueryFragment | QueryBuilder<any>, alias: Alias, cond?: RawJoinCondition, schema?: string): SelectQueryBuilder<Entity, RootAlias, Hint, ModifyContext<Entity, Context, string, Alias>, RawAliases>;
+    leftJoin<Alias extends string>(field: RawQueryFragment | QueryBuilder<any>, alias: Alias, cond?: RawJoinCondition, schema?: string): SelectQueryBuilder<Entity, RootAlias, Hint, ModifyContext<Entity, Context, string, Alias>, RawAliases, '*', CTEs>;
+    leftJoinLateral<Alias extends string>(field: RawQueryFragment | QueryBuilder<any>, alias: Alias, cond?: RawJoinCondition, schema?: string): SelectQueryBuilder<Entity, RootAlias, Hint, ModifyContext<Entity, Context, string, Alias>, RawAliases, '*', CTEs>;
     /**
      * Adds a JOIN clause and automatically selects the joined entity's fields.
      * This is useful for eager loading related entities.
@@ -411,11 +420,26 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      *   .where({ 'a.name': 'John' });
      * ```
      */
-    joinAndSelect<Field extends QBField<Entity, RootAlias, Context>, Alias extends string, const JoinFields extends readonly [JoinSelectField<JoinedEntityType<Entity, Context, Field & string>, Alias>, ...JoinSelectField<JoinedEntityType<Entity, Context, Field & string>, Alias>[]] | undefined = undefined>(field: Field | [Field, RawQueryFragment | QueryBuilder<any>], alias: Alias, cond?: JoinCondition<JoinedEntityType<Entity, Context, Field & string>, Alias>, type?: JoinType, path?: string, fields?: JoinFields, schema?: string): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field, true> & {}, ModifyContext<Entity, Context, Field, Alias, true>, RawAliases, ModifyFields<Fields, RootAlias, Context, Field, Alias, JoinFields>>;
-    leftJoinAndSelect<Field extends QBField<Entity, RootAlias, Context>, Alias extends string, const JoinFields extends readonly [JoinSelectField<JoinedEntityType<Entity, Context, Field & string>, Alias>, ...JoinSelectField<JoinedEntityType<Entity, Context, Field & string>, Alias>[]] | undefined = undefined>(field: Field | [Field, RawQueryFragment | QueryBuilder<any>], alias: Alias, cond?: JoinCondition<JoinedEntityType<Entity, Context, Field & string>, Alias>, fields?: JoinFields, schema?: string): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field, true> & {}, ModifyContext<Entity, Context, Field, Alias, true>, RawAliases, ModifyFields<Fields, RootAlias, Context, Field, Alias, JoinFields>>;
-    leftJoinLateralAndSelect<Field extends QBField<Entity, RootAlias, Context>, Alias extends string, const JoinFields extends readonly [JoinSelectField<JoinedEntityType<Entity, Context, Field & string>, Alias>, ...JoinSelectField<JoinedEntityType<Entity, Context, Field & string>, Alias>[]] | undefined = undefined>(field: [Field, RawQueryFragment | QueryBuilder<any>], alias: Alias, cond?: JoinCondition<JoinedEntityType<Entity, Context, Field & string>, Alias>, fields?: JoinFields, schema?: string): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field, true> & {}, ModifyContext<Entity, Context, Field, Alias, true>, RawAliases, ModifyFields<Fields, RootAlias, Context, Field, Alias, JoinFields>>;
-    innerJoinAndSelect<Field extends QBField<Entity, RootAlias, Context>, Alias extends string, const JoinFields extends readonly [JoinSelectField<JoinedEntityType<Entity, Context, Field & string>, Alias>, ...JoinSelectField<JoinedEntityType<Entity, Context, Field & string>, Alias>[]] | undefined = undefined>(field: Field | [Field, RawQueryFragment | QueryBuilder<any>], alias: Alias, cond?: JoinCondition<JoinedEntityType<Entity, Context, Field & string>, Alias>, fields?: JoinFields, schema?: string): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field, true> & {}, ModifyContext<Entity, Context, Field, Alias, true>, RawAliases, ModifyFields<Fields, RootAlias, Context, Field, Alias, JoinFields>>;
-    innerJoinLateralAndSelect<Field extends QBField<Entity, RootAlias, Context>, Alias extends string, const JoinFields extends readonly [JoinSelectField<JoinedEntityType<Entity, Context, Field & string>, Alias>, ...JoinSelectField<JoinedEntityType<Entity, Context, Field & string>, Alias>[]] | undefined = undefined>(field: [Field, RawQueryFragment | QueryBuilder<any>], alias: Alias, cond?: JoinCondition<JoinedEntityType<Entity, Context, Field & string>, Alias>, fields?: JoinFields, schema?: string): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field, true> & {}, ModifyContext<Entity, Context, Field, Alias, true>, RawAliases, ModifyFields<Fields, RootAlias, Context, Field, Alias, JoinFields>>;
+    joinAndSelect<Field extends QBField<Entity, RootAlias, Context>, Alias extends string, const JoinFields extends readonly [
+        JoinSelectField<JoinedEntityType<Entity, Context, Field & string>, Alias>,
+        ...JoinSelectField<JoinedEntityType<Entity, Context, Field & string>, Alias>[]
+    ] | undefined = undefined>(field: Field | [Field, RawQueryFragment | QueryBuilder<any>], alias: Alias, cond?: JoinCondition<JoinedEntityType<Entity, Context, Field & string>, Alias>, type?: JoinType, path?: string, fields?: JoinFields, schema?: string): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field, true> & {}, ModifyContext<Entity, Context, Field, Alias, true>, RawAliases, ModifyFields<Fields, RootAlias, Context, Field, Alias, JoinFields>, CTEs>;
+    leftJoinAndSelect<Field extends QBField<Entity, RootAlias, Context>, Alias extends string, const JoinFields extends readonly [
+        JoinSelectField<JoinedEntityType<Entity, Context, Field & string>, Alias>,
+        ...JoinSelectField<JoinedEntityType<Entity, Context, Field & string>, Alias>[]
+    ] | undefined = undefined>(field: Field | [Field, RawQueryFragment | QueryBuilder<any>], alias: Alias, cond?: JoinCondition<JoinedEntityType<Entity, Context, Field & string>, Alias>, fields?: JoinFields, schema?: string): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field, true> & {}, ModifyContext<Entity, Context, Field, Alias, true>, RawAliases, ModifyFields<Fields, RootAlias, Context, Field, Alias, JoinFields>, CTEs>;
+    leftJoinLateralAndSelect<Field extends QBField<Entity, RootAlias, Context>, Alias extends string, const JoinFields extends readonly [
+        JoinSelectField<JoinedEntityType<Entity, Context, Field & string>, Alias>,
+        ...JoinSelectField<JoinedEntityType<Entity, Context, Field & string>, Alias>[]
+    ] | undefined = undefined>(field: [Field, RawQueryFragment | QueryBuilder<any>], alias: Alias, cond?: JoinCondition<JoinedEntityType<Entity, Context, Field & string>, Alias>, fields?: JoinFields, schema?: string): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field, true> & {}, ModifyContext<Entity, Context, Field, Alias, true>, RawAliases, ModifyFields<Fields, RootAlias, Context, Field, Alias, JoinFields>, CTEs>;
+    innerJoinAndSelect<Field extends QBField<Entity, RootAlias, Context>, Alias extends string, const JoinFields extends readonly [
+        JoinSelectField<JoinedEntityType<Entity, Context, Field & string>, Alias>,
+        ...JoinSelectField<JoinedEntityType<Entity, Context, Field & string>, Alias>[]
+    ] | undefined = undefined>(field: Field | [Field, RawQueryFragment | QueryBuilder<any>], alias: Alias, cond?: JoinCondition<JoinedEntityType<Entity, Context, Field & string>, Alias>, fields?: JoinFields, schema?: string): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field, true> & {}, ModifyContext<Entity, Context, Field, Alias, true>, RawAliases, ModifyFields<Fields, RootAlias, Context, Field, Alias, JoinFields>, CTEs>;
+    innerJoinLateralAndSelect<Field extends QBField<Entity, RootAlias, Context>, Alias extends string, const JoinFields extends readonly [
+        JoinSelectField<JoinedEntityType<Entity, Context, Field & string>, Alias>,
+        ...JoinSelectField<JoinedEntityType<Entity, Context, Field & string>, Alias>[]
+    ] | undefined = undefined>(field: [Field, RawQueryFragment | QueryBuilder<any>], alias: Alias, cond?: JoinCondition<JoinedEntityType<Entity, Context, Field & string>, Alias>, fields?: JoinFields, schema?: string): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field, true> & {}, ModifyContext<Entity, Context, Field, Alias, true>, RawAliases, ModifyFields<Fields, RootAlias, Context, Field, Alias, JoinFields>, CTEs>;
     protected getFieldsForJoinedLoad(prop: EntityProperty<Entity>, alias: string, explicitFields?: readonly string[]): InternalField<Entity>[];
     /**
      * Apply filters to the QB where condition.
@@ -518,7 +542,7 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      * qb.orderBy({ 'profile.bio': 'asc' }); // nested via dot notation
      * ```
      */
-    orderBy(orderBy: ContextOrderByMap<Entity, RootAlias, Context, RawAliases> | ContextOrderByMap<Entity, RootAlias, Context, RawAliases>[]): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>;
+    orderBy(orderBy: ContextOrderByMap<Entity, RootAlias, Context, RawAliases> | ContextOrderByMap<Entity, RootAlias, Context, RawAliases>[]): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields, CTEs>;
     /**
      * Adds an ORDER BY clause to the query, replacing any existing order.
      *
@@ -531,18 +555,18 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      * ```
      */
     orderBy<const T extends Record<string, QueryOrderKeysFlat>>(orderBy: T & {
-        [K in keyof T]: K extends NestedAutoPath<Entity, RootAlias, Context, K & string> ? T[K] : (K extends RawAliases ? T[K] : never);
-    }): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>;
+        [K in keyof T]: K extends NestedAutoPath<Entity, RootAlias, Context, K & string> ? T[K] : K extends RawAliases ? T[K] : never;
+    }): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields, CTEs>;
     /**
      * Adds additional ORDER BY clause without replacing existing order.
      */
-    andOrderBy(orderBy: ContextOrderByMap<Entity, RootAlias, Context, RawAliases> | ContextOrderByMap<Entity, RootAlias, Context, RawAliases>[]): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>;
+    andOrderBy(orderBy: ContextOrderByMap<Entity, RootAlias, Context, RawAliases> | ContextOrderByMap<Entity, RootAlias, Context, RawAliases>[]): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields, CTEs>;
     /**
      * Adds additional ORDER BY clause without replacing existing order.
      */
     andOrderBy<const T extends Record<string, QueryOrderKeysFlat>>(orderBy: T & {
-        [K in keyof T]: K extends NestedAutoPath<Entity, RootAlias, Context, K & string> ? T[K] : (K extends RawAliases ? T[K] : never);
-    }): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>;
+        [K in keyof T]: K extends NestedAutoPath<Entity, RootAlias, Context, K & string> ? T[K] : K extends RawAliases ? T[K] : never;
+    }): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields, CTEs>;
     private processOrderBy;
     /** Collect custom aliases from select fields (stored as 'resolved as alias' strings by select()). */
     private getSelectAliases;
@@ -555,7 +579,7 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      *   .groupBy('status');
      * ```
      */
-    groupBy<const F extends readonly Field<Entity, RootAlias, Context>[]>(fields: F): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>;
+    groupBy<const F extends readonly Field<Entity, RootAlias, Context>[]>(fields: F): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields, CTEs>;
     /**
      * Adds a GROUP BY clause to the query.
      *
@@ -565,7 +589,7 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      *   .groupBy('status');
      * ```
      */
-    groupBy<F extends Field<Entity, RootAlias, Context>>(fields: F): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>;
+    groupBy<F extends Field<Entity, RootAlias, Context>>(fields: F): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields, CTEs>;
     /**
      * Adds a GROUP BY clause to the query.
      *
@@ -575,7 +599,7 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      *   .groupBy('status');
      * ```
      */
-    groupBy<const P extends string>(fields: NestedAutoPath<Entity, RootAlias, Context, P> | readonly NestedAutoPath<Entity, RootAlias, Context, P>[]): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>;
+    groupBy<const P extends string>(fields: NestedAutoPath<Entity, RootAlias, Context, P> | readonly NestedAutoPath<Entity, RootAlias, Context, P>[]): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields, CTEs>;
     /**
      * Adds a HAVING clause to the query, typically used with GROUP BY.
      *
@@ -586,9 +610,9 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      *   .having({ count: { $gt: 5 } });
      * ```
      */
-    having(cond?: QBFilterQuery<Entity, RootAlias, Context, RawAliases> | string, params?: any[], operator?: keyof typeof GroupOperator): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>;
-    andHaving(cond?: QBFilterQuery<Entity, RootAlias, Context, RawAliases> | string, params?: any[]): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>;
-    orHaving(cond?: QBFilterQuery<Entity, RootAlias, Context, RawAliases> | string, params?: any[]): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>;
+    having(cond?: QBFilterQuery<Entity, RootAlias, Context, RawAliases> | string, params?: any[], operator?: keyof typeof GroupOperator): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields, CTEs>;
+    andHaving(cond?: QBFilterQuery<Entity, RootAlias, Context, RawAliases> | string, params?: any[]): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields, CTEs>;
+    orHaving(cond?: QBFilterQuery<Entity, RootAlias, Context, RawAliases> | string, params?: any[]): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields, CTEs>;
     onConflict<F extends Field<Entity, RootAlias, Context>>(fields?: F | F[] | RawQueryFragment): InsertQueryBuilder<Entity, RootAlias, Context>;
     ignore(): this;
     merge<const P extends string>(data: readonly NestedAutoPath<Entity, RootAlias, Context, P>[]): this;
@@ -607,7 +631,7 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      * qb.select('*').limit(10, 20);    // 10 results starting from offset 20
      * ```
      */
-    limit(limit?: number, offset?: number): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>;
+    limit(limit?: number, offset?: number): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields, CTEs>;
     /**
      * Sets an OFFSET clause to skip a number of results.
      *
@@ -616,7 +640,7 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      * qb.select('*').limit(10).offset(20);  // Results 21-30
      * ```
      */
-    offset(offset?: number): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>;
+    offset(offset?: number): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields, CTEs>;
     withSchema(schema?: string): this;
     setLockMode(mode?: LockMode, tables?: string[]): this;
     setFlushMode(flushMode?: FlushMode): this;
@@ -646,12 +670,17 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      * Specifies FROM which entity's table select/update/delete will be executed, removing all previously set FROM-s.
      * Allows setting a main string alias of the selection data.
      */
-    from<Entity extends object>(target: QueryBuilder<Entity>, aliasName?: string): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>;
+    from<Entity extends object>(target: QueryBuilder<Entity>, aliasName?: string): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields, CTEs>;
     /**
      * Specifies FROM which entity's table select/update/delete will be executed, removing all previously set FROM-s.
      * Allows setting a main string alias of the selection data.
      */
-    from<Entity extends object>(target: EntityName<Entity>): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>;
+    from<Entity extends object>(target: EntityName<Entity>): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields, CTEs>;
+    /**
+     * Specifies a CTE name as the FROM source, with full type safety.
+     * The entity type is inferred from the CTE definition passed to `.with()`.
+     */
+    from<Name extends string & keyof CTEs, Alias extends string = Name>(target: Name, aliasName?: Alias): SelectQueryBuilder<CTEs[Name], Alias, never, never, never, '*', CTEs>;
     getNativeQuery(processVirtualEntity?: boolean): NativeQueryBuilder;
     /**
      * Returns the query with parameters as wildcards.
@@ -750,7 +779,80 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      * You can provide the target entity name as the first parameter and use the second parameter to point to an existing property to infer its field name.
      */
     as<T>(targetEntity: EntityName<T>, alias: EntityKey<T>): NativeQueryBuilder;
-    clone(reset?: boolean | string[], preserve?: string[]): QueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>;
+    /**
+     * 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: (QueryBuilder<any> | NativeQueryBuilder)[]): QueryBuilder<Entity>;
+    /**
+     * 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: (QueryBuilder<any> | NativeQueryBuilder)[]): QueryBuilder<Entity>;
+    private buildUnionQuery;
+    /**
+     * Adds a Common Table Expression (CTE) to the query.
+     * When a `QueryBuilder` is passed, its entity type is tracked for type-safe `from()`.
+     *
+     * @example
+     * ```ts
+     * const recentBooks = em.createQueryBuilder(Book, 'b').select('*').where({ ... });
+     * const qb = em.createQueryBuilder(Author, 'a')
+     *   .with('recent_books', recentBooks)
+     *   .select('*')
+     *   .from('recent_books', 'rb'); // entity type inferred as Book
+     * ```
+     */
+    with<Name extends string, Q extends QueryBuilder<any>>(name: Name, query: Q, options?: CteOptions): QueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields, CTEs & Record<Name, Q extends QueryBuilder<infer T> ? T : object>>;
+    /**
+     * Adds a Common Table Expression (CTE) to the query using a `NativeQueryBuilder` or raw SQL fragment.
+     * The CTE name is tracked but without entity type inference — use `from()` to query from it.
+     */
+    with<Name extends string>(name: Name, query: NativeQueryBuilder | RawQueryFragment, options?: CteOptions): QueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields, CTEs & Record<Name, object>>;
+    /**
+     * Adds a recursive Common Table Expression (CTE) to the query.
+     * When a `QueryBuilder` is passed, its entity type is tracked for type-safe `from()`.
+     *
+     * @example
+     * ```ts
+     * const base = em.createQueryBuilder(Category).select('*').where({ parent: null });
+     * const rec = em.createQueryBuilder(Category, 'c').select('c.*')
+     *   .leftJoin('c.parent', 'ct', { id: sql.ref('c.parentId') });
+     * const qb = em.createQueryBuilder(Category)
+     *   .withRecursive('category_tree', base.unionAll(rec))
+     *   .select('*')
+     *   .from('category_tree', 'ct'); // entity type inferred as Category
+     * ```
+     */
+    withRecursive<Name extends string, Q extends QueryBuilder<any>>(name: Name, query: Q, options?: CteOptions): QueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields, CTEs & Record<Name, Q extends QueryBuilder<infer T> ? T : object>>;
+    /**
+     * Adds a recursive Common Table Expression (CTE) to the query using a `NativeQueryBuilder` or raw SQL fragment.
+     * The CTE name is tracked but without entity type inference — use `from()` to query from it.
+     */
+    withRecursive<Name extends string>(name: Name, query: NativeQueryBuilder | RawQueryFragment, options?: CteOptions): QueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields, CTEs & Record<Name, object>>;
+    private addCte;
+    clone(reset?: boolean | string[], preserve?: string[]): QueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields, CTEs>;
     /**
      * Sets logger context for this query builder.
      */
@@ -836,10 +938,11 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
     private wrapModifySubQuery;
     private getSchema;
     /** @internal */
-    createAlias<U = unknown>(entityName: EntityName<U>, aliasName: string, subQuery?: NativeQueryBuilder): Alias<U>;
+    createAlias<U = unknown>(entityName: EntityName<U>, aliasName: string, subQuery?: NativeQueryBuilder | RawQueryFragment): Alias<U>;
     private createMainAlias;
     private fromSubQuery;
     private fromEntityName;
+    private fromRawTable;
     private createQueryBuilderHelper;
     private ensureFromClause;
     private ensureNotFinalized;
@@ -848,10 +951,36 @@ export interface RunQueryBuilder<Entity extends object, RootAlias extends string
     where(cond: QBFilterQuery<Entity, RootAlias, Context, RawAliases> | string, params?: keyof typeof GroupOperator | any[], operator?: keyof typeof GroupOperator): this;
     execute<Result = QueryResult<Entity>>(method?: 'all' | 'get' | 'run', mapResults?: boolean): Promise<Result>;
 }
-export interface SelectQueryBuilder<Entity extends object = AnyEntity, RootAlias extends string = never, Hint extends string = never, Context extends object = never, RawAliases extends string = never, Fields extends string = '*'> extends QueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields> {
-    execute<Result = Entity[]>(method?: 'all' | 'get' | 'run', mapResults?: boolean): Promise<Result>;
-    execute<Result = Entity[]>(method: 'all', mapResults?: boolean): Promise<Result>;
-    execute<Result = Entity>(method: 'get', mapResults?: boolean): Promise<Result>;
+/**
+ * @internal Optimized DTO type for execute().
+ * Bypasses the double mapped type of EntityDTO<Loaded<T, H, F>> by using DirectDTO
+ * which only iterates selected keys instead of all entity keys.
+ *
+ * - Wildcard, no joins: EntityDTO<T>
+ * - Selected fields, no joins: DirectDTO<T, F> (~132x faster than Pick<EntityDTO<T>, F>)
+ * - Wildcard + single-level join: Omit<EntityDTO<T>> + override populated relations
+ * - Selected fields + single-level join: DirectDTO for root + DirectDTO for joined (~60x faster)
+ * - Wildcard + nested joins: uses SerializeDTO<T, H> (~40x faster than EntityDTO<Loaded<T, H>>)
+ * - Fields + nested joins: falls back to EntityDTO<Loaded<T, H, F>>
+ */
+type DirectDTO<T, F extends keyof T> = {
+    [K in F]: EntityDTOProp<T, NonNullable<T[K]>> | Extract<T[K], null | undefined>;
+};
+type PopulatedDTO<T, K extends keyof T> = NonNullable<T[K]> extends Collection<infer U> ? EntityDTOFlat<U & object>[] : EntityDTOFlat<ExpandProperty<T[K]>>;
+type SubFields<F extends string, Rel extends string> = F extends `${Rel}.${infer Sub}` ? Sub : never;
+type RootFields<F extends string, H extends string> = F extends `${string}.${string}` ? F extends `${H}.${string}` ? never : F : F;
+type JoinDTO<T, K extends keyof T, F extends string> = NonNullable<T[K]> extends Collection<infer U> ? SubFields<F, K & string> extends never ? EntityDTOProp<T, Collection<U>> : DirectDTO<U, (SubFields<F, K & string> | PrimaryProperty<U>) & keyof U>[] : SubFields<F, K & string> extends never ? EntityDTOProp<T, T[K]> : DirectDTO<NonNullable<T[K]>, (SubFields<F, K & string> | PrimaryProperty<NonNullable<T[K]>>) & keyof NonNullable<T[K]>> | Extract<T[K], null | undefined>;
+type ExecuteDTO<T, H extends string, F extends string> = [H] extends [never] ? [F] extends ['*'] ? EntityDTOFlat<T> : DirectDTO<T, F & keyof T> : [F] extends ['*'] ? true extends (H extends `${string}.${string}` ? true : false) ? SerializeDTO<T, H> : Omit<EntityDTOFlat<T>, H & keyof EntityDTOFlat<T>> & {
+    [K in H & keyof T as K & keyof EntityDTOFlat<T>]: PopulatedDTO<T, K> | Extract<T[K], null | undefined>;
+} : true extends (H extends `${string}.${string}` ? true : false) ? EntityDTOFlat<Loaded<T, H, F>> : DirectDTO<T, (RootFields<F, H> | PrimaryProperty<T>) & keyof T> & {
+    [K in H & keyof T]: JoinDTO<T, K, F>;
+};
+/** Shorthand for `QueryBuilder` with all generic parameters set to `any`. */
+export type AnyQueryBuilder<T extends object = AnyEntity> = QueryBuilder<T, any, any, any, any, any, any>;
+export interface SelectQueryBuilder<Entity extends object = AnyEntity, RootAlias extends string = never, Hint extends string = never, Context extends object = never, RawAliases extends string = never, Fields extends string = '*', CTEs extends Record<string, object> = {}> extends QueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields, CTEs> {
+    execute<Result = ExecuteDTO<Entity, Hint, Fields>[]>(method?: 'all' | 'get' | 'run', mapResults?: boolean): Promise<Result>;
+    execute<Result = ExecuteDTO<Entity, Hint, Fields>[]>(method: 'all', mapResults?: boolean): Promise<Result>;
+    execute<Result = ExecuteDTO<Entity, Hint, Fields>>(method: 'get', mapResults?: boolean): Promise<Result>;
     execute<Result = QueryResult<Entity>>(method: 'run', mapResults?: boolean): Promise<Result>;
 }
 export interface CountQueryBuilder<Entity extends object> extends QueryBuilder<Entity, any, any> {