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

package/query/QueryBuilder.d.ts

@@ -1,4 +1,4 @@
-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, 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 { JoinType, QueryType } from './enums.js';
 import type { AbstractSqlDriver } from '../AbstractSqlDriver.js';
 import { type Alias, type OnConflictClause, QueryBuilderHelper } from './QueryBuilderHelper.js';
@@ -52,14 +52,16 @@ type AddToContext<Type extends object, Context, Field extends string, Alias exte
     [K in Alias]: [GetPath<Context, Field>, K, ExpandProperty<Type[GetPropName<Field> & keyof Type]>, Select];
 };
 type GetPath<Context, Field extends string> = GetAlias<Field> extends infer Alias ? IsNever<Alias> extends true ? GetPropName<Field> : Alias extends keyof Context ? Context[Alias] extends [infer Path, ...any[]] ? AppendToHint<Path & string, GetPropName<Field>> : GetPropName<Field> : GetPropName<Field> : GetPropName<Field>;
-type GetType<Type extends object, Context, Field extends string> = GetAlias<Field> extends infer Alias ? IsNever<Alias> extends true ? Type : Alias extends keyof Context ? Context[Alias] extends [string, string, infer PropType, any] ? PropType & object : Type : Type : Type;
+type GetType<Type extends object, Context, Field extends string> = GetAlias<Field> extends infer Alias ? IsNever<Alias> extends true ? Type : [Context] extends [never] ? Type : Alias extends keyof Context ? Context[Alias] extends [string, string, infer PropType, any] ? PropType & object : Type : Type : Type;
 type AddToHint<RootAlias, Context, Field extends string, Select extends boolean = false> = Select extends true ? GetAlias<Field> extends infer Alias ? IsNever<Alias> extends true ? GetPropName<Field> : Alias extends RootAlias ? GetPropName<Field> : Alias extends keyof Context ? Context[Alias] extends [infer Path, ...any[]] ? AppendToHint<Path & string, GetPropName<Field>> : GetPropName<Field> : GetPropName<Field> : GetPropName<Field> : never;
 export type ModifyHint<RootAlias, Context, Hint extends string, Field extends string, Select extends boolean = false> = Hint | AddToHint<RootAlias, Context, Field, Select>;
 export type ModifyContext<Entity extends object, Context, Field extends string, Alias extends string, Select extends boolean = false> = IsNever<Context> extends true ? AddToContext<GetType<Entity, object, Field>, object, Field, Alias, Select> : Context & AddToContext<GetType<Entity, Context, Field>, Context, Field, Alias, Select>;
 type StripRootAlias<F extends string, RootAlias extends string, Context = never> = F extends `${RootAlias}.${infer Field}` ? Field : F extends `${infer Alias}.${string}` ? Alias extends AliasNames<Context> ? never : F : F;
-type ExtractRootFields<Fields, RootAlias extends string, Context = never> = [Fields] extends ['*'] ? '*' : Fields extends `${RootAlias}.*` ? '*' : Fields extends string ? StripRootAlias<Fields, RootAlias, Context> : never;
+type StripFieldAlias<F extends string> = F extends `${infer Path} as ${string}` ? Path : F;
+type ExtractRootFields<Fields, RootAlias extends string, Context = never> = [Fields] extends ['*'] ? '*' : Fields extends `${RootAlias}.*` ? '*' : Fields extends string ? StripRootAlias<StripFieldAlias<Fields>, RootAlias, Context> : never;
 type PrefixWithPath<Path extends string, Field extends string> = `${Path}.${Field}`;
 type StripJoinAlias<F extends string, Alias extends string> = F extends `${Alias}.${infer Field}` ? Field : F;
