@mikro-orm/sql 7.0.0-rc.3 → 7.0.0

package/query/QueryBuilderHelper.js

@@ -1,33 +1,35 @@
-import { ALIAS_REPLACEMENT, ALIAS_REPLACEMENT_RE, ArrayType, inspect, isRaw, LockMode, OptimisticLockError, QueryOperator, QueryOrderNumeric, raw, Raw, QueryHelper, ReferenceKind, Utils, ValidationError, } from '@mikro-orm/core';
-import { JoinType, QueryType } from './enums.js';
+import { ALIAS_REPLACEMENT, ALIAS_REPLACEMENT_RE, ArrayType, JsonType, inspect, isRaw, LockMode, OptimisticLockError, QueryOperator, QueryOrderNumeric, raw, Raw, QueryHelper, ReferenceKind, Utils, ValidationError, } from '@mikro-orm/core';
+import { EMBEDDABLE_ARRAY_OPS, JoinType, QueryType } from './enums.js';
 /**
  * @internal
  */
 export class QueryBuilderHelper {
-    entityName;
-    alias;
-    aliasMap;
-    subQueries;
-    driver;
-    tptAliasMap;
-    platform;
-    metadata;
+    #platform;
+    #metadata;
+    #entityName;
+    #alias;
+    #aliasMap;
+    #subQueries;
+    #driver;
+    #tptAliasMap;
+    /** Monotonically increasing counter for unique JSON array iteration aliases within a single query. */
+    #jsonAliasCounter = 0;
     constructor(entityName, alias, aliasMap, subQueries, driver, tptAliasMap = {}) {
-        this.entityName = entityName;
-        this.alias = alias;
-        this.aliasMap = aliasMap;
-        this.subQueries = subQueries;
-        this.driver = driver;
-        this.tptAliasMap = tptAliasMap;
-        this.platform = this.driver.getPlatform();
-        this.metadata = this.driver.getMetadata();
+        this.#entityName = entityName;
+        this.#alias = alias;
+        this.#aliasMap = aliasMap;
+        this.#subQueries = subQueries;
+        this.#driver = driver;
+        this.#tptAliasMap = tptAliasMap;
+        this.#platform = this.#driver.getPlatform();
+        this.#metadata = this.#driver.getMetadata();
     }
     /**
      * For TPT inheritance, finds the correct alias for a property based on which entity owns it.
      * Returns the main alias if not a TPT property or if the property belongs to the main entity.
      */
     getTPTAliasForProperty(propName, defaultAlias) {
-        const meta = this.aliasMap[defaultAlias]?.meta ?? this.metadata.get(this.entityName);
+        const meta = this.#aliasMap[defaultAlias]?.meta ?? this.#metadata.get(this.#entityName);
         if (meta?.inheritanceType !== 'tpt' || !meta.tptParent) {
             return defaultAlias;
         }
@@ -38,7 +40,7 @@ export class QueryBuilderHelper {
         // Walk up the TPT hierarchy to find which parent owns this property
         let parentMeta = meta.tptParent;
         while (parentMeta) {
-            const parentAlias = this.tptAliasMap[parentMeta.className];
+            const parentAlias = this.#tptAliasMap[parentMeta.className];
             if (parentAlias && parentMeta.ownProps?.some(p => p.name === propName || p.fieldNames?.includes(propName))) {
                 return parentAlias;
             }
@@ -67,13 +69,13 @@ export class QueryBuilderHelper {
                 const prop = this.getProperty(f, a);
                 const fkIdx2 = prop?.fieldNames.findIndex(name => name === f) ?? -1;
                 if (fkIdx2 !== -1) {
-                    parts.push(this.mapper(a !== this.alias ? `${a}.${prop.fieldNames[fkIdx2]}` : prop.fieldNames[fkIdx2], type, value, alias));
+                    parts.push(this.mapper(a !== this.#alias ? `${a}.${prop.fieldNames[fkIdx2]}` : prop.fieldNames[fkIdx2], type, value, alias));
                 }
                 else if (prop) {
-                    parts.push(...prop.fieldNames.map(f => this.mapper(a !== this.alias ? `${a}.${f}` : f, type, value, alias)));
+                    parts.push(...prop.fieldNames.map(f => this.mapper(a !== this.#alias ? `${a}.${f}` : f, type, value, alias)));
                 }
                 else {
-                    parts.push(this.mapper(a !== this.alias ? `${a}.${f}` : f, type, value, alias));
+                    parts.push(this.mapper(a !== this.#alias ? `${a}.${f}` : f, type, value, alias));
                 }
             }
             // flatten the value if we see we are expanding nested composite key
@@ -87,16 +89,16 @@ export class QueryBuilderHelper {
                     }
                 });
             }
-            return raw('(' + parts.map(part => this.platform.quoteIdentifier(part)).join(', ') + ')');
+            return raw('(' + parts.map(part => this.#platform.quoteIdentifier(part)).join(', ') + ')');
         }
         const [a, f] = this.splitField(field);
         const prop = this.getProperty(f, a);
         // For TPT inheritance, resolve the correct alias for this property
         // Only apply TPT resolution when `a` is an actual table alias (in aliasMap),
         // not when it's an embedded property name like 'profile1.identity.links'
-        const isTableAlias = !!this.aliasMap[a];
-        const baseAlias = isTableAlias ? a : this.alias;
-        const resolvedAlias = isTableAlias ? this.getTPTAliasForProperty(prop?.name ?? f, a) : this.alias;
+        const isTableAlias = !!this.#aliasMap[a];
+        const baseAlias = isTableAlias ? a : this.#alias;
+        const resolvedAlias = isTableAlias ? this.getTPTAliasForProperty(prop?.name ?? f, a) : this.#alias;
         const aliasPrefix = isTableNameAliasRequired ? resolvedAlias + '.' : '';
         const fkIdx2 = prop?.fieldNames.findIndex(name => name === f) ?? -1;
         const fkIdx = fkIdx2 === -1 ? 0 : fkIdx2;
@@ -108,13 +110,13 @@ export class QueryBuilderHelper {
             return raw(this.prefix(field, isTableNameAliasRequired));
         }
         if (prop?.formula) {
-            const alias2 = this.platform.quoteIdentifier(a).toString();
+            const alias2 = this.#platform.quoteIdentifier(a).toString();
             const aliasName = alias === undefined ? prop.fieldNames[0] : alias;
-            const as = aliasName === null ? '' : ` as ${this.platform.quoteIdentifier(aliasName)}`;
-            const meta = this.aliasMap[a]?.meta ?? this.metadata.get(this.entityName);
+            const as = aliasName === null ? '' : ` as ${this.#platform.quoteIdentifier(aliasName)}`;
+            const meta = this.#aliasMap[a]?.meta ?? this.#metadata.get(this.#entityName);
             const table = this.createFormulaTable(alias2, meta, schema);
             const columns = meta.createColumnMappingObject(p => this.getTPTAliasForProperty(p.name, a), alias2);
-            let value = this.driver.evaluateFormula(prop.formula, columns, table);
+            let value = this.#driver.evaluateFormula(prop.formula, columns, table);
             if (!this.isTableNameAliasRequired(type)) {
                 value = value.replaceAll(alias2 + '.', '');
             }
@@ -125,16 +127,16 @@ export class QueryBuilderHelper {
             if (prop.fieldNames.length > 1 && fkIdx !== -1) {
                 const fk = prop.targetMeta.getPrimaryProps()[fkIdx];
                 const prefixed = this.prefix(field, isTableNameAliasRequired, true, fkIdx);
-                valueSQL = fk.customType.convertToJSValueSQL(prefixed, this.platform);
+                valueSQL = fk.customType.convertToJSValueSQL(prefixed, this.#platform);
             }
             else {
                 const prefixed = this.prefix(field, isTableNameAliasRequired, true);
-                valueSQL = prop.customType.convertToJSValueSQL(prefixed, this.platform);
+                valueSQL = prop.customType.convertToJSValueSQL(prefixed, this.#platform);
             }
             if (alias === null) {
                 return raw(valueSQL);
             }
-            return raw(`${valueSQL} as ${this.platform.quoteIdentifier(alias ?? prop.fieldNames[fkIdx])}`);
+            return raw(`${valueSQL} as ${this.#platform.quoteIdentifier(alias ?? prop.fieldNames[fkIdx])}`);
         }
         let ret = this.prefix(field, false, false, fkIdx);
         if (alias) {
@@ -149,11 +151,11 @@ export class QueryBuilderHelper {
         if (Array.isArray(data)) {
             return data.map(d => this.processData(d, convertCustomTypes, true));
         }
-        const meta = this.metadata.find(this.entityName);
-        data = this.driver.mapDataToFieldNames(data, true, meta?.properties, convertCustomTypes);
+        const meta = this.#metadata.find(this.#entityName);
+        data = this.#driver.mapDataToFieldNames(data, true, meta?.properties, convertCustomTypes);
         if (!Utils.hasObjectKeys(data) && meta && multi) {
             /* v8 ignore next */
-            data[meta.getPrimaryProps()[0].fieldNames[0]] = this.platform.usesDefaultKeyword() ? raw('default') : undefined;
+            data[meta.getPrimaryProps()[0].fieldNames[0]] = this.#platform.usesDefaultKeyword() ? raw('default') : undefined;
         }
         return data;
     }
@@ -163,11 +165,11 @@ export class QueryBuilderHelper {
         const joinColumns = prop.owner ? prop.referencedColumnNames : prop2.joinColumns;
         const inverseJoinColumns = prop.referencedColumnNames;
         const primaryKeys = prop.owner ? prop.joinColumns : prop2.referencedColumnNames;
-        schema ??= prop.targetMeta?.schema === '*' ? '*' : this.driver.getSchemaName(prop.targetMeta);
+        schema ??= prop.targetMeta?.schema === '*' ? '*' : this.#driver.getSchemaName(prop.targetMeta);
         cond = Utils.merge(cond, prop.where);
         // For inverse side of polymorphic relations, add discriminator condition
         if (!prop.owner && prop2.polymorphic && prop2.discriminatorColumn && prop2.discriminatorMap) {
-            const ownerMeta = this.aliasMap[ownerAlias]?.meta ?? this.metadata.get(this.entityName);
+            const ownerMeta = this.#aliasMap[ownerAlias]?.meta ?? this.#metadata.get(this.#entityName);
             const discriminatorValue = QueryHelper.findDiscriminatorValue(prop2.discriminatorMap, ownerMeta.class);
             if (discriminatorValue) {
                 cond[`${alias}.${prop2.discriminatorColumn}`] = discriminatorValue;
@@ -194,7 +196,7 @@ export class QueryBuilderHelper {
             ownerAlias,
             alias,
             table: this.getTableName(prop.targetMeta.class),
-            schema: prop.targetMeta?.schema === '*' ? '*' : this.driver.getSchemaName(prop.targetMeta, { schema }),
+            schema: prop.targetMeta?.schema === '*' ? '*' : this.#driver.getSchemaName(prop.targetMeta, { schema }),
             joinColumns: prop.referencedColumnNames,
             // For polymorphic relations, fieldNames includes the discriminator column which is not
             // part of the join condition - use joinColumns (the FK columns only) instead
@@ -202,7 +204,7 @@ export class QueryBuilderHelper {
         };
     }
     joinManyToManyReference(prop, ownerAlias, alias, pivotAlias, type, cond, path, schema) {
-        const pivotMeta = this.metadata.find(prop.pivotEntity);
+        const pivotMeta = this.#metadata.find(prop.pivotEntity);
         const ret = {
             [`${ownerAlias}.${prop.name}#${pivotAlias}`]: {
                 prop,
@@ -215,7 +217,7 @@ export class QueryBuilderHelper {
                 primaryKeys: prop.referencedColumnNames,
                 cond: {},
                 table: pivotMeta.tableName,
-                schema: prop.targetMeta?.schema === '*' ? '*' : this.driver.getSchemaName(pivotMeta, { schema }),
+                schema: prop.targetMeta?.schema === '*' ? '*' : this.#driver.getSchemaName(pivotMeta, { schema }),
                 path: path.endsWith('[pivot]') ? path : `${path}[pivot]`,
             },
         };
@@ -229,16 +231,16 @@ export class QueryBuilderHelper {
         ret[`${pivotAlias}.${prop2.name}#${alias}`].schema ??= tmp.length > 1 ? tmp[0] : undefined;
         return ret;
     }
-    processJoins(qb, joins, schema) {
+    processJoins(qb, joins, schema, schemaOverride) {
         Object.values(joins).forEach(join => {
             if ([JoinType.nestedInnerJoin, JoinType.nestedLeftJoin].includes(join.type)) {
                 return;
             }
-            const { sql, params } = this.createJoinExpression(join, joins, schema);
+            const { sql, params } = this.createJoinExpression(join, joins, schema, schemaOverride);
             qb.join(sql, params);
         });
     }
-    createJoinExpression(join, joins, schema) {
+    createJoinExpression(join, joins, schema, schemaOverride) {
         let table = join.table;
         const method = {
             [JoinType.nestedInnerJoin]: 'inner join',
@@ -247,26 +249,26 @@ export class QueryBuilderHelper {
         }[join.type] ?? join.type;
         const conditions = [];
         const params = [];
-        schema = join.schema && join.schema !== '*' ? join.schema : schema;
-        if (schema && schema !== this.platform.getDefaultSchemaName()) {
+        schema = join.schema === '*' ? schema : (join.schema ?? schemaOverride);
+        if (schema && schema !== this.#platform.getDefaultSchemaName()) {
             table = `${schema}.${table}`;
         }
         if (join.prop.name !== '__subquery__') {
             join.primaryKeys.forEach((primaryKey, idx) => {
                 const right = `${join.alias}.${join.joinColumns[idx]}`;
                 if (join.prop.formula) {
-                    const quotedAlias = this.platform.quoteIdentifier(join.ownerAlias).toString();
-                    const ownerMeta = this.aliasMap[join.ownerAlias]?.meta ?? this.metadata.get(this.entityName);
+                    const quotedAlias = this.#platform.quoteIdentifier(join.ownerAlias).toString();
+                    const ownerMeta = this.#aliasMap[join.ownerAlias]?.meta ?? this.#metadata.get(this.#entityName);
                     const table = this.createFormulaTable(quotedAlias, ownerMeta, schema);
                     const columns = ownerMeta.createColumnMappingObject(p => this.getTPTAliasForProperty(p.name, join.ownerAlias), quotedAlias);
-                    const left = this.driver.evaluateFormula(join.prop.formula, columns, table);
-                    conditions.push(`${left} = ${this.platform.quoteIdentifier(right)}`);
+                    const left = this.#driver.evaluateFormula(join.prop.formula, columns, table);
+                    conditions.push(`${left} = ${this.#platform.quoteIdentifier(right)}`);
                     return;
                 }
                 const left = join.prop.object && join.prop.fieldNameRaw
                     ? join.prop.fieldNameRaw.replaceAll(ALIAS_REPLACEMENT, join.ownerAlias)
-                    : this.platform.quoteIdentifier(`${join.ownerAlias}.${primaryKey}`);
-                conditions.push(`${left} = ${this.platform.quoteIdentifier(right)}`);
+                    : this.#platform.quoteIdentifier(`${join.ownerAlias}.${primaryKey}`);
+                conditions.push(`${left} = ${this.#platform.quoteIdentifier(right)}`);
             });
         }
         if (join.prop.targetMeta?.root.inheritanceType === 'sti' &&
@@ -280,31 +282,36 @@ export class QueryBuilderHelper {
         if (join.prop.polymorphic && join.prop.discriminatorColumn && join.prop.discriminatorMap) {
             const discriminatorValue = QueryHelper.findDiscriminatorValue(join.prop.discriminatorMap, join.prop.targetMeta.class);
             if (discriminatorValue) {
-                const discriminatorCol = this.platform.quoteIdentifier(`${join.ownerAlias}.${join.prop.discriminatorColumn}`);
+                const discriminatorCol = this.#platform.quoteIdentifier(`${join.ownerAlias}.${join.prop.discriminatorColumn}`);
                 conditions.push(`${discriminatorCol} = ?`);
                 params.push(discriminatorValue);
             }
         }
         let sql = method + ' ';
         if (join.nested) {
-            sql += `(${this.platform.quoteIdentifier(table)} as ${this.platform.quoteIdentifier(join.alias)}`;
+            const asKeyword = this.#platform.usesAsKeyword() ? ' as ' : ' ';
+            sql += `(${this.#platform.quoteIdentifier(table)}${asKeyword}${this.#platform.quoteIdentifier(join.alias)}`;
             for (const nested of join.nested) {
-                const { sql: nestedSql, params: nestedParams } = this.createJoinExpression(nested, joins, schema);
+                const { sql: nestedSql, params: nestedParams } = this.createJoinExpression(nested, joins, schema, schemaOverride);
                 sql += ' ' + nestedSql;
                 params.push(...nestedParams);
             }
             sql += `)`;
         }
         else if (join.subquery) {
-            sql += `(${join.subquery}) as ${this.platform.quoteIdentifier(join.alias)}`;
+            const asKeyword = this.#platform.usesAsKeyword() ? ' as ' : ' ';
+            sql += `(${join.subquery})${asKeyword}${this.#platform.quoteIdentifier(join.alias)}`;
         }
         else {
-            sql += `${this.platform.quoteIdentifier(table)} as ${this.platform.quoteIdentifier(join.alias)}`;
+            sql +=
+                this.#platform.quoteIdentifier(table) +
+                    (this.#platform.usesAsKeyword() ? ' as ' : ' ') +
+                    this.#platform.quoteIdentifier(join.alias);
         }
-        const oldAlias = this.alias;
-        this.alias = join.alias;
+        const oldAlias = this.#alias;
+        this.#alias = join.alias;
         const subquery = this._appendQueryCondition(QueryType.SELECT, join.cond);
-        this.alias = oldAlias;
+        this.#alias = oldAlias;
         if (subquery.sql) {
             conditions.push(subquery.sql);
             subquery.params.forEach(p => params.push(p));
@@ -327,12 +334,12 @@ export class QueryBuilderHelper {
         ];
     }
     isOneToOneInverse(field, meta) {
-        meta ??= this.metadata.find(this.entityName);
+        meta ??= this.#metadata.find(this.#entityName);
         const prop = meta.properties[field.replace(/:ref$/, '')];
         return prop?.kind === ReferenceKind.ONE_TO_ONE && !prop.owner;
     }
     getTableName(entityName) {
-        const meta = this.metadata.find(entityName);
+        const meta = this.#metadata.find(entityName);
         return meta?.tableName ?? Utils.className(entityName);
     }
     /**
@@ -346,7 +353,7 @@ export class QueryBuilderHelper {
             return false;
         }
         // when including the opening bracket/paren we consider it complex
-        return !re.source.match(/[{[(]/);
+        return !/[{[(]/.exec(re.source);
     }
     getRegExpParam(re) {
         const value = re.source
@@ -427,17 +434,37 @@ export class QueryBuilderHelper {
         const parts = [];
         const params = [];
         if (this.isSimpleRegExp(cond[key])) {
-            parts.push(`${this.platform.quoteIdentifier(this.mapper(key, type))} like ?`);
+            parts.push(`${this.#platform.quoteIdentifier(this.mapper(key, type))} like ?`);
             params.push(this.getRegExpParam(cond[key]));
             return { sql: parts.join(' and '), params };
         }
+        if (Utils.isPlainObject(cond[key]) && !Raw.isKnownFragmentSymbol(key)) {
+            const [a, f] = this.splitField(key);
+            const prop = this.getProperty(f, a);
+            if (prop?.kind === ReferenceKind.EMBEDDED && prop.array) {
+                const keys = Object.keys(cond[key]);
+                const hasOnlyArrayOps = keys.every((k) => EMBEDDABLE_ARRAY_OPS.includes(k));
+                if (!hasOnlyArrayOps) {
+                    return this.processEmbeddedArrayCondition(cond[key], prop, a);
+                }
+            }
+            // $elemMatch on JSON properties — iterate array elements via EXISTS subquery.
+            // When combined with other operators (e.g. $contains), processObjectSubCondition
+            // splits them first (size > 1), so $elemMatch arrives here alone.
+            if (prop && cond[key].$elemMatch != null && Utils.getObjectKeysSize(cond[key]) === 1) {
+                if (!(prop.customType instanceof JsonType)) {
+                    throw new ValidationError(`$elemMatch can only be used on JSON array properties, but '${this.#entityName}.${prop.name}' has type '${prop.type}'`);
+                }
+                return this.processJsonElemMatch(cond[key].$elemMatch, prop, a);
+            }
+        }
         if (Utils.isPlainObject(cond[key]) || cond[key] instanceof RegExp) {
             return this.processObjectSubCondition(cond, key, type);
         }
         const op = cond[key] === null ? 'is' : '=';
         if (Raw.isKnownFragmentSymbol(key)) {
             const raw = Raw.getKnownFragment(key);
-            const sql = raw.sql.replaceAll(ALIAS_REPLACEMENT, this.alias);
+            const sql = raw.sql.replaceAll(ALIAS_REPLACEMENT, this.#alias);
             const value = Utils.asArray(cond[key]);
             params.push(...raw.params);
             if (value.length > 0) {
@@ -450,13 +477,13 @@ export class QueryBuilderHelper {
             return { sql: parts.join(' and '), params };
         }
         const fields = Utils.splitPrimaryKeys(key);
-        if (this.subQueries[key]) {
+        if (this.#subQueries[key]) {
             const val = this.getValueReplacement(fields, cond[key], params, key);
-            parts.push(`(${this.subQueries[key]}) ${op} ${val}`);
+            parts.push(`(${this.#subQueries[key]}) ${op} ${val}`);
             return { sql: parts.join(' and '), params };
         }
         const val = this.getValueReplacement(fields, cond[key], params, key);
-        parts.push(`${this.platform.quoteIdentifier(this.mapper(key, type, cond[key], null))} ${op} ${val}`);
+        parts.push(`${this.#platform.quoteIdentifier(this.mapper(key, type, cond[key], null))} ${op} ${val}`);
         return { sql: parts.join(' and '), params };
     }
     processObjectSubCondition(cond, key, type) {
@@ -478,7 +505,7 @@ export class QueryBuilderHelper {
             return { sql: parts.join(' and '), params };
         }
         if (value instanceof RegExp) {
-            value = this.platform.getRegExpValue(value);
+            value = this.#platform.getRegExpValue(value);
         }
         // operators
         const op = Object.keys(QueryOperator).find(op => op in value);
@@ -491,17 +518,17 @@ export class QueryBuilderHelper {
         const fields = rawField ? [key] : Utils.splitPrimaryKeys(key);
         if (fields.length > 1 && Array.isArray(value[op])) {
             const singleTuple = !value[op].every((v) => Array.isArray(v));
-            if (!this.platform.allowsComparingTuples()) {
+            if (!this.#platform.allowsComparingTuples()) {
                 const mapped = fields.map(f => this.mapper(f, type));
                 if (op === '$in') {
                     const conds = value[op].map(() => {
-                        return `(${mapped.map(field => `${this.platform.quoteIdentifier(field)} = ?`).join(' and ')})`;
+                        return `(${mapped.map(field => `${this.#platform.quoteIdentifier(field)} = ?`).join(' and ')})`;
                     });
                     parts.push(`(${conds.join(' or ')})`);
                     params.push(...Utils.flatten(value[op]));
                     return { sql: parts.join(' and '), params };
                 }
-                parts.push(...mapped.map(field => `${this.platform.quoteIdentifier(field)} = ?`));
+                parts.push(...mapped.map(field => `${this.#platform.quoteIdentifier(field)} = ?`));
                 params.push(...Utils.flatten(value[op]));
                 return { sql: parts.join(' and '), params };
             }
@@ -511,9 +538,9 @@ export class QueryBuilderHelper {
                 value[op] = raw(sql, tmp);
             }
         }
-        if (this.subQueries[key]) {
+        if (this.#subQueries[key]) {
             const val = this.getValueReplacement(fields, value[op], params, op);
-            parts.push(`(${this.subQueries[key]}) ${replacement} ${val}`);
+            parts.push(`(${this.#subQueries[key]}) ${replacement} ${val}`);
             return { sql: parts.join(' and '), params };
         }
         const [a, f] = rawField ? [] : this.splitField(key);
@@ -526,7 +553,7 @@ export class QueryBuilderHelper {
             if (!prop) {
                 throw new Error(`Cannot use $fulltext operator on ${String(key)}, property not found`);
             }
-            const { sql, params: params2 } = raw(this.platform.getFullTextWhereClause(prop), {
+            const { sql, params: params2 } = raw(this.#platform.getFullTextWhereClause(prop), {
                 column: this.mapper(key, type, undefined, null),
                 query: value[op],
             });
@@ -536,6 +563,12 @@ export class QueryBuilderHelper {
         else if (['$in', '$nin'].includes(op) && Array.isArray(value[op]) && value[op].length === 0) {
             parts.push(`1 = ${op === '$in' ? 0 : 1}`);
         }
+        else if (op === '$re') {
+            const mappedKey = this.mapper(key, type, value[op], null);
+            const processed = this.#platform.mapRegExpCondition(mappedKey, value);
+            parts.push(processed.sql);
+            params.push(...processed.params);
+        }
         else if (value[op] instanceof Raw || typeof value[op]?.toRaw === 'function') {
             const query = value[op] instanceof Raw ? value[op] : value[op].toRaw();
             const mappedKey = this.mapper(key, type, query, null);
@@ -543,13 +576,13 @@ export class QueryBuilderHelper {
             if (['$in', '$nin'].includes(op)) {
                 sql = `(${sql})`;
             }
-            parts.push(`${this.platform.quoteIdentifier(mappedKey)} ${replacement} ${sql}`);
+            parts.push(`${this.#platform.quoteIdentifier(mappedKey)} ${replacement} ${sql}`);
             params.push(...query.params);
         }
         else {
             const mappedKey = this.mapper(key, type, value[op], null);
             const val = this.getValueReplacement(fields, value[op], params, op, prop);
-            parts.push(`${this.platform.quoteIdentifier(mappedKey)} ${replacement} ${val}`);
+            parts.push(`${this.#platform.quoteIdentifier(mappedKey)} ${replacement} ${val}`);
         }
         return { sql: parts.join(' and '), params };
     }
@@ -564,7 +597,7 @@ export class QueryBuilderHelper {
                 return `(${tmp.join(', ')})`;
             }
             if (prop?.customType instanceof ArrayType) {
-                const item = prop.customType.convertToDatabaseValue(value, this.platform, {
+                const item = prop.customType.convertToDatabaseValue(value, this.#platform, {
                     fromQuery: true,
                     key,
                     mode: 'query',
@@ -592,7 +625,7 @@ export class QueryBuilderHelper {
             replacement = op === '$eq' ? 'is' : 'is not';
         }
         if (op === '$re') {
-            replacement = this.platform.getRegExpOperator(value[op], value.$flags);
+            replacement = this.#platform.getRegExpOperator(value[op], value.$flags);
         }
         if (replacement.includes('?')) {
             replacement = replacement.replaceAll('?', '\\?');
@@ -637,7 +670,7 @@ export class QueryBuilderHelper {
             const order = typeof direction === 'number' ? QueryOrderNumeric[direction] : direction;
             if (Raw.isKnownFragmentSymbol(key)) {
                 const raw = Raw.getKnownFragment(key);
-                ret.push(...this.platform.getOrderByExpression(this.platform.formatQuery(raw.sql, raw.params), order, collation));
+                ret.push(...this.#platform.getOrderByExpression(this.#platform.formatQuery(raw.sql, raw.params), order, collation));
                 continue;
             }
             for (const f of Utils.splitPrimaryKeys(key)) {
@@ -651,60 +684,24 @@ export class QueryBuilderHelper {
                 const rawColumn = typeof column === 'string'
                     ? column
                         .split('.')
-                        .map(e => this.platform.quoteIdentifier(e))
+                        .map(e => this.#platform.quoteIdentifier(e))
                         .join('.')
                     : column;
                 const customOrder = prop?.customOrder;
-                let colPart = customOrder ? this.platform.generateCustomOrder(rawColumn, customOrder) : rawColumn;
+                let colPart = customOrder ? this.#platform.generateCustomOrder(rawColumn, customOrder) : rawColumn;
                 if (isRaw(colPart)) {
-                    colPart = this.platform.formatQuery(colPart.sql, colPart.params);
+                    colPart = this.#platform.formatQuery(colPart.sql, colPart.params);
                 }
                 if (Array.isArray(order)) {
                     order.forEach(part => ret.push(...this.getQueryOrderFromObject(type, part, populate, collation)));
                 }
                 else {
-                    ret.push(...this.platform.getOrderByExpression(colPart, order, collation));
+                    ret.push(...this.#platform.getOrderByExpression(colPart, order, collation));
                 }
             }
         }
         return ret;
     }
-    finalize(type, qb, meta, data, returning) {
-        const usesReturningStatement = this.platform.usesReturningStatement() || this.platform.usesOutputStatement();
-        if (!meta || !data || !usesReturningStatement) {
-            return;
-        }
-        // always respect explicit returning hint
-        if (returning && returning.length > 0) {
-            qb.returning(returning.map(field => this.mapper(field, type)));
-            return;
-        }
-        if (type === QueryType.INSERT) {
-            const returningProps = meta.hydrateProps
-                .filter(prop => prop.returning || (prop.persist !== false && ((prop.primary && prop.autoincrement) || prop.defaultRaw)))
-                .filter(prop => !(prop.name in data));
-            if (returningProps.length > 0) {
-                qb.returning(Utils.flatten(returningProps.map(prop => prop.fieldNames)));
-            }
-            return;
-        }
-        if (type === QueryType.UPDATE) {
-            const returningProps = meta.hydrateProps.filter(prop => prop.fieldNames && isRaw(data[prop.fieldNames[0]]));
-            if (returningProps.length > 0) {
-                const fields = returningProps.flatMap((prop) => {
-                    if (prop.hasConvertToJSValueSQL) {
-                        const aliased = this.platform.quoteIdentifier(prop.fieldNames[0]);
-                        const sql = prop.customType.convertToJSValueSQL(aliased, this.platform) +
-                            ' as ' +
-                            this.platform.quoteIdentifier(prop.fieldNames[0]);
-                        return [raw(sql)];
-                    }
-                    return prop.fieldNames;
-                });
-                qb.returning(fields);
-            }
-        }
-    }
     splitField(field, greedyAlias = false) {
         const parts = field.split('.');
         const ref = parts[parts.length - 1].split(':')[1];
@@ -712,7 +709,7 @@ export class QueryBuilderHelper {
             parts[parts.length - 1] = parts[parts.length - 1].substring(0, parts[parts.length - 1].indexOf(':'));
         }
         if (parts.length === 1) {
-            return [this.alias, parts[0], ref];
+            return [this.#alias, parts[0], ref];
         }
         if (greedyAlias) {
             const fromField = parts.pop();
@@ -724,28 +721,28 @@ export class QueryBuilderHelper {
         return [fromAlias, fromField, ref];
     }
     getLockSQL(qb, lockMode, lockTables = [], joinsMap) {
-        const meta = this.metadata.find(this.entityName);
+        const meta = this.#metadata.find(this.#entityName);
         if (lockMode === LockMode.OPTIMISTIC && meta && !meta.versionProperty) {
-            throw OptimisticLockError.lockFailed(Utils.className(this.entityName));
+            throw OptimisticLockError.lockFailed(Utils.className(this.#entityName));
         }
         if (lockMode !== LockMode.OPTIMISTIC && lockTables.length === 0 && joinsMap) {
             const joins = Object.values(joinsMap);
             const innerJoins = joins.filter(join => [JoinType.innerJoin, JoinType.innerJoinLateral, JoinType.nestedInnerJoin].includes(join.type));
             if (joins.length > innerJoins.length) {
-                lockTables.push(this.alias, ...innerJoins.map(join => join.alias));
+                lockTables.push(this.#alias, ...innerJoins.map(join => join.alias));
             }
         }
         qb.lockMode(lockMode, lockTables);
     }
     updateVersionProperty(qb, data) {
-        const meta = this.metadata.find(this.entityName);
+        const meta = this.#metadata.find(this.#entityName);
         if (!meta?.versionProperty || meta.versionProperty in data) {
             return;
         }
         const versionProperty = meta.properties[meta.versionProperty];
-        let sql = this.platform.quoteIdentifier(versionProperty.fieldNames[0]) + ' + 1';
+        let sql = this.#platform.quoteIdentifier(versionProperty.fieldNames[0]) + ' + 1';
         if (versionProperty.runtimeType === 'Date') {
-            sql = this.platform.getCurrentTimestampSQL(versionProperty.length);
+            sql = this.#platform.getCurrentTimestampSQL(versionProperty.length);
         }
         qb.update({ [versionProperty.fieldNames[0]]: raw(sql) });
     }
@@ -753,8 +750,8 @@ export class QueryBuilderHelper {
         let ret;
         if (!this.isPrefixed(field)) {
             // For TPT inheritance, resolve the correct alias for this property
-            const tptAlias = this.getTPTAliasForProperty(field, this.alias);
-            const alias = always ? (quote ? tptAlias : this.platform.quoteIdentifier(tptAlias)) + '.' : '';
+            const tptAlias = this.getTPTAliasForProperty(field, this.#alias);
+            const alias = always ? (quote ? tptAlias : this.#platform.quoteIdentifier(tptAlias)) + '.' : '';
             const fieldName = this.fieldName(field, tptAlias, always, idx);
             if (fieldName instanceof Raw) {
                 return fieldName.sql;
@@ -767,7 +764,7 @@ export class QueryBuilderHelper {
             // For TPT inheritance, resolve the correct alias for this property
             // Only apply TPT resolution when `a` is an actual table alias (in aliasMap),
             // not when it's an embedded property name like 'profile1.identity.links'
-            const isTableAlias = !!this.aliasMap[a];
+            const isTableAlias = !!this.#aliasMap[a];
             const resolvedAlias = isTableAlias ? this.getTPTAliasForProperty(f, a) : a;
             const fieldName = this.fieldName(f, resolvedAlias, always, idx);
             if (fieldName instanceof Raw) {
@@ -776,7 +773,7 @@ export class QueryBuilderHelper {
             ret = resolvedAlias + '.' + fieldName;
         }
         if (quote) {
-            return this.platform.quoteIdentifier(ret);
+            return this.#platform.quoteIdentifier(ret);
         }
         return ret;
     }
@@ -806,7 +803,7 @@ export class QueryBuilderHelper {
         return { sql: `(${parts.join(' or ')})`, params };
     }
     isPrefixed(field) {
-        return !!field.match(/[\w`"[\]]+\./);
+        return !!/[\w`"[\]]+\./.exec(field);
     }
     fieldName(field, alias, always, idx = 0) {
         const prop = this.getProperty(field, alias);
@@ -817,7 +814,7 @@ export class QueryBuilderHelper {
             if (!always) {
                 return raw(prop.fieldNameRaw
                     .replace(new RegExp(ALIAS_REPLACEMENT_RE + '\\.?', 'g'), '')
-                    .replace(this.platform.quoteIdentifier('') + '.', ''));
+                    .replace(this.#platform.quoteIdentifier('') + '.', ''));
             }
             if (alias) {
                 return raw(prop.fieldNameRaw.replace(new RegExp(ALIAS_REPLACEMENT_RE, 'g'), alias));
@@ -829,8 +826,8 @@ export class QueryBuilderHelper {
         return prop.fieldNames?.[idx] ?? field;
     }
     getProperty(field, alias) {
-        const entityName = this.aliasMap[alias]?.entityName || this.entityName;
-        const meta = this.metadata.find(entityName);
+        const entityName = this.#aliasMap[alias]?.entityName || this.#entityName;
+        const meta = this.#metadata.find(entityName);
         // raw table name (e.g. CTE) — no metadata available
         if (!meta) {
             return undefined;
@@ -852,8 +849,198 @@ export class QueryBuilderHelper {
     isTableNameAliasRequired(type) {
         return [QueryType.SELECT, QueryType.COUNT].includes(type);
     }
+    processEmbeddedArrayCondition(cond, prop, alias) {
+        const column = this.#platform.quoteIdentifier(`${alias}.${prop.fieldNames[0]}`);
+        const resolveProperty = (key) => {
+            const { embProp, jsonPropName } = this.resolveEmbeddedProp(prop, key);
+            return { name: jsonPropName, type: embProp.runtimeType ?? 'string' };
+        };
+        const invalidObjectError = (key) => ValidationError.invalidEmbeddableQuery(this.#entityName, key, prop.type);
+        const parts = [];
+        const allParams = [];
+        // Top-level $not generates NOT EXISTS (no element matches the inner condition).
+        const { $not, ...rest } = cond;
+        if (Utils.hasObjectKeys(rest)) {
+            const result = this.buildJsonArrayExists(rest, column, false, resolveProperty, invalidObjectError);
+            if (result) {
+                parts.push(result.sql);
+                allParams.push(...result.params);
+            }
+        }
+        if ($not != null) {
+            if (!Utils.isPlainObject($not)) {
+                throw new ValidationError(`Invalid query: $not in embedded array queries expects an object value`);
+            }
+            const result = this.buildJsonArrayExists($not, column, true, resolveProperty, invalidObjectError);
+            if (result) {
+                parts.push(result.sql);
+                allParams.push(...result.params);
+            }
+        }
+        if (parts.length === 0) {
+            return { sql: '1 = 1', params: [] };
+        }
+        return { sql: parts.join(' and '), params: allParams };
+    }
+    buildJsonArrayExists(cond, column, negate, resolveProperty, invalidObjectError) {
+        const jeAlias = `__je${this.#jsonAliasCounter++}`;
+        const referencedProps = new Map();
+        const { sql: whereSql, params } = this.buildArrayElementWhere(cond, jeAlias, referencedProps, resolveProperty, invalidObjectError);
+        if (!whereSql) {
+            return null;
+        }
+        const from = this.#platform.getJsonArrayFromSQL(column, jeAlias, [...referencedProps.values()]);
+        const exists = this.#platform.getJsonArrayExistsSQL(from, whereSql);
+        return { sql: negate ? `not ${exists}` : exists, params };
+    }
+    resolveEmbeddedProp(prop, key) {
+        const embProp = prop.embeddedProps[key] ?? Object.values(prop.embeddedProps).find(p => p.name === key);
+        if (!embProp) {
+            throw ValidationError.invalidEmbeddableQuery(this.#entityName, key, prop.type);
+        }
+        const prefix = `${prop.fieldNames[0]}~`;
+        const raw = embProp.fieldNames[0];
+        const jsonPropName = raw.startsWith(prefix) ? raw.slice(prefix.length) : raw;
+        return { embProp, jsonPropName };
+    }
+    buildEmbeddedArrayOperatorCondition(lhs, value, params) {
+        const supported = new Set(['$eq', '$ne', '$gt', '$gte', '$lt', '$lte', '$in', '$nin', '$not', '$like', '$exists']);
+        const parts = [];
+        // Clone to avoid getOperatorReplacement mutating the original (it sets value[op] = null for $exists).
+        value = { ...value };
+        for (const op of Object.keys(value)) {
+            if (!supported.has(op)) {
+                throw new ValidationError(`Operator ${op} is not supported in embedded array queries`);
+            }
+            const replacement = this.getOperatorReplacement(op, value);
+            const val = value[op];
+            if (['$in', '$nin'].includes(op)) {
+                if (!Array.isArray(val)) {
+                    throw new ValidationError(`Invalid query: ${op} operator expects an array value`);
+                }
+                else if (val.length === 0) {
+                    parts.push(`1 = ${op === '$in' ? 0 : 1}`);
+                }
+                else {
+                    val.forEach((v) => params.push(v));
+                    parts.push(`${lhs} ${replacement} (${val.map(() => '?').join(', ')})`);
+                }
+            }
+            else if (op === '$exists') {
+                parts.push(`${lhs} ${replacement} null`);
+            }
+            else if (val === null) {
+                parts.push(`${lhs} ${replacement} null`);
+            }
+            else {
+                parts.push(`${lhs} ${replacement} ?`);
+                params.push(val);
+            }
+        }
+        return parts.join(' and ');
+    }
+    processJsonElemMatch(cond, prop, alias) {
+        const column = this.#platform.quoteIdentifier(`${alias}.${prop.fieldNames[0]}`);
+        const result = this.buildJsonArrayExists(cond, column, false, (key, value) => {
+            this.#platform.validateJsonPropertyName(key);
+            return { name: key, type: this.inferJsonValueType(value) };
+        }, () => ValidationError.invalidQueryCondition(cond));
+        return result ?? { sql: '1 = 1', params: [] };
+    }
+    /**
+     * Shared logic for building WHERE conditions inside JSON array EXISTS subqueries.
+     * Used by both embedded array queries (metadata-driven) and $elemMatch (type-inferred).
+     */
+    buildArrayElementWhere(cond, jeAlias, referencedProps, resolveProperty, invalidObjectError) {
+        const parts = [];
+        const params = [];
+        for (const k of Object.keys(cond)) {
+            if (k === '$and' || k === '$or') {
+                const items = cond[k];
+                if (items.length === 0) {
+                    continue;
+                }
+                const subParts = [];
+                for (const item of items) {
+                    const sub = this.buildArrayElementWhere(item, jeAlias, referencedProps, resolveProperty, invalidObjectError);
+                    if (sub.sql) {
+                        subParts.push(sub.sql);
+                        params.push(...sub.params);
+                    }
+                }
+                if (subParts.length > 0) {
+                    const joiner = k === '$or' ? ' or ' : ' and ';
+                    parts.push(`(${subParts.join(joiner)})`);
+                }
+                continue;
+            }
+            // Within $or/$and scope, $not provides element-level negation:
+            // "this element does not match the condition".
+            if (k === '$not') {
+                const sub = this.buildArrayElementWhere(cond[k], jeAlias, referencedProps, resolveProperty, invalidObjectError);
+                if (sub.sql) {
+                    parts.push(`not (${sub.sql})`);
+                    params.push(...sub.params);
+                }
+                continue;
+            }
+            const value = cond[k];
+            const { name, type } = resolveProperty(k, value);
+            referencedProps.set(k, { name, type });
+            const lhs = this.#platform.getJsonArrayElementPropertySQL(jeAlias, name, type);
+            if (Utils.isPlainObject(value)) {
+                const valueKeys = Object.keys(value);
+                if (valueKeys.some(vk => !Utils.isOperator(vk))) {
+                    throw invalidObjectError(k);
+                }
+                const sub = this.buildEmbeddedArrayOperatorCondition(lhs, value, params);
+                parts.push(sub);
+            }
+            else if (value === null) {
+                parts.push(`${lhs} is null`);
+            }
+            else {
+                parts.push(`${lhs} = ?`);
+                params.push(value);
+            }
+        }
+        return { sql: parts.join(' and '), params };
+    }
+    inferJsonValueType(value) {
+        if (typeof value === 'number') {
+            return 'number';
+        }
+        if (typeof value === 'boolean') {
+            return 'boolean';
+        }
+        if (typeof value === 'bigint') {
+            return 'bigint';
+        }
+        if (Utils.isPlainObject(value)) {
+            for (const v of Object.values(value)) {
+                if (typeof v === 'number') {
+                    return 'number';
+                }
+                if (typeof v === 'boolean') {
+                    return 'boolean';
+                }
+                if (typeof v === 'bigint') {
+                    return 'bigint';
+                }
+                if (Array.isArray(v) && v.length > 0) {
+                    if (typeof v[0] === 'number') {
+                        return 'number';
+                    }
+                    if (typeof v[0] === 'boolean') {
+                        return 'boolean';
+                    }
+                }
+            }
+        }
+        return 'string';
+    }
     processOnConflictCondition(cond, schema) {
-        const meta = this.metadata.get(this.entityName);
+        const meta = this.#metadata.get(this.#entityName);
         const tableName = meta.tableName;
         for (const key of Object.keys(cond)) {
             const mapped = this.mapper(key, QueryType.UPSERT);