@wildo-ai/saas-backend-lib 1.0.1

package/src/databases/services/postgresql-aggregation.backend.service.ts

@@ -0,0 +1,794 @@
+/** ──────────────────────────────────────────────────────────────
+ * PostgreSQLAggregationCompilerBackendService
+ *
+ * Compiles an AggregationExpression AST into a parameterized SQL query
+ * targeting PostgreSQL (14+).
+ *
+ * Design mirrors MongoAggregationCompilerBackendService:
+ *   AST → compile() → { sql, params, table, statementTimeoutMs }
+ *
+ * SQL generation order:
+ *   1. CTEs (Common Table Expressions) — joins (if any)
+ *   2. SELECT — aggregate functions + dimension aliases
+ *   3. FROM — primary table (+ JOIN clauses)
+ *   4. WHERE — combined filters
+ *   5. GROUP BY — dimensions (with binning / time truncation)
+ *   6. HAVING — post-aggregation filters
+ *   7. ORDER BY
+ *   8. LIMIT
+ *
+ * Window functions:
+ *   PostgreSQL natively supports all window function types via
+ *   OVER (PARTITION BY ... ORDER BY ...) — far more than MongoDB.
+ *   All window types are handled in-DB.
+ *
+ * Parameterization:
+ *   All user-supplied values go through $N positional parameters
+ *   to prevent SQL injection. Table/column names are double-quoted.
+ * ────────────────────────────────────────────────────────────── */
+
+import { injectable, inject } from 'inversify';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import type { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import { AggregateFunction, ComparisonOperator, DimensionSortBy, JoinType, SortDirection, WindowFunctionType } from '@wildo-ai/saas-models';
+import type {
+  AggregationExpression,
+  AggregationMeasureNode,
+  AggregationDimensionNode,
+  AggregationJoinNode,
+  AggregationHavingNode,
+  AggregationWindowNode,
+  PostgreSQLAggregationQuery,
+} from '~wildo-backend-lib/databases/models/aggregation.backend.schemas';
+import type { ResourceFilter } from '~wildo-backend-lib/databases/models/filter.backend.schemas';
+
+/** All PostgreSQL window function types — PG handles them all natively */
+const IN_DB_WINDOW_FUNCTIONS = new Set<WindowFunctionType>([
+  WindowFunctionType.RUNNING_TOTAL,
+  WindowFunctionType.RUNNING_AVG,
+  WindowFunctionType.RANK,
+  WindowFunctionType.DENSE_RANK,
+  WindowFunctionType.LAG,
+  WindowFunctionType.LEAD,
+  WindowFunctionType.PERCENT_OF_TOTAL,
+  WindowFunctionType.DIFFERENCE,
+  WindowFunctionType.PERCENT_CHANGE,
+  WindowFunctionType.MOVING_AVG,
+]);
+
+@injectable()
+export class PostgreSQLAggregationCompilerBackendService {
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,
+  ) {}
+
+  // ── Public API ──────────────────────────────────────────────
+
+  /**
+   * Compile an AggregationExpression into a parameterized PostgreSQL query.
+   */
+  compile(expression: AggregationExpression): PostgreSQLAggregationQuery {
+    const ctx = new SqlBuildContext();
+
+    // 1. Build join clauses (pass source table for FK qualification)
+    const joinClauses = expression.joins.map(j => this.buildJoinClause(j, expression.collection, ctx));
+
+    // 2. Build WHERE clause from filter
+    const whereSql = expression.filter && Object.keys(expression.filter).length > 0
+      ? this.buildWhereClause(expression.filter, ctx, expression.collection)
+      : null;
+
+    // 3. Build SELECT expressions (dimensions + measures)
+    //    Also collects a measureRef → aggregate SQL map for HAVING resolution
+    const measureExprMap = new Map<string, string>();
+    const selectExprs = this.buildSelectExpressions(expression, ctx, measureExprMap);
+
+    // 4. Build GROUP BY expressions
+    const groupByExprs = this.buildGroupByExpressions(expression.dimensions);
+
+    // 5. Build HAVING clause using the full aggregate expressions (not aliases)
+    const havingSql = expression.having.length > 0
+      ? this.buildHavingClause(expression.having, measureExprMap, ctx)
+      : null;
+
+    // 6. Build window function expressions (added to SELECT via subquery or direct)
+    const windowExprs = this.buildWindowExpressions(expression.windowFunctions, expression.dimensions, expression.collection);
+
+    // 7. Build ORDER BY
+    const orderBySql = this.buildOrderByClause(expression);
+
+    // 8. Build LIMIT (parameterized) — use != null to correctly handle limit: 0
+    const limitSql = expression.limit != null ? `LIMIT ${ctx.addParam(expression.limit)}` : '';
+
+    // ── Assemble the query ────────────────────────────────────
+
+    const table = this.quoteIdentifier(expression.collection);
+
+    // If we have window functions, wrap the aggregate query in a subquery
+    // and add window function columns on top
+    let sql: string;
+
+    if (windowExprs.length > 0) {
+      // Inner query: standard GROUP BY aggregate
+      const innerSelect = selectExprs.join(',\n  ');
+      const innerFrom = `FROM ${table}`;
+      const innerJoins = joinClauses.length > 0 ? '\n' + joinClauses.join('\n') : '';
+      const innerWhere = whereSql ? `WHERE ${whereSql}` : '';
+      const innerGroupBy = groupByExprs.length > 0 ? `GROUP BY ${groupByExprs.join(', ')}` : '';
+      const innerHaving = havingSql ? `HAVING ${havingSql}` : '';
+
+      const innerQuery = [
+        `SELECT\n  ${innerSelect}`,
+        innerFrom + innerJoins,
+        innerWhere,
+        innerGroupBy,
+        innerHaving,
+      ].filter(Boolean).join('\n');
+
+      // Outer query: add window function columns
+      const windowSelectExprs = windowExprs.map(w => w.selectExpr);
+      const outerSelect = ['_inner.*', ...windowSelectExprs].join(',\n  ');
+
+      sql = [
+        `SELECT\n  ${outerSelect}`,
+        `FROM (\n${innerQuery}\n) AS _inner`,
+        orderBySql,
+        limitSql,
+      ].filter(Boolean).join('\n');
+    } else {
+      // Simple query: no window functions
+      const selectSql = selectExprs.join(',\n  ');
+      const fromSql = `FROM ${table}`;
+      const joinsSql = joinClauses.length > 0 ? '\n' + joinClauses.join('\n') : '';
+
+      sql = [
+        `SELECT\n  ${selectSql}`,
+        fromSql + joinsSql,
+        whereSql ? `WHERE ${whereSql}` : '',
+        groupByExprs.length > 0 ? `GROUP BY ${groupByExprs.join(', ')}` : '',
+        havingSql ? `HAVING ${havingSql}` : '',
+        orderBySql,
+        limitSql,
+      ].filter(Boolean).join('\n');
+    }
+
+    this.logger.debug(
+      `PostgreSQLAggregationCompiler: compiled query for ${expression.collection} ` +
+      `(${ctx.params.length} params, ${expression.dimensions.length} dims, ${expression.measures.length} measures)`,
+    );
+
+    return {
+      sql,
+      params: ctx.params,
+      table: expression.collection,
+      statementTimeoutMs: expression.timeoutMs,
+    };
+  }
+
+  /**
+   * All window function types are supported in-DB by PostgreSQL.
+   */
+  getInDbWindowTypes(): Set<WindowFunctionType> {
+    return IN_DB_WINDOW_FUNCTIONS;
+  }
+
+  // ── SELECT Expressions ──────────────────────────────────────
+
+  private buildSelectExpressions(
+    expression: AggregationExpression,
+    ctx: SqlBuildContext,
+    measureExprMap: Map<string, string>,
+  ): string[] {
+    const exprs: string[] = [];
+
+    // Dimensions
+    for (const dim of expression.dimensions) {
+      const dimExpr = this.buildDimensionExpression(dim, expression.timezone, expression.collection, ctx);
+      exprs.push(`${dimExpr} AS ${this.quoteIdentifier(dim.ref)}`);
+    }
+
+    // Measures — also record the raw aggregate expression for HAVING resolution
+    for (const measure of expression.measures) {
+      const measureExpr = this.buildMeasureExpression(measure, expression.collection, ctx);
+      measureExprMap.set(measure.ref, measureExpr);
+      exprs.push(`${measureExpr} AS ${this.quoteIdentifier(measure.ref)}`);
+    }
+
+    return exprs;
+  }
+
+  // ── Dimension Expression ────────────────────────────────────
+
+  private buildDimensionExpression(
+    dim: AggregationDimensionNode,
+    timezone: string,
+    table: string,
+    ctx: SqlBuildContext,
+  ): string {
+    const fieldPath = this.resolveFieldPath(dim.field.physicalPath, dim.field.isJoined ? dim.field.joinAlias : undefined, table);
+
+    if (dim.timeGranularity) {
+      // Time dimension: date_trunc with timezone
+      const tz = ctx.addParam(timezone);
+      return `date_trunc(${ctx.addParam(dim.timeGranularity)}, ${fieldPath} AT TIME ZONE ${tz})`;
+    }
+
+    if (dim.bin) {
+      return this.buildBinExpression(fieldPath, dim.bin, ctx);
+    }
+
+    // Categorical dimension: direct column reference
+    return fieldPath;
+  }
+
+  // ── Binning Expression ──────────────────────────────────────
+
+  private buildBinExpression(
+    fieldPath: string,
+    bin: { step: number } | { boundaries: number[] },
+    ctx: SqlBuildContext,
+  ): string {
+    if ('step' in bin) {
+      // Step-based: floor(value / step) * step
+      const step = ctx.addParam(bin.step);
+      return `(floor(${fieldPath} / ${step}) * ${step})`;
+    }
+
+    // Boundary-based: CASE WHEN ... THEN ... END
+    const boundaries = bin.boundaries;
+
+    if (boundaries.length < 2) {
+      this.logger.warn('PostgreSQLAggregationCompiler: boundary binning requires at least 2 boundaries, falling back to cast');
+      return `CAST(${fieldPath} AS TEXT)`;
+    }
+
+    const cases: string[] = [];
+
+    // First case: value < first boundary
+    cases.push(`WHEN ${fieldPath} < ${ctx.addParam(boundaries[0])} THEN ${ctx.addParam(`< ${boundaries[0]}`)}`);
+
+    // Middle cases: each boundary range
+    for (let i = 0; i < boundaries.length - 1; i++) {
+      cases.push(
+        `WHEN ${fieldPath} >= ${ctx.addParam(boundaries[i])} AND ${fieldPath} < ${ctx.addParam(boundaries[i + 1])} ` +
+        `THEN ${ctx.addParam(`${boundaries[i]} – ${boundaries[i + 1]}`)}`,
+      );
+    }
+
+    // Else: >= last boundary
+    const elseLabel = ctx.addParam(`≥ ${boundaries[boundaries.length - 1]}`);
+
+    return `CASE ${cases.join(' ')} ELSE ${elseLabel} END`;
+  }
+
+  // ── Measure Expression ──────────────────────────────────────
+
+  private buildMeasureExpression(
+    measure: AggregationMeasureNode,
+    table: string,
+    ctx: SqlBuildContext,
+  ): string {
+    const fieldPath = measure.field.logicalName === '*'
+      ? '*'
+      : this.resolveFieldPath(measure.field.physicalPath, measure.field.isJoined ? measure.field.joinAlias : undefined, table);
+
+    // Compute the filter-wrapped field lazily — only for aggregates that need it.
+    // COUNT and COUNT_DISTINCT use their own filter patterns to avoid phantom params.
+    const getEffectiveField = (): string =>
+      measure.filter
+        ? `CASE WHEN ${this.buildFilterCondition(measure.filter, ctx, table)} THEN ${fieldPath} ELSE NULL END`
+        : fieldPath;
+
+    switch (measure.aggregate) {
+      // ── Basic ──
+      case AggregateFunction.COUNT:
+        if (measure.filter) {
+          return `COUNT(CASE WHEN ${this.buildFilterCondition(measure.filter, ctx, table)} THEN 1 END)`;
+        }
+        return fieldPath === '*' ? 'COUNT(*)' : `COUNT(${fieldPath})`;
+
+      case AggregateFunction.COUNT_DISTINCT:
+        if (measure.filter) {
+          return `COUNT(DISTINCT CASE WHEN ${this.buildFilterCondition(measure.filter, ctx, table)} THEN ${fieldPath} END)`;
+        }
+        return `COUNT(DISTINCT ${fieldPath})`;
+
+      case AggregateFunction.SUM:
+        return `SUM(${getEffectiveField()})`;
+
+      case AggregateFunction.AVG:
+        return `AVG(${getEffectiveField()})`;
+
+      case AggregateFunction.MIN:
+        return `MIN(${getEffectiveField()})`;
+
+      case AggregateFunction.MAX:
+        return `MAX(${getEffectiveField()})`;
+
+      // ── Statistical ──
+      case AggregateFunction.MEDIAN:
+        return `PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY ${getEffectiveField()})`;
+
+      case AggregateFunction.PERCENTILE: {
+        const p = (measure.percentileValue ?? 50) / 100;
+        return `PERCENTILE_CONT(${ctx.addParam(p)}) WITHIN GROUP (ORDER BY ${getEffectiveField()})`;
+      }
+
+      case AggregateFunction.STDDEV:
+        return `STDDEV_POP(${getEffectiveField()})`;
+
+      case AggregateFunction.VARIANCE:
+        return `VAR_POP(${getEffectiveField()})`;
+
+      // ── Boolean / existence ──
+      case AggregateFunction.ANY_VALUE:
+        // PostgreSQL doesn't have ANY_VALUE natively, use (array_agg(...))[1]
+        return `(ARRAY_AGG(${getEffectiveField()}))[1]`;
+
+      case AggregateFunction.BOOL_AND:
+        return `BOOL_AND(${getEffectiveField()})`;
+
+      case AggregateFunction.BOOL_OR:
+        return `BOOL_OR(${getEffectiveField()})`;
+
+      // ── Array ──
+      case AggregateFunction.ARRAY_AGG:
+        if (measure.arrayLimit) {
+          return `(ARRAY_AGG(${getEffectiveField()}))[1:${ctx.addParam(measure.arrayLimit)}]`;
+        }
+        return `ARRAY_AGG(${getEffectiveField()})`;
+
+      case AggregateFunction.STRING_AGG: {
+        const sep = measure.separator ?? ', ';
+        return `STRING_AGG(CAST(${getEffectiveField()} AS TEXT), ${ctx.addParam(sep)})`;
+      }
+
+      default:
+        this.logger.warn(`PostgreSQLAggregationCompiler: unknown aggregate '${measure.aggregate}', defaulting to SUM`);
+        return `SUM(${getEffectiveField()})`;
+    }
+  }
+
+  // ── GROUP BY Expressions ────────────────────────────────────
+
+  private buildGroupByExpressions(
+    dimensions: AggregationDimensionNode[],
+  ): string[] {
+    // GROUP BY can reference ordinal positions or repeat the expression.
+    // We use ordinal positions (1-based) pointing to SELECT columns.
+    // Dimensions are always the first N columns in SELECT.
+    return dimensions.map((_, i) => String(i + 1));
+  }
+
+  // ── JOIN Clause ─────────────────────────────────────────────
+
+  private buildJoinClause(
+    join: AggregationJoinNode,
+    sourceTable: string,
+    ctx: SqlBuildContext,
+  ): string {
+    const joinType = join.joinType === JoinType.LEFT ? 'LEFT JOIN' : 'INNER JOIN';
+    const targetTable = this.quoteIdentifier(join.targetCollection);
+    const alias = this.quoteIdentifier(join.alias);
+    // FK field lives on the SOURCE table — qualify it to prevent ambiguity
+    const fkField = `${this.quoteIdentifier(sourceTable)}.${this.quoteIdentifier(join.foreignKeyField.physicalPath)}`;
+    const pkField = `${alias}.${this.quoteIdentifier(join.targetPkField)}`;
+
+    let onClause = `${fkField} = ${pkField}`;
+
+    // Add auth filter to JOIN condition — use the alias (not original table name)
+    // since the JOIN uses "AS alias" and SQL requires the alias in ON conditions
+    if (join.authFilter && Object.keys(join.authFilter).length > 0) {
+      const authSql = this.buildFilterCondition(join.authFilter, ctx, join.alias);
+      onClause += ` AND ${authSql}`;
+    }
+
+    return `${joinType} ${targetTable} AS ${alias} ON ${onClause}`;
+  }
+
+  // ── WHERE Clause ────────────────────────────────────────────
+
+  private buildWhereClause(
+    filter: ResourceFilter,
+    ctx: SqlBuildContext,
+    table: string,
+  ): string {
+    return this.buildFilterCondition(filter, ctx, table);
+  }
+
+  /**
+   * Convert a MongoDB-style filter to a SQL condition.
+   *
+   * The `tableOrAlias` parameter is used to qualify all field references,
+   * preventing "ambiguous column reference" errors when JOINs are present.
+   *
+   * Supports:
+   *   { field: value }           → "table"."field" = $N
+   *   { field: { $gt: value } }  → "table"."field" > $N
+   *   { $and: [...] }            → (...) AND (...)
+   *   { $or: [...] }             → (...) OR (...)
+   */
+  private buildFilterCondition(
+    filter: ResourceFilter,
+    ctx: SqlBuildContext,
+    tableOrAlias: string,
+  ): string {
+    const conditions: string[] = [];
+
+    for (const [key, value] of Object.entries(filter)) {
+      if (key === '$and' && Array.isArray(value)) {
+        const subConditions = value.map(v => this.buildFilterCondition(v as ResourceFilter, ctx, tableOrAlias));
+        conditions.push(`(${subConditions.join(' AND ')})`);
+        continue;
+      }
+
+      if (key === '$or' && Array.isArray(value)) {
+        const subConditions = value.map(v => this.buildFilterCondition(v as ResourceFilter, ctx, tableOrAlias));
+        conditions.push(`(${subConditions.join(' OR ')})`);
+        continue;
+      }
+
+      if (key === '$not' && value && typeof value === 'object') {
+        conditions.push(`NOT (${this.buildFilterCondition(value as ResourceFilter, ctx, tableOrAlias)})`);
+        continue;
+      }
+
+      // Qualify field with table/alias to prevent ambiguity in JOINed queries
+      const fieldRef = `${this.quoteIdentifier(tableOrAlias)}.${this.quoteIdentifier(key)}`;
+
+      if (value === null || value === undefined) {
+        conditions.push(`${fieldRef} IS NULL`);
+        continue;
+      }
+
+      if (typeof value === 'object' && !Array.isArray(value)) {
+        // Operator-based filter: { $gt: 100, $lt: 200 }
+        const opObj = value as Record<string, unknown>;
+        for (const [op, opVal] of Object.entries(opObj)) {
+          // Skip $options — it's handled as part of $regex/$startsWith/$endsWith/$contains
+          if (op === '$options') continue;
+          conditions.push(this.buildOperatorCondition(fieldRef, op, opVal, opObj, ctx));
+        }
+        continue;
+      }
+
+      // Simple equality
+      conditions.push(`${fieldRef} = ${ctx.addParam(value)}`);
+    }
+
+    if (conditions.length === 0) return 'TRUE';
+    if (conditions.length === 1) return conditions[0]!;
+    return conditions.join(' AND ');
+  }
+
+  private buildOperatorCondition(
+    fieldRef: string,
+    op: string,
+    value: unknown,
+    /** Full operator object — used to read sibling keys like $options */
+    operatorObj: Record<string, unknown>,
+    ctx: SqlBuildContext,
+  ): string {
+    switch (op) {
+      case '$eq':
+        return value === null ? `${fieldRef} IS NULL` : `${fieldRef} = ${ctx.addParam(value)}`;
+      case '$ne':
+        return value === null ? `${fieldRef} IS NOT NULL` : `${fieldRef} <> ${ctx.addParam(value)}`;
+      case '$gt':
+        return `${fieldRef} > ${ctx.addParam(value)}`;
+      case '$gte':
+        return `${fieldRef} >= ${ctx.addParam(value)}`;
+      case '$lt':
+        return `${fieldRef} < ${ctx.addParam(value)}`;
+      case '$lte':
+        return `${fieldRef} <= ${ctx.addParam(value)}`;
+      case '$in':
+        if (Array.isArray(value) && value.length > 0) {
+          const placeholders = value.map(v => ctx.addParam(v)).join(', ');
+          return `${fieldRef} IN (${placeholders})`;
+        }
+        return 'FALSE'; // Empty IN → always false
+      case '$nin':
+        if (Array.isArray(value) && value.length > 0) {
+          const placeholders = value.map(v => ctx.addParam(v)).join(', ');
+          return `${fieldRef} NOT IN (${placeholders})`;
+        }
+        return 'TRUE'; // Empty NOT IN → always true
+      case '$exists':
+        return value ? `${fieldRef} IS NOT NULL` : `${fieldRef} IS NULL`;
+      case '$regex': {
+        // Honor sibling $options for case-insensitive matching
+        const options = typeof operatorObj['$options'] === 'string' ? operatorObj['$options'] : '';
+        const regexOp = options.includes('i') ? '~*' : '~';
+        return `${fieldRef} ${regexOp} ${ctx.addParam(value)}`;
+      }
+      case '$startsWith': {
+        const escaped = this.escapeLikeValue(value);
+        const likeOptions = typeof operatorObj['$options'] === 'string' ? operatorObj['$options'] : '';
+        const likeOp = likeOptions.includes('i') ? 'ILIKE' : 'LIKE';
+        return `${fieldRef} ${likeOp} ${ctx.addParam(`${escaped}%`)}`;
+      }
+      case '$endsWith': {
+        const escaped = this.escapeLikeValue(value);
+        const likeOptions = typeof operatorObj['$options'] === 'string' ? operatorObj['$options'] : '';
+        const likeOp = likeOptions.includes('i') ? 'ILIKE' : 'LIKE';
+        return `${fieldRef} ${likeOp} ${ctx.addParam(`%${escaped}`)}`;
+      }
+      case '$contains': {
+        const escaped = this.escapeLikeValue(value);
+        const likeOptions = typeof operatorObj['$options'] === 'string' ? operatorObj['$options'] : '';
+        const likeOp = likeOptions.includes('i') ? 'ILIKE' : 'LIKE';
+        return `${fieldRef} ${likeOp} ${ctx.addParam(`%${escaped}%`)}`;
+      }
+      default:
+        this.logger.warn(`PostgreSQLAggregationCompiler: unsupported filter operator '${op}'`);
+        return 'TRUE';
+    }
+  }
+
+  // ── HAVING Clause ───────────────────────────────────────────
+
+  /**
+   * Build HAVING clause using full aggregate expressions, not SELECT aliases.
+   *
+   * PostgreSQL does NOT allow referencing SELECT aliases in HAVING.
+   * Instead, we repeat the aggregate expression from the SELECT:
+   *   HAVING SUM("revenue") > $1   (not HAVING "totalRevenue" > $1)
+   *
+   * The measureExprMap is built during buildSelectExpressions and maps
+   * each measure ref to its full aggregate SQL expression.
+   */
+  private buildHavingClause(
+    havingClauses: AggregationHavingNode[],
+    measureExprMap: Map<string, string>,
+    ctx: SqlBuildContext,
+  ): string {
+    const conditions: string[] = [];
+
+    for (const clause of havingClauses) {
+      // Use the full aggregate expression if available, otherwise fall back to quoted ref
+      const aggExpr = measureExprMap.get(clause.measureRef);
+      if (!aggExpr) {
+        this.logger.warn(
+          `PostgreSQLAggregationCompiler: HAVING references unknown measure '${clause.measureRef}', skipping`,
+        );
+        continue;
+      }
+
+      const val = ctx.addParam(clause.value);
+
+      switch (clause.operator) {
+        case ComparisonOperator.EQ:
+          conditions.push(`${aggExpr} = ${val}`);
+          break;
+        case ComparisonOperator.NE:
+          conditions.push(`${aggExpr} <> ${val}`);
+          break;
+        case ComparisonOperator.GT:
+          conditions.push(`${aggExpr} > ${val}`);
+          break;
+        case ComparisonOperator.GTE:
+          conditions.push(`${aggExpr} >= ${val}`);
+          break;
+        case ComparisonOperator.LT:
+          conditions.push(`${aggExpr} < ${val}`);
+          break;
+        case ComparisonOperator.LTE:
+          conditions.push(`${aggExpr} <= ${val}`);
+          break;
+        default:
+          this.logger.warn(`PostgreSQLAggregationCompiler: unsupported HAVING operator: ${clause.operator}`);
+      }
+    }
+
+    return conditions.join(' AND ');
+  }
+
+  // ── Window Function Expressions ─────────────────────────────
+
+  /**
+   * Build window function SELECT expressions.
+   *
+   * PostgreSQL supports all window functions natively:
+   *   SUM(...) OVER (ORDER BY dim)                    → running_total
+   *   AVG(...) OVER (ORDER BY dim)                    → running_avg
+   *   RANK() OVER (ORDER BY measure DESC)             → rank
+   *   DENSE_RANK() OVER (ORDER BY measure DESC)       → dense_rank
+   *   LAG(field, 1) OVER (ORDER BY dim)               → lag
+   *   LEAD(field, 1) OVER (ORDER BY dim)              → lead
+   *   field / SUM(field) OVER ()                      → percent_of_total
+   *   field - LAG(field) OVER (ORDER BY dim)           → difference
+   *   (field - LAG(field) OVER (...)) / LAG(field)... → percent_change
+   *   AVG(field) OVER (ORDER BY dim ROWS BETWEEN N PRECEDING AND CURRENT ROW) → moving_avg
+   */
+  private buildWindowExpressions(
+    windowFunctions: AggregationWindowNode[],
+    dimensions: AggregationDimensionNode[],
+    table: string,
+  ): { selectExpr: string }[] {
+    if (!windowFunctions || windowFunctions.length === 0) return [];
+
+    const defaultOrderRef = dimensions[0]?.ref;
+
+    return windowFunctions.map(wf => {
+      const ref = this.quoteIdentifier(wf.ref);
+      const sourceRef = this.quoteIdentifier(wf.sourceRef);
+      const orderByRef = this.quoteIdentifier(wf.orderBy || defaultOrderRef || wf.sourceRef);
+      const partitionClause = wf.partitionBy ? `PARTITION BY ${this.quoteIdentifier(wf.partitionBy)}` : '';
+
+      const overClause = (parts: string[]): string => {
+        const filtered = parts.filter(Boolean);
+        return `OVER (${filtered.join(' ')})`;
+      };
+
+      let expr: string;
+
+      switch (wf.type) {
+        case WindowFunctionType.RUNNING_TOTAL:
+          expr = `SUM(${sourceRef}) ${overClause([partitionClause, `ORDER BY ${orderByRef}`, 'ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW'])}`;
+          break;
+
+        case WindowFunctionType.RUNNING_AVG:
+          expr = `AVG(${sourceRef}) ${overClause([partitionClause, `ORDER BY ${orderByRef}`, 'ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW'])}`;
+          break;
+
+        case WindowFunctionType.RANK:
+          expr = `RANK() ${overClause([partitionClause, `ORDER BY ${sourceRef} DESC`])}`;
+          break;
+
+        case WindowFunctionType.DENSE_RANK:
+          expr = `DENSE_RANK() ${overClause([partitionClause, `ORDER BY ${sourceRef} DESC`])}`;
+          break;
+
+        case WindowFunctionType.LAG:
+          expr = `LAG(${sourceRef}, 1) ${overClause([partitionClause, `ORDER BY ${orderByRef}`])}`;
+          break;
+
+        case WindowFunctionType.LEAD:
+          expr = `LEAD(${sourceRef}, 1) ${overClause([partitionClause, `ORDER BY ${orderByRef}`])}`;
+          break;
+
+        case WindowFunctionType.PERCENT_OF_TOTAL:
+          // value / SUM(value) OVER (PARTITION BY ...)
+          expr = `${sourceRef}::DOUBLE PRECISION / NULLIF(SUM(${sourceRef}) ${overClause([partitionClause])}, 0)`;
+          break;
+
+        case WindowFunctionType.DIFFERENCE:
+          // value - LAG(value, 1) OVER (...)
+          expr = `${sourceRef} - LAG(${sourceRef}, 1) ${overClause([partitionClause, `ORDER BY ${orderByRef}`])}`;
+          break;
+
+        case WindowFunctionType.PERCENT_CHANGE: {
+          // (value - LAG(value)) / NULLIF(LAG(value), 0)
+          // Note: LAG() is evaluated twice. PostgreSQL does not deduplicate window function
+          // calls, so this is slightly suboptimal. A CTE-based approach could avoid this,
+          // but the extra complexity is not warranted for the typical result set sizes.
+          const lagExpr = `LAG(${sourceRef}, 1) ${overClause([partitionClause, `ORDER BY ${orderByRef}`])}`;
+          expr = `(${sourceRef} - ${lagExpr}) / NULLIF(${lagExpr}, 0)`;
+          break;
+        }
+
+        case WindowFunctionType.MOVING_AVG: {
+          const windowSize = wf.windowSize ?? 3;
+          // Window frame bounds must be literal integers per SQL spec — cannot be parameterized
+          const preceding = windowSize - 1;
+          expr = `AVG(${sourceRef}) ${overClause([
+            partitionClause,
+            `ORDER BY ${orderByRef}`,
+            `ROWS BETWEEN ${preceding} PRECEDING AND CURRENT ROW`,
+          ])}`;
+          break;
+        }
+
+        default:
+          this.logger.warn(`PostgreSQLAggregationCompiler: unsupported window function '${wf.type}'`);
+          expr = 'NULL';
+      }
+
+      return { selectExpr: `${expr} AS ${ref}` };
+    });
+  }
+
+  // ── ORDER BY Clause ─────────────────────────────────────────
+
+  private buildOrderByClause(expression: AggregationExpression): string {
+    const parts: string[] = [];
+
+    if (expression.orderBy.length > 0) {
+      for (const ob of expression.orderBy) {
+        const dir = ob.direction === SortDirection.ASC ? 'ASC' : 'DESC';
+        parts.push(`${this.quoteIdentifier(ob.ref)} ${dir}`);
+      }
+    } else {
+      // Check per-dimension sort
+      for (const dim of expression.dimensions) {
+        if (dim.sort) {
+          if (dim.sort.by === DimensionSortBy.MEASURE && dim.sort.measureRef) {
+            const dir = dim.sort.direction === SortDirection.ASC ? 'ASC' : 'DESC';
+            parts.push(`${this.quoteIdentifier(dim.sort.measureRef)} ${dir}`);
+          } else {
+            const dir = dim.sort.direction === SortDirection.ASC ? 'ASC' : 'DESC';
+            parts.push(`${this.quoteIdentifier(dim.ref)} ${dir}`);
+          }
+          break; // Only use first dimension's sort
+        }
+      }
+
+      // Default: first dimension ascending
+      if (parts.length === 0 && expression.dimensions.length > 0) {
+        parts.push(`${this.quoteIdentifier(expression.dimensions[0]!.ref)} ASC`);
+      }
+    }
+
+    return parts.length > 0 ? `ORDER BY ${parts.join(', ')}` : '';
+  }
+
+  // ── Field Resolution ────────────────────────────────────────
+
+  /**
+   * Resolve a physical field path to a fully-qualified SQL column reference.
+   *
+   * Always qualifies with table/alias to prevent "ambiguous column reference"
+   * errors when JOINs are present.
+   *
+   * For joined fields: "alias"."field"
+   * For main table fields: "table"."field"
+   */
+  private resolveFieldPath(
+    physicalPath: string,
+    joinAlias: string | undefined,
+    table: string,
+  ): string {
+    if (joinAlias) {
+      // Joined field: alias.field → "alias"."field"
+      const fieldName = physicalPath.includes('.')
+        ? physicalPath.split('.').slice(1).join('.')
+        : physicalPath;
+      return `${this.quoteIdentifier(joinAlias)}.${this.quoteIdentifier(fieldName)}`;
+    }
+
+    // Main table field — always qualify with table name to prevent ambiguity
+    return `${this.quoteIdentifier(table)}.${this.quoteIdentifier(physicalPath)}`;
+  }
+
+  // ── Utilities ───────────────────────────────────────────────
+
+  /**
+   * Escape special LIKE pattern characters (%, _, \) in user-supplied values.
+   * Consistent with PostgreSQLFilterBackendService's LIKE escaping.
+   */
+  private escapeLikeValue(value: unknown): string {
+    return String(value)
+      .replace(/\\/g, '\\\\')
+      .replace(/%/g, '\\%')
+      .replace(/_/g, '\\_');
+  }
+
+  /**
+   * Quote a SQL identifier (table or column name) to prevent injection
+   * and handle reserved words.
+   */
+  private quoteIdentifier(name: string): string {
+    // Replace any double quotes in the name to prevent injection
+    const safe = name.replace(/"/g, '""');
+    return `"${safe}"`;
+  }
+}
+
+// ── SQL Build Context ─────────────────────────────────────────
+
+/**
+ * Tracks positional parameters ($1, $2, ...) during SQL construction.
+ * Ensures all values are parameterized — no string interpolation of user data.
+ */
+class SqlBuildContext {
+  readonly params: unknown[] = [];
+
+  /**
+   * Add a parameter and return its positional placeholder ($N).
+   */
+  addParam(value: unknown): string {
+    this.params.push(value);
+    return `$${this.params.length}`;
+  }
+}