@mikro-orm/knex 6.0.0-dev.4 → 6.0.0-dev.5

package/{dist/query → query}/QueryBuilder.js

@@ -25,11 +25,21 @@ const CriteriaNodeFactory_1 = require("./CriteriaNodeFactory");
  * ```
  */
 class QueryBuilder {
+    get mainAlias() {
+        this.ensureFromClause();
+        return this._mainAlias;
+    }
+    get alias() {
+        return this.mainAlias.aliasName;
+    }
+    get helper() {
+        this.ensureFromClause();
+        return this._helper;
+    }
     /**
      * @internal
      */
     constructor(entityName, metadata, driver, context, alias, connectionType, em) {
-        this.entityName = entityName;
         this.metadata = metadata;
         this.driver = driver;
         this.context = context;
@@ -43,23 +53,25 @@ class QueryBuilder {
         this.flags = new Set([core_1.QueryFlag.CONVERT_CUSTOM_TYPES]);
         this.finalized = false;
         this._joins = {};
-        this._aliasMap = {};
+        this._explicitAlias = false;
         this._cond = {};
         this._orderBy = [];
         this._groupBy = [];
         this._having = {};
         this._joinedProps = new Map();
         this.subQueries = {};
+        this._aliases = {};
         this.platform = this.driver.getPlatform();
         this.knex = this.driver.getConnection(this.connectionType).getKnex();
         if (alias) {
             this.aliasCounter++;
+            this._explicitAlias = true;
         }
-        this.alias = alias ?? this.getNextAlias(this.entityName);
-        this._aliasMap[this.alias] = this.entityName;
-        this.helper = new QueryBuilderHelper_1.QueryBuilderHelper(this.entityName, this.alias, this._aliasMap, this.subQueries, this.metadata, this.knex, this.platform);
+        // @ts-expect-error union type does not match the overloaded method signature
+        this.from(entityName, alias);
     }
     select(fields, distinct = false) {
+        this.ensureNotFinalized();
         this._fields = core_1.Utils.asArray(fields);
         if (distinct) {
             this.flags.add(core_1.QueryFlag.DISTINCT);
@@ -67,11 +79,22 @@ class QueryBuilder {
         return this.init(enums_1.QueryType.SELECT);
     }
     addSelect(fields) {
+        this.ensureNotFinalized();
         if (this.type && this.type !== enums_1.QueryType.SELECT) {
             return this;
         }
         return this.select([...core_1.Utils.asArray(this._fields), ...core_1.Utils.asArray(fields)]);
     }
+    distinct() {
+        this.ensureNotFinalized();
+        return this.setFlag(core_1.QueryFlag.DISTINCT);
+    }
+    /** postgres only */
+    distinctOn(fields) {
+        this.ensureNotFinalized();
+        this._distinctOn = core_1.Utils.asArray(fields);
+        return this;
+    }
     insert(data) {
         return this.init(enums_1.QueryType.INSERT, data);
     }
@@ -85,7 +108,15 @@ class QueryBuilder {
         return this.init(enums_1.QueryType.TRUNCATE);
     }
     count(field, distinct = false) {
-        this._fields = [...(field ? core_1.Utils.asArray(field) : this.metadata.find(this.entityName).primaryKeys)];
+        if (field) {
+            this._fields = core_1.Utils.asArray(field);
+        }
+        else if (this.hasToManyJoins()) {
+            this._fields = this.mainAlias.metadata.primaryKeys;
+        }
+        else {
+            this._fields = [this.raw('*')];
+        }
         if (distinct) {
             this.flags.add(core_1.QueryFlag.DISTINCT);
         }
@@ -99,6 +130,9 @@ class QueryBuilder {
         return this.join(field, alias, cond, 'leftJoin');
     }
     joinAndSelect(field, alias, cond = {}, type = 'innerJoin', path) {
+        if (!this.type) {
+            this.select('*');
+        }
         const prop = this.joinReference(field, alias, cond, type, path);
         this.addSelect(this.getFieldsForJoinedLoad(prop, alias));
         const [fromAlias] = this.helper.splitField(field);
@@ -124,24 +158,34 @@ class QueryBuilder {
         return fields;
     }
     withSubQuery(subQuery, alias) {
+        this.ensureNotFinalized();
         this.subQueries[alias] = subQuery.toString();
         return this;
     }
     where(cond, params, operator) {
+        this.ensureNotFinalized();
         if (core_1.Utils.isString(cond)) {
             cond = { [`(${cond})`]: core_1.Utils.asArray(params) };
             operator = operator || '$and';
         }
         else {
-            cond = core_1.QueryHelper.processWhere(cond, this.entityName, this.metadata, this.platform, this.flags.has(core_1.QueryFlag.CONVERT_CUSTOM_TYPES));
+            cond = core_1.QueryHelper.processWhere({
+                where: cond,
+                entityName: this.mainAlias.entityName,
+                metadata: this.metadata,
+                platform: this.platform,
+                aliasMap: this.getAliasMap(),
+                aliased: !this.type || [enums_1.QueryType.SELECT, enums_1.QueryType.COUNT].includes(this.type),
+                convertCustomTypes: this.flags.has(core_1.QueryFlag.CONVERT_CUSTOM_TYPES),
+            });
         }
         const op = operator || params;
         const topLevel = !op || !core_1.Utils.hasObjectKeys(this._cond);
-        const criteriaNode = CriteriaNodeFactory_1.CriteriaNodeFactory.createNode(this.metadata, this.entityName, cond);
+        const criteriaNode = CriteriaNodeFactory_1.CriteriaNodeFactory.createNode(this.metadata, this.mainAlias.entityName, cond);
         if ([enums_1.QueryType.UPDATE, enums_1.QueryType.DELETE].includes(this.type) && criteriaNode.willAutoJoin(this)) {
             // use sub-query to support joining
             this.setFlag(this.type === enums_1.QueryType.UPDATE ? core_1.QueryFlag.UPDATE_SUB_QUERY : core_1.QueryFlag.DELETE_SUB_QUERY);
-            this.select(this.metadata.find(this.entityName).primaryKeys, true);
+            this.select(this.mainAlias.metadata.primaryKeys, true);
         }
         if (topLevel) {
             this._cond = criteriaNode.process(this);
@@ -166,27 +210,39 @@ class QueryBuilder {
         return this.where(cond, params, '$or');
     }
     orderBy(orderBy) {
+        this.ensureNotFinalized();
         this._orderBy = [];
         core_1.Utils.asArray(orderBy).forEach(o => {
-            const processed = core_1.QueryHelper.processWhere(o, this.entityName, this.metadata, this.platform, false);
-            this._orderBy.push(CriteriaNodeFactory_1.CriteriaNodeFactory.createNode(this.metadata, this.entityName, processed).process(this));
+            const processed = core_1.QueryHelper.processWhere({
+                where: o,
+                entityName: this.mainAlias.entityName,
+                metadata: this.metadata,
+                platform: this.platform,
+                aliasMap: this.getAliasMap(),
+                aliased: !this.type || [enums_1.QueryType.SELECT, enums_1.QueryType.COUNT].includes(this.type),
+                convertCustomTypes: false,
+            });
+            this._orderBy.push(CriteriaNodeFactory_1.CriteriaNodeFactory.createNode(this.metadata, this.mainAlias.entityName, processed).process(this));
         });
         return this;
     }
     groupBy(fields) {
+        this.ensureNotFinalized();
         this._groupBy = core_1.Utils.asArray(fields);
         return this;
     }
     having(cond = {}, params) {
+        this.ensureNotFinalized();
         if (core_1.Utils.isString(cond)) {
             cond = { [`(${cond})`]: core_1.Utils.asArray(params) };
         }
-        this._having = CriteriaNodeFactory_1.CriteriaNodeFactory.createNode(this.metadata, this.entityName, cond).process(this);
+        this._having = CriteriaNodeFactory_1.CriteriaNodeFactory.createNode(this.metadata, this.mainAlias.entityName, cond).process(this);
         return this;
     }
     onConflict(fields = []) {
+        this.ensureNotFinalized();
         this._onConflict = this._onConflict || [];
-        this._onConflict.push({ fields: core_1.Utils.asArray(fields) });
+        this._onConflict.push({ fields: core_1.Utils.asArray(fields).map(f => f.toString()) });
         return this;
     }
     ignore() {
@@ -200,14 +256,19 @@ class QueryBuilder {
         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;
     }
     /**
      * @internal
      */
-    populate(populate) {
+    populate(populate, populateWhere) {
+        this.ensureNotFinalized();
         this._populate = populate;
+        this._populateWhere = populateWhere;
         return this;
     }
     /**
@@ -222,6 +283,7 @@ class QueryBuilder {
         return raw;
     }
     limit(limit, offset = 0) {
+        this.ensureNotFinalized();
         this._limit = limit;
         if (offset) {
             this.offset(offset);
@@ -229,14 +291,17 @@ class QueryBuilder {
         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 && mode !== core_1.LockMode.OPTIMISTIC && !this.context) {
             throw core_1.ValidationError.transactionRequired();
         }
@@ -245,18 +310,22 @@ class QueryBuilder {
         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;
     }
     cache(config = true) {
+        this.ensureNotFinalized();
         this._cache = config;
         return this;
     }
@@ -264,31 +333,46 @@ class QueryBuilder {
      * Adds index hint to the FROM clause.
      */
     indexHint(sql) {
+        this.ensureNotFinalized();
         this._indexHint = sql;
         return this;
     }
+    from(target, aliasName) {
+        this.ensureNotFinalized();
+        if (target instanceof QueryBuilder) {
+            this.fromSubQuery(target, aliasName);
+        }
+        else {
+            const entityName = core_1.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;
+    }
     getKnexQuery() {
         this.finalize();
         const qb = this.getQueryBase();
-        core_1.Utils.runIfNotEmpty(() => this.helper.appendQueryCondition(this.type, this._cond, qb), this._cond && !this._onConflict);
+        core_1.Utils.runIfNotEmpty(() => this.helper.appendQueryCondition(this.type ?? enums_1.QueryType.SELECT, this._cond, qb), this._cond && !this._onConflict);
         core_1.Utils.runIfNotEmpty(() => qb.groupBy(this.prepareFields(this._groupBy, 'groupBy')), this._groupBy);
-        core_1.Utils.runIfNotEmpty(() => this.helper.appendQueryCondition(this.type, this._having, qb, undefined, 'having'), this._having);
+        core_1.Utils.runIfNotEmpty(() => this.helper.appendQueryCondition(this.type ?? enums_1.QueryType.SELECT, this._having, qb, undefined, 'having'), this._having);
         core_1.Utils.runIfNotEmpty(() => {
-            const queryOrder = this.helper.getQueryOrder(this.type, this._orderBy, this._populateMap);
+            const queryOrder = this.helper.getQueryOrder(this.type ?? enums_1.QueryType.SELECT, this._orderBy, this._populateMap);
             if (queryOrder) {
                 return qb.orderByRaw(queryOrder);
             }
         }, this._orderBy);
         core_1.Utils.runIfNotEmpty(() => qb.limit(this._limit), this._limit != null);
         core_1.Utils.runIfNotEmpty(() => qb.offset(this._offset), this._offset);
-        core_1.Utils.runIfNotEmpty(() => this.helper.appendOnConflictClause(this.type, this._onConflict, qb), this._onConflict);
+        core_1.Utils.runIfNotEmpty(() => this.helper.appendOnConflictClause(this.type ?? enums_1.QueryType.SELECT, this._onConflict, qb), this._onConflict);
         if (this.type === enums_1.QueryType.TRUNCATE && this.platform.usesCascadeStatement()) {
             return this.knex.raw(qb.toSQL().toNative().sql + ' cascade');
         }
         if (this.lockMode) {
             this.helper.getLockSQL(qb, this.lockMode, this.lockTables);
         }
-        this.helper.finalize(this.type, qb, this.metadata.find(this.entityName));
+        this.helper.finalize(this.type ?? enums_1.QueryType.SELECT, qb, this.mainAlias.metadata);
         return qb;
     }
     /**
@@ -310,9 +394,12 @@ class QueryBuilder {
         const query = this.getKnexQuery().toSQL();
         return this.platform.formatQuery(query.sql, query.bindings);
     }
+    /**
+     * @internal
+     */
     getAliasForJoinPath(path) {
-        if (!path || path === this.entityName) {
-            return this.alias;
+        if (!path || path === this.mainAlias.entityName) {
+            return this.mainAlias.aliasName;
         }
         const join = Object.values(this._joins).find(j => j.path === path);
         if (path.endsWith('[pivot]') && join) {
@@ -320,25 +407,34 @@ class QueryBuilder {
         }
         return join?.inverseAlias || join?.alias;
     }
+    /**
+     * @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 = 'all', mapResults = true) {
-        if (!this.connectionType && method !== 'run' && [enums_1.QueryType.INSERT, enums_1.QueryType.UPDATE, enums_1.QueryType.DELETE, enums_1.QueryType.TRUNCATE].includes(this.type)) {
+        if (!this.connectionType && method !== 'run' && [enums_1.QueryType.INSERT, enums_1.QueryType.UPDATE, enums_1.QueryType.DELETE, enums_1.QueryType.TRUNCATE].includes(this.type ?? enums_1.QueryType.SELECT)) {
             this.connectionType = 'write';
         }
         const query = this.getKnexQuery().toSQL();
-        const cached = await this.em?.tryCache(this.entityName, this._cache, ['qb.execute', query.sql, query.bindings, method]);
+        const cached = await this.em?.tryCache(this.mainAlias.entityName, this._cache, ['qb.execute', query.sql, query.bindings, method]);
         if (cached?.data) {
             return cached.data;
         }
         const type = this.connectionType || (method === 'run' ? 'write' : 'read');
         const res = await this.driver.getConnection(type).execute(query.sql, query.bindings, method, this.context);
-        const meta = this.metadata.find(this.entityName);
+        const meta = this.mainAlias.metadata;
         if (!mapResults || !meta) {
             await this.em?.storeCache(this._cache, cached, res);
             return res;
@@ -363,12 +459,12 @@ class QueryBuilder {
      * Executes the query, returning array of results
      */
     async getResultList() {
-        await this.em.tryFlush(this.entityName, { flushMode: this.flushMode });
+        await this.em.tryFlush(this.mainAlias.entityName, { flushMode: this.flushMode });
         let res = await this.execute('all', true);
         if (this._joinedProps.size > 0) {
-            res = this.driver.mergeJoinedResult(res, this.metadata.find(this.entityName));
+            res = this.driver.mergeJoinedResult(res, this.mainAlias.metadata);
         }
-        return res.map(r => this.em.map(this.entityName, r, { schema: this._schema }));
+        return res.map(r => this.em.map(this.mainAlias.entityName, r, { schema: this._schema }));
     }
     /**
      * Executes the query, returning the first result or null
@@ -380,35 +476,32 @@ class QueryBuilder {
     /**
      * Executes count query (without offset and limit), returning total count of results
      */
-    async getCount(field, distinct = false) {
-        const qb = this.clone();
-        qb.count(field, distinct).limit(undefined).offset(undefined);
-        const res = await qb.execute('get', false);
+    async getCount(field, distinct) {
+        let res;
+        if (this.type === enums_1.QueryType.COUNT) {
+            res = await this.execute('get', false);
+        }
+        else {
+            const qb = this.clone();
+            qb.count(field, distinct ?? qb.hasToManyJoins()).limit(undefined).offset(undefined).orderBy([]);
+            res = await qb.execute('get', false);
+        }
         return res ? +res.count : 0;
     }
     /**
      * Provides promise-like interface so we can await the QB instance.
      */
     then(onfulfilled, onrejected) {
-        return this.getInnerPromise().then(onfulfilled, onrejected);
-    }
-    getInnerPromise() {
-        if (!this.innerPromise) {
-            this.innerPromise = (async () => {
-                switch (this.type) {
-                    case enums_1.QueryType.INSERT:
-                    case enums_1.QueryType.UPDATE:
-                    case enums_1.QueryType.DELETE:
-                    case enums_1.QueryType.TRUNCATE:
-                        return this.execute('run');
-                    case enums_1.QueryType.SELECT:
-                        return this.getResultList();
-                    case enums_1.QueryType.COUNT:
-                        return this.getCount();
-                }
-            })();
+        switch (this.type ?? enums_1.QueryType.SELECT) {
+            case enums_1.QueryType.INSERT:
+            case enums_1.QueryType.UPDATE:
+            case enums_1.QueryType.DELETE:
+            case enums_1.QueryType.TRUNCATE:
+                return this.execute('run').then(onfulfilled, onrejected);
+            case enums_1.QueryType.COUNT:
+                return this.getCount().then(onfulfilled, onrejected);
+            case enums_1.QueryType.SELECT: return this.getResultList().then(onfulfilled, onrejected);
         }
-        return this.innerPromise;
     }
     /**
      * Returns knex instance with sub-query aliased with given alias.
@@ -425,11 +518,11 @@ class QueryBuilder {
         return qb.as(alias);
     }
     clone() {
-        const qb = new QueryBuilder(this.entityName, this.metadata, this.driver, this.context, this.alias, this.connectionType, this.em);
+        const qb = new QueryBuilder(this.mainAlias.entityName, this.metadata, this.driver, this.context, this.mainAlias.aliasName, this.connectionType, this.em);
         Object.assign(qb, this);
         // clone array/object properties
         const properties = [
-            'flags', '_populate', '_populateMap', '_joins', '_joinedProps', '_aliasMap', '_cond', '_data', '_orderBy',
+            'flags', '_populate', '_populateWhere', '_populateMap', '_joins', '_joinedProps', '_cond', '_data', '_orderBy',
             '_schema', '_indexHint', '_cache', 'subQueries', 'lockMode', 'lockTables',
         ];
         properties.forEach(prop => qb[prop] = core_1.Utils.copy(this[prop]));
@@ -437,27 +530,45 @@ class QueryBuilder {
         if (this._fields) {
             qb._fields = [...this._fields];
         }
+        qb._aliases = { ...this._aliases };
         qb.finalized = false;
         return qb;
     }
     getKnex() {
-        const tableName = this.helper.getTableName(this.entityName) + (this.finalized && this.helper.isTableNameAliasRequired(this.type) ? ` as ${this.alias}` : '');
-        const qb = this.knex(tableName);
+        const qb = this.knex.queryBuilder();
+        const { subQuery, aliasName, entityName } = this.mainAlias;
+        const ref = subQuery ? subQuery : this.knex.ref(this.helper.getTableName(entityName));
+        if (this.finalized && (this._explicitAlias || this.helper.isTableNameAliasRequired(this.type))) {
+            ref.as(aliasName);
+        }
+        const schema = this.getSchema(this.mainAlias);
+        if (schema) {
+            ref.withSchema(schema);
+        }
+        qb.from(ref);
         if (this.context) {
             qb.transacting(this.context);
         }
         return qb;
     }
     joinReference(field, alias, cond, type, path) {
+        this.ensureNotFinalized();
         const [fromAlias, fromField] = this.helper.splitField(field);
-        const entityName = this._aliasMap[fromAlias];
+        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 ${field}, but ${fromField} is not a defined relation on ${meta.className}`);
         }