+export type JoinSelectField<JoinedEntity, Alias extends string> = (keyof JoinedEntity & string) | `${Alias}.${keyof JoinedEntity & string}`;
 type AddJoinFields<RootAlias, Context, Field extends string, Alias extends string, JoinFields extends readonly string[]> = JoinFields extends readonly (infer F)[] ? F extends string ? PrefixWithPath<AddToHint<RootAlias, Context, Field, true> & string, StripJoinAlias<F, Alias>> : never : never;
 export type ModifyFields<CurrentFields extends string, RootAlias, Context, Field extends string, Alias extends string, JoinFields extends readonly string[] | undefined> = JoinFields extends readonly string[] ? CurrentFields | AddJoinFields<RootAlias, Context, Field, Alias, JoinFields> : CurrentFields;
 type EntityRelations<T> = EntityKey<T, true>;
@@ -68,25 +70,33 @@ type AliasNames<Context> = Context[keyof Context] extends infer Join ? Join exte
 type ContextRelationKeys<Context> = Context[keyof Context] extends infer Join ? Join extends any ? Join extends [string, infer Alias, infer Type, any] ? `${Alias & string}.${EntityRelations<Type & object>}` : never : never : never;
 export type QBField<Entity, RootAlias extends string, Context> = EntityRelations<Entity> | `${RootAlias}.${EntityRelations<Entity>}` | ([Context] extends [never] ? never : ContextRelationKeys<Context>);
 type ContextFieldKeys<Context> = Context[keyof Context] extends infer Join ? Join extends any ? Join extends [string, infer Alias, infer Type, any] ? `${Alias & string}.${keyof Type & string}` : never : never : never;
-export type Field<Entity, RootAlias extends string = never, Context = never> = EntityKey<Entity> | (IsNever<RootAlias> extends true ? never : `${RootAlias}.${EntityKey<Entity>}` | `${RootAlias}.*`) | ([Context] extends [never] ? never : ContextFieldKeys<Context> | `${AliasNames<Context>}.*`) | '*' | QueryBuilder<any> | NativeQueryBuilder | RawQueryFragment<any> | (RawQueryFragment & symbol);
+type WithAlias<T extends string> = T | `${T} as ${string}`;
+export type Field<Entity, RootAlias extends string = never, Context = never> = WithAlias<EntityKey<Entity>> | (IsNever<RootAlias> extends true ? never : WithAlias<`${RootAlias}.${EntityKey<Entity>}`> | `${RootAlias}.*`) | ([Context] extends [never] ? never : WithAlias<ContextFieldKeys<Context>> | `${AliasNames<Context>}.*`) | '*' | QueryBuilder<any> | NativeQueryBuilder | RawQueryFragment<any> | (RawQueryFragment & symbol);
 type RootAliasOrderKeys<RootAlias extends string, Entity> = {
     [K in `${RootAlias}.${EntityKey<Entity>}`]?: QueryOrderKeysFlat;
 };
 type ContextOrderKeys<Context> = {
     [K in ContextFieldKeys<Context>]?: QueryOrderKeysFlat;
 };
-export type ContextOrderByMap<Entity, RootAlias extends string = never, Context = never> = QueryOrderMap<Entity> | ((IsNever<RootAlias> extends true ? {} : RootAliasOrderKeys<RootAlias, Entity>) & ([Context] extends [never] ? {} : ContextOrderKeys<Context>));
+type RawOrderKeys<RawAliases extends string> = {
+    [K in RawAliases]?: QueryOrderKeysFlat;
+};
+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 : 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];
 };
-type JoinCondition<JoinedEntity extends object, Alias extends string> = ObjectQuery<JoinedEntity> | AliasedObjectQuery<JoinedEntity, Alias>;
+type JoinCondition<JoinedEntity extends object, Alias extends string> = (ObjectQuery<JoinedEntity> | AliasedObjectQuery<JoinedEntity, Alias>) & {
+    $not?: JoinCondition<JoinedEntity, Alias>;
+    $or?: JoinCondition<JoinedEntity, Alias>[];
+    $and?: JoinCondition<JoinedEntity, Alias>[];
+};
 type RawJoinCondition = {
     [key: string]: FilterValue<Scalar> | RawQueryFragment;
 };
