@mikro-orm/sql 7.1.0-dev.13 → 7.1.0-dev.15

package/AbstractSqlDriver.d.ts

@@ -147,6 +147,13 @@ export declare abstract class AbstractSqlDriver<Connection extends AbstractSqlCo
     mapPropToFieldNames<T extends object>(qb: AnyQueryBuilder<T>, prop: EntityProperty<T>, tableAlias: string, meta: EntityMetadata<T>, schema?: string, explicitFields?: readonly InternalField<T>[]): InternalField<T>[];
     /** @internal */
     createQueryBuilder<T extends object>(entityName: EntityName<T> | AnyQueryBuilder<T>, ctx?: Transaction, preferredConnectionType?: ConnectionType, convertCustomTypes?: boolean, loggerContext?: LoggingOptions, alias?: string, em?: SqlEntityManager): AnyQueryBuilder<T>;
+    /**
+     * Renders a `FilterQuery` predicate into a SQL fragment (without the `WHERE` keyword and
+     * without table-alias prefixes) suitable for inlining into a partial-index DDL statement.
+     * Used by `DatabaseTable.addIndex` when the user passes an object `where` on `@Index` /
+     * `@Unique`. Strings are returned unchanged.
+     */
+    renderPartialIndexWhere<T extends object>(entityName: EntityName<T>, where: string | FilterQuery<T>): string;
     protected resolveConnectionType(args: {
         ctx?: Transaction;
         connectionType?: ConnectionType;

package/AbstractSqlDriver.js

@@ -1944,6 +1944,57 @@ export class AbstractSqlDriver extends DatabaseDriver {
         }
         return qb;
     }
+    /**
+     * Renders a `FilterQuery` predicate into a SQL fragment (without the `WHERE` keyword and
+     * without table-alias prefixes) suitable for inlining into a partial-index DDL statement.
+     * Used by `DatabaseTable.addIndex` when the user passes an object `where` on `@Index` /
+     * `@Unique`. Strings are returned unchanged.
+     */
+    renderPartialIndexWhere(entityName, where) {
+        if (typeof where === 'string') {
+            return where;
+        }
+        const name = Utils.className(entityName);
+        if (where == null || (Utils.isPlainObject(where) && Object.keys(where).length === 0)) {
+            throw new Error(`Cannot render partial-index predicate for entity '${name}': \`where\` is empty.`);
+        }
+        const alias = '__p';
+        const qb = this.createQueryBuilder(entityName, undefined, undefined, undefined, undefined, alias);
+        qb.where(where);
+        const sql = qb.getFormattedQuery();
+        // Relation traversal produces join clauses whose aliased identifiers can't be inlined
+        // into a CREATE INDEX ... WHERE clause — reject with a clear error rather than emitting broken DDL.
+        if (/\bjoin\b/i.test(sql.split(/\bwhere\b/i)[0])) {
+            throw new Error(`Cannot render partial-index predicate for entity '${name}': \`where\` may not traverse relations.`);
+        }
+        // Anchor at end-of-string only — the synthetic QB has no top-level order by / limit /
+        // group by / having / offset, so any such keyword inside the captured predicate is
+        // inside a subquery and must not terminate the match.
+        const match = /\bwhere\s+([\s\S]+)$/i.exec(sql);
+        if (!match) {
+            throw new Error(`Failed to render partial-index predicate for entity '${name}': ${sql}`);
+        }
+        const quote = (s) => this.platform.quoteIdentifier(s);
+        const aliasPrefix = new RegExp(`${quote(alias).replace(/[[\]]/g, '\\$&')}\\.`, 'g');
+        const stripped = match[1].replace(aliasPrefix, '').trim();
+        // Any qualified column reference remaining after the alias strip points at another table or
+        // subquery and can't be inlined into a CREATE INDEX ... WHERE predicate. Covers both
+        // QB-generated sub-aliases (quoted, e.g. `"e0"."col"`) and raw fragments with bare refs
+        // (e.g. `raw('other_table.col = 1')`). String literals are erased first so dots inside
+        // them (e.g. JSON path operands like `'$.path'`) don't trip the guard.
+        // Both patterns use a `(?!\s*\()` lookahead so schema-qualified function calls
+        // (`pg_catalog.lower(name)`, `"public".my_func(col)`) are accepted — only `<id>.<id>` not
+        // followed by `(` is treated as a cross-table column reference.
+        const withoutStrings = stripped.replace(/'(?:[^']|'')*'/g, "''");
+        const quotedIdent = String.raw `(?:"(?:[^"]|"")+"|\`(?:[^\`]|\`\`)+\`|\[(?:[^\]]|\]\])+\])`;
+        const anyIdent = `(?:${quotedIdent}|[A-Za-z_]\\w*)`;
+        const quotedCrossRef = new RegExp(`${quotedIdent}\\s*\\.\\s*${anyIdent}(?!\\s*\\()`);
+        const bareCrossRef = /\b[A-Za-z_]\w*\s*\.\s*[A-Za-z_]\w*\b(?!\s*\()/;
+        if (quotedCrossRef.test(withoutStrings) || bareCrossRef.test(withoutStrings)) {
+            throw new Error(`Cannot render partial-index predicate for entity '${name}': \`where\` references another table or subquery which cannot be inlined into a CREATE INDEX ... WHERE clause.`);
+        }
+        return stripped;
+    }
     resolveConnectionType(args) {
         if (args.ctx) {
             return 'write';

package/dialects/mysql/MySqlSchemaHelper.d.ts

@@ -11,6 +11,7 @@ export declare class MySqlSchemaHelper extends SchemaHelper {
         'current_timestamp(?)': string[];
         '0': string[];
     };
+    private static readonly PARTIAL_INDEX_RE;
     getSchemaBeginning(charset: string, disableForeignKeys?: boolean): string;
     disableForeignKeysSQL(): string;
     enableForeignKeysSQL(): string;
@@ -22,8 +23,10 @@ export declare class MySqlSchemaHelper extends SchemaHelper {
     getAllIndexes(connection: AbstractSqlConnection, tables: Table[], ctx?: Transaction): Promise<Dictionary<IndexDef[]>>;
     getCreateIndexSQL(tableName: string, index: IndexDef, partialExpression?: boolean): string;
     /**
-     * Build the column list for a MySQL index, with MySQL-specific handling for collation.
-     * MySQL requires collation to be specified as an expression: (column_name COLLATE collation_name)
+     * Build the column list for a MySQL index. MySQL requires collation via an expression:
+     * `(column COLLATE collation_name)`. Partial indexes (`where`) are emulated via functional
+     * indexes — requires MySQL 8.0.13+. MariaDB does not support inline functional indexes
+     * and overrides to throw at a higher level.
      */
     protected getIndexColumns(index: IndexDef): string;
     /**

package/dialects/mysql/MySqlSchemaHelper.js

@@ -7,6 +7,10 @@ export class MySqlSchemaHelper extends SchemaHelper {
         'current_timestamp(?)': ['current_timestamp(?)'],
         '0': ['0', 'false'],
     };
+    // Greedy `(.+)` so nested CASE expressions inside the predicate don't trip the match on
+    // an inner `then <col> end` — the trailing `$` anchor forces the regex engine to extend
+    // the capture to the outermost case-end boundary.
+    static PARTIAL_INDEX_RE = /^\s*\(\s*case\s+when\s+(.+)\s+then\s+`([^`]+)`\s+end\s*\)\s*$/is;
     getSchemaBeginning(charset, disableForeignKeys) {
         if (disableForeignKeys) {
             return `set names ${charset};\n${this.disableForeignKeysSQL()}\n\n`;
@@ -84,8 +88,11 @@ export class MySqlSchemaHelper extends SchemaHelper {
         const ret = {};
         for (const index of allIndexes) {
             const key = this.getTableKey(index);
+            const partialMatch = !index.column_name && typeof index.expression === 'string'
+                ? MySqlSchemaHelper.PARTIAL_INDEX_RE.exec(index.expression)
+                : null;
             const indexDef = {
-                columnNames: [index.column_name],
+                columnNames: [partialMatch ? partialMatch[2] : index.column_name],
                 keyName: index.index_name,
                 unique: !index.non_unique,
                 primary: index.index_name === 'PRIMARY',
@@ -113,7 +120,10 @@ export class MySqlSchemaHelper extends SchemaHelper {
             if (index.is_visible === 'NO') {
                 indexDef.invisible = true;
             }
-            if (!index.column_name || index.expression?.match(/ where /i)) {
+            if (partialMatch) {
+                indexDef.where = partialMatch[1].trim();
+            }
+            else if (!index.column_name || index.expression?.match(/ where /i)) {
                 indexDef.expression = index.expression; // required for the `getCreateIndexSQL()` call
                 indexDef.expression = this.getCreateIndexSQL(index.table_name, indexDef, !!index.expression);
             }
@@ -150,10 +160,15 @@ export class MySqlSchemaHelper extends SchemaHelper {
         return this.appendMySqlIndexSuffix(sql, index);
     }
     /**
-     * Build the column list for a MySQL index, with MySQL-specific handling for collation.
-     * MySQL requires collation to be specified as an expression: (column_name COLLATE collation_name)
+     * Build the column list for a MySQL index. MySQL requires collation via an expression:
+     * `(column COLLATE collation_name)`. Partial indexes (`where`) are emulated via functional
+     * indexes — requires MySQL 8.0.13+. MariaDB does not support inline functional indexes
+     * and overrides to throw at a higher level.
      */
     getIndexColumns(index) {
+        if (index.where) {
+            return this.emulatePartialIndexColumns(index);
+        }
         if (index.columns?.length) {
             return index.columns
                 .map(col => {

package/dialects/postgresql/PostgreSqlSchemaHelper.d.ts

@@ -14,6 +14,8 @@ export declare class PostgreSqlSchemaHelper extends SchemaHelper {
         'null::timestamp with time zone': string[];
         'null::timestamp without time zone': string[];
     };
+    private static readonly PARTIAL_WHERE_RE;
+    private static readonly FUNCTIONAL_COL_RE;
     getSchemaBeginning(charset: string, disableForeignKeys?: boolean): string;
     getCreateDatabaseSQL(name: string): string;
     getListTablesSQL(): string;

package/dialects/postgresql/PostgreSqlSchemaHelper.js

@@ -12,6 +12,8 @@ export class PostgreSqlSchemaHelper extends SchemaHelper {
         'null::timestamp with time zone': ['null'],
         'null::timestamp without time zone': ['null'],
     };
+    static PARTIAL_WHERE_RE = /\swhere\s+(.+)$/is;
+    static FUNCTIONAL_COL_RE = /[(): ,"'`]/;
     getSchemaBeginning(charset, disableForeignKeys) {
         if (disableForeignKeys) {
             return `set names '${charset}';\n${this.disableForeignKeysSQL()}\n\n`;
@@ -165,9 +167,22 @@ export class PostgreSqlSchemaHelper extends SchemaHelper {
             if (index.condeferrable) {
                 indexDef.deferMode = index.condeferred ? DeferMode.INITIALLY_DEFERRED : DeferMode.INITIALLY_IMMEDIATE;
             }
-            if (index.index_def.some((col) => /[(): ,"'`]/.exec(col)) || index.expression?.match(/ where /i)) {
+            const hasFunctionalColumns = index.index_def.some((col) => PostgreSqlSchemaHelper.FUNCTIONAL_COL_RE.exec(col));
+            const whereMatch = hasFunctionalColumns
+                ? null
+                : PostgreSqlSchemaHelper.PARTIAL_WHERE_RE.exec(index.expression ?? '');
+            if (hasFunctionalColumns) {
+                // Functional-column expression can't be diffed structurally — keep the whole CREATE
+                // statement (WHERE included) on `expression`; don't try to split the predicate.
                 indexDef.expression = index.expression;
             }
+            else if (whereMatch) {
+                let where = whereMatch[1].trim();
+                if (where.startsWith('(') && where.endsWith(')') && this.isBalancedWrap(where)) {
+                    where = where.slice(1, -1).trim();
+                }
+                indexDef.where = where;
+            }
             if (index.deferrable) {
                 indexDef.deferMode = index.initially_deferred ? DeferMode.INITIALLY_DEFERRED : DeferMode.INITIALLY_IMMEDIATE;
             }

package/dialects/sqlite/SqliteSchemaHelper.d.ts

@@ -5,6 +5,7 @@ import type { Column, IndexDef, Table, TableDifference, SqlTriggerDef } from '..
 import type { DatabaseTable } from '../../schema/DatabaseTable.js';
 import type { DatabaseSchema } from '../../schema/DatabaseSchema.js';
 export declare class SqliteSchemaHelper extends SchemaHelper {
+    private static readonly PARTIAL_WHERE_RE;
     disableForeignKeysSQL(): string;
     enableForeignKeysSQL(): string;
     supportsSchemaConstraints(): boolean;

package/dialects/sqlite/SqliteSchemaHelper.js

@@ -15,6 +15,7 @@ const SPATIALITE_VIEWS = [
     'ElementaryGeometries',
 ];
 export class SqliteSchemaHelper extends SchemaHelper {
+    static PARTIAL_WHERE_RE = /\swhere\s+(.+?)\s*$/is;
     disableForeignKeysSQL() {
         return 'pragma foreign_keys = off;';
     }
@@ -216,10 +217,10 @@ export class SqliteSchemaHelper extends SchemaHelper {
         if (index.columnNames.some(column => column.includes('.'))) {
             // JSON columns can have unique index but not unique constraint, and we need to distinguish those, so we can properly drop them
             const columns = this.platform.getJsonIndexDefinition(index);
-            return `${sqlPrefix} (${columns.join(', ')})`;
+            return `${sqlPrefix} (${columns.join(', ')})${this.getIndexWhereClause(index)}`;
         }
         // Use getIndexColumns to support advanced options like sort order and collation
-        return `${sqlPrefix} (${this.getIndexColumns(index)})`;
+        return `${sqlPrefix} (${this.getIndexColumns(index)})${this.getIndexWhereClause(index)}`;
     }
     parseTableDefinition(sql, cols) {
         const columns = {};
@@ -355,6 +356,16 @@ export class SqliteSchemaHelper extends SchemaHelper {
         const sql = `pragma ${prefix}table_info(\`${tableName}\`)`;
         const cols = await connection.execute(sql, [], 'all', ctx);
         const indexes = await connection.execute(`pragma ${prefix}index_list(\`${tableName}\`)`, [], 'all', ctx);
+        // sqlite_master.sql holds the original CREATE INDEX statement — the only place a partial
+        // index's WHERE predicate is preserved (PRAGMA index_* don't expose it).
+        const indexSqls = await connection.execute(`select name, sql from ${prefix}sqlite_master where type = 'index' and tbl_name = ?`, [tableName], 'all', ctx);
+        const wherePredicates = new Map();
+        for (const row of indexSqls) {
+            const match = row.sql && SqliteSchemaHelper.PARTIAL_WHERE_RE.exec(row.sql);
+            if (match) {
+                wherePredicates.set(row.name, match[1].trim());
+            }
+        }
         const ret = [];
         for (const col of cols.filter(c => c.pk)) {
             ret.push({
@@ -367,12 +378,14 @@ export class SqliteSchemaHelper extends SchemaHelper {
         }
         for (const index of indexes.filter(index => !this.isImplicitIndex(index.name))) {
             const res = await connection.execute(`pragma ${prefix}index_info(\`${index.name}\`)`, [], 'all', ctx);
+            const where = wherePredicates.get(index.name);
             ret.push(...res.map(row => ({
                 columnNames: [row.name],
                 keyName: index.name,
                 unique: !!index.unique,
                 constraint: !!index.unique,
                 primary: false,
+                ...(where ? { where } : {}),
             })));
         }
         return this.mapIndexes(ret);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikro-orm/sql",
-  "version": "7.1.0-dev.13",
+  "version": "7.1.0-dev.15",
   "description": "TypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. Supports MongoDB, MySQL, PostgreSQL and SQLite databases as well as usage with vanilla JavaScript.",
   "keywords": [
     "data-mapper",
@@ -53,7 +53,7 @@
     "@mikro-orm/core": "^7.0.11"
   },
   "peerDependencies": {
-    "@mikro-orm/core": "7.1.0-dev.13"
+    "@mikro-orm/core": "7.1.0-dev.15"
   },
   "engines": {
     "node": ">= 22.17.0"

package/query/CriteriaNode.d.ts

@@ -21,7 +21,7 @@ export declare class CriteriaNode<T extends object> implements ICriteriaNode<T>
     shouldInline(payload: any): boolean;
     willAutoJoin(qb: IQueryBuilder<T>, alias?: string, options?: ICriteriaNodeProcessOptions): boolean;
     shouldRename(payload: any): boolean;
-    renameFieldToPK<T>(qb: IQueryBuilder<T>, ownerAlias?: string): string;
+    renameFieldToPK<T>(qb: IQueryBuilder<T>, ownerAlias?: string, options?: ICriteriaNodeProcessOptions): string;
     getPath(opts?: {
         addIndex?: boolean;
         parentPath?: string;

package/query/CriteriaNode.js

@@ -83,8 +83,8 @@ export class CriteriaNode {
                 return false;
         }
     }
-    renameFieldToPK(qb, ownerAlias) {
-        const joinAlias = qb.getAliasForJoinPath(this.getPath(), { matchPopulateJoins: true });
+    renameFieldToPK(qb, ownerAlias, options) {
+        const joinAlias = qb.getAliasForJoinPath(this.getPath(), { ...options, matchPopulateJoins: true });
         if (!joinAlias &&
             this.parent &&
             [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(this.prop.kind) &&

package/query/ObjectCriteriaNode.js

@@ -105,7 +105,7 @@ export class ObjectCriteriaNode extends CriteriaNode {
                 this.inlineChildPayload(o, payload, field, a, childAlias);
             }
             else if (childNode.shouldRename(payload)) {
-                this.inlineCondition(childNode.renameFieldToPK(qb, alias), o, payload);
+                this.inlineCondition(childNode.renameFieldToPK(qb, alias, options), o, payload);
             }
             else if (isRawField) {
                 const rawField = RawQueryFragment.getKnownFragment(field);

package/schema/DatabaseTable.d.ts

@@ -67,6 +67,7 @@ export declare class DatabaseTable {
         name?: string;
         type?: string;
         expression?: string | IndexCallback<any>;
+        where?: string | Dictionary;
         deferMode?: DeferMode | `${DeferMode}`;
         options?: Dictionary;
         columns?: {
@@ -82,6 +83,7 @@ export declare class DatabaseTable {
         disabled?: boolean;
         clustered?: boolean;
     }, type: 'index' | 'unique' | 'primary'): void;
+    private processIndexWhere;
     addCheck(check: CheckDef): void;
     addTrigger(trigger: SqlTriggerDef): void;
     toJSON(): Dictionary;

package/schema/DatabaseTable.js

@@ -204,6 +204,7 @@ export class DatabaseTable {
                 name: index.keyName,
                 deferMode: index.deferMode,
                 expression: index.expression,
+                where: index.where,
                 // Advanced index options - convert column names to property names
                 columns: index.columns?.map(col => ({
                     ...col,
@@ -234,7 +235,7 @@ export class DatabaseTable {
                 index.invisible ||
                 index.disabled ||
                 index.clustered;
-            const isTrivial = !index.deferMode && !index.expression && !hasAdvancedOptions;
+            const isTrivial = !index.deferMode && !index.expression && !index.where && !hasAdvancedOptions;
             if (isTrivial) {
                 // Index is for FK. Map to the FK prop and move on.
                 const fkForIndex = fkIndexes.get(index);
@@ -876,16 +877,25 @@ export class DatabaseTable {
         if (index.fillFactor != null && (index.fillFactor < 0 || index.fillFactor > 100)) {
             throw new Error(`fillFactor must be between 0 and 100, got ${index.fillFactor} for index '${name}' on entity '${meta.className}'`);
         }
+        // The `expression` escape hatch takes the full index definition as raw SQL; combining it
+        // with `where` is dialect-dependent (PG/Oracle/MySQL drop `where`, MSSQL appends it) so we
+        // reject the combination up-front and ask users to inline the predicate into `expression`.
+        if (index.expression && index.where != null) {
+            throw new Error(`Index '${name}' on entity '${meta.className}': cannot combine \`expression\` with \`where\` — inline the WHERE clause into the \`expression\` escape hatch, or drop \`expression\` and use structured \`properties\` + \`where\`.`);
+        }
+        const where = this.processIndexWhere(index.where, meta);
         this.#indexes.push({
             keyName: name,
             columnNames: properties,
             composite: properties.length > 1,
-            // JSON columns can have unique index but not unique constraint, and we need to distinguish those, so we can properly drop them
-            constraint: type !== 'index' && !properties.some((d) => d.includes('.')),
+            // JSON columns can have unique index but not unique constraint, and we need to distinguish those, so we can properly drop them.
+            // Partial indexes (`where`) must use CREATE [UNIQUE] INDEX form — constraints can't carry predicates.
+            constraint: type !== 'index' && !properties.some((d) => d.includes('.')) && !where,
             primary: type === 'primary',
             unique: type !== 'index',
             type: index.type,
             expression: this.processIndexExpression(name, index.expression, meta),
+            where,
             options: index.options,
             deferMode: index.deferMode,
             columns,
@@ -896,6 +906,15 @@ export class DatabaseTable {
             clustered: index.clustered,
         });
     }
+    processIndexWhere(where, meta) {
+        if (where == null) {
+            return undefined;
+        }
+        // The driver is always an `AbstractSqlDriver` here — `DatabaseTable` is only instantiated
+        // by SQL-side schema code, so the platform's config-bound driver is guaranteed to be one.
+        const driver = this.#platform.getConfig().getDriver();
+        return driver.renderPartialIndexWhere(meta.class, where);
+    }
     addCheck(check) {
         this.#checks.push(check);
     }

package/schema/SchemaComparator.js

@@ -266,6 +266,19 @@ export class SchemaComparator {
             if (!this.diffIndex(index, toTableIndex)) {
                 continue;
             }
+            // Constraint-vs-index form mismatch needs drop+create with the OLD form's drop SQL,
+            // which `changedIndexes` (uses new form only) can't do. Primary keys stay on the
+            // changed path which emits `add primary key`.
+            if (!index.primary && !!index.constraint !== !!toTableIndex.constraint) {
+                tableDifferences.removedIndexes[index.keyName] = index;
+                tableDifferences.addedIndexes[index.keyName] = toTableIndex;
+                this.log(`index ${index.keyName} changed form in table ${tableDifferences.name}`, {
+                    fromTableIndex: index,
+                    toTableIndex,
+                });
+                changes += 2;
+                continue;
+            }
             tableDifferences.changedIndexes[index.keyName] = toTableIndex;
             this.log(`index ${index.keyName} changed in table ${tableDifferences.name}`, {
                 fromTableIndex: index,
@@ -572,7 +585,8 @@ export class SchemaComparator {
      * Compares index1 with index2 and returns index2 if there are any differences or false in case there are no differences.
      */
     diffIndex(index1, index2) {
-        // if one of them is a custom expression or full text index, compare only by name
+        // Opaque raw expressions (`expression` escape hatch) and full-text indexes can't be
+        // compared structurally — fall back to name-only matching.
         if (index1.expression || index2.expression || index1.type === 'fulltext' || index2.type === 'fulltext') {
             return index1.keyName !== index2.keyName;
         }
@@ -623,6 +637,11 @@ export class SchemaComparator {
         if (!!index1.clustered !== !!index2.clustered) {
             return false;
         }
+        // Compare WHERE predicate of partial indexes structurally (whitespace/quoting/casing
+        // are normalized via the same helper used for check constraints).
+        if (this.diffExpression(index1.where ?? '', index2.where ?? '')) {
+            return false;
+        }
         if (!index1.unique && !index1.primary) {
             // this is a special case: If the current key is neither primary or unique, any unique or
             // primary key will always have the same effect for the index and there cannot be any constraint

package/schema/SchemaHelper.d.ts

@@ -41,6 +41,46 @@ export declare abstract class SchemaHelper {
      * Hook for adding driver-specific index options (e.g., fill factor for PostgreSQL).
      */
     protected getCreateIndexSuffix(_index: IndexDef): string;
+    /**
+     * Default emits ` where <predicate>` for partial indexes. Only Oracle overrides this to
+     * return `''` (it emulates partials via CASE-WHEN columns). MySQL sidesteps the whole path
+     * with its own `getCreateIndexSQL` that never calls this, and MariaDB refuses the feature
+     * entirely via an override on `getIndexColumns`.
+     */
+    protected getIndexWhereClause(index: IndexDef): string;
+    /**
+     * Wraps each indexed column in `(CASE WHEN <predicate> THEN <col> END)` for dialects that
+     * emulate partial indexes via functional indexes (MySQL/MariaDB/Oracle). Combined with NULL
+     * being treated as distinct in unique indexes, this enforces uniqueness only where the
+     * predicate holds. Throws if combined with the advanced `columns` option.
+     */
+    protected emulatePartialIndexColumns(index: IndexDef): string;
+    /**
+     * Strips `<col> IS NOT NULL` clauses (with the dialect's identifier quoting) from an
+     * introspected partial-index predicate when the column matches one of the index's own
+     * columns. MikroORM auto-emits this guard for unique indexes on nullable columns
+     * (MSSQL, Oracle) — it's an internal artifact, not user intent.
+     *
+     * Strips at most one guard per column (the tail-most occurrence), matching how MikroORM
+     * appends a single guard per index column. This preserves user intent when they redundantly
+     * include the same `<col> IS NOT NULL` in their predicate — the guard we added is removed,
+     * their copy survives.
+     */
+    protected stripAutoNotNullFilter(filterDef: string, columnNames: string[], identifierPattern: RegExp): string;
+    /**
+     * Whether `[…]` is a quoted identifier (MSSQL convention). Other dialects either reuse
+     * `[` for array literals/constructors or never produce it in introspected predicates,
+     * so the default is `false` and the MSSQL helper opts in.
+     */
+    protected get bracketQuotedIdentifiers(): boolean;
+    /**
+     * Splits on top-level ` AND ` (case-insensitive), ignoring matches that sit inside string
+     * literals, quoted identifiers, or parenthesized groups — so a predicate like
+     * `'foo AND bar' = col` or `(a AND b) OR c` is not mis-split.
+     */
+    protected splitTopLevelAnd(s: string): string[];
+    /** Returns true iff the leading `(` matches the trailing `)` (i.e. they wrap the whole string). */
+    protected isBalancedWrap(s: string): boolean;
     /**
      * Build the column list for an index, supporting advanced options like sort order, nulls ordering, and collation.
      * Note: Prefix length is only supported by MySQL/MariaDB which override this method.

package/schema/SchemaHelper.js

@@ -110,7 +110,7 @@ export class SchemaHelper {
             // JSON columns can have unique index but not unique constraint, and we need to distinguish those, so we can properly drop them
             sql = `create ${index.unique ? 'unique ' : ''}index ${keyName} on ${tableName}`;
             const columns = this.platform.getJsonIndexDefinition(index);
-            return `${sql} (${columns.join(', ')})${this.getCreateIndexSuffix(index)}${defer}`;
+            return `${sql} (${columns.join(', ')})${this.getCreateIndexSuffix(index)}${this.getIndexWhereClause(index)}${defer}`;
         }
         // Build column list with advanced options
         const columns = this.getIndexColumns(index);
@@ -119,7 +119,7 @@ export class SchemaHelper {
         if (index.include?.length) {
             sql += ` include (${index.include.map(c => this.quote(c)).join(', ')})`;
         }
-        return sql + this.getCreateIndexSuffix(index) + defer;
+        return sql + this.getCreateIndexSuffix(index) + this.getIndexWhereClause(index) + defer;
     }
     /**
      * Hook for adding driver-specific index options (e.g., fill factor for PostgreSQL).
@@ -127,6 +127,153 @@ export class SchemaHelper {
     getCreateIndexSuffix(_index) {
         return '';
     }
+    /**
+     * Default emits ` where <predicate>` for partial indexes. Only Oracle overrides this to
+     * return `''` (it emulates partials via CASE-WHEN columns). MySQL sidesteps the whole path
+     * with its own `getCreateIndexSQL` that never calls this, and MariaDB refuses the feature
+     * entirely via an override on `getIndexColumns`.
+     */
+    getIndexWhereClause(index) {
+        return index.where ? ` where ${index.where}` : '';
+    }
+    /**
+     * Wraps each indexed column in `(CASE WHEN <predicate> THEN <col> END)` for dialects that
+     * emulate partial indexes via functional indexes (MySQL/MariaDB/Oracle). Combined with NULL
+     * being treated as distinct in unique indexes, this enforces uniqueness only where the
+     * predicate holds. Throws if combined with the advanced `columns` option.
+     */
+    emulatePartialIndexColumns(index) {
+        if (index.columns?.length) {
+            throw new Error(`Index '${index.keyName}': combining \`where\` with advanced \`columns\` options is not supported when emulating a partial index via functional expressions; use plain \`properties\` (or \`columnNames\`).`);
+        }
+        const predicate = index.where;
+        return index.columnNames.map(c => `(case when ${predicate} then ${this.quote(c)} end)`).join(', ');
+    }
+    /**
+     * Strips `<col> IS NOT NULL` clauses (with the dialect's identifier quoting) from an
+     * introspected partial-index predicate when the column matches one of the index's own
+     * columns. MikroORM auto-emits this guard for unique indexes on nullable columns
+     * (MSSQL, Oracle) — it's an internal artifact, not user intent.
+     *
+     * Strips at most one guard per column (the tail-most occurrence), matching how MikroORM
+     * appends a single guard per index column. This preserves user intent when they redundantly
+     * include the same `<col> IS NOT NULL` in their predicate — the guard we added is removed,
+     * their copy survives.
+     */
+    stripAutoNotNullFilter(filterDef, columnNames, identifierPattern) {
+        // Peel off any number of balanced wrapping paren layers. Introspection sources differ
+        // (MSSQL `filter_definition` wraps once, Oracle `INDEX_EXPRESSIONS` typically not at all),
+        // and a user `where` round-tripped through a dialect that double-wraps would otherwise slip
+        // past the auto-NOT-NULL recognizer below.
+        let inner = filterDef.trim();
+        while (inner.startsWith('(') && inner.endsWith(')') && this.isBalancedWrap(inner)) {
+            inner = inner.slice(1, -1).trim();
+        }
+        const clauses = this.splitTopLevelAnd(inner);
+        const autoCol = (clause) => {
+            let trimmed = clause.trim();
+            while (trimmed.startsWith('(') && trimmed.endsWith(')') && this.isBalancedWrap(trimmed)) {
+                trimmed = trimmed.slice(1, -1).trim();
+            }
+            const match = identifierPattern.exec(trimmed);
+            return match && columnNames.includes(match[1]) ? match[1] : null;
+        };
+        const seen = new Set();
+        const kept = [];
+        for (let i = clauses.length - 1; i >= 0; i--) {
+            const col = autoCol(clauses[i]);
+            if (col && !seen.has(col)) {
+                seen.add(col);
+                continue;
+            }
+            kept.unshift(clauses[i]);
+        }
+        return kept.join(' and ').trim();
+    }
+    /**
+     * Whether `[…]` is a quoted identifier (MSSQL convention). Other dialects either reuse
+     * `[` for array literals/constructors or never produce it in introspected predicates,
+     * so the default is `false` and the MSSQL helper opts in.
+     */
+    get bracketQuotedIdentifiers() {
+        return false;
+    }
+    /**
+     * Splits on top-level ` AND ` (case-insensitive), ignoring matches that sit inside string
+     * literals, quoted identifiers, or parenthesized groups — so a predicate like
+     * `'foo AND bar' = col` or `(a AND b) OR c` is not mis-split.
+     */
+    splitTopLevelAnd(s) {
+        const parts = [];
+        let depth = 0;
+        let quote = null;
+        let start = 0;
+        let i = 0;
+        while (i < s.length) {
+            const c = s[i];
+            if (quote) {
+                // Handle SQL's doubled-delimiter escape inside quoted strings/identifiers:
+                // `'` → `''`, `"` → `""`, `` ` `` → ```` `` ````, MSSQL `]` → `]]`.
+                if (c === quote && s[i + 1] === quote) {
+                    i += 2;
+                    continue;
+                }
+                if (c === quote) {
+                    quote = null;
+                }
+                i++;
+                continue;
+            }
+            if (c === "'" || c === '"' || c === '`') {
+                quote = c;
+                i++;
+                continue;
+            }
+            if (c === '[' && this.bracketQuotedIdentifiers) {
+                quote = ']';
+                i++;
+                continue;
+            }
+            if (c === '(') {
+                depth++;
+                i++;
+                continue;
+            }
+            if (c === ')') {
+                depth--;
+                i++;
+                continue;
+            }
+            if (depth === 0 && /\s/.test(c)) {
+                const m = /^\s+and\s+/i.exec(s.slice(i));
+                if (m) {
+                    parts.push(s.slice(start, i).trim());
+                    i += m[0].length;
+                    start = i;
+                    continue;
+                }
+            }
+            i++;
+        }
+        parts.push(s.slice(start).trim());
+        return parts.filter(p => p.length > 0);
+    }
+    /** Returns true iff the leading `(` matches the trailing `)` (i.e. they wrap the whole string). */
+    isBalancedWrap(s) {
+        let depth = 0;
+        for (let i = 0; i < s.length; i++) {
+            if (s[i] === '(') {
+                depth++;
+            }
+            else if (s[i] === ')') {
+                depth--;
+                if (depth === 0 && i < s.length - 1) {
+                    return false;
+                }
+            }
+        }
+        return depth === 0;
+    }
     /**
      * Build the column list for an index, supporting advanced options like sort order, nulls ordering, and collation.
      * Note: Prefix length is only supported by MySQL/MariaDB which override this method.

package/typings.d.ts

@@ -71,6 +71,11 @@ export interface IndexDef {
     primary: boolean;
     composite?: boolean;
     expression?: string;
+    /**
+     * WHERE predicate for partial indexes, normalized to a SQL fragment after metadata
+     * resolution and introspection. Mutually exclusive with `expression`.
+     */
+    where?: string;
     options?: Dictionary;
     type?: string | Readonly<{
         indexType?: string;
@@ -246,7 +251,7 @@ export interface ICriteriaNode<T extends object> {
     shouldInline(payload: any): boolean;
     willAutoJoin(qb: IQueryBuilder<T>, alias?: string, options?: ICriteriaNodeProcessOptions): boolean;
     shouldRename(payload: any): boolean;
-    renameFieldToPK<T>(qb: IQueryBuilder<T>, ownerAlias?: string): string;
+    renameFieldToPK<T>(qb: IQueryBuilder<T>, ownerAlias?: string, options?: ICriteriaNodeProcessOptions): string;
     getPath(opts?: {
         addIndex?: boolean;
     }): string;