-        this._aliasMap[alias] = prop.type;
-        cond = core_1.QueryHelper.processWhere(cond, this.entityName, this.metadata, this.platform);
+        this.createAlias(prop.type, alias);
+        cond = core_1.QueryHelper.processWhere({
+            where: cond,
+            entityName: this.mainAlias.entityName,
+            metadata: this.metadata,
+            platform: this.platform,
+            aliasMap: this.getAliasMap(),
+            aliased: !this.type || [enums_1.QueryType.SELECT, enums_1.QueryType.COUNT].includes(this.type),
+        });
         let aliasedName = `${fromAlias}.${prop.name}#${alias}`;
         path ?? (path = `${(Object.values(this._joins).find(j => j.alias === fromAlias)?.path ?? entityName)}.${prop.name}`);
         if (prop.reference === core_1.ReferenceType.ONE_TO_MANY) {
@@ -467,12 +578,12 @@ class QueryBuilder {
             let pivotAlias = alias;
             if (type !== 'pivotJoin') {
                 const oldPivotAlias = this.getAliasForJoinPath(path + '[pivot]');
-                pivotAlias = oldPivotAlias ?? this.getNextAlias(prop.pivotTable);
+                pivotAlias = oldPivotAlias ?? this.getNextAlias(prop.pivotEntity);
                 aliasedName = `${fromAlias}.${prop.name}#${pivotAlias}`;
             }
             const joins = this.helper.joinManyToManyReference(prop, fromAlias, alias, pivotAlias, type, cond, path);
             Object.assign(this._joins, joins);
-            this._aliasMap[pivotAlias] = prop.pivotTable;
+            this.createAlias(prop.pivotEntity, pivotAlias);
         }
         else if (prop.reference === core_1.ReferenceType.ONE_TO_ONE) {
             this._joins[aliasedName] = this.helper.joinOneToReference(prop, fromAlias, alias, type, cond);
@@ -493,24 +604,50 @@ class QueryBuilder {
             }
             const join = Object.keys(this._joins).find(k => field === k.substring(0, k.indexOf('#')));
             if (join && type === 'where') {
-                return ret.push(...this.helper.mapJoinColumns(this.type, this._joins[join]));
+                return ret.push(...this.helper.mapJoinColumns(this.type ?? enums_1.QueryType.SELECT, this._joins[join]));
             }
             const [a, f] = this.helper.splitField(field);
             const prop = this.helper.getProperty(f, a);
+            /* istanbul ignore next */
             if (prop && [core_1.ReferenceType.ONE_TO_MANY, core_1.ReferenceType.MANY_TO_MANY].includes(prop.reference)) {
                 return;
             }
+            if (prop?.embedded) {
+                const fieldName = this.helper.mapper(prop.fieldNames[0], this.type);
+                ret.push(fieldName);
+                return;
+            }
+            if (prop?.reference === core_1.ReferenceType.EMBEDDED) {
+                if (prop.object) {
+                    ret.push(this.helper.mapper(prop.fieldNames[0], this.type));
+                }
+                else {
+                    const nest = (prop) => {
+                        for (const childProp of Object.values(prop.embeddedProps)) {
+                            if (childProp.fieldNames) {
+                                ret.push(this.helper.mapper(childProp.fieldNames[0], this.type));
+                            }
+                            else {
+                                nest(childProp);
+                            }
+                        }
+                    };
+                    nest(prop);
+                }
+                return;
+            }
             ret.push(this.helper.mapper(field, this.type));
         });
