@mikro-orm/sql 7.0.0-dev.216 → 7.0.0-dev.218

package/query/QueryBuilder.d.ts

@@ -1,9 +1,9 @@
-import { type AnyEntity, type ConnectionType, type Dictionary, type EntityData, type EntityKey, type EntityManager, type EntityMetadata, type EntityName, type EntityProperty, type ExpandProperty, type FilterOptions, type FlushMode, type GroupOperator, type Loaded, LockMode, type LoggingOptions, type MetadataStorage, type ObjectQuery, PopulateHint, type PopulateOptions, type QBFilterQuery, type QBQueryOrderMap, QueryFlag, type QueryOrderMap, type QueryResult, RawQueryFragment, type RequiredEntityData, type Transaction } from '@mikro-orm/core';
+import { type AnyEntity, type AutoPath, type ConnectionType, type Dictionary, type EntityData, type EntityKey, type EntityManager, type EntityMetadata, type EntityName, type EntityProperty, type ExpandProperty, 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 { 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 { Field, ICriteriaNodeProcessOptions, JoinOptions } from '../typings.js';
+import type { ICriteriaNodeProcessOptions, InternalField, JoinOptions } from '../typings.js';
 import type { AbstractSqlPlatform } from '../AbstractSqlPlatform.js';
 import { NativeQueryBuilder } from './NativeQueryBuilder.js';
 export interface ExecuteOptions {
@@ -34,26 +34,101 @@ export interface QBStreamOptions {
      */
     rawResults?: boolean;
 }
-type AnyString = string & {};
-type Compute<T> = {
-    [K in keyof T]: T[K];
-} & {};
 type IsNever<T, True = true, False = false> = [T] extends [never] ? True : False;
 type GetAlias<T extends string> = T extends `${infer A}.${string}` ? A : never;
 type GetPropName<T extends string> = T extends `${string}.${infer P}` ? P : T;
 type AppendToHint<Parent extends string, Child extends string> = `${Parent}.${Child}`;
+/**
+ * Context tuple format: [Path, Alias, Type, Select]
+ * - Path: The relation path from root entity (e.g., 'books', 'books.author')
+ * - Alias: The SQL alias used in the query (e.g., 'b', 'a1')
+ * - Type: The entity type of the joined relation
+ * - Select: Whether this join was created via joinAndSelect (affects Fields tracking)
+ *
+ * Example: After `qb.leftJoin('a.books', 'b')`, Context becomes:
+ * { b: ['books', 'b', Book, false] }
+ */
 type AddToContext<Type extends object, Context, Field extends string, Alias extends string, Select extends boolean> = {
     [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] ? PropType & object : Type : Type : Type;
+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 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> = Compute<IsNever<Context> extends true ? AddToContext<GetType<Entity, object, Field>, object, Field, Alias, Select> : Context & AddToContext<GetType<Entity, Context, Field>, Context, Field, Alias, 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 PrefixWithPath<Path extends string, Field extends string> = `${Path}.${Field}`;
+type StripJoinAlias<F extends string, Alias extends string> = F extends `${Alias}.${infer Field}` ? Field : F;
+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>;
-type AddAliasesFromContext<Context> = Context[keyof Context] extends infer Join ? Join extends any ? Join extends [string, infer Alias, infer Type, any] ? `${Alias & string}.${EntityRelations<Type & {}>}` : never : never : never;
-export type QBField<Entity, RootAlias extends string, Context> = (EntityRelations<Entity> | `${RootAlias}.${EntityRelations<Entity>}` | AddAliasesFromContext<Context>) & {} | AnyString;
-type EntityKeyOrString<Entity extends object = AnyEntity> = AnyString | keyof Entity;
+type JoinedEntityType<Entity extends object, Context, Field extends string> = ExpandProperty<GetType<Entity, Context, Field>[GetPropName<Field> & keyof GetType<Entity, Context, Field>]>;
+type AliasNames<Context> = Context[keyof Context] extends infer Join ? Join extends any ? Join extends [string, infer Alias, any, any] ? Alias & string : never : never : never;
+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 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 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 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 RawJoinCondition = {
+    [key: string]: FilterValue<Scalar> | RawQueryFragment;
+};
+type ExtractRawAliasFromField<F> = F extends RawQueryFragment<infer A> ? (A extends string ? A : never) : 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 = {
+    $eq?: Scalar | readonly Scalar[] | Subquery | null;
+    $ne?: Scalar | readonly Scalar[] | Subquery | null;
+    $in?: readonly Scalar[] | Raw | Subquery;
+    $nin?: readonly Scalar[] | Raw | Subquery;
+    $gt?: Scalar | Subquery;
+    $gte?: Scalar | Subquery;
+    $lt?: Scalar | Subquery;
+    $lte?: Scalar | Subquery;
+    $like?: string;
+    $re?: string;
+    $ilike?: string;
+    $fulltext?: string;
+    $overlap?: readonly string[] | string | object;
+    $contains?: readonly string[] | string | object;
+    $contained?: readonly string[] | string | object;
+    $exists?: boolean;
+    $hasKey?: string;
+    $hasKeys?: readonly string[];
+    $hasSomeKeys?: readonly string[];
+};
+type AliasedFilterValue = Scalar | FlatOperatorMap | readonly Scalar[] | null | QueryBuilder<any> | NativeQueryBuilder;
+type TypedAliasedFilterValue<T> = FilterValue<ExpandProperty<T>> | QueryBuilder<any> | NativeQueryBuilder;
+type RootAliasFilterKeys<RootAlias extends string, Entity> = {
+    [K in EntityKey<Entity> as `${RootAlias}.${K}`]?: TypedAliasedFilterValue<Entity[K]>;
+};
+type ContextFilterKeys<Context> = {
+    [K in ContextFieldKeys<Context>]?: AliasedFilterValue;
+};
+type RawFilterKeys<RawAliases extends string> = {
+    [K in RawAliases]?: AliasedFilterValue;
+};
+type NestedFilterCondition<Entity, RootAlias extends string, Context, RawAliases extends string> = ObjectQuery<Entity> | ((IsNever<RootAlias> extends true ? {} : RootAliasFilterKeys<RootAlias, Entity>) & ([Context] extends [never] ? {} : ContextFilterKeys<Context>) & (IsNever<RawAliases> extends true ? {} : RawFilterKeys<RawAliases>));
+type GroupOperators<RootAlias extends string, Context, Entity, RawAliases extends string> = {
+    $and?: NestedFilterCondition<Entity, RootAlias, Context, RawAliases>[];
+    $or?: NestedFilterCondition<Entity, RootAlias, Context, RawAliases>[];
+    $not?: NestedFilterCondition<Entity, RootAlias, Context, RawAliases>;
+};
+export type AliasedFilterCondition<RootAlias extends string, Context, Entity, RawAliases extends string = never> = (IsNever<RootAlias> extends true ? {} : RootAliasFilterKeys<RootAlias, Entity>) & ([Context] extends [never] ? {} : ContextFilterKeys<Context>) & (IsNever<RawAliases> extends true ? {} : RawFilterKeys<RawAliases>) & GroupOperators<RootAlias, Context, Entity, RawAliases>;
+export type QBFilterQuery<Entity, RootAlias extends string = never, Context = never, RawAliases extends string = never> = ObjectQuery<Entity> | AliasedFilterCondition<RootAlias, Context, Entity, RawAliases>;
 /**
  * SQL query builder with fluent interface.
  *
@@ -73,13 +148,14 @@ type EntityKeyOrString<Entity extends object = AnyEntity> = AnyString | keyof En
  * 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> {
+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 {
     protected readonly metadata: MetadataStorage;
     protected readonly driver: AbstractSqlDriver;
     protected readonly context?: Transaction | undefined;
     protected connectionType?: ConnectionType | undefined;
     protected em?: SqlEntityManager | undefined;
     protected loggerContext?: (LoggingOptions & Dictionary) | undefined;
+    readonly __subquery: true;
     get mainAlias(): Alias<Entity>;
     get alias(): string;
     get helper(): QueryBuilderHelper;
@@ -87,7 +163,7 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
     /** @internal */
     _type?: QueryType;
     /** @internal */
-    _fields?: Field<Entity>[];
+    _fields?: InternalField<Entity>[];
     /** @internal */
     _populate: PopulateOptions<Entity>[];
     /** @internal */
@@ -108,9 +184,9 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
     protected _cond: Dictionary;
     protected _data: Dictionary;
     protected _orderBy: QueryOrderMap<Entity>[];
-    protected _groupBy: Field<Entity>[];
+    protected _groupBy: InternalField<Entity>[];
     protected _having: Dictionary;
-    protected _returning?: Field<Entity>[];
+    protected _returning?: InternalField<Entity>[];
     protected _onConflict?: OnConflictClause<Entity>[];
     protected _limit?: number;
     protected _offset?: number;
@@ -137,27 +213,192 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      * @internal
      */
     constructor(entityName: EntityName<Entity> | QueryBuilder<Entity, any, any, any>, metadata: MetadataStorage, driver: AbstractSqlDriver, context?: Transaction | undefined, alias?: string, connectionType?: ConnectionType | undefined, em?: SqlEntityManager | undefined, loggerContext?: (LoggingOptions & Dictionary) | undefined);
-    select(fields: Field<Entity> | Field<Entity>[], distinct?: boolean): SelectQueryBuilder<Entity, RootAlias, Hint, Context>;
-    addSelect(fields: Field<Entity> | Field<Entity>[]): SelectQueryBuilder<Entity, RootAlias, Hint, Context>;
-    distinct(): SelectQueryBuilder<Entity, RootAlias, Hint, Context>;
+    /**
+     * Creates a SELECT query, specifying the fields to retrieve.
+     *
+     * @example
+     * ```ts
+     * // Select specific fields
+     * const qb = em.createQueryBuilder(User, 'u');
+     * qb.select(['u.id', 'u.name', 'u.email']);
+     *
+     * // Select with raw expressions
+     * qb.select([raw('count(*) as total')]);
+     *
+     * // Select with distinct
+     * 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>>;
+    /**
+     * Creates a SELECT query, specifying the fields to retrieve.
+     *
+     * @example
+     * ```ts
+     * // Select specific fields
+     * const qb = em.createQueryBuilder(User, 'u');
+     * qb.select(['u.id', 'u.name', 'u.email']);
+     *
+     * // Select with raw expressions
+     * qb.select([raw('count(*) as total')]);
+     *
+     * // Select with distinct
+     * 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>>;
+    /**
+     * Creates a SELECT query, specifying the fields to retrieve.
+     *
+     * @example
+     * ```ts
+     * // Select specific fields with nested paths (e.g., for embedded properties)
+     * const qb = em.createQueryBuilder(User, 'u');
+     * 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>>;
+    /**
+     * Creates a SELECT query, specifying the fields to retrieve.
+     *
+     * @example
+     * ```ts
+     * // Select specific fields
+     * const qb = em.createQueryBuilder(User, 'u');
+     * qb.select(['u.id', 'u.name', 'u.email']);
+     *
+     * // Select with raw expressions
+     * qb.select([raw('count(*) as total')]);
+     *
+     * // Select with distinct
+     * 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>>;
+    /**
+     * 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>;
+    /** postgres only */
+    distinctOn<const F extends readonly Field<Entity, RootAlias, Context>[]>(fields: F): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>;
     /** postgres only */
-    distinctOn(fields: EntityKeyOrString<Entity> | EntityKeyOrString<Entity>[]): SelectQueryBuilder<Entity, RootAlias, Hint, Context>;
-    insert(data: RequiredEntityData<Entity> | RequiredEntityData<Entity>[]): InsertQueryBuilder<Entity>;
-    update(data: EntityData<Entity>): UpdateQueryBuilder<Entity>;
-    delete(cond?: QBFilterQuery): DeleteQueryBuilder<Entity>;
+    distinctOn<F extends Field<Entity, RootAlias, Context>>(fields: F): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>;
+    /**
+     * Creates an INSERT query with the given data.
+     *
+     * @example
+     * ```ts
+     * await em.createQueryBuilder(User)
+     *   .insert({ name: 'John', email: 'john@example.com' })
+     *   .execute();
+     *
+     * // Bulk insert
+     * await em.createQueryBuilder(User)
+     *   .insert([{ name: 'John' }, { name: 'Jane' }])
+     *   .execute();
+     * ```
+     */
+    insert(data: RequiredEntityData<Entity> | RequiredEntityData<Entity>[]): InsertQueryBuilder<Entity, RootAlias, Context>;
+    /**
+     * Creates an UPDATE query with the given data.
+     * Use `where()` to specify which rows to update.
+     *
+     * @example
+     * ```ts
+     * await em.createQueryBuilder(User)
+     *   .update({ name: 'John Doe' })
+     *   .where({ id: 1 })
+     *   .execute();
+     * ```
+     */
+    update(data: EntityData<Entity>): UpdateQueryBuilder<Entity, RootAlias, Context>;
+    /**
+     * Creates a DELETE query.
+     * Use `where()` to specify which rows to delete.
+     *
+     * @example
+     * ```ts
+     * await em.createQueryBuilder(User)
+     *   .delete()
+     *   .where({ id: 1 })
+     *   .execute();
+     *
+     * // Or pass the condition directly
+     * await em.createQueryBuilder(User)
+     *   .delete({ isActive: false })
+     *   .execute();
+     * ```
+     */
+    delete(cond?: QBFilterQuery<Entity, RootAlias, Context, RawAliases>): DeleteQueryBuilder<Entity, RootAlias, Context>;
+    /**
+     * Creates a TRUNCATE query to remove all rows from the table.
+     */
     truncate(): TruncateQueryBuilder<Entity>;
-    count(field?: EntityKeyOrString<Entity> | EntityKeyOrString<Entity>[], distinct?: boolean): CountQueryBuilder<Entity>;
-    join<Field extends QBField<Entity, RootAlias, Context>, Alias extends string>(field: Field | RawQueryFragment | QueryBuilder<any>, alias: Alias, cond?: QBFilterQuery, type?: JoinType, path?: string, schema?: string): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field> & {}, ModifyContext<Entity, Context, Field, Alias>>;
-    innerJoin<Field extends QBField<Entity, RootAlias, Context>, Alias extends string>(field: Field | RawQueryFragment | QueryBuilder<any>, alias: Alias, cond?: QBFilterQuery, schema?: string): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field> & {}, ModifyContext<Entity, Context, Field, Alias>>;
-    innerJoinLateral(field: RawQueryFragment | QueryBuilder<any>, alias: string, cond: QBFilterQuery, schema?: string): this;
-    leftJoin<Field extends QBField<Entity, RootAlias, Context>, Alias extends string>(field: Field | RawQueryFragment | QueryBuilder<any>, alias: Alias, cond?: QBFilterQuery, schema?: string): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field> & {}, ModifyContext<Entity, Context, Field, Alias>>;
-    leftJoinLateral(field: RawQueryFragment | QueryBuilder<any>, alias: string, cond: QBFilterQuery, schema?: string): this;
-    joinAndSelect<Field extends QBField<Entity, RootAlias, Context>, Alias extends string>(field: Field | [field: Field, qb: RawQueryFragment | QueryBuilder<any>], alias: Alias, cond?: QBFilterQuery, type?: JoinType, path?: string, fields?: string[], schema?: string): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field, true> & {}, ModifyContext<Entity, Context, Field, Alias, true>>;
-    leftJoinAndSelect<Field extends QBField<Entity, RootAlias, Context>, Alias extends string>(field: Field | [field: Field, qb: RawQueryFragment | QueryBuilder<any>], alias: Alias, cond?: QBFilterQuery, fields?: string[], schema?: string): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field, true> & {}, ModifyContext<Entity, Context, Field, Alias, true>>;
-    leftJoinLateralAndSelect<Field extends QBField<Entity, RootAlias, Context>, Alias extends string>(field: [field: Field, qb: RawQueryFragment | QueryBuilder<any>], alias: Alias, cond?: QBFilterQuery, fields?: string[], schema?: string): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field, true> & {}, ModifyContext<Entity, Context, Field, Alias, true>>;
-    innerJoinAndSelect<Field extends QBField<Entity, RootAlias, Context>, Alias extends string>(field: Field | [field: Field, qb: RawQueryFragment | QueryBuilder<any>], alias: Alias, cond?: QBFilterQuery, fields?: string[], schema?: string): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field, true> & {}, ModifyContext<Entity, Context, Field, Alias, true>>;
-    innerJoinLateralAndSelect<Field extends QBField<Entity, RootAlias, Context>, Alias extends string>(field: [field: Field, qb: RawQueryFragment | QueryBuilder<any>], alias: Alias, cond?: QBFilterQuery, fields?: string[], schema?: string): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field, true> & {}, ModifyContext<Entity, Context, Field, Alias, true>>;
-    protected getFieldsForJoinedLoad(prop: EntityProperty<Entity>, alias: string, explicitFields?: string[]): Field<Entity>[];
+    /**
+     * Creates a COUNT query to count matching rows.
+     *
+     * @example
+     * ```ts
+     * const count = await em.createQueryBuilder(User)
+     *   .count()
+     *   .where({ isActive: true })
+     *   .execute('get');
+     * ```
+     */
+    count<F extends Field<Entity, RootAlias, Context>>(field?: F | F[], distinct?: boolean): CountQueryBuilder<Entity>;
+    /**
+     * Adds a JOIN clause to the query for an entity relation.
+     *
+     * @example
+     * ```ts
+     * const qb = em.createQueryBuilder(Book, 'b');
+     * qb.select('*')
+     *   .join('b.author', 'a')
+     *   .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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * Adds a JOIN clause and automatically selects the joined entity's fields.
+     * This is useful for eager loading related entities.
+     *
+     * @example
+     * ```ts
+     * const qb = em.createQueryBuilder(Book, 'b');
+     * qb.select('*')
+     *   .joinAndSelect('b.author', 'a')
+     *   .where({ 'a.name': 'John' });
+     * ```
+     */
+    joinAndSelect<Field 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>>;
+    protected getFieldsForJoinedLoad(prop: EntityProperty<Entity>, alias: string, explicitFields?: readonly string[]): InternalField<Entity>[];
     /**
      * Apply filters to the QB where condition.
      */
@@ -172,29 +413,191 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      */
     applyJoinedFilters(em: EntityManager, filterOptions: FilterOptions | undefined): Promise<void>;
     withSubQuery(subQuery: RawQueryFragment | NativeQueryBuilder, alias: string): this;
-    where(cond: QBFilterQuery<Entity>, operator?: keyof typeof GroupOperator): this;
+    /**
+     * Adds a WHERE clause to the query using an object condition.
+     *
+     * Supports filtering by:
+     * - Direct entity properties: `{ name: 'John' }`
+     * - Nested relations/embedded: `{ author: { name: 'John' } }`
+     * - Aliased properties after joins: `{ 'a.name': 'John' }` or `{ 'b.title': 'test' }`
+     * - Filter operators: `{ age: { $gte: 18 } }`
+     * - Logical operators: `{ $or: [{ name: 'John' }, { name: 'Jane' }] }`
+     *
+     * @example
+     * ```ts
+     * // Filter by entity properties
+     * qb.where({ name: 'John', age: { $gte: 18 } });
+     *
+     * // Filter by nested relation
+     * qb.where({ author: { name: 'John' } });
+     *
+     * // Filter by aliased properties after join
+     * qb.leftJoin('a.books', 'b').where({ 'b.title': 'test' });
+     *
+     * // Combine with logical operators
+     * qb.where({ $or: [{ status: 'active' }, { role: 'admin' }] });
+     * ```
+     */
+    where(cond: QBFilterQuery<Entity, RootAlias, Context, RawAliases>, operator?: keyof typeof GroupOperator): this;
+    /**
+     * Adds a WHERE clause to the query using a raw SQL string or fragment.
+     *
+     * @example
+     * ```ts
+     * // Raw SQL with parameters
+     * qb.where('name = ? AND age >= ?', ['John', 18]);
+     *
+     * // Using raw() helper
+     * qb.where(raw('lower(name) = ?', ['john']));
+     * ```
+     */
     where(cond: string | RawQueryFragment, params?: any[], operator?: keyof typeof GroupOperator): this;
-    andWhere(cond: QBFilterQuery<Entity>): this;
+    /**
+     * Adds an AND WHERE clause to the query using an object condition.
+     *
+     * @example
+     * ```ts
+     * qb.where({ status: 'active' }).andWhere({ role: 'admin' });
+     * qb.where({ name: 'John' }).andWhere({ 'b.title': 'test' });
+     * ```
+     */
+    andWhere(cond: QBFilterQuery<Entity, RootAlias, Context, RawAliases>): this;
+    /**
+     * Adds an AND WHERE clause to the query using a raw SQL string or fragment.
+     *
+     * @example
+     * ```ts
+     * qb.where({ status: 'active' }).andWhere('age >= ?', [18]);
+     * ```
+     */
     andWhere(cond: string | RawQueryFragment, params?: any[]): this;
-    orWhere(cond: QBFilterQuery<Entity>): this;
+    /**
+     * Adds an OR WHERE clause to the query using an object condition.
+     *
+     * @example
+     * ```ts
+     * qb.where({ status: 'active' }).orWhere({ role: 'admin' });
+     * qb.where({ name: 'John' }).orWhere({ name: 'Jane' });
+     * ```
+     */
+    orWhere(cond: QBFilterQuery<Entity, RootAlias, Context, RawAliases>): this;
+    /**
+     * Adds an OR WHERE clause to the query using a raw SQL string or fragment.
+     *
+     * @example
+     * ```ts
+     * qb.where({ status: 'active' }).orWhere('role = ?', ['admin']);
+     * ```
+     */
     orWhere(cond: string | RawQueryFragment, params?: any[]): this;
-    orderBy(orderBy: QBQueryOrderMap<Entity> | QBQueryOrderMap<Entity>[]): SelectQueryBuilder<Entity, RootAlias, Hint, Context>;
-    andOrderBy(orderBy: QBQueryOrderMap<Entity> | QBQueryOrderMap<Entity>[]): SelectQueryBuilder<Entity, RootAlias, Hint, Context>;
+    /**
+     * Adds an ORDER BY clause to the query, replacing any existing order.
+     *
+     * @example
+     * ```ts
+     * qb.orderBy({ name: 'asc', createdAt: 'desc' });
+     * qb.orderBy([{ name: 'asc' }, { createdAt: 'desc' }]);
+     * qb.orderBy({ profile: { bio: 'asc' } }); // nested via object
+     * 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>;
+    /**
+     * Adds an ORDER BY clause to the query, replacing any existing order.
+     *
+     * @example
+     * ```ts
+     * qb.orderBy({ name: 'asc', createdAt: 'desc' });
+     * qb.orderBy([{ name: 'asc' }, { createdAt: 'desc' }]);
+     * qb.orderBy({ profile: { bio: 'asc' } }); // nested via object
+     * qb.orderBy({ 'profile.bio': 'asc' }); // nested via dot notation
+     * ```
+     */
+    orderBy<const T extends Record<string, QueryOrderKeysFlat>>(orderBy: T & {
+        [K in keyof T]: K extends NestedAutoPath<Entity, RootAlias, Context, K & string> ? 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>;
+    /**
+     * 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;
+    }): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>;
     private processOrderBy;
-    groupBy(fields: EntityKeyOrString<Entity> | readonly EntityKeyOrString<Entity>[]): SelectQueryBuilder<Entity, RootAlias, Hint, Context>;
-    having(cond?: QBFilterQuery | string, params?: any[], operator?: keyof typeof GroupOperator): SelectQueryBuilder<Entity, RootAlias, Hint, Context>;
-    andHaving(cond?: QBFilterQuery | string, params?: any[]): SelectQueryBuilder<Entity, RootAlias, Hint, Context>;
-    orHaving(cond?: QBFilterQuery | string, params?: any[]): SelectQueryBuilder<Entity, RootAlias, Hint, Context>;
-    onConflict(fields?: Field<Entity> | Field<Entity>[]): InsertQueryBuilder<Entity>;
+    /**
+     * Adds a GROUP BY clause to the query.
+     *
+     * @example
+     * ```ts
+     * qb.select([raw('count(*) as count'), 'status'])
+     *   .groupBy('status');
+     * ```
+     */
+    groupBy<const F extends readonly Field<Entity, RootAlias, Context>[]>(fields: F): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>;
+    /**
+     * Adds a GROUP BY clause to the query.
+     *
+     * @example
+     * ```ts
+     * qb.select([raw('count(*) as count'), 'status'])
+     *   .groupBy('status');
+     * ```
+     */
+    groupBy<F extends Field<Entity, RootAlias, Context>>(fields: F): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>;
+    /**
+     * Adds a GROUP BY clause to the query.
+     *
+     * @example
+     * ```ts
+     * qb.select([raw('count(*) as count'), 'status'])
+     *   .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>;
+    /**
+     * Adds a HAVING clause to the query, typically used with GROUP BY.
+     *
+     * @example
+     * ```ts
+     * qb.select([raw('count(*) as count'), 'status'])
+     *   .groupBy('status')
+     *   .having({ count: { $gt: 5 } });
+     * ```
+     */
+    having(cond?: 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>;
+    onConflict<F extends Field<Entity, RootAlias, Context>>(fields?: F | F[] | RawQueryFragment): InsertQueryBuilder<Entity, RootAlias, Context>;
     ignore(): this;
-    merge(data?: EntityData<Entity> | Field<Entity>[]): this;
-    returning(fields?: Field<Entity> | Field<Entity>[]): this;
+    merge<const P extends string>(data: readonly NestedAutoPath<Entity, RootAlias, Context, P>[]): this;
+    merge<F extends Field<Entity, RootAlias, Context>>(data?: EntityData<Entity> | F[]): this;
+    returning<F extends Field<Entity, RootAlias, Context>>(fields?: F | F[]): this;
     /**
      * @internal
      */
     populate(populate: PopulateOptions<Entity>[], populateWhere?: ObjectQuery<Entity> | PopulateHint | `${PopulateHint}`, populateFilter?: ObjectQuery<Entity> | PopulateHint | `${PopulateHint}`): this;
-    limit(limit?: number, offset?: number): SelectQueryBuilder<Entity, RootAlias, Hint, Context>;
-    offset(offset?: number): SelectQueryBuilder<Entity, RootAlias, Hint, Context>;
+    /**
+     * Sets a LIMIT clause to restrict the number of results.
+     *
+     * @example
+     * ```ts
+     * qb.select('*').limit(10);        // First 10 results
+     * qb.select('*').limit(10, 20);    // 10 results starting from offset 20
+     * ```
+     */
+    limit(limit?: number, offset?: number): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>;
+    /**
+     * Sets an OFFSET clause to skip a number of results.
+     *
+     * @example
+     * ```ts
+     * qb.select('*').limit(10).offset(20);  // Results 21-30
+     * ```
+     */
+    offset(offset?: number): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>;
     withSchema(schema?: string): this;
     setLockMode(mode?: LockMode, tables?: string[]): this;
     setFlushMode(flushMode?: FlushMode): this;
@@ -220,8 +623,12 @@ 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>;
-    from<Entity extends object>(target: EntityName<Entity>): SelectQueryBuilder<Entity, RootAlias, Hint, Context>;
+    from<Entity extends object>(target: QueryBuilder<Entity>, aliasName?: string): SelectQueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>;
+    /**
+     * 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>;
     getNativeQuery(processVirtualEntity?: boolean): NativeQueryBuilder;
     /**
      * Returns the query with parameters as wildcards.
@@ -281,30 +688,30 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      * }
      * ```
      */
-    stream(options?: QBStreamOptions): AsyncIterableIterator<Loaded<Entity, Hint>>;
+    stream(options?: QBStreamOptions): AsyncIterableIterator<Loaded<Entity, Hint, Fields>>;
     /**
      * Alias for `qb.getResultList()`
      */
-    getResult(): Promise<Loaded<Entity, Hint>[]>;
+    getResult(): Promise<Loaded<Entity, Hint, Fields>[]>;
     /**
      * Executes the query, returning array of results mapped to entity instances.
      */
-    getResultList(limit?: number): Promise<Loaded<Entity, Hint>[]>;
+    getResultList(limit?: number): Promise<Loaded<Entity, Hint, Fields>[]>;
     private propagatePopulateHint;
     private mapResult;
     private mapResults;
     /**
      * Executes the query, returning the first result or null
      */
-    getSingleResult(): Promise<Entity | null>;
+    getSingleResult(): Promise<Loaded<Entity, Hint, Fields> | null>;
     /**
      * Executes count query (without offset and limit), returning total count of results
      */
-    getCount(field?: EntityKeyOrString<Entity> | EntityKeyOrString<Entity>[], distinct?: boolean): Promise<number>;
+    getCount<F extends Field<Entity, RootAlias, Context>>(field?: F | F[], distinct?: boolean): Promise<number>;
     /**
      * Executes the query, returning both array of results and total count query (without offset and limit).
      */
-    getResultAndCount(): Promise<[Entity[], number]>;
+    getResultAndCount(): Promise<[Loaded<Entity, Hint, Fields>[], number]>;
     /**
      * Returns native query builder instance with sub-query aliased with given alias.
      */
@@ -314,7 +721,7 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      * You can provide the target entity name as the first parameter and use the second parameter to point to an existing property to infer its field name.
      */
     as<T>(targetEntity: EntityName<T>, alias: EntityKey<T>): NativeQueryBuilder;
-    clone(reset?: boolean | string[], preserve?: string[]): QueryBuilder<Entity>;
+    clone(reset?: boolean | string[], preserve?: string[]): QueryBuilder<Entity, RootAlias, Hint, Context, RawAliases, Fields>;
     /**
      * Sets logger context for this query builder.
      */
@@ -325,7 +732,13 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
     getLoggerContext<T extends Dictionary & LoggingOptions = Dictionary>(): T;
     private fromVirtual;
     private joinReference;
-    protected prepareFields<T>(fields: Field<T>[], type?: 'where' | 'groupBy' | 'sub-query', schema?: string): (string | RawQueryFragment)[];
+    protected prepareFields<T>(fields: InternalField<T>[], type?: 'where' | 'groupBy' | 'sub-query', schema?: string): (string | RawQueryFragment)[];
+    /**
+     * Resolves nested paths like `a.books.title` to their actual field references.
+     * Auto-joins relations as needed and returns `{alias}.{field}`.
+     * For embeddeds: navigates into flattened embeddeds to return the correct field name.
+     */
+    protected resolveNestedPath(field: string): string | string[];
     private init;
     private getQueryBase;
     private applyDiscriminatorCondition;
@@ -373,11 +786,11 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
     private ensureFromClause;
     private ensureNotFinalized;
 }
-export interface RunQueryBuilder<Entity extends object> extends Omit<QueryBuilder<Entity, any, any, any>, 'getResult' | 'getSingleResult' | 'getResultList' | 'where'> {
-    where(cond: QBFilterQuery<Entity> | string, params?: keyof typeof GroupOperator | any[], operator?: keyof typeof GroupOperator): this;
+export interface RunQueryBuilder<Entity extends object, RootAlias extends string = never, Context extends object = never, RawAliases extends string = never> extends Omit<QueryBuilder<Entity, RootAlias, never, Context, RawAliases, '*'>, 'getResult' | 'getSingleResult' | 'getResultList' | 'where'> {
+    where(cond: QBFilterQuery<Entity, RootAlias, Context, RawAliases> | string, params?: keyof typeof GroupOperator | any[], operator?: keyof typeof GroupOperator): this;
     execute<Result = QueryResult<Entity>>(method?: 'all' | 'get' | 'run', mapResults?: boolean): Promise<Result>;
 }
-export interface SelectQueryBuilder<Entity extends object = AnyEntity, RootAlias extends string = never, Hint extends string = never, Context extends object = never> extends QueryBuilder<Entity, RootAlias, Hint, Context> {
+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>;
@@ -397,11 +810,11 @@ export interface CountQueryBuilder<Entity extends object> extends QueryBuilder<E
         count: number;
     }>>(method: 'run', mapResults?: boolean): Promise<Result>;
 }
-export interface InsertQueryBuilder<T extends object> extends RunQueryBuilder<T> {
+export interface InsertQueryBuilder<T extends object, RootAlias extends string = never, Context extends object = never> extends RunQueryBuilder<T, RootAlias, Context> {
 }
-export interface UpdateQueryBuilder<T extends object> extends RunQueryBuilder<T> {
+export interface UpdateQueryBuilder<T extends object, RootAlias extends string = never, Context extends object = never> extends RunQueryBuilder<T, RootAlias, Context> {
 }
-export interface DeleteQueryBuilder<T extends object> extends RunQueryBuilder<T> {
+export interface DeleteQueryBuilder<T extends object, RootAlias extends string = never, Context extends object = never> extends RunQueryBuilder<T, RootAlias, Context> {
 }
 export interface TruncateQueryBuilder<T extends object> extends RunQueryBuilder<T> {
 }