-type ExtractRawAliasFromField<F> = F extends RawQueryFragment<infer A> ? (A extends string ? A : never) : 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 = {
@@ -194,6 +204,7 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
     protected _joinedProps: Map<string, PopulateOptions<any>>;
     protected _cache?: boolean | number | [string, number];
     protected _indexHint?: string;
+    protected _collation?: string;
     protected _comments: string[];
     protected _hintComments: string[];
     protected flushMode?: FlushMode;
@@ -228,6 +239,10 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      * // Select with raw expressions
      * qb.select([raw('count(*) as total')]);
      *
+     * // Select with aliases (works for regular and formula properties)
+     * qb.select(['id', 'fullName as displayName']);
+     * qb.select(['id', sql.ref('fullName').as('displayName')]);
+     *
      * // Select with distinct
      * qb.select('*', true);
      * ```
@@ -396,11 +411,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 string[] | 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 string[] | 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 string[] | 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 string[] | 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 string[] | 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>>;
+    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>>;
     protected getFieldsForJoinedLoad(prop: EntityProperty<Entity>, alias: string, explicitFields?: readonly string[]): InternalField<Entity>[];
     /**
      * Apply filters to the QB where condition.
@@ -503,7 +518,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> | ContextOrderByMap<Entity, RootAlias, Context>[]): 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>;
     /**
      * Adds an ORDER BY clause to the query, replacing any existing order.
      *
@@ -516,19 +531,21 @@ 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] : never;
+        [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>;
     /**
      * Adds additional ORDER BY clause without replacing existing order.
      */
-    andOrderBy(orderBy: ContextOrderByMap<Entity, RootAlias, Context> | ContextOrderByMap<Entity, RootAlias, Context>[]): 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>;
     /**
      * 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] : never;
+        [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>;
     private processOrderBy;
+    /** Collect custom aliases from select fields (stored as 'resolved as alias' strings by select()). */
+    private getSelectAliases;
     /**
      * Adds a GROUP BY clause to the query.
      *
@@ -611,6 +628,10 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      * Adds index hint to the FROM clause.
      */
     indexHint(sql: string | undefined): this;
+    /**
+     * Adds COLLATE clause to ORDER BY expressions.
+     */
+    collation(collation: string | undefined): this;
     /**
      * Prepend comment to the sql query using the syntax `/* ... *&#8205;/`. Some characters are forbidden such as `/*, *&#8205;/` and `?`.
      */
@@ -827,10 +848,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>;
 }
