@mikro-orm/sql 7.0.0-dev.296 → 7.0.0-dev.299

package/AbstractSqlDriver.d.ts

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

package/SqlEntityManager.d.ts

@@ -20,7 +20,7 @@ export declare class SqlEntityManager<Driver extends AbstractSqlDriver = Abstrac
     /**
      * Shortcut for `createQueryBuilder()`
      */
-    qb<Entity extends object, RootAlias extends string = never>(entityName: EntityName<Entity>, alias?: RootAlias, type?: ConnectionType, loggerContext?: LoggingOptions): QueryBuilder<Entity, RootAlias, never, never, never, "*">;
+    qb<Entity extends object, RootAlias extends string = never>(entityName: EntityName<Entity>, alias?: RootAlias, type?: ConnectionType, loggerContext?: LoggingOptions): QueryBuilder<Entity, RootAlias, never, never, never, "*", {}>;
     /**
      * Returns configured Kysely instance.
      */

package/dialects/mssql/MsSqlNativeQueryBuilder.d.ts

@@ -11,4 +11,6 @@ export declare class MsSqlNativeQueryBuilder extends NativeQueryBuilder {
     protected compileSelect(): void;
     protected addLockClause(): void;
     protected compileTruncate(): void;
+    /** MSSQL has no RECURSIVE keyword — CTEs are implicitly recursive. */
+    protected getCteKeyword(_hasRecursive: boolean): string;
 }

package/dialects/mssql/MsSqlNativeQueryBuilder.js