-        const meta = this.metadata.find(this.entityName);
+        const meta = this.mainAlias.metadata;
         /* istanbul ignore next */
         const requiresSQLConversion = meta?.props.filter(p => p.customType?.convertToJSValueSQL) ?? [];
-        if (this.flags.has(core_1.QueryFlag.CONVERT_CUSTOM_TYPES) && (fields.includes('*') || fields.includes(`${this.alias}.*`)) && requiresSQLConversion.length > 0) {
+        if (this.flags.has(core_1.QueryFlag.CONVERT_CUSTOM_TYPES) && (fields.includes('*') || fields.includes(`${this.mainAlias.aliasName}.*`)) && requiresSQLConversion.length > 0) {
             requiresSQLConversion.forEach(p => ret.push(this.helper.mapper(p.name, this.type)));
         }
         Object.keys(this._populateMap).forEach(f => {
             if (!fields.includes(f.replace(/#\w+$/, '')) && type === 'where') {
-                ret.push(...this.helper.mapJoinColumns(this.type, this._joins[f]));
+                const cols = this.helper.mapJoinColumns(this.type ?? enums_1.QueryType.SELECT, this._joins[f]);
+                ret.push(...cols);
             }
             if (this._joins[f].prop.reference !== core_1.ReferenceType.ONE_TO_ONE && this._joins[f].inverseJoinColumns) {
                 this._joins[f].inverseJoinColumns.forEach(inverseJoinColumn => {
@@ -521,8 +658,8 @@ class QueryBuilder {
         return ret;
     }
     init(type, data, cond) {
+        this.ensureNotFinalized();
         this.type = type;
-        this._aliasMap[this.alias] = this.entityName;
         if ([enums_1.QueryType.UPDATE, enums_1.QueryType.DELETE].includes(type) && core_1.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.`);
         }
@@ -530,6 +667,9 @@ class QueryBuilder {
             delete this._fields;
         }
         if (data) {
+            if (core_1.Utils.isEntity(data)) {
+                data = (0, core_1.helper)(data).toJSON();
+            }
             this._data = this.helper.processData(data, this.flags.has(core_1.QueryFlag.CONVERT_CUSTOM_TYPES));
         }
         if (cond) {
@@ -539,22 +679,23 @@ class QueryBuilder {
     }
     getQueryBase() {
         const qb = this.getKnex();
-        const meta = this.metadata.find(this.entityName);
-        const metaSchema = meta?.schema && meta.schema !== '*' ? meta.schema : undefined;
-        const schema = this._schema ?? metaSchema ?? this.em?.config.get('schema');
+        const schema = this.getSchema(this.mainAlias);
         if (schema) {
             qb.withSchema(schema);
         }
         if (this._indexHint) {
-            const alias = this.helper.isTableNameAliasRequired(this.type) ? ` as ${this.platform.quoteIdentifier(this.alias)}` : '';
+            const alias = this.helper.isTableNameAliasRequired(this.type) ? ` as ${this.platform.quoteIdentifier(this.mainAlias.aliasName)}` : '';
             const schemaQuoted = schema ? this.platform.quoteIdentifier(schema) + '.' : '';
-            const tableName = schemaQuoted + this.platform.quoteIdentifier(this.helper.getTableName(this.entityName)) + alias;
+            const tableName = schemaQuoted + this.platform.quoteIdentifier(this.helper.getTableName(this.mainAlias.entityName)) + alias;
             qb.from(this.knex.raw(`${tableName} ${this._indexHint}`));
         }
         switch (this.type) {
             case enums_1.QueryType.SELECT:
                 qb.select(this.prepareFields(this._fields));
-                if (this.flags.has(core_1.QueryFlag.DISTINCT)) {
+                if (this._distinctOn) {
+                    qb.distinctOn(this._distinctOn);
+                }
+                else if (this.flags.has(core_1.QueryFlag.DISTINCT)) {
                     qb.distinct();
                 }
                 this.helper.processJoins(qb, this._joins, schema);
@@ -588,7 +729,7 @@ class QueryBuilder {
         if (!this.type) {
             this.select('*');
         }
-        const meta = this.metadata.find(this.entityName);
+        const meta = this.mainAlias.metadata;
         if (meta && this.flags.has(core_1.QueryFlag.AUTO_JOIN_ONE_TO_ONE_OWNER)) {
             const relationsToPopulate = this._populate.map(({ field }) => field);
             meta.relations
@@ -600,7 +741,7 @@ class QueryBuilder {
             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 (this._joins[join] && this.helper.isOneToOneInverse(fromField)) {
+            if (join && this._joins[join] && this.helper.isOneToOneInverse(fromField)) {
                 return this._populateMap[join] = this._joins[join].alias;
             }
             if (this.metadata.find(field)?.pivotTable) { // pivot table entity
@@ -608,16 +749,17 @@ class QueryBuilder {
             }
             else if (meta && this.helper.isOneToOneInverse(fromField)) {
                 const prop = meta.properties[fromField];
-                const alias = this.getNextAlias(prop.pivotTable ?? prop.type);
-                this._joins[join] = this.helper.joinOneToReference(prop, this.alias, alias, 'leftJoin');
-                this._populateMap[join] = this._joins[join].alias;
+                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, 'leftJoin');
+                this._populateMap[aliasedName] = this._joins[aliasedName].alias;
             }
         });
-        if (meta && (this._fields?.includes('*') || this._fields?.includes(`${this.alias}.*`))) {
+        if (meta && (this._fields?.includes('*') || this._fields?.includes(`${this.mainAlias.aliasName}.*`))) {
             meta.props
                 .filter(prop => prop.formula && (!prop.lazy || this.flags.has(core_1.QueryFlag.INCLUDE_LAZY_FORMULAS)))
                 .map(prop => {
-                const alias = this.knex.ref(this.alias).toString();
+                const alias = this.knex.ref(this.mainAlias.aliasName).toString();
                 const aliased = this.knex.ref(prop.fieldNames[0]).toString();
                 return `${prop.formula(alias)} as ${aliased}`;
             })
@@ -627,13 +769,22 @@ class QueryBuilder {
         core_1.QueryHelper.processObjectParams(this._data);
         core_1.QueryHelper.processObjectParams(this._cond);
         core_1.QueryHelper.processObjectParams(this._having);
-        this.finalized = true;
-        if (meta && this.flags.has(core_1.QueryFlag.PAGINATE) && this._limit > 0) {
+        // automatically enable paginate flag when we detect to-many joins
+        if (!this.flags.has(core_1.QueryFlag.DISABLE_PAGINATE) && this.hasToManyJoins()) {
+            this.flags.add(core_1.QueryFlag.PAGINATE);
+        }
+        if (meta && this.flags.has(core_1.QueryFlag.PAGINATE) && (this._limit > 0 || this._offset > 0)) {
             this.wrapPaginateSubQuery(meta);
         }
         if (meta && (this.flags.has(core_1.QueryFlag.UPDATE_SUB_QUERY) || this.flags.has(core_1.QueryFlag.DELETE_SUB_QUERY))) {
             this.wrapModifySubQuery(meta);
         }
+        this.finalized = true;
+    }
+    hasToManyJoins() {
+        return Object.values(this._joins).some(join => {
+            return [core_1.ReferenceType.ONE_TO_MANY, core_1.ReferenceType.MANY_TO_MANY].includes(join.prop.reference);
+        });
     }
     wrapPaginateSubQuery(meta) {
         const pks = this.prepareFields(meta.primaryKeys, 'sub-query');
@@ -645,28 +796,38 @@ class QueryBuilder {
             const orderBy = [];
             for (const orderMap of this._orderBy) {
                 for (const [field, direction] of Object.entries(orderMap)) {
+                    const [a, f] = this.helper.splitField(field);
+                    const prop = this.helper.getProperty(f, a);
+                    const type = this.platform.castColumn(prop);
                     orderBy.push({
-                        [`min(${this.ref(field)})`]: direction,
+                        [`min(${this.ref(this.helper.mapper(field, this.type, undefined, null))}${type})`]: direction,
                     });
                 }
             }
             subQuery.orderBy(orderBy);
         }
         subQuery.finalized = true;
-        const knexQuery = subQuery.as(this.alias).clearSelect().select(pks);
+        const knexQuery = subQuery.as(this.mainAlias.aliasName).clearSelect().select(pks);
         // 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.getKnex().select(pks).from(knexQuery);
         this._limit = undefined;
         this._offset = undefined;
+        const cond = this._cond;
         this.select(this._fields).where({ [core_1.Utils.getPrimaryKeyHash(meta.primaryKeys)]: { $in: subSubQuery } });
+        if (this._populateWhere === core_1.PopulateHint.INFER) {
+            this.andWhere(cond);
+        }
+        else if (typeof this._populateWhere === 'object') {
+            this.andWhere(this._populateWhere);
+        }
     }
     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.getKnex().select(this.prepareFields(meta.primaryKeys)).from(subQuery.as(this.alias));
+        const subSubQuery = this.getKnex().select(this.prepareFields(meta.primaryKeys)).from(subQuery.as(this.mainAlias.aliasName));
         const method = this.flags.has(core_1.QueryFlag.UPDATE_SUB_QUERY) ? 'update' : 'delete';
         this._cond = {}; // otherwise we would trigger validation error
         this[method](this._data).where({
@@ -675,14 +836,54 @@ class QueryBuilder {
     }
     autoJoinPivotTable(field) {
         const pivotMeta = this.metadata.find(field);
-        const owner = pivotMeta.props.find(prop => prop.reference === core_1.ReferenceType.MANY_TO_ONE && prop.owner);
-        const inverse = pivotMeta.props.find(prop => prop.reference === core_1.ReferenceType.MANY_TO_ONE && !prop.owner);
+        const owner = pivotMeta.relations[0];
+        const inverse = pivotMeta.relations[1];
         const prop = this._cond[pivotMeta.name + '.' + owner.name] || this._orderBy[pivotMeta.name + '.' + owner.name] ? inverse : owner;
         const pivotAlias = this.getNextAlias(pivotMeta.name);
-        this._joins[field] = this.helper.joinPivotTable(field, prop, this.alias, pivotAlias, 'leftJoin');
+        this._joins[field] = this.helper.joinPivotTable(field, prop, this.mainAlias.aliasName, pivotAlias, 'leftJoin');
         core_1.Utils.renameKey(this._cond, `${field}.${owner.name}`, core_1.Utils.getPrimaryKeyHash(owner.fieldNames.map(fieldName => `${pivotAlias}.${fieldName}`)));
         core_1.Utils.renameKey(this._cond, `${field}.${inverse.name}`, core_1.Utils.getPrimaryKeyHash(inverse.fieldNames.map(fieldName => `${pivotAlias}.${fieldName}`)));
         this._populateMap[field] = this._joins[field].alias;
     }
+    getSchema(alias) {
+        const { metadata } = alias;
+        const metaSchema = metadata?.schema && metadata.schema !== '*' ? metadata.schema : undefined;
+        return this._schema ?? metaSchema ?? this.em?.config.get('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.getKnexQuery();
+        const { entityName } = target.mainAlias;
+        aliasName ?? (aliasName = this.getNextAlias(entityName));
+        this.createMainAlias(entityName, aliasName, subQuery);
+    }
+    fromEntityName(entityName, aliasName) {
+        aliasName ?? (aliasName = this._mainAlias?.aliasName ?? this.getNextAlias(entityName));
+        this.createMainAlias(entityName, aliasName);
+    }
+    createQueryBuilderHelper() {
+        return new QueryBuilderHelper_1.QueryBuilderHelper(this.mainAlias.entityName, this.mainAlias.aliasName, this._aliases, this.subQueries, this.knex, this.driver);
+    }
+    ensureFromClause() {
+        /* istanbul 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.');
+        }
+    }
 }
 exports.QueryBuilder = QueryBuilder;