metal-orm 1.0.12 → 1.0.14

package/src/core/dialect/abstract.ts

@@ -1,4 +1,11 @@
-import { SelectQueryNode, InsertQueryNode, UpdateQueryNode, DeleteQueryNode } from '../ast/query.js';
+import {
+  SelectQueryNode,
+  InsertQueryNode,
+  UpdateQueryNode,
+  DeleteQueryNode,
+  SetOperationKind,
+  CommonTableExpressionNode
+} from '../ast/query.js';
 import {
   ExpressionNode,
   BinaryExpressionNode,
@@ -56,22 +63,23 @@ export interface DeleteCompiler {
 /**
  * Abstract base class for SQL dialect implementations
  */
-export abstract class Dialect
-  implements SelectCompiler, InsertCompiler, UpdateCompiler, DeleteCompiler
-{
+export abstract class Dialect
+  implements SelectCompiler, InsertCompiler, UpdateCompiler, DeleteCompiler
+{
   /**
    * Compiles a SELECT query AST to SQL
    * @param ast - Query AST to compile
    * @returns Compiled query with SQL and parameters
    */
-  compileSelect(ast: SelectQueryNode): CompiledQuery {
-    const ctx = this.createCompilerContext();
-    const rawSql = this.compileSelectAst(ast, ctx).trim();
-    const sql = rawSql.endsWith(';') ? rawSql : `${rawSql};`;
-    return {
-      sql,
-      params: [...ctx.params]
-    };
+  compileSelect(ast: SelectQueryNode): CompiledQuery {
+    const ctx = this.createCompilerContext();
+    const normalized = this.normalizeSelectAst(ast);
+    const rawSql = this.compileSelectAst(normalized, ctx).trim();
+    const sql = rawSql.endsWith(';') ? rawSql : `${rawSql};`;
+    return {
+      sql,
+      params: [...ctx.params]
+    };
   }
 
   compileInsert(ast: InsertQueryNode): CompiledQuery {
@@ -94,15 +102,19 @@ export abstract class Dialect
     };
   }
 
-  compileDelete(ast: DeleteQueryNode): CompiledQuery {
-    const ctx = this.createCompilerContext();
-    const rawSql = this.compileDeleteAst(ast, ctx).trim();
+  compileDelete(ast: DeleteQueryNode): CompiledQuery {
+    const ctx = this.createCompilerContext();
+    const rawSql = this.compileDeleteAst(ast, ctx).trim();
     const sql = rawSql.endsWith(';') ? rawSql : `${rawSql};`;
     return {
       sql,
       params: [...ctx.params]
-    };
-  }
+    };
+  }
+
+  supportsReturning(): boolean {
+    return false;
+  }
 
   /**
    * Compiles SELECT query AST to SQL (to be implemented by concrete dialects)
@@ -110,7 +122,7 @@ export abstract class Dialect
    * @param ctx - Compiler context
    * @returns SQL string
    */
-  protected abstract compileSelectAst(ast: SelectQueryNode, ctx: CompilerContext): string;
+  protected abstract compileSelectAst(ast: SelectQueryNode, ctx: CompilerContext): string;
 
   protected abstract compileInsertAst(ast: InsertQueryNode, ctx: CompilerContext): string;
   protected abstract compileUpdateAst(ast: UpdateQueryNode, ctx: CompilerContext): string;
@@ -149,16 +161,23 @@ export abstract class Dialect
    * Does not add ';' at the end
    * @param ast - Query AST
    * @param ctx - Compiler context
-   * @returns SQL for EXISTS subquery
-   */
-  protected compileSelectForExists(ast: SelectQueryNode, ctx: CompilerContext): string {
-    const full = this.compileSelectAst(ast, ctx).trim().replace(/;$/, '');
-    const upper = full.toUpperCase();
-    const fromIndex = upper.indexOf(' FROM ');
-    if (fromIndex === -1) {
-      return full;
-    }
-
+   * @returns SQL for EXISTS subquery
+   */
+  protected compileSelectForExists(ast: SelectQueryNode, ctx: CompilerContext): string {
+    const normalized = this.normalizeSelectAst(ast);
+    const full = this.compileSelectAst(normalized, ctx).trim().replace(/;$/, '');
+
+    // When the subquery is a set operation, wrap it as a derived table to keep valid syntax.
+    if (normalized.setOps && normalized.setOps.length > 0) {
+      return `SELECT 1 FROM (${full}) AS _exists`;
+    }
+
+    const upper = full.toUpperCase();
+    const fromIndex = upper.indexOf(' FROM ');
+    if (fromIndex === -1) {
+      return full;
+    }
+
     const tail = full.slice(fromIndex);
     return `SELECT 1${tail}`;
   }
@@ -185,15 +204,81 @@ export abstract class Dialect
    * @param index - Parameter index
    * @returns Formatted placeholder string
    */
-  protected formatPlaceholder(index: number): string {
-    return '?';
-  }
-
-  private readonly expressionCompilers: Map<string, (node: ExpressionNode, ctx: CompilerContext) => string>;
-  private readonly operandCompilers: Map<string, (node: OperandNode, ctx: CompilerContext) => string>;
-
-  protected constructor() {
-    this.expressionCompilers = new Map();
+  protected formatPlaceholder(index: number): string {
+    return '?';
+  }
+
+  /**
+   * Whether the current dialect supports a given set operation.
+   * Override in concrete dialects to restrict support.
+   */
+  protected supportsSetOperation(kind: SetOperationKind): boolean {
+    return true;
+  }
+
+  /**
+   * Validates set-operation semantics:
+   * - Ensures the dialect supports requested operators.
+   * - Enforces that only the outermost compound query may have ORDER/LIMIT/OFFSET.
+   * @param ast - Query to validate
+   * @param isOutermost - Whether this node is the outermost compound query
+   */
+  protected validateSetOperations(ast: SelectQueryNode, isOutermost = true): void {
+    const hasSetOps = !!(ast.setOps && ast.setOps.length);
+    if (!isOutermost && (ast.orderBy || ast.limit !== undefined || ast.offset !== undefined)) {
+      throw new Error('ORDER BY / LIMIT / OFFSET are only allowed on the outermost compound query.');
+    }
+
+    if (hasSetOps) {
+      for (const op of ast.setOps!) {
+        if (!this.supportsSetOperation(op.operator)) {
+          throw new Error(`Set operation ${op.operator} is not supported by this dialect.`);
+        }
+        this.validateSetOperations(op.query, false);
+      }
+    }
+  }
+
+  /**
+   * Hoists CTEs from set-operation operands to the outermost query so WITH appears once.
+   * @param ast - Query AST
+   * @returns Normalized AST without inner CTEs and a list of hoisted CTEs
+   */
+  private hoistCtes(ast: SelectQueryNode): { normalized: SelectQueryNode; hoistedCtes: CommonTableExpressionNode[] } {
+    let hoisted: CommonTableExpressionNode[] = [];
+
+    const normalizedSetOps = ast.setOps?.map(op => {
+      const { normalized: child, hoistedCtes: childHoisted } = this.hoistCtes(op.query);
+      const childCtes = child.ctes ?? [];
+      if (childCtes.length) {
+        hoisted = hoisted.concat(childCtes);
+      }
+      hoisted = hoisted.concat(childHoisted);
+      const queryWithoutCtes = childCtes.length ? { ...child, ctes: undefined } : child;
+      return { ...op, query: queryWithoutCtes };
+    });
+
+    const normalized: SelectQueryNode = normalizedSetOps ? { ...ast, setOps: normalizedSetOps } : ast;
+    return { normalized, hoistedCtes: hoisted };
+  }
+
+  /**
+   * Normalizes a SELECT AST before compilation (validation + CTE hoisting).
+   * @param ast - Query AST
+   * @returns Normalized query AST
+   */
+  protected normalizeSelectAst(ast: SelectQueryNode): SelectQueryNode {
+    this.validateSetOperations(ast, true);
+    const { normalized, hoistedCtes } = this.hoistCtes(ast);
+    const combinedCtes = [...(normalized.ctes ?? []), ...hoistedCtes];
+    return combinedCtes.length ? { ...normalized, ctes: combinedCtes } : normalized;
+  }
+
+  private readonly expressionCompilers: Map<string, (node: ExpressionNode, ctx: CompilerContext) => string>;
+  private readonly operandCompilers: Map<string, (node: OperandNode, ctx: CompilerContext) => string>;
+
+  protected constructor() {
+    this.expressionCompilers = new Map();
     this.operandCompilers = new Map();
     this.registerDefaultOperandCompilers();
     this.registerDefaultExpressionCompilers();

package/src/core/dialect/base/sql-dialect.ts

@@ -18,17 +18,29 @@ export abstract class SqlDialectBase extends Dialect {
    * Compiles SELECT query AST to SQL using common rules.
    */
   protected compileSelectAst(ast: SelectQueryNode, ctx: CompilerContext): string {
+    const hasSetOps = !!(ast.setOps && ast.setOps.length);
     const ctes = this.compileCtes(ast, ctx);
-    const columns = this.compileSelectColumns(ast, ctx);
-    const from = this.compileFrom(ast.from);
-    const joins = this.compileJoins(ast, ctx);
-    const whereClause = this.compileWhere(ast.where, ctx);
-    const groupBy = this.compileGroupBy(ast);
-    const having = this.compileHaving(ast, ctx);
+
+    // When set operations exist, omit ORDER BY/OFFSET/LIMIT from the operands and apply at the end.
+    const baseAst: SelectQueryNode = hasSetOps
+      ? { ...ast, setOps: undefined, orderBy: undefined, limit: undefined, offset: undefined }
+      : ast;
+
+    const baseSelect = this.compileSelectCore(baseAst, ctx);
+
+    if (!hasSetOps) {
+      return `${ctes}${baseSelect}`;
+    }
+
+    const compound = ast.setOps!
+      .map(op => `${op.operator} ${this.wrapSetOperand(this.compileSelectAst(op.query, ctx))}`)
+      .join(' ');
+
     const orderBy = this.compileOrderBy(ast);
     const pagination = this.compilePagination(ast, orderBy);
 
-    return `${ctes}SELECT ${this.compileDistinct(ast)}${columns} FROM ${from}${joins}${whereClause}${groupBy}${having}${orderBy}${pagination}`;
+    const combined = `${this.wrapSetOperand(baseSelect)} ${compound}`;
+    return `${ctes}${combined}${orderBy}${pagination}`;
   }
 
   protected compileInsertAst(ast: InsertQueryNode, ctx: CompilerContext): string {
@@ -41,6 +53,22 @@ export abstract class SqlDialectBase extends Dialect {
     return `INSERT INTO ${table} (${columnList}) VALUES ${values}${returning}`;
   }
 
+  /**
+   * Compiles a single SELECT (no set operations, no CTE prefix).
+   */
+  private compileSelectCore(ast: SelectQueryNode, ctx: CompilerContext): string {
+    const columns = this.compileSelectColumns(ast, ctx);
+    const from = this.compileFrom(ast.from);
+    const joins = this.compileJoins(ast, ctx);
+    const whereClause = this.compileWhere(ast.where, ctx);
+    const groupBy = this.compileGroupBy(ast);
+    const having = this.compileHaving(ast, ctx);
+    const orderBy = this.compileOrderBy(ast);
+    const pagination = this.compilePagination(ast, orderBy);
+
+    return `SELECT ${this.compileDistinct(ast)}${columns} FROM ${from}${joins}${whereClause}${groupBy}${having}${orderBy}${pagination}`;
+  }
+
   protected compileUpdateAst(ast: UpdateQueryNode, ctx: CompilerContext): string {
     const table = this.compileTableName(ast.table);
     const assignments = ast.set.map(assignment => {
@@ -69,6 +97,16 @@ export abstract class SqlDialectBase extends Dialect {
     throw new Error('RETURNING is not supported by this dialect.');
   }
 
+  protected formatReturningColumns(returning: ColumnNode[]): string {
+    return returning
+      .map(column => {
+        const tablePart = column.table ? `${this.quoteIdentifier(column.table)}.` : '';
+        const aliasPart = column.alias ? ` AS ${this.quoteIdentifier(column.alias)}` : '';
+        return `${tablePart}${this.quoteIdentifier(column.name)}${aliasPart}`;
+      })
+      .join(', ');
+  }
+
   /**
    * DISTINCT clause. Override for DISTINCT ON support.
    */
@@ -149,7 +187,7 @@ export abstract class SqlDialectBase extends Dialect {
       const cols = cte.columns && cte.columns.length
         ? `(${cte.columns.map(c => this.quoteIdentifier(c)).join(', ')})`
         : '';
-      const query = this.stripTrailingSemicolon(this.compileSelectAst(cte.query, ctx));
+      const query = this.stripTrailingSemicolon(this.compileSelectAst(this.normalizeSelectAst(cte.query), ctx));
       return `${name}${cols} AS (${query})`;
     }).join(', ');
     return `${prefix}${cteDefs} `;
@@ -158,4 +196,9 @@ export abstract class SqlDialectBase extends Dialect {
   protected stripTrailingSemicolon(sql: string): string {
     return sql.trim().replace(/;$/, '');
   }
+
+  protected wrapSetOperand(sql: string): string {
+    const trimmed = this.stripTrailingSemicolon(sql);
+    return `(${trimmed})`;
+  }
 }

package/src/core/dialect/mssql/index.ts

@@ -1,6 +1,6 @@
-import { CompilerContext, Dialect } from '../abstract.js';
-import { SelectQueryNode, InsertQueryNode, UpdateQueryNode, DeleteQueryNode } from '../../ast/query.js';
-import { JsonPathNode } from '../../ast/expression.js';
+import { CompilerContext, Dialect } from '../abstract.js';
+import { SelectQueryNode, InsertQueryNode, UpdateQueryNode, DeleteQueryNode } from '../../ast/query.js';
+import { JsonPathNode } from '../../ast/expression.js';
 
 /**
  * Microsoft SQL Server dialect implementation
@@ -42,77 +42,36 @@ export class SqlServerDialect extends Dialect {
     return `@p${index}`;
   }
 
-  /**
-   * Compiles SELECT query AST to SQL Server SQL
-   * @param ast - Query AST
-   * @param ctx - Compiler context
-   * @returns SQL Server SQL string
-   */
-  protected compileSelectAst(ast: SelectQueryNode, ctx: CompilerContext): string {
-    const columns = ast.columns.map(c => {
-      let expr = '';
-      if (c.type === 'Function') {
-        expr = this.compileOperand(c, ctx);
-      } else if (c.type === 'Column') {
-        expr = `${this.quoteIdentifier(c.table)}.${this.quoteIdentifier(c.name)}`;
-      } else if (c.type === 'ScalarSubquery') {
-        expr = this.compileOperand(c, ctx);
-      } else if (c.type === 'WindowFunction') {
-        expr = this.compileOperand(c, ctx);
-      }
-
-      if (c.alias) {
-        if (c.alias.includes('(')) return c.alias;
-        return `${expr} AS ${this.quoteIdentifier(c.alias)}`;
-      }
-      return expr;
-    }).join(', ');
-
-    const distinct = ast.distinct ? 'DISTINCT ' : '';
-    const from = `${this.quoteIdentifier(ast.from.name)}`;
-
-    const joins = ast.joins.map(j => {
-      const table = this.quoteIdentifier(j.table.name);
-      const cond = this.compileExpression(j.condition, ctx);
-      return `${j.kind} JOIN ${table} ON ${cond}`;
-    }).join(' ');
-    const whereClause = this.compileWhere(ast.where, ctx);
-
-    const groupBy = ast.groupBy && ast.groupBy.length > 0
-      ? ' GROUP BY ' + ast.groupBy.map(c => `${this.quoteIdentifier(c.table)}.${this.quoteIdentifier(c.name)}`).join(', ')
-      : '';
-
-    const having = ast.having
-      ? ` HAVING ${this.compileExpression(ast.having, ctx)}`
-      : '';
-
-    const orderBy = ast.orderBy && ast.orderBy.length > 0
-      ? ' ORDER BY ' + ast.orderBy.map(o => `${this.quoteIdentifier(o.column.table)}.${this.quoteIdentifier(o.column.name)} ${o.direction}`).join(', ')
-      : '';
-
-    let pagination = '';
-    if (ast.limit || ast.offset) {
-      const off = ast.offset || 0;
-      const orderClause = orderBy || ' ORDER BY (SELECT NULL)';
-      pagination = `${orderClause} OFFSET ${off} ROWS`;
-      if (ast.limit) {
-        pagination += ` FETCH NEXT ${ast.limit} ROWS ONLY`;
-      }
-      return `SELECT ${distinct}${columns} FROM ${from}${joins ? ' ' + joins : ''}${whereClause}${groupBy}${having}${pagination};`;
-    }
-
-    const ctes = ast.ctes && ast.ctes.length > 0
-      ? 'WITH ' + ast.ctes.map(cte => {
-        // MSSQL does not use RECURSIVE keyword
-        const name = this.quoteIdentifier(cte.name);
-        const cols = cte.columns ? `(${cte.columns.map(c => this.quoteIdentifier(c)).join(', ')})` : '';
-        const query = this.compileSelectAst(cte.query, ctx).trim().replace(/;$/, '');
-        return `${name}${cols} AS (${query})`;
-      }).join(', ') + ' '
-      : '';
-
-    return `${ctes}SELECT ${distinct}${columns} FROM ${from}${joins ? ' ' + joins : ''}${whereClause}${groupBy}${having}${orderBy};`;
-  }
+  /**
+   * Compiles SELECT query AST to SQL Server SQL
+   * @param ast - Query AST
+   * @param ctx - Compiler context
+   * @returns SQL Server SQL string
+   */
+  protected compileSelectAst(ast: SelectQueryNode, ctx: CompilerContext): string {
+    const hasSetOps = !!(ast.setOps && ast.setOps.length);
+    const ctes = this.compileCtes(ast, ctx);
+
+    const baseAst: SelectQueryNode = hasSetOps
+      ? { ...ast, setOps: undefined, orderBy: undefined, limit: undefined, offset: undefined }
+      : ast;
+
+    const baseSelect = this.compileSelectCore(baseAst, ctx);
+
+    if (!hasSetOps) {
+      return `${ctes}${baseSelect}`;
+    }
+
+    const compound = ast.setOps!
+      .map(op => `${op.operator} ${this.wrapSetOperand(this.compileSelectAst(op.query, ctx))}`)
+      .join(' ');
+
+    const orderBy = this.compileOrderBy(ast);
+    const pagination = this.compilePagination(ast, orderBy);
+    const combined = `${this.wrapSetOperand(baseSelect)} ${compound}`;
+    const tail = pagination || orderBy;
+    return `${ctes}${combined}${tail}`;
+  }
 
   protected compileInsertAst(ast: InsertQueryNode, ctx: CompilerContext): string {
     const table = this.quoteIdentifier(ast.into.name);
@@ -133,9 +92,95 @@ export class SqlServerDialect extends Dialect {
     return `UPDATE ${table} SET ${assignments}${whereClause};`;
   }
 
-  protected compileDeleteAst(ast: DeleteQueryNode, ctx: CompilerContext): string {
-    const table = this.quoteIdentifier(ast.from.name);
-    const whereClause = this.compileWhere(ast.where, ctx);
-    return `DELETE FROM ${table}${whereClause};`;
-  }
-}
+  protected compileDeleteAst(ast: DeleteQueryNode, ctx: CompilerContext): string {
+    const table = this.quoteIdentifier(ast.from.name);
+    const whereClause = this.compileWhere(ast.where, ctx);
+    return `DELETE FROM ${table}${whereClause};`;
+  }
+
+  private compileSelectCore(ast: SelectQueryNode, ctx: CompilerContext): string {
+    const columns = ast.columns.map(c => {
+      let expr = '';
+      if (c.type === 'Function') {
+        expr = this.compileOperand(c, ctx);
+      } else if (c.type === 'Column') {
+        expr = `${this.quoteIdentifier(c.table)}.${this.quoteIdentifier(c.name)}`;
+      } else if (c.type === 'ScalarSubquery') {
+        expr = this.compileOperand(c, ctx);
+      } else if (c.type === 'WindowFunction') {
+        expr = this.compileOperand(c, ctx);
+      }
+
+      if (c.alias) {
+        if (c.alias.includes('(')) return c.alias;
+        return `${expr} AS ${this.quoteIdentifier(c.alias)}`;
+      }
+      return expr;
+    }).join(', ');
+
+    const distinct = ast.distinct ? 'DISTINCT ' : '';
+    const from = `${this.quoteIdentifier(ast.from.name)}`;
+
+    const joins = ast.joins.map(j => {
+      const table = this.quoteIdentifier(j.table.name);
+      const cond = this.compileExpression(j.condition, ctx);
+      return `${j.kind} JOIN ${table} ON ${cond}`;
+    }).join(' ');
+    const whereClause = this.compileWhere(ast.where, ctx);
+
+    const groupBy = ast.groupBy && ast.groupBy.length > 0
+      ? ' GROUP BY ' + ast.groupBy.map(c => `${this.quoteIdentifier(c.table)}.${this.quoteIdentifier(c.name)}`).join(', ')
+      : '';
+
+    const having = ast.having
+      ? ` HAVING ${this.compileExpression(ast.having, ctx)}`
+      : '';
+
+    const orderBy = this.compileOrderBy(ast);
+    const pagination = this.compilePagination(ast, orderBy);
+
+    if (pagination) {
+      return `SELECT ${distinct}${columns} FROM ${from}${joins ? ' ' + joins : ''}${whereClause}${groupBy}${having}${pagination}`;
+    }
+
+    return `SELECT ${distinct}${columns} FROM ${from}${joins ? ' ' + joins : ''}${whereClause}${groupBy}${having}${orderBy}`;
+  }
+
+  private compileOrderBy(ast: SelectQueryNode): string {
+    if (!ast.orderBy || ast.orderBy.length === 0) return '';
+    return ' ORDER BY ' + ast.orderBy
+      .map(o => `${this.quoteIdentifier(o.column.table)}.${this.quoteIdentifier(o.column.name)} ${o.direction}`)
+      .join(', ');
+  }
+
+  private compilePagination(ast: SelectQueryNode, orderBy: string): string {
+    const hasLimit = ast.limit !== undefined;
+    const hasOffset = ast.offset !== undefined;
+    if (!hasLimit && !hasOffset) return '';
+
+    const off = ast.offset ?? 0;
+    const orderClause = orderBy || ' ORDER BY (SELECT NULL)';
+    let pagination = `${orderClause} OFFSET ${off} ROWS`;
+    if (hasLimit) {
+      pagination += ` FETCH NEXT ${ast.limit} ROWS ONLY`;
+    }
+    return pagination;
+  }
+
+  private compileCtes(ast: SelectQueryNode, ctx: CompilerContext): string {
+    if (!ast.ctes || ast.ctes.length === 0) return '';
+    // MSSQL does not use RECURSIVE keyword, but supports recursion when CTE references itself.
+    const defs = ast.ctes.map(cte => {
+      const name = this.quoteIdentifier(cte.name);
+      const cols = cte.columns ? `(${cte.columns.map(c => this.quoteIdentifier(c)).join(', ')})` : '';
+      const query = this.compileSelectAst(this.normalizeSelectAst(cte.query), ctx).trim().replace(/;$/, '');
+      return `${name}${cols} AS (${query})`;
+    }).join(', ');
+    return `WITH ${defs} `;
+  }
+
+  private wrapSetOperand(sql: string): string {
+    const trimmed = sql.trim().replace(/;$/, '');
+    return `(${trimmed})`;
+  }
+}

package/src/core/dialect/postgres/index.ts

@@ -35,12 +35,11 @@ export class PostgresDialect extends SqlDialectBase {
 
   protected compileReturning(returning: ColumnNode[] | undefined, ctx: CompilerContext): string {
     if (!returning || returning.length === 0) return '';
-    const columns = returning
-      .map(column => {
-        const tablePart = column.table ? `${this.quoteIdentifier(column.table)}.` : '';
-        return `${tablePart}${this.quoteIdentifier(column.name)}`;
-      })
-      .join(', ');
+    const columns = this.formatReturningColumns(returning);
     return ` RETURNING ${columns}`;
   }
+
+  supportsReturning(): boolean {
+    return true;
+  }
 }

package/src/core/dialect/sqlite/index.ts

@@ -35,12 +35,11 @@ export class SqliteDialect extends SqlDialectBase {
 
   protected compileReturning(returning: ColumnNode[] | undefined, ctx: CompilerContext): string {
     if (!returning || returning.length === 0) return '';
-    const columns = returning
-      .map(column => {
-        const tablePart = column.table ? `${this.quoteIdentifier(column.table)}.` : '';
-        return `${tablePart}${this.quoteIdentifier(column.name)}`;
-      })
-      .join(', ');
+    const columns = this.formatReturningColumns(returning);
     return ` RETURNING ${columns}`;
   }
+
+  supportsReturning(): boolean {
+    return true;
+  }
 }

package/src/orm/execute.ts

@@ -1,9 +1,9 @@
 import { TableDef } from '../schema/table.js';
 import { Entity } from '../schema/types.js';
-import { hydrateRows } from './hydration.js';
-import { OrmContext } from './orm-context.js';
-import { SelectQueryBuilder } from '../query-builder/select.js';
-import { createEntityFromRow } from './entity.js';
+import { hydrateRows } from './hydration.js';
+import { OrmContext } from './orm-context.js';
+import { SelectQueryBuilder } from '../query-builder/select.js';
+import { createEntityFromRow, createEntityProxy } from './entity.js';
 
 type Row = Record<string, any>;
 
@@ -22,15 +22,24 @@ const flattenResults = (results: { columns: string[]; values: unknown[][] }[]):
   return rows;
 };
 
-export async function executeHydrated<TTable extends TableDef>(
-  ctx: OrmContext,
-  qb: SelectQueryBuilder<any, TTable>
-): Promise<Entity<TTable>[]> {
-  const compiled = ctx.dialect.compileSelect(qb.getAST());
-  const executed = await ctx.executor.executeSql(compiled.sql, compiled.params);
-  const rows = flattenResults(executed);
-  const hydrated = hydrateRows(rows, qb.getHydrationPlan());
-  return hydrated.map(row =>
-    createEntityFromRow(ctx, qb.getTable(), row, qb.getLazyRelations())
-  );
-}
+export async function executeHydrated<TTable extends TableDef>(
+  ctx: OrmContext,
+  qb: SelectQueryBuilder<any, TTable>
+): Promise<Entity<TTable>[]> {
+  const ast = qb.getAST();
+  const compiled = ctx.dialect.compileSelect(ast);
+  const executed = await ctx.executor.executeSql(compiled.sql, compiled.params);
+  const rows = flattenResults(executed);
+
+  // Set-operation queries cannot be reliably hydrated and should not collapse duplicates.
+  if (ast.setOps && ast.setOps.length > 0) {
+    return rows.map(row =>
+      createEntityProxy(ctx, qb.getTable(), row, qb.getLazyRelations())
+    );
+  }
+
+  const hydrated = hydrateRows(rows, qb.getHydrationPlan());
+  return hydrated.map(row =>
+    createEntityFromRow(ctx, qb.getTable(), row, qb.getLazyRelations())
+  );
+}