@@ -19,6 +19,7 @@ export class MsSqlNativeQueryBuilder extends NativeQueryBuilder {
         if (this.options.comment) {
             this.parts.push(...this.options.comment.map(comment => `/* ${comment} */`));
         }
+        this.compileCtes();
         if (this.options.onConflict && !Utils.isEmpty(Utils.asArray(this.options.data)[0])) {
             this.compileUpsert();
         }
@@ -197,4 +198,8 @@ export class MsSqlNativeQueryBuilder extends NativeQueryBuilder {
         const sql = `delete from ${tableName}; declare @count int = case @@rowcount when 0 then 1 else 0 end; dbcc checkident ('${tableName.replace(/[[\]]/g, '')}', reseed, @count)`;
         this.parts.push(sql);
     }
+    /** MSSQL has no RECURSIVE keyword — CTEs are implicitly recursive. */
+    getCteKeyword(_hasRecursive) {
+        return 'with';
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikro-orm/sql",
-  "version": "7.0.0-dev.296",
+  "version": "7.0.0-dev.299",
   "description": "TypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. Supports MongoDB, MySQL, PostgreSQL and SQLite databases as well as usage with vanilla JavaScript.",
   "type": "module",
   "exports": {
@@ -56,6 +56,6 @@
     "@mikro-orm/core": "^6.6.8"
   },
   "peerDependencies": {
-    "@mikro-orm/core": "7.0.0-dev.296"
+    "@mikro-orm/core": "7.0.0-dev.299"
   }
 }

package/query/NativeQueryBuilder.d.ts

@@ -1,6 +1,17 @@
 import { type Dictionary, LockMode, type QueryFlag, RawQueryFragment, type Subquery } from '@mikro-orm/core';
 import { QueryType } from './enums.js';
 import type { AbstractSqlPlatform } from '../AbstractSqlPlatform.js';
+export interface CteOptions {
+    columns?: string[];
+    /** PostgreSQL: MATERIALIZED / NOT MATERIALIZED */
+    materialized?: boolean;
+}
+interface CteClause extends CteOptions {
+    name: string;
+    sql: string;
+    params: unknown[];
+    recursive?: boolean;
+}
 interface Options {
     tableName?: string | RawQueryFragment;
     indexHint?: string;
@@ -32,6 +43,7 @@ interface Options {
     hintComment?: string[];
     flags?: Set<QueryFlag>;
     wrap?: [prefix: string, suffix: string];
+    ctes?: CteClause[];
 }
 interface TableOptions {
     schema?: string;
@@ -65,6 +77,17 @@ export declare class NativeQueryBuilder implements Subquery {
     groupBy(groupBy: (string | RawQueryFragment)[]): this;
     join(sql: string, params: unknown[]): this;
     orderBy(orderBy: string): this;
+    /**
+     * The sub-query is compiled eagerly at call time — later mutations to the
+     * sub-query builder will not be reflected in this CTE.
+     */
+    with(name: string, query: NativeQueryBuilder | RawQueryFragment, options?: CteOptions): this;
+    /**
+     * Adds a recursive CTE (`WITH RECURSIVE` on PostgreSQL/MySQL/SQLite, plain `WITH` on MSSQL).
+     * The sub-query is compiled eagerly — later mutations will not be reflected.
+     */
+    withRecursive(name: string, query: NativeQueryBuilder | RawQueryFragment, options?: CteOptions): this;
+    private addCte;
     toString(): string;
     compile(): {
         sql: string;
@@ -103,6 +126,8 @@ export declare class NativeQueryBuilder implements Subquery {
     protected compileDelete(): void;
     protected compileTruncate(): void;
     protected addHintComment(): void;
+    protected compileCtes(): void;
+    protected getCteKeyword(hasRecursive: boolean): string;
     protected getTableName(): string;
     protected quote(id: string | RawQueryFragment | NativeQueryBuilder): string;
 }

package/query/NativeQueryBuilder.js

@@ -59,6 +59,36 @@ export class NativeQueryBuilder {
         this.options.orderBy = orderBy;
         return this;
     }
+    /**
+     * The sub-query is compiled eagerly at call time — later mutations to the
+     * sub-query builder will not be reflected in this CTE.
+     */
+    with(name, query, options) {
+        return this.addCte(name, query, options);
+    }
+    /**
+     * Adds a recursive CTE (`WITH RECURSIVE` on PostgreSQL/MySQL/SQLite, plain `WITH` on MSSQL).
+     * The sub-query is compiled eagerly — later mutations will not be reflected.
+     */
+    withRecursive(name, query, options) {
+        return this.addCte(name, query, options, true);
+    }
+    addCte(name, query, options, recursive) {
+        this.options.ctes ??= [];
+        if (this.options.ctes.some(cte => cte.name === name)) {
+            throw new Error(`CTE with name '${name}' already exists`);
+        }
+        const { sql, params } = query instanceof NativeQueryBuilder ? query.compile() : { sql: query.sql, params: [...query.params] };
+        this.options.ctes.push({
+            name,
+            sql,
+            params,
+            recursive,
+            columns: options?.columns,
+            materialized: options?.materialized,
+        });
+        return this;
+    }
     toString() {
         const { sql, params } = this.compile();
         return this.platform.formatQuery(sql, params);
@@ -72,6 +102,7 @@ export class NativeQueryBuilder {
         if (this.options.comment) {
             this.parts.push(...this.options.comment.map(comment => `/* ${comment} */`));
         }
+        this.compileCtes();
         switch (this.type) {
             case QueryType.SELECT:
             case QueryType.COUNT:
@@ -387,6 +418,35 @@ export class NativeQueryBuilder {
             this.parts.push(`/*+ ${this.options.hintComment.join(' ')} */`);
         }
     }
+    compileCtes() {
+        const ctes = this.options.ctes;
+        if (!ctes || ctes.length === 0) {
+            return;
+        }
+        const hasRecursive = ctes.some(cte => cte.recursive);
+        const keyword = this.getCteKeyword(hasRecursive);
+        const cteParts = [];
+        for (const cte of ctes) {
+            let part = this.quote(cte.name);
+            if (cte.columns?.length) {
+                part += ` (${cte.columns.map(c => this.quote(c)).join(', ')})`;
+            }
+            part += ' as';
+            if (cte.materialized === true) {
+                part += ' materialized';
+            }
+            else if (cte.materialized === false) {
+                part += ' not materialized';
+            }
+            part += ` (${cte.sql})`;
+            this.params.push(...cte.params);
+            cteParts.push(part);
+        }
+        this.parts.push(`${keyword} ${cteParts.join(', ')}`);
+    }
+    getCteKeyword(hasRecursive) {
+        return hasRecursive ? 'with recursive' : 'with';
+    }
     getTableName() {
         if (!this.options.tableName) {
             throw new Error('No table name provided');

package/query/QueryBuilder.d.ts

@@ -1,11 +1,11 @@
-import { type AnyEntity, type AutoPath, type Collection, type ConnectionType, type Dictionary, type EntityData, type EntityDTOFlat, type EntityDTOProp, 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 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 { 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;
@@ -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;
@@ -224,6 +224,11 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
         sql: string;
         params: readonly unknown[];
     };
+    protected _ctes: (CteOptions & {
+        name: string;
+        query: NativeQueryBuilder | RawQueryFragment;
+        recursive?: boolean;
+    })[];
     protected readonly platform: AbstractSqlPlatform;
     private tptJoinsApplied;
     private readonly autoJoinedPaths;
@@ -251,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.
      *
@@ -268,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.
      *
@@ -279,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.
      *
@@ -296,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.
      *
@@ -380,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.
@@ -415,11 +420,11 @@ 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.
@@ -522,7 +527,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.
      *
@@ -536,17 +541,17 @@ 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>;
+    }): 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>;
+    }): 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;
@@ -559,7 +564,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.
      *
@@ -569,7 +574,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.
      *
@@ -579,7 +584,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.
      *
@@ -590,9 +595,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;
@@ -611,7 +616,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.
      *
@@ -620,7 +625,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;
@@ -650,12 +655,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.
@@ -786,7 +796,48 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      */
     union(...others: (QueryBuilder<any> | NativeQueryBuilder)[]): QueryBuilder<Entity>;
     private buildUnionQuery;
-    clone(reset?: boolean | string[], preserve?: string[]): QueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>;
+    /**
+     * 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.
      */
@@ -876,6 +927,7 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
     private createMainAlias;
     private fromSubQuery;
     private fromEntityName;
+    private fromRawTable;
     private createQueryBuilderHelper;
     private ensureFromClause;
     private ensureNotFinalized;
@@ -910,7 +962,9 @@ type ExecuteDTO<T, H extends string, F extends string> = [
 } : 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>;
 };
-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> {
+/** 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>;