@mikro-orm/sql 7.0.0-dev.97 → 7.0.0-dev.99

package/query/QueryBuilder.js

@@ -0,0 +1,1558 @@
+import { helper, isRaw, LoadStrategy, LockMode, PopulateHint, QueryFlag, QueryHelper, raw, RawQueryFragment, Reference, ReferenceKind, serialize, Utils, ValidationError, inspect, } from '@mikro-orm/core';
+import { JoinType, QueryType } from './enums.js';
+import { QueryBuilderHelper } from './QueryBuilderHelper.js';
+import { CriteriaNodeFactory } from './CriteriaNodeFactory.js';
+import { NativeQueryBuilder } from './NativeQueryBuilder.js';
+/**
+ * SQL query builder with fluent interface.
+ *
+ * ```ts
+ * const qb = orm.em.createQueryBuilder(Publisher);
+ * qb.select('*')
+ *   .where({
+ *     name: 'test 123',
+ *     type: PublisherType.GLOBAL,
+ *   })
+ *   .orderBy({
+ *     name: QueryOrder.DESC,
+ *     type: QueryOrder.ASC,
+ *   })
+ *   .limit(2, 1);
+ *
+ * const publisher = await qb.getSingleResult();
+ * ```
+ */
+export class QueryBuilder {
+    metadata;
+    driver;
+    context;
+    connectionType;
+    em;
+    loggerContext;
+    get mainAlias() {
+        this.ensureFromClause();
+        return this._mainAlias;
+    }
+    get alias() {
+        return this.mainAlias.aliasName;
+    }
+    get helper() {
+        this.ensureFromClause();
+        return this._helper;
+    }
+    get type() {
+        return this._type ?? QueryType.SELECT;
+    }
+    /** @internal */
+    _populate = [];
+    /** @internal */
+    _populateMap = {};
+    /** @internal */
+    rawFragments = new Set();
+    aliasCounter = 0;
+    flags = new Set([QueryFlag.CONVERT_CUSTOM_TYPES]);
+    finalized = false;
+    populateHintFinalized = false;
+    _joins = {};
+    _explicitAlias = false;
+    _schema;
+    _cond = {};
+    _data;
+    _orderBy = [];
+    _groupBy = [];
+    _having = {};
+    _returning;
+    _onConflict;
+    _limit;
+    _offset;
+    _distinctOn;
+    _joinedProps = new Map();
+    _cache;
+    _indexHint;
+    _comments = [];
+    _hintComments = [];
+    flushMode;
+    lockMode;
+    lockTables;
+    subQueries = {};
+    _mainAlias;
+    _aliases = {};
+    _helper;
+    _query;
+    platform;
+    /**
+     * @internal
+     */
+    constructor(entityName, metadata, driver, context, alias, connectionType, em, loggerContext) {
+        this.metadata = metadata;
+        this.driver = driver;
+        this.context = context;
+        this.connectionType = connectionType;
+        this.em = em;
+        this.loggerContext = loggerContext;
+        this.platform = this.driver.getPlatform();
+        if (alias) {
+            this.aliasCounter++;
+            this._explicitAlias = true;
+        }
+        // @ts-expect-error union type does not match the overloaded method signature
+        this.from(entityName, alias);
+    }
+    select(fields, distinct = false) {
+        this.ensureNotFinalized();
+        this._fields = Utils.asArray(fields);
+        if (distinct) {
+            this.flags.add(QueryFlag.DISTINCT);
+        }
+        return this.init(QueryType.SELECT);
+    }
+    addSelect(fields) {
+        this.ensureNotFinalized();
+        if (this._type && this._type !== QueryType.SELECT) {
+            return this;
+        }
+        return this.select([...Utils.asArray(this._fields), ...Utils.asArray(fields)]);
+    }
+    distinct() {
+        this.ensureNotFinalized();
+        return this.setFlag(QueryFlag.DISTINCT);
+    }
+    /** postgres only */
+    distinctOn(fields) {
+        this.ensureNotFinalized();
+        this._distinctOn = Utils.asArray(fields);
+        return this;
+    }
+    insert(data) {
+        return this.init(QueryType.INSERT, data);
+    }
+    update(data) {
+        return this.init(QueryType.UPDATE, data);
+    }
+    delete(cond) {
+        return this.init(QueryType.DELETE, undefined, cond);
+    }
+    truncate() {
+        return this.init(QueryType.TRUNCATE);
+    }
+    count(field, distinct = false) {
+        if (field) {
+            this._fields = Utils.asArray(field);
+        }
+        else if (distinct || this.hasToManyJoins()) {
+            this._fields = this.mainAlias.metadata.primaryKeys;
+        }
+        else {
+            this._fields = [raw('*')];
+        }
+        if (distinct) {
+            this.flags.add(QueryFlag.DISTINCT);
+        }
+        return this.init(QueryType.COUNT);
+    }
+    join(field, alias, cond = {}, type = JoinType.innerJoin, path, schema) {
+        this.joinReference(field, alias, cond, type, path, schema);
+        return this;
+    }
+    innerJoin(field, alias, cond = {}, schema) {
+        this.join(field, alias, cond, JoinType.innerJoin, undefined, schema);
+        return this;
+    }
+    innerJoinLateral(field, alias, cond, schema) {
+        this.join(field, alias, cond, JoinType.innerJoinLateral, undefined, schema);
+        return this;
+    }
+    leftJoin(field, alias, cond = {}, schema) {
+        return this.join(field, alias, cond, JoinType.leftJoin, undefined, schema);
+    }
+    leftJoinLateral(field, alias, cond, schema) {
+        return this.join(field, alias, cond, JoinType.leftJoinLateral, undefined, schema);
+    }
+    joinAndSelect(field, alias, cond = {}, type = JoinType.innerJoin, path, fields, schema) {
+        if (!this._type) {
+            this.select('*');
+        }
+        let subquery;
+        if (Array.isArray(field)) {
+            const rawFragment = field[1] instanceof QueryBuilder ? field[1].toRaw() : field[1];
+            subquery = this.platform.formatQuery(rawFragment.sql, rawFragment.params);
+            field = field[0];
+        }
+        const { prop, key } = this.joinReference(field, alias, cond, type, path, schema, subquery);
+        const [fromAlias] = this.helper.splitField(field);
+        if (subquery) {
+            this._joins[key].subquery = subquery;
+        }
+        const populate = this._joinedProps.get(fromAlias);
+        const item = { field: prop.name, strategy: LoadStrategy.JOINED, children: [] };
+        if (populate) {
+            populate.children.push(item);
+        }
+        else { // root entity
+            this._populate.push(item);
+        }
+        this._joinedProps.set(alias, item);
+        this.addSelect(this.getFieldsForJoinedLoad(prop, alias, fields));
+        return this;
+    }
+    leftJoinAndSelect(field, alias, cond = {}, fields, schema) {
+        return this.joinAndSelect(field, alias, cond, JoinType.leftJoin, undefined, fields, schema);
+    }
+    leftJoinLateralAndSelect(field, alias, cond = {}, fields, schema) {
+        return this.joinAndSelect(field, alias, cond, JoinType.leftJoinLateral, undefined, fields, schema);
+    }
+    innerJoinAndSelect(field, alias, cond = {}, fields, schema) {
+        return this.joinAndSelect(field, alias, cond, JoinType.innerJoin, undefined, fields, schema);
+    }
+    innerJoinLateralAndSelect(field, alias, cond = {}, fields, schema) {
+        return this.joinAndSelect(field, alias, cond, JoinType.innerJoinLateral, undefined, fields, schema);
+    }
+    getFieldsForJoinedLoad(prop, alias, explicitFields) {
+        const fields = [];
+        const populate = [];
+        const joinKey = Object.keys(this._joins).find(join => join.endsWith(`#${alias}`));
+        if (joinKey) {
+            const path = this._joins[joinKey].path.split('.').slice(1);
+            let children = this._populate;
+            for (let i = 0; i < path.length; i++) {
+                const child = children.filter(hint => {
+                    const [propName] = hint.field.split(':', 2);
+                    return propName === path[i];
+                });
+                children = child.flatMap(c => c.children);
+            }
+            populate.push(...children);
+        }
+        for (const p of prop.targetMeta.getPrimaryProps()) {
+            fields.push(...this.driver.mapPropToFieldNames(this, p, alias));
+        }
+        if (explicitFields) {
+            for (const field of explicitFields) {
+                const [a, f] = this.helper.splitField(field);
+                const p = prop.targetMeta.properties[f];
+                if (p) {
+                    fields.push(...this.driver.mapPropToFieldNames(this, p, alias));
+                }
+                else {
+                    fields.push(`${a}.${f} as ${a}__${f}`);
+                }
+            }
+        }
+        prop.targetMeta.props
+            .filter(prop => {
+            if (!explicitFields) {
+                return this.platform.shouldHaveColumn(prop, populate);
+            }
+            return prop.primary && !explicitFields.includes(prop.name) && !explicitFields.includes(`${alias}.${prop.name}`);
+        })
+            .forEach(prop => fields.push(...this.driver.mapPropToFieldNames(this, prop, alias)));
+        return fields;
+    }
+    /**
+     * Apply filters to the QB where condition.
+     */
+    async applyFilters(filterOptions = {}) {
+        /* v8 ignore next */
+        if (!this.em) {
+            throw new Error('Cannot apply filters, this QueryBuilder is not attached to an EntityManager');
+        }
+        const cond = await this.em.applyFilters(this.mainAlias.entityName, {}, filterOptions, 'read');
+        this.andWhere(cond);
+    }
+    autoJoinedPaths = [];
+    /**
+     * @internal
+     */
+    scheduleFilterCheck(path) {
+        this.autoJoinedPaths.push(path);
+    }
+    /**
+     * @internal
+     */
+    async applyJoinedFilters(em, filterOptions) {
+        for (const path of this.autoJoinedPaths) {
+            const join = this.getJoinForPath(path);
+            if (join.type === JoinType.pivotJoin) {
+                continue;
+            }
+            filterOptions = QueryHelper.mergePropertyFilters(join.prop.filters, filterOptions);
+            const cond = await em.applyFilters(join.prop.type, join.cond, filterOptions, 'read');
+            if (Utils.hasObjectKeys(cond)) {
+                // remove nested filters, we only care about scalars here, nesting would require another join branch
+                for (const key of Object.keys(cond)) {
+                    if (Utils.isPlainObject(cond[key]) && Object.keys(cond[key]).every(k => !(Utils.isOperator(k) && !['$some', '$none', '$every'].includes(k)))) {
+                        delete cond[key];
+                    }
+                }
+                if (Utils.hasObjectKeys(join.cond)) {
+                    /* v8 ignore next */
+                    join.cond = { $and: [join.cond, cond] };
+                }
+                else {
+                    join.cond = { ...cond };
+                }
+            }
+        }
+    }
+    withSubQuery(subQuery, alias) {
+        this.ensureNotFinalized();
+        if (subQuery instanceof RawQueryFragment) {
+            this.subQueries[alias] = this.platform.formatQuery(subQuery.sql, subQuery.params);
+        }
+        else {
+            this.subQueries[alias] = subQuery.toString();
+        }
+        return this;
+    }
+    where(cond, params, operator) {
+        this.ensureNotFinalized();
+        const rawField = RawQueryFragment.getKnownFragment(cond);
+        if (rawField) {
+            const sql = this.platform.formatQuery(rawField.sql, rawField.params);
+            cond = { [raw(`(${sql})`)]: Utils.asArray(params) };
+            operator ??= '$and';
+        }
+        else if (typeof cond === 'string') {
+            cond = { [raw(`(${cond})`, Utils.asArray(params))]: [] };
+            operator ??= '$and';
+        }
+        else {
+            cond = QueryHelper.processWhere({
+                where: cond,
+                entityName: this.mainAlias.entityName,
+                metadata: this.metadata,
+                platform: this.platform,
+                aliasMap: this.getAliasMap(),
+                aliased: [QueryType.SELECT, QueryType.COUNT].includes(this.type),
+                convertCustomTypes: this.flags.has(QueryFlag.CONVERT_CUSTOM_TYPES),
+            });
+        }
+        const op = operator || params;
+        const topLevel = !op || !Utils.hasObjectKeys(this._cond);
+        const criteriaNode = CriteriaNodeFactory.createNode(this.metadata, this.mainAlias.entityName, cond);
+        const ignoreBranching = this.__populateWhere === 'infer';
+        if ([QueryType.UPDATE, QueryType.DELETE].includes(this.type) && criteriaNode.willAutoJoin(this, undefined, { ignoreBranching })) {
+            // use sub-query to support joining
+            this.setFlag(this.type === QueryType.UPDATE ? QueryFlag.UPDATE_SUB_QUERY : QueryFlag.DELETE_SUB_QUERY);
+            this.select(this.mainAlias.metadata.primaryKeys, true);
+        }
+        if (topLevel) {
+            this._cond = criteriaNode.process(this, { ignoreBranching });
+        }
+        else if (Array.isArray(this._cond[op])) {
+            this._cond[op].push(criteriaNode.process(this, { ignoreBranching }));
+        }
+        else {
+            const cond1 = [this._cond, criteriaNode.process(this, { ignoreBranching })];
+            this._cond = { [op]: cond1 };
+        }
+        if (this._onConflict) {
+            this._onConflict[this._onConflict.length - 1].where = this.helper.processOnConflictCondition(this._cond, this._schema);
+            this._cond = {};
+        }
+        return this;
+    }
+    andWhere(cond, params) {
+        return this.where(cond, params, '$and');
+    }
+    orWhere(cond, params) {
+        return this.where(cond, params, '$or');
+    }
+    orderBy(orderBy) {
+        return this.processOrderBy(orderBy, true);
+    }
+    andOrderBy(orderBy) {
+        return this.processOrderBy(orderBy, false);
+    }
+    processOrderBy(orderBy, reset = true) {
+        this.ensureNotFinalized();
+        if (reset) {
+            this._orderBy = [];
+        }
+        Utils.asArray(orderBy).forEach(o => {
+            const processed = QueryHelper.processWhere({
+                where: o,
+                entityName: this.mainAlias.entityName,
+                metadata: this.metadata,
+                platform: this.platform,
+                aliasMap: this.getAliasMap(),
+                aliased: [QueryType.SELECT, QueryType.COUNT].includes(this.type),
+                convertCustomTypes: false,
+                type: 'orderBy',
+            });
+            this._orderBy.push(CriteriaNodeFactory.createNode(this.metadata, this.mainAlias.entityName, processed).process(this, { matchPopulateJoins: true, type: 'orderBy' }));
+        });
+        return this;
+    }
+    groupBy(fields) {
+        this.ensureNotFinalized();
+        this._groupBy = Utils.asArray(fields);
+        return this;
+    }
+    having(cond = {}, params, operator) {
+        this.ensureNotFinalized();
+        if (typeof cond === 'string') {
+            cond = { [raw(`(${cond})`, params)]: [] };
+        }
+        cond = CriteriaNodeFactory.createNode(this.metadata, this.mainAlias.entityName, cond).process(this);
+        if (!this._having || !operator) {
+            this._having = cond;
+        }
+        else {
+            const cond1 = [this._having, cond];
+            this._having = { [operator]: cond1 };
+        }
+        return this;
+    }
+    andHaving(cond, params) {
+        return this.having(cond, params, '$and');
+    }
+    orHaving(cond, params) {
+        return this.having(cond, params, '$or');
+    }
+    onConflict(fields = []) {
+        const meta = this.mainAlias.metadata;
+        this.ensureNotFinalized();
+        this._onConflict ??= [];
+        this._onConflict.push({
+            fields: isRaw(fields)
+                ? fields
+                : Utils.asArray(fields).flatMap(f => {
+                    const key = f.toString();
+                    /* v8 ignore next */
+                    return meta.properties[key]?.fieldNames ?? [key];
+                }),
+        });
+        return this;
+    }
+    ignore() {
+        if (!this._onConflict) {
+            throw new Error('You need to call `qb.onConflict()` first to use `qb.ignore()`');
+        }
+        this._onConflict[this._onConflict.length - 1].ignore = true;
+        return this;
+    }
+    merge(data) {
+        if (!this._onConflict) {
+            throw new Error('You need to call `qb.onConflict()` first to use `qb.merge()`');
+        }
+        if (Array.isArray(data) && data.length === 0) {
+            return this.ignore();
+        }
+        this._onConflict[this._onConflict.length - 1].merge = data;
+        return this;
+    }
+    returning(fields) {
+        this._returning = Utils.asArray(fields);
+        return this;
+    }
+    /**
+     * @internal
+     */
+    populate(populate, populateWhere, populateFilter) {
+        this.ensureNotFinalized();
+        this._populate = populate;
+        this._populateWhere = populateWhere;
+        this._populateFilter = populateFilter;
+        return this;
+    }
+    limit(limit, offset = 0) {
+        this.ensureNotFinalized();
+        this._limit = limit;
+        if (offset) {
+            this.offset(offset);
+        }
+        return this;
+    }
+    offset(offset) {
+        this.ensureNotFinalized();
+        this._offset = offset;
+        return this;
+    }
+    withSchema(schema) {
+        this.ensureNotFinalized();
+        this._schema = schema;
+        return this;
+    }
+    setLockMode(mode, tables) {
+        this.ensureNotFinalized();
+        if (mode != null && ![LockMode.OPTIMISTIC, LockMode.NONE].includes(mode) && !this.context) {
+            throw ValidationError.transactionRequired();
+        }
+        this.lockMode = mode;
+        this.lockTables = tables;
+        return this;
+    }
+    setFlushMode(flushMode) {
+        this.ensureNotFinalized();
+        this.flushMode = flushMode;
+        return this;
+    }
+    setFlag(flag) {
+        this.ensureNotFinalized();
+        this.flags.add(flag);
+        return this;
+    }
+    unsetFlag(flag) {
+        this.ensureNotFinalized();
+        this.flags.delete(flag);
+        return this;
+    }
+    hasFlag(flag) {
+        return this.flags.has(flag);
+    }
+    cache(config = true) {
+        this.ensureNotFinalized();
+        this._cache = config;
+        return this;
+    }
+    /**
+     * Adds index hint to the FROM clause.
+     */
+    indexHint(sql) {
+        this.ensureNotFinalized();
+        this._indexHint = sql;
+        return this;
+    }
+    /**
+     * Prepend comment to the sql query using the syntax `/* ... *&#8205;/`. Some characters are forbidden such as `/*, *&#8205;/` and `?`.
+     */
+    comment(comment) {
+        this.ensureNotFinalized();
+        this._comments.push(...Utils.asArray(comment));
+        return this;
+    }
+    /**
+     * Add hints to the query using comment-like syntax `/*+ ... *&#8205;/`. MySQL and Oracle use this syntax for optimizer hints.
+     * Also various DB proxies and routers use this syntax to pass hints to alter their behavior. In other dialects the hints
+     * are ignored as simple comments.
+     */
+    hintComment(comment) {
+        this.ensureNotFinalized();
+        this._hintComments.push(...Utils.asArray(comment));
+        return this;
+    }
+    from(target, aliasName) {
+        this.ensureNotFinalized();
+        if (target instanceof QueryBuilder) {
+            this.fromSubQuery(target, aliasName);
+        }
+        else {
+            const entityName = Utils.className(target);
+            if (aliasName && this._mainAlias && entityName !== this._mainAlias.aliasName) {
+                throw new Error(`Cannot override the alias to '${aliasName}' since a query already contains references to '${this._mainAlias.aliasName}'`);
+            }
+            this.fromEntityName(entityName, aliasName);
+        }
+        return this;
+    }
+    getNativeQuery(processVirtualEntity = true) {
+        if (this._query?.qb) {
+            return this._query.qb;
+        }
+        this._query = {};
+        this.finalize();
+        const qb = this.getQueryBase(processVirtualEntity);
+        Utils.runIfNotEmpty(() => this.helper.appendQueryCondition(this.type, this._cond, qb), this._cond && !this._onConflict);
+        Utils.runIfNotEmpty(() => qb.groupBy(this.prepareFields(this._groupBy, 'groupBy')), this._groupBy);
+        Utils.runIfNotEmpty(() => this.helper.appendQueryCondition(this.type, this._having, qb, undefined, 'having'), this._having);
+        Utils.runIfNotEmpty(() => {
+            const queryOrder = this.helper.getQueryOrder(this.type, this._orderBy, this._populateMap);
+            if (queryOrder.length > 0) {
+                const sql = Utils.unique(queryOrder).join(', ');
+                qb.orderBy(sql);
+                return;
+            }
+        }, this._orderBy);
+        Utils.runIfNotEmpty(() => qb.limit(this._limit), this._limit != null);
+        Utils.runIfNotEmpty(() => qb.offset(this._offset), this._offset);
+        Utils.runIfNotEmpty(() => qb.comment(this._comments), this._comments);
+        Utils.runIfNotEmpty(() => qb.hintComment(this._hintComments), this._hintComments);
+        Utils.runIfNotEmpty(() => this.helper.appendOnConflictClause(QueryType.UPSERT, this._onConflict, qb), this._onConflict);
+        if (this.lockMode) {
+            this.helper.getLockSQL(qb, this.lockMode, this.lockTables, this._joins);
+        }
+        this.helper.finalize(this.type, qb, this.mainAlias.metadata, this._data, this._returning);
+        this.clearRawFragmentsCache();
+        return this._query.qb = qb;
+    }
+    /**
+     * @internal
+     */
+    clearRawFragmentsCache() {
+        this.rawFragments.forEach(key => RawQueryFragment.remove(key));
+        this.rawFragments.clear();
+    }
+    /**
+     * Returns the query with parameters as wildcards.
+     */
+    getQuery() {
+        return this.toQuery().sql;
+    }
+    /**
+     * Returns raw fragment representation of this QueryBuilder.
+     */
+    toRaw() {
+        const { sql, params } = this.toQuery();
+        return raw(sql, params);
+    }
+    toQuery() {
+        if (this._query?.sql) {
+            return { sql: this._query.sql, params: this._query.params };
+        }
+        const query = this.getNativeQuery().compile();
+        this._query.sql = query.sql;
+        this._query.params = query.params;
+        return { sql: this._query.sql, params: this._query.params };
+    }
+    /**
+     * Returns the list of all parameters for this query.
+     */
+    getParams() {
+        return this.toQuery().params;
+    }
+    /**
+     * Returns raw interpolated query string with all the parameters inlined.
+     */
+    getFormattedQuery() {
+        const query = this.toQuery();
+        return this.platform.formatQuery(query.sql, query.params);
+    }
+    /**
+     * @internal
+     */
+    getAliasForJoinPath(path, options) {
+        if (!path || path === this.mainAlias.entityName) {
+            return this.mainAlias.aliasName;
+        }
+        const join = typeof path === 'string' ? this.getJoinForPath(path, options) : path;
+        if (join?.path?.endsWith('[pivot]')) {
+            return join.alias;
+        }
+        return join?.inverseAlias || join?.alias;
+    }
+    /**
+     * @internal
+     */
+    getJoinForPath(path, options) {
+        const joins = Object.values(this._joins);
+        if (joins.length === 0) {
+            return undefined;
+        }
+        let join = joins.find(j => j.path === path);
+        if (options?.preferNoBranch) {
+            join = joins.find(j => {
+                return j.path?.replace(/\[\d+]|\[populate]/g, '') === path.replace(/\[\d+]|\[populate]/g, '');
+            });
+        }
+        if (!join && options?.ignoreBranching) {
+            join = joins.find(j => {
+                return j.path?.replace(/\[\d+]/g, '') === path.replace(/\[\d+]/g, '');
+            });
+        }
+        if (!join && options?.matchPopulateJoins && options?.ignoreBranching) {
+            join = joins.find(j => {
+                return j.path?.replace(/\[\d+]|\[populate]/g, '') === path.replace(/\[\d+]|\[populate]/g, '');
+            });
+        }
+        if (!join && options?.matchPopulateJoins) {
+            join = joins.find(j => {
+                return j.path?.replace(/\[populate]/g, '') === path.replace(/\[populate]/g, '');
+            });
+        }
+        return join;
+    }
+    /**
+     * @internal
+     */
+    getNextAlias(entityName = 'e') {
+        return this.driver.config.getNamingStrategy().aliasName(entityName, this.aliasCounter++);
+    }
+    /**
+     * @internal
+     */
+    getAliasMap() {
+        return Object.fromEntries(Object.entries(this._aliases).map(([key, value]) => [key, value.entityName]));
+    }
+    /**
+     * Executes this QB and returns the raw results, mapped to the property names (unless disabled via last parameter).
+     * Use `method` to specify what kind of result you want to get (array/single/meta).
+     */
+    async execute(method, options) {
+        options = typeof options === 'boolean' ? { mapResults: options } : (options ?? {});
+        options.mergeResults ??= true;
+        options.mapResults ??= true;
+        const isRunType = [QueryType.INSERT, QueryType.UPDATE, QueryType.DELETE, QueryType.TRUNCATE].includes(this.type);
+        method ??= isRunType ? 'run' : 'all';
+        if (!this.connectionType && (isRunType || this.context)) {
+            this.connectionType = 'write';
+        }
+        if (!this.finalized && method === 'get' && this.type === QueryType.SELECT) {
+            this.limit(1);
+        }
+        const query = this.toQuery();
+        const cached = await this.em?.tryCache(this.mainAlias.entityName, this._cache, ['qb.execute', query.sql, query.params, method]);
+        if (cached?.data !== undefined) {
+            return cached.data;
+        }
+        const loggerContext = { id: this.em?.id, ...this.loggerContext };
+        const res = await this.getConnection().execute(query.sql, query.params, method, this.context, loggerContext);
+        const meta = this.mainAlias.metadata;
+        if (!options.mapResults || !meta) {
+            await this.em?.storeCache(this._cache, cached, res);
+            return res;
+        }
+        if (method === 'run') {
+            return res;
+        }
+        const joinedProps = this.driver.joinedProps(meta, this._populate);
+        let mapped;
+        if (Array.isArray(res)) {
+            const map = {};
+            mapped = res.map(r => this.driver.mapResult(r, meta, this._populate, this, map));
+            if (options.mergeResults && joinedProps.length > 0) {
+                mapped = this.driver.mergeJoinedResult(mapped, this.mainAlias.metadata, joinedProps);
+            }
+        }
+        else {
+            mapped = [this.driver.mapResult(res, meta, joinedProps, this)];
+        }
+        if (method === 'get') {
+            await this.em?.storeCache(this._cache, cached, mapped[0]);
+            return mapped[0];
+        }
+        await this.em?.storeCache(this._cache, cached, mapped);
+        return mapped;
+    }
+    getConnection() {
+        const write = !this.platform.getConfig().get('preferReadReplicas');
+        const type = this.connectionType || (write ? 'write' : 'read');
+        return this.driver.getConnection(type);
+    }
+    /**
+     * Executes the query and returns an async iterable (async generator) that yields results one by one.
+     * By default, the results are merged and mapped to entity instances, without adding them to the identity map.
+     * You can disable merging and mapping by passing the options `{ mergeResults: false, mapResults: false }`.
+     * This is useful for processing large datasets without loading everything into memory at once.
+     *
+     * ```ts
+     * const qb = em.createQueryBuilder(Book, 'b');
+     * qb.select('*').where({ title: '1984' }).leftJoinAndSelect('b.author', 'a');
+     *
+     * for await (const book of qb.stream()) {
+     *   // book is an instance of Book entity
+     *   console.log(book.title, book.author.name);
+     * }
+     * ```
+     */
+    async *stream(options) {
+        options ??= {};
+        options.mergeResults ??= true;
+        options.mapResults ??= true;
+        const query = this.toQuery();
+        const loggerContext = { id: this.em?.id, ...this.loggerContext };
+        const res = this.getConnection().stream(query.sql, query.params, this.context, loggerContext);
+        const meta = this.mainAlias.metadata;
+        if (options.rawResults || !meta) {
+            yield* res;
+            return;
+        }
+        const joinedProps = this.driver.joinedProps(meta, this._populate);
+        const stack = [];
+        const hash = (data) => {
+            return Utils.getPrimaryKeyHash(meta.primaryKeys.map(pk => data[pk]));
+        };
+        for await (const row of res) {
+            const mapped = this.driver.mapResult(row, meta, this._populate, this);
+            if (!options.mergeResults || joinedProps.length === 0) {
+                yield this.mapResult(mapped, options.mapResults);
+                continue;
+            }
+            if (stack.length > 0 && hash(stack[stack.length - 1]) !== hash(mapped)) {
+                const res = this.driver.mergeJoinedResult(stack, this.mainAlias.metadata, joinedProps);
+                for (const row of res) {
+                    yield this.mapResult(row, options.mapResults);
+                }
+                stack.length = 0;
+            }
+            stack.push(mapped);
+        }
+        if (stack.length > 0) {
+            const merged = this.driver.mergeJoinedResult(stack, this.mainAlias.metadata, joinedProps);
+            yield this.mapResult(merged[0], options.mapResults);
+        }
+    }
+    /**
+     * Alias for `qb.getResultList()`
+     */
+    async getResult() {
+        return this.getResultList();
+    }
+    /**
+     * Executes the query, returning array of results mapped to entity instances.
+     */
+    async getResultList(limit) {
+        await this.em.tryFlush(this.mainAlias.entityName, { flushMode: this.flushMode });
+        const res = await this.execute('all', true);
+        return this.mapResults(res, limit);
+    }
+    propagatePopulateHint(entity, hint) {
+        helper(entity).__serializationContext.populate = hint.concat(helper(entity).__serializationContext.populate ?? []);
+        hint.forEach(hint => {
+            const [propName] = hint.field.split(':', 2);
+            const value = Reference.unwrapReference(entity[propName]);
+            if (Utils.isEntity(value)) {
+                this.propagatePopulateHint(value, hint.children ?? []);
+            }
+            else if (Utils.isCollection(value)) {
+                value.populated();
+                value.getItems(false).forEach(item => this.propagatePopulateHint(item, hint.children ?? []));
+            }
+        });
+    }
+    mapResult(row, map = true) {
+        if (!map) {
+            return row;
+        }
+        const entity = this.em.map(this.mainAlias.entityName, row, { schema: this._schema });
+        this.propagatePopulateHint(entity, this._populate);
+        return entity;
+    }
+    mapResults(res, limit) {
+        const entities = [];
+        for (const row of res) {
+            const entity = this.mapResult(row);
+            this.propagatePopulateHint(entity, this._populate);
+            entities.push(entity);
+            if (limit != null && --limit === 0) {
+                break;
+            }
+        }
+        return Utils.unique(entities);
+    }
+    /**
+     * Executes the query, returning the first result or null
+     */
+    async getSingleResult() {
+        if (!this.finalized) {
+            this.limit(1);
+        }
+        const [res] = await this.getResultList(1);
+        return res || null;
+    }
+    /**
+     * Executes count query (without offset and limit), returning total count of results
+     */
+    async getCount(field, distinct) {
+        let res;
+        if (this.type === QueryType.COUNT) {
+            res = await this.execute('get', false);
+        }
+        else {
+            const qb = this._type === undefined ? this : this.clone();
+            qb.processPopulateHint(); // needs to happen sooner so `qb.hasToManyJoins()` reports correctly
+            qb.count(field, distinct ?? qb.hasToManyJoins()).limit(undefined).offset(undefined).orderBy([]);
+            res = await qb.execute('get', false);
+        }
+        return res ? +res.count : 0;
+    }
+    /**
+     * Executes the query, returning both array of results and total count query (without offset and limit).
+     */
+    async getResultAndCount() {
+        return [
+            await this.clone().getResultList(),
+            await this.clone().getCount(),
+        ];
+    }
+    /**
+     * Returns native query builder instance with sub-query aliased with given alias.
+     * You can provide `EntityName.propName` as alias, then the field name will be used based on the metadata
+     */
+    as(alias) {
+        const qb = this.getNativeQuery();
+        if (alias.includes('.')) {
+            const [a, f] = alias.split('.');
+            const meta = this.metadata.find(a);
+            /* v8 ignore next */
+            alias = meta?.properties[f]?.fieldNames[0] ?? alias;
+        }
+        qb.as(alias);
+        // tag the instance, so it is possible to detect it easily
+        Object.defineProperty(qb, '__as', { enumerable: false, value: alias });
+        return qb;
+    }
+    clone(reset) {
+        const qb = new QueryBuilder(this.mainAlias.entityName, this.metadata, this.driver, this.context, this.mainAlias.aliasName, this.connectionType, this.em);
+        if (reset === true) {
+            return qb;
+        }
+        reset = reset || [];
+        // 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',
+            '_comments', '_hintComments', 'rawFragments', 'aliasCounter',
+        ];
+        RawQueryFragment.cloneRegistry = this.rawFragments;
+        for (const prop of Object.keys(this)) {
+            if (reset.includes(prop) || ['_helper', '_query'].includes(prop)) {
+                continue;
+            }
+            qb[prop] = properties.includes(prop) ? Utils.copy(this[prop]) : this[prop];
+        }
+        delete RawQueryFragment.cloneRegistry;
+        /* v8 ignore next */
+        if (this._fields && !reset.includes('_fields')) {
+            qb._fields = [...this._fields];
+        }
+        qb._aliases = { ...this._aliases };
+        qb._helper.aliasMap = qb._aliases;
+        qb.finalized = false;
+        return qb;
+    }
+    /**
+     * Sets logger context for this query builder.
+     */
+    setLoggerContext(context) {
+        this.loggerContext = context;
+    }
+    /**
+     * Gets logger context for this query builder.
+     */
+    getLoggerContext() {
+        this.loggerContext ??= {};
+        return this.loggerContext;
+    }
+    fromVirtual(meta) {
+        if (typeof meta.expression === 'string') {
+            return `(${meta.expression}) as ${this.platform.quoteIdentifier(this.alias)}`;
+        }
+        const res = meta.expression(this.em, this._cond, {});
+        if (typeof res === 'string') {
+            return `(${res}) as ${this.platform.quoteIdentifier(this.alias)}`;
+        }
+        if (res instanceof QueryBuilder) {
+            return `(${res.getFormattedQuery()}) as ${this.platform.quoteIdentifier(this.alias)}`;
+        }
+        if (res instanceof RawQueryFragment) {
+            const query = this.platform.formatQuery(res.sql, res.params);
+            return `(${query}) as ${this.platform.quoteIdentifier(this.alias)}`;
+        }
+        /* v8 ignore next */
+        return res;
+    }
+    joinReference(field, alias, cond, type, path, schema, subquery) {
+        this.ensureNotFinalized();
+        if (typeof field === 'object') {
+            const prop = {
+                name: '__subquery__',
+                kind: ReferenceKind.MANY_TO_ONE,
+            };
+            if (field instanceof QueryBuilder) {
+                prop.type = field.mainAlias.entityName;
+                prop.targetMeta = field.mainAlias.metadata;
+                field = field.getNativeQuery();
+            }
+            if (field instanceof RawQueryFragment) {
+                field = this.platform.formatQuery(field.sql, field.params);
+            }
+            const key = `${this.alias}.${prop.name}#${alias}`;
+            this._joins[key] = {
+                prop,
+                alias,
+                type,
+                cond,
+                schema,
+                subquery: field.toString(),
+                ownerAlias: this.alias,
+            };
+            return { prop, key };
+        }
+        if (!subquery && type.includes('lateral')) {
+            throw new Error(`Lateral join can be used only with a sub-query.`);
+        }
+        const [fromAlias, fromField] = this.helper.splitField(field);
+        const q = (str) => `'${str}'`;
+        if (!this._aliases[fromAlias]) {
+            throw new Error(`Trying to join ${q(fromField)} with alias ${q(fromAlias)}, but ${q(fromAlias)} is not a known alias. Available aliases are: ${Object.keys(this._aliases).map(q).join(', ')}.`);
+        }
+        const entityName = this._aliases[fromAlias].entityName;
+        const meta = this.metadata.get(entityName);
+        const prop = meta.properties[fromField];
+        if (!prop) {
+            throw new Error(`Trying to join ${q(field)}, but ${q(fromField)} is not a defined relation on ${meta.className}.`);
+        }
+        this.createAlias(prop.type, alias);
+        cond = QueryHelper.processWhere({
+            where: cond,
+            entityName: this.mainAlias.entityName,
+            metadata: this.metadata,
+            platform: this.platform,
+            aliasMap: this.getAliasMap(),
+            aliased: [QueryType.SELECT, QueryType.COUNT].includes(this.type),
+        });
+        const criteriaNode = CriteriaNodeFactory.createNode(this.metadata, prop.targetMeta.className, cond);
+        cond = criteriaNode.process(this, { ignoreBranching: true, alias });
+        let aliasedName = `${fromAlias}.${prop.name}#${alias}`;
+        path ??= `${(Object.values(this._joins).find(j => j.alias === fromAlias)?.path ?? entityName)}.${prop.name}`;
+        if (prop.kind === ReferenceKind.ONE_TO_MANY) {
+            this._joins[aliasedName] = this.helper.joinOneToReference(prop, fromAlias, alias, type, cond, schema);
+            this._joins[aliasedName].path ??= path;
+        }
+        else if (prop.kind === ReferenceKind.MANY_TO_MANY) {
+            let pivotAlias = alias;
+            if (type !== JoinType.pivotJoin) {
+                const oldPivotAlias = this.getAliasForJoinPath(path + '[pivot]');
+                pivotAlias = oldPivotAlias ?? this.getNextAlias(prop.pivotEntity);
+                aliasedName = `${fromAlias}.${prop.name}#${pivotAlias}`;
+            }
+            const joins = this.helper.joinManyToManyReference(prop, fromAlias, alias, pivotAlias, type, cond, path, schema);
+            Object.assign(this._joins, joins);
+            this.createAlias(prop.pivotEntity, pivotAlias);
+            this._joins[aliasedName].path ??= path;
+            aliasedName = Object.keys(joins)[1];
+        }
+        else if (prop.kind === ReferenceKind.ONE_TO_ONE) {
+            this._joins[aliasedName] = this.helper.joinOneToReference(prop, fromAlias, alias, type, cond, schema);
+            this._joins[aliasedName].path ??= path;
+        }
+        else { // MANY_TO_ONE
+            this._joins[aliasedName] = this.helper.joinManyToOneReference(prop, fromAlias, alias, type, cond, schema);
+            this._joins[aliasedName].path ??= path;
+        }
+        return { prop, key: aliasedName };
+    }
+    prepareFields(fields, type = 'where') {
+        const ret = [];
+        const getFieldName = (name) => {
+            return this.helper.mapper(name, this.type, undefined, type === 'groupBy' ? null : undefined);
+        };
+        fields.forEach(field => {
+            const rawField = RawQueryFragment.getKnownFragment(field, false);
+            if (rawField) {
+                ret.push(rawField);
+                return;
+            }
+            if (typeof field !== 'string') {
+                ret.push(field);
+                return;
+            }
+            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]));
+                return;
+            }
+            const [a, f] = this.helper.splitField(field);
+            const prop = this.helper.getProperty(f, a);
+            /* v8 ignore next */
+            if (prop && [ReferenceKind.ONE_TO_MANY, ReferenceKind.MANY_TO_MANY].includes(prop.kind)) {
+                return;
+            }
+            if (prop?.persist === false && !prop.embedded && !prop.formula && type === 'where') {
+                return;
+            }
+            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));
+                return;
+            }
+            if (prop?.kind === ReferenceKind.EMBEDDED) {
+                const nest = (prop) => {
+                    for (const childProp of Object.values(prop.embeddedProps)) {
+                        if (childProp.fieldNames && (childProp.kind !== ReferenceKind.EMBEDDED || childProp.object) && childProp.persist !== false) {
+                            ret.push(getFieldName(childProp.fieldNames[0]));
+                        }
+                        else {
+                            nest(childProp);
+                        }
+                    }
+                };
+                nest(prop);
+                return;
+            }
+            if (prop && prop.fieldNames.length > 1) {
+                ret.push(...prop.fieldNames.map(f => getFieldName(f)));
+                return;
+            }
+            ret.push(getFieldName(field));
+        });
+        const meta = this.mainAlias.metadata;
+        /* v8 ignore next */
+        const requiresSQLConversion = meta?.props.filter(p => p.hasConvertToJSValueSQL && p.persist !== false) ?? [];
+        if (this.flags.has(QueryFlag.CONVERT_CUSTOM_TYPES) && (fields.includes('*') || fields.includes(`${this.mainAlias.aliasName}.*`)) && requiresSQLConversion.length > 0) {
+            for (const p of requiresSQLConversion) {
+                ret.push(this.helper.mapper(p.name, this.type));
+            }
+        }
+        for (const f of Object.keys(this._populateMap)) {
+            if (type === 'where' && this._joins[f]) {
+                const cols = this.helper.mapJoinColumns(this.type, this._joins[f]);
+                for (const col of cols) {
+                    ret.push(col);
+                }
+            }
+        }
+        return Utils.unique(ret);
+    }
+    init(type, data, cond) {
+        this.ensureNotFinalized();
+        this._type = type;
+        if ([QueryType.UPDATE, QueryType.DELETE].includes(type) && Utils.hasObjectKeys(this._cond)) {
+            throw new Error(`You are trying to call \`qb.where().${type.toLowerCase()}()\`. Calling \`qb.${type.toLowerCase()}()\` before \`qb.where()\` is required.`);
+        }
+        if (!this.helper.isTableNameAliasRequired(type)) {
+            delete this._fields;
+        }
+        if (data) {
+            if (Utils.isEntity(data)) {
+                data = this.em?.getComparator().prepareEntity(data) ?? serialize(data);
+            }
+            this._data = this.helper.processData(data, this.flags.has(QueryFlag.CONVERT_CUSTOM_TYPES), false);
+        }
+        if (cond) {
+            this.where(cond);
+        }
+        return this;
+    }
+    getQueryBase(processVirtualEntity) {
+        const qb = this.platform.createNativeQueryBuilder().setFlags(this.flags);
+        const { subQuery, aliasName, entityName, metadata } = this.mainAlias;
+        const requiresAlias = this.finalized && (this._explicitAlias || this.helper.isTableNameAliasRequired(this.type));
+        const alias = requiresAlias ? aliasName : undefined;
+        const schema = this.getSchema(this.mainAlias);
+        const tableName = subQuery ? subQuery.as(aliasName) : this.helper.getTableName(entityName);
+        const joinSchema = this._schema ?? this.em?.schema ?? schema;
+        if (metadata?.virtual && processVirtualEntity) {
+            qb.from(raw(this.fromVirtual(metadata)), { indexHint: this._indexHint });
+        }
+        else {
+            qb.from(tableName, {
+                schema,
+                alias,
+                indexHint: this._indexHint,
+            });
+        }
+        switch (this.type) {
+            case QueryType.SELECT:
+                qb.select(this.prepareFields(this._fields));
+                if (this._distinctOn) {
+                    qb.distinctOn(this.prepareFields(this._distinctOn));
+                }
+                else if (this.flags.has(QueryFlag.DISTINCT)) {
+                    qb.distinct();
+                }
+                this.helper.processJoins(qb, this._joins, joinSchema);
+                break;
+            case QueryType.COUNT: {
+                const fields = this._fields.map(f => this.helper.mapper(f, this.type));
+                qb.count(fields, this.flags.has(QueryFlag.DISTINCT));
+                this.helper.processJoins(qb, this._joins, joinSchema);
+                break;
+            }
+            case QueryType.INSERT:
+                qb.insert(this._data);
+                break;
+            case QueryType.UPDATE:
+                qb.update(this._data);
+                this.helper.processJoins(qb, this._joins, joinSchema);
+                this.helper.updateVersionProperty(qb, this._data);
+                break;
+            case QueryType.DELETE:
+                qb.delete();
+                break;
+            case QueryType.TRUNCATE:
+                qb.truncate();
+                break;
+        }
+        return qb;
+    }
+    applyDiscriminatorCondition() {
+        const meta = this.mainAlias.metadata;
+        if (!meta?.discriminatorValue) {
+            return;
+        }
+        const types = Object.values(meta.root.discriminatorMap).map(cls => this.metadata.find(cls));
+        const children = [];
+        const lookUpChildren = (ret, type) => {
+            const children = types.filter(meta2 => meta2.extends === type);
+            children.forEach(m => lookUpChildren(ret, m.className));
+            ret.push(...children.filter(c => c.discriminatorValue));
+            return children;
+        };
+        lookUpChildren(children, meta.className);
+        this.andWhere({
+            [meta.root.discriminatorColumn]: children.length > 0 ? { $in: [meta.discriminatorValue, ...children.map(c => c.discriminatorValue)] } : meta.discriminatorValue,
+        });
+    }
+    finalize() {
+        if (this.finalized) {
+            return;
+        }
+        if (!this._type) {
+            this.select('*');
+        }
+        const meta = this.mainAlias.metadata;
+        this.applyDiscriminatorCondition();
+        this.processPopulateHint();
+        this.processNestedJoins();
+        if (meta && (this._fields?.includes('*') || this._fields?.includes(`${this.mainAlias.aliasName}.*`))) {
+            meta.props
+                .filter(prop => prop.formula && (!prop.lazy || this.flags.has(QueryFlag.INCLUDE_LAZY_FORMULAS)))
+                .map(prop => {
+                const alias = this.platform.quoteIdentifier(this.mainAlias.aliasName);
+                const aliased = this.platform.quoteIdentifier(prop.fieldNames[0]);
+                return `${prop.formula(alias)} as ${aliased}`;
+            })
+                .filter(field => !this._fields.some(f => {
+                if (f instanceof RawQueryFragment) {
+                    return f.sql === field && f.params.length === 0;
+                }
+                return f === field;
+            }))
+                .forEach(field => this._fields.push(raw(field)));
+        }
+        QueryHelper.processObjectParams(this._data);
+        QueryHelper.processObjectParams(this._cond);
+        QueryHelper.processObjectParams(this._having);
+        // automatically enable paginate flag when we detect to-many joins, but only if there is no `group by` clause
+        if (!this.flags.has(QueryFlag.DISABLE_PAGINATE) && this._groupBy.length === 0 && this.hasToManyJoins()) {
+            this.flags.add(QueryFlag.PAGINATE);
+        }
+        if (meta && 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))) {
+            this.wrapModifySubQuery(meta);
+        }
+        this.finalized = true;
+    }
+    /** @internal */
+    processPopulateHint() {
+        if (this.populateHintFinalized) {
+            return;
+        }
+        const meta = this.mainAlias.metadata;
+        if (meta && this.flags.has(QueryFlag.AUTO_JOIN_ONE_TO_ONE_OWNER)) {
+            const relationsToPopulate = this._populate.map(({ field }) => field);
+            meta.relations
+                .filter(prop => prop.kind === ReferenceKind.ONE_TO_ONE && !prop.owner && !relationsToPopulate.includes(prop.name) && !relationsToPopulate.includes(`${prop.name}:ref`))
+                .map(prop => ({ field: `${prop.name}:ref` }))
+                .forEach(item => this._populate.push(item));
+        }
+        this._populate.forEach(({ field }) => {
+            const [fromAlias, fromField] = this.helper.splitField(field);
+            const aliasedField = `${fromAlias}.${fromField}`;
+            const join = Object.keys(this._joins).find(k => `${aliasedField}#${this._joins[k].alias}` === k);
+            if (join && this._joins[join] && this.helper.isOneToOneInverse(fromField)) {
+                this._populateMap[join] = this._joins[join].alias;
+                return;
+            }
+            if (meta && this.helper.isOneToOneInverse(fromField)) {
+                const prop = meta.properties[fromField];
+                const alias = this.getNextAlias(prop.pivotEntity ?? prop.type);
+                const aliasedName = `${fromAlias}.${prop.name}#${alias}`;
+                this._joins[aliasedName] = this.helper.joinOneToReference(prop, this.mainAlias.aliasName, alias, JoinType.leftJoin);
+                this._joins[aliasedName].path = `${(Object.values(this._joins).find(j => j.alias === fromAlias)?.path ?? meta.className)}.${prop.name}`;
+                this._populateMap[aliasedName] = this._joins[aliasedName].alias;
+                this.createAlias(prop.type, alias);
+            }
+        });
+        this.processPopulateWhere(false);
+        this.processPopulateWhere(true);
+        this.populateHintFinalized = true;
+    }
+    processPopulateWhere(filter) {
+        const key = filter ? '_populateFilter' : '_populateWhere';
+        if (this[key] == null || this[key] === PopulateHint.ALL) {
+            return;
+        }
+        let joins = Object.values(this._joins);
+        for (const join of joins) {
+            join.cond_ ??= join.cond;
+            join.cond = { ...join.cond };
+        }
+        if (typeof this[key] === 'object') {
+            const cond = CriteriaNodeFactory
+                .createNode(this.metadata, this.mainAlias.entityName, this[key])
+                .process(this, { matchPopulateJoins: true, ignoreBranching: true, preferNoBranch: true, filter });
+            // there might be new joins created by processing the `populateWhere` object
+            joins = Object.values(this._joins);
+            this.mergeOnConditions(joins, cond, filter);
+        }
+    }
+    mergeOnConditions(joins, cond, filter, op) {
+        for (const k of Object.keys(cond)) {
+            if (Utils.isOperator(k)) {
+                if (Array.isArray(cond[k])) {
+                    cond[k].forEach((c) => this.mergeOnConditions(joins, c, filter, k));
+                }
+                /* v8 ignore next */
+                this.mergeOnConditions(joins, cond[k], filter, k);
+            }
+            const [alias] = this.helper.splitField(k);
+            const join = joins.find(j => j.alias === alias);
+            if (join) {
+                const parentJoin = joins.find(j => j.alias === join.ownerAlias);
+                // https://stackoverflow.com/a/56815807/3665878
+                if (parentJoin && !filter) {
+                    const nested = (parentJoin.nested ??= new Set());
+                    join.type = join.type === JoinType.innerJoin || ([ReferenceKind.ONE_TO_MANY, ReferenceKind.MANY_TO_MANY].includes(parentJoin.prop.kind))
+                        ? JoinType.nestedInnerJoin
+                        : JoinType.nestedLeftJoin;
+                    nested.add(join);
+                }
+                if (join.cond[k]) {
+                    /* v8 ignore next */
+                    join.cond = { [op ?? '$and']: [join.cond, { [k]: cond[k] }] };
+                }
+                else if (op === '$or') {
+                    join.cond.$or ??= [];
+                    join.cond.$or.push({ [k]: cond[k] });
+                }
+                else {
+                    join.cond = { ...join.cond, [k]: cond[k] };
+                }
+            }
+        }
+    }
+    /**
+     * When adding an inner join on a left joined relation, we need to nest them,
+     * otherwise the inner join could discard rows of the root table.
+     */
+    processNestedJoins() {
+        if (this.flags.has(QueryFlag.DISABLE_NESTED_INNER_JOIN)) {
+            return;
+        }
+        const joins = Object.values(this._joins);
+        const lookupParentGroup = (j) => {
+            return j.nested ?? (j.parent ? lookupParentGroup(j.parent) : undefined);
+        };
+        for (const join of joins) {
+            if (join.type === JoinType.innerJoin) {
+                join.parent = joins.find(j => j.alias === join.ownerAlias);
+                // https://stackoverflow.com/a/56815807/3665878
+                if (join.parent?.type === JoinType.leftJoin || join.parent?.type === JoinType.nestedLeftJoin) {
+                    const nested = ((join.parent).nested ??= new Set());
+                    join.type = join.type === JoinType.innerJoin
+                        ? JoinType.nestedInnerJoin
+                        : JoinType.nestedLeftJoin;
+                    nested.add(join);
+                }
+                else if (join.parent?.type === JoinType.nestedInnerJoin) {
+                    const group = lookupParentGroup(join.parent);
+                    const nested = group ?? ((join.parent).nested ??= new Set());
+                    join.type = join.type === JoinType.innerJoin
+                        ? JoinType.nestedInnerJoin
+                        : JoinType.nestedLeftJoin;
+                    nested.add(join);
+                }
+            }
+        }
+    }
+    hasToManyJoins() {
+        return Object.values(this._joins).some(join => {
+            return [ReferenceKind.ONE_TO_MANY, ReferenceKind.MANY_TO_MANY].includes(join.prop.kind);
+        });
+    }
+    wrapPaginateSubQuery(meta) {
+        const pks = this.prepareFields(meta.primaryKeys, 'sub-query');
+        const subQuery = this.clone(['_orderBy', '_fields', 'lockMode', 'lockTableAliases']).select(pks).groupBy(pks).limit(this._limit);
+        // revert the on conditions added via populateWhere, we want to apply those only once
+        for (const join of Object.values(subQuery._joins)) {
+            if (join.cond_) {
+                join.cond = join.cond_;
+            }
+        }
+        if (this._offset) {
+            subQuery.offset(this._offset);
+        }
+        const addToSelect = [];
+        if (this._orderBy.length > 0) {
+            const orderBy = [];
+            for (const orderMap of this._orderBy) {
+                for (const [field, direction] of Object.entries(orderMap)) {
+                    if (RawQueryFragment.isKnownFragment(field)) {
+                        const rawField = RawQueryFragment.getKnownFragment(field, false);
+                        this.rawFragments.add(field);
+                        orderBy.push({ [rawField.clone()]: direction });
+                        continue;
+                    }
+                    const [a, f] = this.helper.splitField(field);
+                    const prop = this.helper.getProperty(f, a);
+                    const type = this.platform.castColumn(prop);
+                    const fieldName = this.helper.mapper(field, this.type, undefined, null);
+                    if (!prop?.persist && !prop?.formula && !prop?.hasConvertToJSValueSQL && !pks.includes(fieldName)) {
+                        addToSelect.push(fieldName);
+                    }
+                    const quoted = this.platform.quoteIdentifier(fieldName);
+                    const key = raw(`min(${quoted}${type})`);
+                    orderBy.push({ [key]: direction });
+                }
+            }
+            subQuery.orderBy(orderBy);
+        }
+        subQuery.finalized = true;
+        const innerQuery = subQuery.as(this.mainAlias.aliasName).clear('select').select(pks);
+        if (addToSelect.length > 0) {
+            addToSelect.forEach(prop => {
+                const field = this._fields.find(field => {
+                    if (typeof field === 'object' && field && '__as' in field) {
+                        return field.__as === prop;
+                    }
+                    if (field instanceof RawQueryFragment) {
+                        // not perfect, but should work most of the time, ideally we should check only the alias (`... as alias`)
+                        return field.sql.includes(prop);
+                    }
+                    return false;
+                });
+                /* v8 ignore next */
+                if (field instanceof RawQueryFragment) {
+                    innerQuery.select(field);
+                }
+                else if (field instanceof NativeQueryBuilder) {
+                    innerQuery.select(field.toRaw());
+                }
+                else if (field) {
+                    innerQuery.select(field);
+                }
+            });
+        }
+        // multiple sub-queries are needed to get around mysql limitations with order by + limit + where in + group by (o.O)
+        // https://stackoverflow.com/questions/17892762/mysql-this-version-of-mysql-doesnt-yet-support-limit-in-all-any-some-subqu
+        const subSubQuery = this.platform.createNativeQueryBuilder();
+        subSubQuery.select(pks).from(innerQuery);
+        this._limit = undefined;
+        this._offset = undefined;
+        if (!this._fields.some(f => RawQueryFragment.isKnownFragment(f))) {
+            this.pruneExtraJoins(meta);
+        }
+        const { sql, params } = subSubQuery.compile();
+        this.select(this._fields).where({ [Utils.getPrimaryKeyHash(meta.primaryKeys)]: { $in: raw(sql, params) } });
+    }
+    pruneExtraJoins(meta) {
+        // remove joins that are not used for population or ordering to improve performance
+        const populate = new Set();
+        const orderByAliases = this._orderBy
+            .flatMap(hint => Object.keys(hint))
+            .map(k => k.split('.')[0]);
+        function addPath(hints, prefix = '') {
+            for (const hint of hints) {
+                const field = hint.field.split(':')[0];
+                populate.add((prefix ? prefix + '.' : '') + field);
+                if (hint.children) {
+                    addPath(hint.children, (prefix ? prefix + '.' : '') + field);
+                }
+            }
+        }
+        addPath(this._populate);
+        const joins = Object.entries(this._joins);
+        const rootAlias = this.alias;
+        function addParentAlias(alias) {
+            const join = joins.find(j => j[1].alias === alias);
+            if (join && join[1].ownerAlias !== rootAlias) {
+                orderByAliases.push(join[1].ownerAlias);
+                addParentAlias(join[1].ownerAlias);
+            }
+        }
+        for (const orderByAlias of orderByAliases) {
+            addParentAlias(orderByAlias);
+        }
+        for (const [key, join] of joins) {
+            const path = join.path?.replace(/\[populate]|\[pivot]|:ref/g, '').replace(new RegExp(`^${meta.className}.`), '');
+            if (!populate.has(path ?? '') && !orderByAliases.includes(join.alias)) {
+                delete this._joins[key];
+            }
+        }
+    }
+    wrapModifySubQuery(meta) {
+        const subQuery = this.clone();
+        subQuery.finalized = true;
+        // wrap one more time to get around MySQL limitations
+        // https://stackoverflow.com/questions/45494/mysql-error-1093-cant-specify-target-table-for-update-in-from-clause
+        const subSubQuery = this.platform.createNativeQueryBuilder();
+        const method = this.flags.has(QueryFlag.UPDATE_SUB_QUERY) ? 'update' : 'delete';
+        const pks = this.prepareFields(meta.primaryKeys, 'sub-query');
+        this._cond = {}; // otherwise we would trigger validation error
+        this._joins = {}; // included in the subquery
+        subSubQuery.select(pks).from(subQuery.as(this.mainAlias.aliasName));
+        const { sql, params } = subSubQuery.compile();
+        this[method](this._data).where({
+            [Utils.getPrimaryKeyHash(meta.primaryKeys)]: { $in: raw(sql, params) },
+        });
+    }
+    getSchema(alias) {
+        const { metadata } = alias;
+        const metaSchema = metadata?.schema && metadata.schema !== '*' ? metadata.schema : undefined;
+        const schema = this._schema ?? metaSchema ?? this.em?.schema ?? this.em?.config.getSchema(true);
+        if (schema === this.platform.getDefaultSchemaName()) {
+            return undefined;
+        }
+        return schema;
+    }
+    createAlias(entityName, aliasName, subQuery) {
+        const metadata = this.metadata.find(entityName);
+        const alias = { aliasName, entityName, metadata, subQuery };
+        this._aliases[aliasName] = alias;
+        return alias;
+    }
+    createMainAlias(entityName, aliasName, subQuery) {
+        this._mainAlias = this.createAlias(entityName, aliasName, subQuery);
+        this._helper = this.createQueryBuilderHelper();
+        return this._mainAlias;
+    }
+    fromSubQuery(target, aliasName) {
+        const subQuery = target.getNativeQuery();
+        const { entityName } = target.mainAlias;
+        aliasName ??= this.getNextAlias(entityName);
+        this.createMainAlias(entityName, aliasName, subQuery);
+    }
+    fromEntityName(entityName, aliasName) {
+        aliasName ??= this._mainAlias?.aliasName ?? this.getNextAlias(entityName);
+        this.createMainAlias(entityName, aliasName);
+    }
+    createQueryBuilderHelper() {
+        return new QueryBuilderHelper(this.mainAlias.entityName, this.mainAlias.aliasName, this._aliases, this.subQueries, this.driver);
+    }
+    ensureFromClause() {
+        /* v8 ignore next */
+        if (!this._mainAlias) {
+            throw new Error(`Cannot proceed to build a query because the main alias is not set.`);
+        }
+    }
+    ensureNotFinalized() {
+        if (this.finalized) {
+            throw new Error('This QueryBuilder instance is already finalized, clone it first if you want to modify it.');
+        }
+    }
+    /** @ignore */
+    /* v8 ignore next */
+    [Symbol.for('nodejs.util.inspect.custom')](depth = 2) {
+        const object = { ...this };
+        const hidden = ['metadata', 'driver', 'context', 'platform', 'type'];
+        Object.keys(object).filter(k => k.startsWith('_')).forEach(k => delete object[k]);
+        Object.keys(object).filter(k => object[k] == null).forEach(k => delete object[k]);
+        hidden.forEach(k => delete object[k]);
+        let prefix = this.type ? this.type.substring(0, 1) + this.type.toLowerCase().substring(1) : '';
+        if (this._data) {
+            object.data = this._data;
+        }
+        if (this._schema) {
+            object.schema = this._schema;
+        }
+        if (!Utils.isEmpty(this._cond)) {
+            object.where = this._cond;
+        }
+        if (this._onConflict?.[0]) {
+            prefix = 'Upsert';
+            object.onConflict = this._onConflict[0];
+        }
+        if (!Utils.isEmpty(this._orderBy)) {
+            object.orderBy = this._orderBy;
+        }
+        const name = this._mainAlias ? `${prefix}QueryBuilder<${this._mainAlias?.entityName}>` : 'QueryBuilder';
+        const ret = inspect(object, { depth });
+        return ret === '[Object]' ? `[${name}]` : name + ' ' + ret;
+    }
+}