+/**
+ * @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>;
+};
 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>;
+    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> {

package/query/QueryBuilder.js

@@ -3,6 +3,8 @@ import { JoinType, QueryType } from './enums.js';
 import { QueryBuilderHelper } from './QueryBuilderHelper.js';
 import { CriteriaNodeFactory } from './CriteriaNodeFactory.js';
 import { NativeQueryBuilder } from './NativeQueryBuilder.js';
+/** Matches 'path as alias' — safe because ORM property names are JS identifiers (no spaces). */
+const FIELD_ALIAS_RE = /^(.+?)\s+as\s+(\w+)$/i;
 /**
  * SQL query builder with fluent interface.
  *
@@ -67,6 +69,7 @@ export class QueryBuilder {
     _joinedProps = new Map();
     _cache;
     _indexHint;
+    _collation;
     _comments = [];
     _hintComments = [];
     flushMode;
@@ -103,8 +106,19 @@ export class QueryBuilder {
         this.ensureNotFinalized();
         this._fields = Utils.asArray(fields).flatMap(f => {
             if (typeof f !== 'string') {
+                // Normalize sql.ref('prop') and sql.ref('prop').as('alias') to string form
+                if (isRaw(f) && f.sql === '??' && f.params.length === 1) {
+                    return this.resolveNestedPath(String(f.params[0]));
+                }
+                if (isRaw(f) && f.sql === '?? as ??' && f.params.length === 2) {
+                    return `${this.resolveNestedPath(String(f.params[0]))} as ${String(f.params[1])}`;
+                }
                 return f;
             }
+            const asMatch = f.match(FIELD_ALIAS_RE);
+            if (asMatch) {
+                return `${this.resolveNestedPath(asMatch[1].trim())} as ${asMatch[2]}`;
+            }
             return this.resolveNestedPath(f);
         });
         if (distinct) {
@@ -307,7 +321,7 @@ export class QueryBuilder {
         for (const p of targetMeta.getPrimaryProps()) {
             fields.push(...this.driver.mapPropToFieldNames(this, p, alias, targetMeta, schema));
         }
-        if (explicitFields) {
+        if (explicitFields && explicitFields.length > 0) {
             for (const field of explicitFields) {
                 const [a, f] = this.helper.splitField(field);
                 const p = targetMeta.properties[f];
@@ -321,7 +335,7 @@ export class QueryBuilder {
         }
         targetMeta.props
             .filter(prop => {
-            if (!explicitFields) {
+            if (!explicitFields || explicitFields.length === 0) {
                 return this.platform.shouldHaveColumn(prop, populate);
             }
             return prop.primary && !explicitFields.includes(prop.name) && !explicitFields.includes(`${alias}.${prop.name}`);
@@ -457,7 +471,18 @@ export class QueryBuilder {
         if (reset) {
             this._orderBy = [];
         }
-        Utils.asArray(orderBy).forEach(o => {
+        const selectAliases = this.getSelectAliases();
+        Utils.asArray(orderBy).forEach(orig => {
+            // Shallow clone to avoid mutating the caller's object — safe because the clone
+            // is only used within this loop iteration and `orig` is not referenced afterward.
+            const o = { ...orig };
+            // Wrap known select aliases in raw() so they bypass property validation and alias prefixing
+            for (const key of Object.keys(o)) {
+                if (selectAliases.has(key)) {
+                    o[raw('??', [key])] = o[key];
+                    delete o[key];
+                }
+            }
             this.helper.validateQueryOrder(o);
             const processed = QueryHelper.processWhere({
                 where: o,
@@ -476,10 +501,27 @@ export class QueryBuilder {
         });
         return this;
     }
+    /** Collect custom aliases from select fields (stored as 'resolved as alias' strings by select()). */
+    getSelectAliases() {
+        const aliases = new Set();
+        for (const field of this._fields ?? []) {
+            if (typeof field === 'string') {
+                const m = field.match(FIELD_ALIAS_RE);
+                if (m) {
+                    aliases.add(m[2]);
+                }
+            }
+        }
+        return aliases;
+    }
     groupBy(fields) {
         this.ensureNotFinalized();
         this._groupBy = Utils.asArray(fields).flatMap(f => {
             if (typeof f !== 'string') {
+                // Normalize sql.ref('prop') to string for proper formula resolution
+                if (isRaw(f) && f.sql === '??' && f.params.length === 1) {
+                    return this.resolveNestedPath(String(f.params[0]));
+                }
                 return f;
             }
             return this.resolveNestedPath(f);
@@ -501,7 +543,7 @@ export class QueryBuilder {
         if (typeof cond === 'string') {
             cond = { [raw(`(${cond})`, params)]: [] };
         }
-        const processed = CriteriaNodeFactory.createNode(this.metadata, this.mainAlias.entityName, cond, undefined, undefined, false).process(this);
+        const processed = CriteriaNodeFactory.createNode(this.metadata, this.mainAlias.entityName, cond, undefined, undefined, false).process(this, { type: 'having' });
         if (!this._having || !operator) {
             this._having = processed;
         }
@@ -638,6 +680,14 @@ export class QueryBuilder {
         this._indexHint = sql;
         return this;
     }
+    /**
+     * Adds COLLATE clause to ORDER BY expressions.
+     */
+    collation(collation) {
+        this.ensureNotFinalized();
+        this._collation = collation;
+        return this;
+    }
     /**
      * Prepend comment to the sql query using the syntax `/* ... *‍/`. Some characters are forbidden such as `/*, *‍/` and `?`.
      */
@@ -682,7 +732,7 @@ export class QueryBuilder {
         Utils.runIfNotEmpty(() => qb.groupBy(this.prepareFields(this._groupBy, 'groupBy', schema)), isNotEmptyObject(this._groupBy));
         Utils.runIfNotEmpty(() => this.helper.appendQueryCondition(this.type, this._having, qb, undefined, 'having'), isNotEmptyObject(this._having));
         Utils.runIfNotEmpty(() => {
-            const queryOrder = this.helper.getQueryOrder(this.type, this._orderBy, this._populateMap);
+            const queryOrder = this.helper.getQueryOrder(this.type, this._orderBy, this._populateMap, this._collation);
             if (queryOrder.length > 0) {
                 const sql = Utils.unique(queryOrder).join(', ');
                 qb.orderBy(sql);
@@ -1015,7 +1065,7 @@ export class QueryBuilder {
         // clone array/object properties
         const properties = [
             'flags', '_populate', '_populateWhere', '_populateFilter', '__populateWhere', '_populateMap', '_joins', '_joinedProps', '_cond', '_data', '_orderBy',
-            '_schema', '_indexHint', '_cache', 'subQueries', 'lockMode', 'lockTables', '_groupBy', '_having', '_returning',
+            '_schema', '_indexHint', '_collation', '_cache', 'subQueries', 'lockMode', 'lockTables', '_groupBy', '_having', '_returning',
             '_comments', '_hintComments', 'aliasCounter',
         ];
         for (const prop of Object.keys(this)) {
@@ -1167,14 +1217,23 @@ export class QueryBuilder {
     }
     prepareFields(fields, type = 'where', schema) {
         const ret = [];
-        const getFieldName = (name) => {
-            return this.helper.mapper(name, this.type, undefined, type === 'groupBy' ? null : undefined, schema);
+        const getFieldName = (name, customAlias) => {
+            const alias = customAlias ?? (type === 'groupBy' ? null : undefined);
+            return this.helper.mapper(name, this.type, undefined, alias, schema);
         };
-        fields.forEach(field => {
-            if (typeof field !== 'string') {
-                ret.push(field);
+        fields.forEach(originalField => {
+            if (typeof originalField !== 'string') {
+                ret.push(originalField);
                 return;
             }
+            // Strip 'as alias' suffix if present — the alias is passed to mapper at the end
+            let field = originalField;
+            let customAlias;
+            const asMatch = originalField.match(FIELD_ALIAS_RE);
+            if (asMatch) {
+                field = asMatch[1].trim();
+                customAlias = asMatch[2];
+            }
             const join = Object.keys(this._joins).find(k => field === k.substring(0, k.indexOf('#')));
             if (join && type === 'where') {
                 ret.push(...this.helper.mapJoinColumns(this.type, this._joins[join]));
@@ -1192,10 +1251,13 @@ export class QueryBuilder {
             if (prop?.embedded || (prop?.kind === ReferenceKind.EMBEDDED && prop.object)) {
                 const name = prop.embeddedPath?.join('.') ?? prop.fieldNames[0];
                 const aliased = this._aliases[a] ? `${a}.${name}` : name;
-                ret.push(getFieldName(aliased));
+                ret.push(getFieldName(aliased, customAlias));
                 return;
             }
             if (prop?.kind === ReferenceKind.EMBEDDED) {
+                if (customAlias) {
+                    throw new Error(`Cannot use 'as ${customAlias}' alias on embedded property '${field}' because it expands to multiple columns. Alias individual fields instead (e.g. '${field}.propertyName as ${customAlias}').`);
+                }
                 const nest = (prop) => {
                     for (const childProp of Object.values(prop.embeddedProps)) {
                         if (childProp.fieldNames && (childProp.kind !== ReferenceKind.EMBEDDED || childProp.object) && childProp.persist !== false) {
@@ -1209,11 +1271,14 @@ export class QueryBuilder {
                 nest(prop);
                 return;
             }
-            if (prop && prop.fieldNames.length > 1) {
+            if (prop && prop.fieldNames.length > 1 && !prop.fieldNames.includes(f)) {
+                if (customAlias) {
+                    throw new Error(`Cannot use 'as ${customAlias}' alias on '${field}' because it expands to multiple columns (${prop.fieldNames.join(', ')}).`);
+                }
                 ret.push(...prop.fieldNames.map(f => getFieldName(f)));
                 return;
             }
-            ret.push(getFieldName(field));
+            ret.push(getFieldName(field, customAlias));
         });
         const requiresSQLConversion = this.mainAlias.meta.props.filter(p => p.hasConvertToJSValueSQL && p.persist !== false);
         if (this.flags.has(QueryFlag.CONVERT_CUSTOM_TYPES) &&
@@ -1528,7 +1593,7 @@ export class QueryBuilder {
         if (!this.flags.has(QueryFlag.DISABLE_PAGINATE) && this._groupBy.length === 0 && this.hasToManyJoins()) {
             this.flags.add(QueryFlag.PAGINATE);
         }
-        if (meta && this.flags.has(QueryFlag.PAGINATE) && !this.flags.has(QueryFlag.DISABLE_PAGINATE) && (this._limit > 0 || this._offset > 0)) {
+        if (meta && !meta.virtual && this.flags.has(QueryFlag.PAGINATE) && !this.flags.has(QueryFlag.DISABLE_PAGINATE) && (this._limit > 0 || this._offset > 0)) {
             this.wrapPaginateSubQuery(meta);
         }
         if (meta && (this.flags.has(QueryFlag.UPDATE_SUB_QUERY) || this.flags.has(QueryFlag.DELETE_SUB_QUERY))) {

package/query/QueryBuilderHelper.d.ts

@@ -52,8 +52,8 @@ export declare class QueryBuilderHelper {
     private getValueReplacement;
     private getOperatorReplacement;
     validateQueryOrder<T>(orderBy: QueryOrderMap<T>): void;
-    getQueryOrder(type: QueryType, orderBy: FlatQueryOrderMap | FlatQueryOrderMap[], populate: Dictionary<string>): string[];
-    getQueryOrderFromObject(type: QueryType, orderBy: FlatQueryOrderMap, populate: Dictionary<string>): string[];
+    getQueryOrder(type: QueryType, orderBy: FlatQueryOrderMap | FlatQueryOrderMap[], populate: Dictionary<string>, collation?: string): string[];
+    getQueryOrderFromObject(type: QueryType, orderBy: FlatQueryOrderMap, populate: Dictionary<string>, collation?: string): string[];
     finalize(type: QueryType, qb: NativeQueryBuilder, meta?: EntityMetadata, data?: Dictionary, returning?: InternalField<any>[]): void;
     splitField<T>(field: EntityKey<T>, greedyAlias?: boolean): [string, EntityKey<T>, string | undefined];
     getLockSQL(qb: NativeQueryBuilder, lockMode: LockMode, lockTables?: string[], joinsMap?: Dictionary<JoinOptions>): void;

package/query/QueryBuilderHelper.js

@@ -110,8 +110,8 @@ export class QueryBuilderHelper {
         }
         if (prop?.formula) {
             const alias2 = this.platform.quoteIdentifier(a).toString();
-            const aliased = this.platform.quoteIdentifier(prop.fieldNames[0]).toString();
-            const as = alias === null ? '' : ` as ${aliased}`;
+            const aliasName = alias === undefined ? prop.fieldNames[0] : alias;
+            const as = aliasName === null ? '' : ` as ${this.platform.quoteIdentifier(aliasName)}`;
             const meta = this.aliasMap[a]?.meta ?? this.metadata.get(this.entityName);
             const table = this.createFormulaTable(alias2, meta, schema);
             const columns = meta.createColumnMappingObject(p => this.getTPTAliasForProperty(p.name, a), alias2);
@@ -605,20 +605,20 @@ export class QueryBuilderHelper {
             ].join('\n'));
         }
     }
-    getQueryOrder(type, orderBy, populate) {
+    getQueryOrder(type, orderBy, populate, collation) {
         if (Array.isArray(orderBy)) {
-            return orderBy.flatMap(o => this.getQueryOrder(type, o, populate));
+            return orderBy.flatMap(o => this.getQueryOrder(type, o, populate, collation));
         }
-        return this.getQueryOrderFromObject(type, orderBy, populate);
+        return this.getQueryOrderFromObject(type, orderBy, populate, collation);
     }
-    getQueryOrderFromObject(type, orderBy, populate) {
+    getQueryOrderFromObject(type, orderBy, populate, collation) {
         const ret = [];
         for (const key of Utils.getObjectQueryKeys(orderBy)) {
             const direction = orderBy[key];
             const order = typeof direction === 'number' ? QueryOrderNumeric[direction] : direction;
             if (Raw.isKnownFragmentSymbol(key)) {
                 const raw = Raw.getKnownFragment(key);
-                ret.push(...this.platform.getOrderByExpression(this.platform.formatQuery(raw.sql, raw.params), order));
+                ret.push(...this.platform.getOrderByExpression(this.platform.formatQuery(raw.sql, raw.params), order, collation));
                 continue;
             }
             for (const f of Utils.splitPrimaryKeys(key)) {
@@ -638,10 +638,10 @@ export class QueryBuilderHelper {
                     colPart = this.platform.formatQuery(colPart.sql, colPart.params);
                 }
                 if (Array.isArray(order)) {
-                    order.forEach(part => ret.push(...this.getQueryOrderFromObject(type, part, populate)));
+                    order.forEach(part => ret.push(...this.getQueryOrderFromObject(type, part, populate, collation)));
                 }
                 else {
-                    ret.push(...this.platform.getOrderByExpression(colPart, order));
+                    ret.push(...this.platform.getOrderByExpression(colPart, order, collation));
                 }
             }
         }

package/schema/SchemaComparator.js

@@ -165,6 +165,7 @@ export class SchemaComparator {
         if (this.diffComment(fromTable.comment, toTable.comment)) {
             tableDifferences.changedComment = toTable.comment;
             this.log(`table comment changed for ${tableDifferences.name}`, { fromTableComment: fromTable.comment, toTableComment: toTable.comment });
+            changes++;
         }
         const fromTableColumns = fromTable.getColumns();
         const toTableColumns = toTable.getColumns();

package/schema/SqlSchemaGenerator.d.ts

@@ -1,4 +1,5 @@
-import { AbstractSchemaGenerator, type ClearDatabaseOptions, type CreateSchemaOptions, type Dictionary, type DropSchemaOptions, type EnsureDatabaseOptions, type EntityMetadata, type ISchemaGenerator, type MikroORM, type Transaction, type UpdateSchemaOptions } from '@mikro-orm/core';
+import { type ClearDatabaseOptions, type CreateSchemaOptions, type Dictionary, type DropSchemaOptions, type EnsureDatabaseOptions, type EntityMetadata, type ISchemaGenerator, type MikroORM, type Transaction, type UpdateSchemaOptions } from '@mikro-orm/core';
+import { AbstractSchemaGenerator } from '@mikro-orm/core/schema';
 import type { SchemaDifference } from '../typings.js';
 import { DatabaseSchema } from './DatabaseSchema.js';
 import type { AbstractSqlDriver } from '../AbstractSqlDriver.js';

package/schema/SqlSchemaGenerator.js

@@ -1,4 +1,5 @@
-import { AbstractSchemaGenerator, CommitOrderCalculator, Utils, } from '@mikro-orm/core';
+import { CommitOrderCalculator, Utils, } from '@mikro-orm/core';
+import { AbstractSchemaGenerator } from '@mikro-orm/core/schema';
 import { DatabaseSchema } from './DatabaseSchema.js';
 import { SchemaComparator } from './SchemaComparator.js';
 export class SqlSchemaGenerator extends AbstractSchemaGenerator {