turbine-orm 0.81.0 → 0.90.0

package/dist/query/aggregates.d.ts

@@ -29,6 +29,16 @@ import type { BuilderCtx } from './where.js';
  * one policy.
  */
 export declare function assertAggregatePiiOptIn(table: string, meta: TableMetadata | undefined, field: string, column: string, usage: string, includePii: boolean | undefined): void;
+/**
+ * `by` is required, and must be a non-empty array of field names and
+ * `{ field, path }` JSON keys. Checked before anything reads it: a missing
+ * `by` was a TypeError ("args.by is not iterable"), a string was iterated
+ * character by character ("Unknown field \"n\""), an empty array emitted
+ * `GROUP BY ` with nothing after it for the server to reject, and a `null`
+ * entry was a TypeError. Exported for PowqlInterface, whose groupBy takes
+ * the same `by`.
+ */
+export declare function assertGroupByKeys(table: string, by: unknown): void;
 export declare function buildGroupBy<T extends object>(qi: BuilderCtx, args: GroupByArgs<T>): DeferredQuery<Record<string, unknown>[]>;
 export declare function buildGroupByOrderBy(qi: BuilderCtx, orderBy: GroupByOrderBy | GroupByOrderBy[], byOrderExprs: Map<string, string>, aggOrderExprs: Map<string, string>): string;
 /**
@@ -98,6 +108,12 @@ export declare function buildHavingClauses<T extends object>(qi: BuilderCtx, hav
  * shorthand for equality. Operands are not numeric-only: `_min` / `_max`
  * return a stored cell, so `MIN("title") > 'm'` is as valid as
  * `SUM("views") > 10`. Unknown operator keys throw {@link ValidationError}.
+ *
+ * `operandType` is the column type a `_min` / `_max` operand is compared with.
+ * When given, each operand (and each `in` / `notIn` element) is bound through
+ * the where compiler's {@link whereMod.textComparedOperand}, so on MySQL a
+ * number compared with the MIN of a text column is sent as text rather than
+ * compared numerically (`'0zz' = 0` is true there).
  */
-export declare function buildHavingNumericClauses(qi: BuilderCtx, expr: string, filter: unknown, params: unknown[]): string[];
+export declare function buildHavingNumericClauses(qi: BuilderCtx, expr: string, filter: unknown, params: unknown[], operandType?: string): string[];
 export declare function buildAggregate<T extends object>(qi: BuilderCtx, args: AggregateArgs<T>): DeferredQuery<AggregateResult<T>>;

package/dist/query/aggregates.js

@@ -10,11 +10,11 @@
  */
 import { UnsupportedFeatureError, ValidationError } from '../errors.js';
 import { snakeToCamel } from '../schema.js';
-import { dedupeColumnList, isJsonPathOrderBy, isUnmatchedPlainObject, isVectorOrderBy, isWhereOperator, normalizeOrderBy, orderByEntries, } from './filters.js';
+import { assertEqualityOperand, dedupeColumnList, isJsonPathOrderBy, isUnmatchedPlainObject, isVectorOrderBy, isWhereOperator, normalizeOrderBy, orderByEntries, setOwn, } from './filters.js';
 import { assertOrderDirection, resolveSkipGlobalFilters, resolveUnsafeFlag } from './types.js';
-import { isTemporalInfinity, ownLookup, parseDbDate, resolveColumnName, warnRedundantSortTerm } from './utils.js';
+import { isTemporalInfinity, ownLookup, parseDbDate, resolveColumnName, suggestKey, warnRedundantSortTerm, } from './utils.js';
 import * as whereMod from './where.js';
-import { assertWhereDepth } from './where-compile.js';
+import { assertWhereDepth, combinatorBranches } from './where-compile.js';
 /**
  * Enforce the PII contract on the aggregate surface. A PII-tagged
  * (`defineSchema` `pii: true`) column is excluded from every default
@@ -44,7 +44,39 @@ export function assertAggregatePiiOptIn(table, meta, field, column, usage, inclu
         '`_count` over a PII column (a count, not a value) and `where` / `orderBy` / `having` on PII ' +
         'columns need no opt-in.');
 }
+/**
+ * `by` is required, and must be a non-empty array of field names and
+ * `{ field, path }` JSON keys. Checked before anything reads it: a missing
+ * `by` was a TypeError ("args.by is not iterable"), a string was iterated
+ * character by character ("Unknown field \"n\""), an empty array emitted
+ * `GROUP BY ` with nothing after it for the server to reject, and a `null`
+ * entry was a TypeError. Exported for PowqlInterface, whose groupBy takes
+ * the same `by`.
+ */
+export function assertGroupByKeys(table, by) {
+    if (!Array.isArray(by)) {
+        const example = typeof by === 'string' ? `, for example \`by: [${JSON.stringify(by)}]\`` : '';
+        throw new ValidationError(`groupBy on table "${table}" requires \`by\`, an array of field names${example}; got ${describeByValue(by)}.`);
+    }
+    if (by.length === 0) {
+        throw new ValidationError(`groupBy on table "${table}" requires at least one \`by\` key. To aggregate every row as one group, use aggregate().`);
+    }
+    for (const entry of by) {
+        if (typeof entry !== 'string' && (typeof entry !== 'object' || entry === null || Array.isArray(entry))) {
+            throw new ValidationError(`groupBy \`by\` on table "${table}" takes field names and { field, path } JSON keys; got ${describeByValue(entry)}.`);
+        }
+    }
+}
+/** The kind of a bad `by` value, never the value itself. */
+function describeByValue(value) {
+    if (value === null || value === undefined)
+        return String(value);
+    if (Array.isArray(value))
+        return 'an array';
+    return typeof value === 'object' ? 'an object' : `a ${typeof value}`;
+}
 export function buildGroupBy(qi, args) {
+    assertGroupByKeys(qi.table, args.by);
     const meta = qi.schema.tables[qi.table];
     // Up-front, so a bad `by` key is reported before anything else in the call,
     // and through `qi.toColumn` (the ONE `resolveColumnName` rule) rather than
@@ -243,6 +275,8 @@ export function buildGroupBy(qi, args) {
     buildAggregates('_avg', 'AVG', args._avg);
     buildAggregates('_min', 'MIN', args._min);
     buildAggregates('_max', 'MAX', args._max);
+    const percentiles = planPercentiles(qi, args._percentile, params, includePii, 'groupBy', claimResultKey);
+    selectExprs.push(...percentiles.map((plan) => plan.expr));
     let sql = `SELECT ${selectExprs.join(', ')} FROM ${fromSql} GROUP BY ${groupExprs.join(', ')}`;
     // HAVING, filter whole groups by their aggregate values.
     // Appends to the same `params` array, so placeholders continue from the
@@ -356,6 +390,8 @@ export function buildGroupBy(qi, args) {
                 restructured._min = minObj;
             if (hasMaxs)
                 restructured._max = maxObj;
+            if (percentiles.length > 0)
+                restructured._percentile = readPercentiles(qi, percentiles, row);
             return restructured;
         }),
         tag: `${qi.table}.groupBy`,
@@ -435,7 +471,9 @@ export function buildGroupByOrderBy(qi, orderBy, byOrderExprs, aggOrderExprs) {
     const pushOrderTerm = (expr, label, value) => {
         const first = seen.get(expr);
         if (first !== undefined) {
-            warnRedundantSortTerm(qi.table, 'groupBy orderBy', [{ key: label, first, resolved: expr }]);
+            warnRedundantSortTerm(whereMod.adviceLogger(qi), qi.table, 'groupBy orderBy', [
+                { key: label, first, resolved: expr },
+            ]);
             return;
         }
         seen.set(expr, label);
@@ -445,6 +483,9 @@ export function buildGroupByOrderBy(qi, orderBy, byOrderExprs, aggOrderExprs) {
     for (const [key, value] of orderByEntries(orderBy)) {
         if (value === undefined)
             continue;
+        if (key === '_percentile') {
+            throw new ValidationError(`groupBy orderBy on table "${qi.table}": ${PERCENTILE_NOT_ORDERABLE}`);
+        }
         // Aggregate ordering blocks.
         if (aggBlocks.has(key)) {
             if (key === '_count') {
@@ -529,7 +570,7 @@ export function resolveJsonPathTarget(qi, context, field, path) {
  * JSON paths push their text[] param here, after the WHERE params.
  */
 export function buildDistinctOnSource(qi, distinctOn, whereSql, params) {
-    if (qi.dialect.name !== 'postgresql') {
+    if (!qi.dialect.capabilities.distinctOn) {
         throw new UnsupportedFeatureError('DISTINCT ON row source (groupBy distinctOn)', qi.dialect.name, 'groupBy({ distinctOn }) requires PostgreSQL: SELECT DISTINCT ON is not portable.');
     }
     if (!Array.isArray(distinctOn.columns) || distinctOn.columns.length === 0) {
@@ -544,9 +585,9 @@ export function buildDistinctOnSource(qi, distinctOn, whereSql, params) {
     // twice (see `dedupeColumnList`). The orderBy below needs no equivalent: its
     // keys come from an object, and the DISTINCT ON columns lead the ORDER BY, so
     // a key repeating one of them is already merged by `orderParts`' construction.
-    const dedupedCols = dedupeColumnList(qi.tableMeta, distinctOn.columns);
+    const dedupedCols = dedupeColumnList(qi.tableMeta, distinctOn.columns, 'distinctOn.columns');
     if (dedupedCols)
-        warnRedundantSortTerm(qi.table, 'groupBy distinctOn.columns', dedupedCols.dropped);
+        warnRedundantSortTerm(whereMod.adviceLogger(qi), qi.table, 'groupBy distinctOn.columns', dedupedCols.dropped);
     const distinctCols = (dedupedCols?.columns ?? distinctOn.columns).map((c) => qi.q(qi.toColumn(c)));
     // DISTINCT ON expressions must lead the ORDER BY; the user's orderBy then
     // decides which row survives per combination.
@@ -610,6 +651,8 @@ export function buildHavingClauses(qi, having, params, jsonAggExprs, groupKeys,
     assertWhereDepth(depth, 'having');
     const clauses = [];
     for (const [key, value] of Object.entries(having)) {
+        // Same `undefined` rule as the where walk (`walkWhere`): the args seam
+        // removes it, and a key still holding it here is skipped.
         if (value === undefined)
             continue;
         // Top-level `_count` (no field) → COUNT(*) for the whole group.
@@ -641,9 +684,16 @@ export function buildHavingClauses(qi, having, params, jsonAggExprs, groupKeys,
             quotedCol ??= qi.q(qi.toColumn(key));
             return quotedCol;
         };
+        const plainAggregate = (agg) => agg.fn === 'AVG' ? avgCall(qi, qi.toColumn(key)) : `${agg.fn}(${columnExpr()})`;
         for (const agg of aggEntries) {
-            const expr = jsonAggExprs?.get(`${key}:${agg.key}`) ?? `${agg.fn}(${columnExpr()})`;
-            clauses.push(...buildHavingNumericClauses(qi, expr, agg.filter, params));
+            const jsonExpr = jsonAggExprs?.get(`${key}:${agg.key}`);
+            const expr = jsonExpr ?? plainAggregate(agg);
+            // `_min` / `_max` return the column's own stored value, so their operands
+            // bind the way a where operand against that column does.
+            const operandType = jsonExpr === undefined && (agg.fn === 'MIN' || agg.fn === 'MAX')
+                ? qi.columnPgTypeMap.get(qi.toColumn(key))
+                : undefined;
+            clauses.push(...buildHavingNumericClauses(qi, expr, agg.filter, params, operandType));
         }
     }
     return clauses;
@@ -670,12 +720,15 @@ function splitHavingField(qi, field, value) {
         if (fn) {
             aggEntries.push({ key: k, fn, filter: v });
         }
+        else if (k === '_percentile') {
+            throw new ValidationError(`groupBy having on "${qi.table}.${field}": ${PERCENTILE_NOT_ORDERABLE}`);
+        }
         else if (k.startsWith('_')) {
             throw new ValidationError(`Unknown aggregate "${k}" in having for field "${field}" on table "${qi.table}". ` +
                 `Supported: ${Object.keys(HAVING_AGGREGATE_FNS).join(', ')}.`);
         }
         else {
-            scalarKeys[k] = v;
+            setOwn(scalarKeys, k, v);
         }
     }
     if (aggEntries.length === 0)
@@ -685,12 +738,18 @@ function splitHavingField(qi, field, value) {
 /**
  * Compile a `having` AND / OR / NOT branch. Each condition is a nested
  * {@link HavingClause}; its own clauses are ANDed (parenthesized when there is
- * more than one) before being combined. `AND` contributes its parts directly
- * (the caller ANDs them), mirroring {@link buildWhereClause}'s combinator
- * shapes so HAVING and WHERE read the same way.
+ * more than one) before being combined. The branch shapes are the WHERE
+ * combinator rule ({@link combinatorBranches}), so HAVING and WHERE accept and
+ * refuse the same values and mean the same thing by them: `AND` contributes its
+ * parts directly (the caller ANDs them), `OR: []` matches no group, a `NOT`
+ * object negates the object as a whole, and a `NOT` array negates each branch.
  */
 function buildHavingCombinator(qi, key, value, params, jsonAggExprs, groupKeys, depth = 0) {
-    const conditions = Array.isArray(value) ? value : [value];
+    const branches = combinatorBranches(key, value, qi.table, 'having');
+    if (branches === null)
+        return [];
+    if (branches.length === 0)
+        return key === 'OR' ? ['1 = 0'] : [];
     // Same variable-arity shape as the WHERE combinators: an ARRAY branch writes
     // one parenthesized condition per element into the SQL text, so a
     // caller-sized `having.OR` is a new statement per length.
@@ -702,15 +761,11 @@ function buildHavingCombinator(qi, key, value, params, jsonAggExprs, groupKeys,
     // them through the cache later cannot silently reopen the hole, and so the
     // rule reads the same in both clause compilers. The DEPTH cap above is the
     // half of this that bites here and now.
-    if (Array.isArray(value) && key !== 'NOT')
+    if (Array.isArray(value))
         qi.markVariableArity();
     const parts = [];
-    for (const condition of conditions) {
-        if (!isUnmatchedPlainObject(condition)) {
-            throw new ValidationError(`Invalid having "${key}" on table "${qi.table}": expected ` +
-                `${key === 'OR' ? 'an array of having objects' : 'a having object (or an array of them)'}.`);
-        }
-        const sub = buildHavingClauses(qi, condition, params, jsonAggExprs, groupKeys, depth + 1);
+    for (const branch of branches) {
+        const sub = buildHavingClauses(qi, branch, params, jsonAggExprs, groupKeys, depth + 1);
         if (sub.length === 0)
             continue;
         parts.push(sub.length === 1 ? sub[0] : `(${sub.join(' AND ')})`);
@@ -721,6 +776,8 @@ function buildHavingCombinator(qi, key, value, params, jsonAggExprs, groupKeys,
         return parts;
     if (key === 'OR')
         return [`(${parts.join(' OR ')})`];
+    if (Array.isArray(value))
+        return parts.map((part) => `NOT (${part})`);
     return [`NOT (${parts.join(' AND ')})`];
 }
 /**
@@ -774,6 +831,7 @@ function buildHavingScalarClauses(qi, field, value, params, groupKeys) {
                 .join(', ')} on ${ref.label} in having for table "${qi.table}".`);
     }
     else {
+        assertEqualityOperand(value, { column: ref.label, table: qi.table, kind: 'scalar' });
         params.push(value);
         clauses.push(`${ref.expr} = ${qi.p(params.length)}`);
     }
@@ -785,14 +843,22 @@ function buildHavingScalarClauses(qi, field, value, params, groupKeys) {
  * shorthand for equality. Operands are not numeric-only: `_min` / `_max`
  * return a stored cell, so `MIN("title") > 'm'` is as valid as
  * `SUM("views") > 10`. Unknown operator keys throw {@link ValidationError}.
+ *
+ * `operandType` is the column type a `_min` / `_max` operand is compared with.
+ * When given, each operand (and each `in` / `notIn` element) is bound through
+ * the where compiler's {@link whereMod.textComparedOperand}, so on MySQL a
+ * number compared with the MIN of a text column is sent as text rather than
+ * compared numerically (`'0zz' = 0` is true there).
  */
-export function buildHavingNumericClauses(qi, expr, filter, params) {
+export function buildHavingNumericClauses(qi, expr, filter, params, operandType) {
+    const bind = (value) => operandType === undefined ? value : whereMod.textComparedOperand(qi, operandType, value);
+    const bindList = (value) => operandType !== undefined && Array.isArray(value) ? value.map(bind) : value;
     if (filter === null) {
         throw new ValidationError(`Invalid having filter on "${expr}" for table "${qi.table}": expected a value or operator object.`);
     }
     // Bare value (number, string, boolean, Date, …) → equality.
     if (typeof filter !== 'object' || filter instanceof Date) {
-        params.push(filter);
+        params.push(bind(filter));
         return [`${expr} = ${qi.p(params.length)}`];
     }
     const op = filter;
@@ -805,35 +871,35 @@ export function buildHavingNumericClauses(qi, expr, filter, params) {
     }
     const clauses = [];
     if (op.equals !== undefined) {
-        params.push(op.equals);
+        params.push(bind(op.equals));
         clauses.push(`${expr} = ${qi.p(params.length)}`);
     }
     if (op.not !== undefined) {
-        params.push(op.not);
+        params.push(bind(op.not));
         clauses.push(`${expr} != ${qi.p(params.length)}`);
     }
     if (op.gt !== undefined) {
-        params.push(op.gt);
+        params.push(bind(op.gt));
         clauses.push(`${expr} > ${qi.p(params.length)}`);
     }
     if (op.gte !== undefined) {
-        params.push(op.gte);
+        params.push(bind(op.gte));
         clauses.push(`${expr} >= ${qi.p(params.length)}`);
     }
     if (op.lt !== undefined) {
-        params.push(op.lt);
+        params.push(bind(op.lt));
         clauses.push(`${expr} < ${qi.p(params.length)}`);
     }
     if (op.lte !== undefined) {
-        params.push(op.lte);
+        params.push(bind(op.lte));
         clauses.push(`${expr} <= ${qi.p(params.length)}`);
     }
     if (op.in !== undefined) {
-        params.push(qi.inParam(op.in));
+        params.push(qi.inParam(bindList(op.in)));
         clauses.push(qi.inClause(expr, qi.p(params.length), false));
     }
     if (op.notIn !== undefined) {
-        params.push(qi.inParam(op.notIn));
+        params.push(qi.inParam(bindList(op.notIn)));
         clauses.push(qi.inClause(expr, qi.p(params.length), true));
     }
     return clauses;
@@ -918,9 +984,19 @@ function isExactNumericType(pgType) {
 }
 /** `AVG(col)`, float-cast unless the source column is exact (see {@link isExactNumericType}). */
 function plainAvgExpr(qi, col) {
-    const inner = `AVG(${qi.q(col)})`;
+    const inner = avgCall(qi, col);
     return isExactNumericType(whereMod.getColumnPgType(qi, col)) ? inner : qi.castAgg(inner, 'float');
 }
+/**
+ * `AVG(col)` over a plain column, with the input widened where the engine
+ * would otherwise average an integer column as an integer (see
+ * {@link Dialect.averageArgument}). Shared by SELECT and HAVING, so a filter
+ * on `_avg` compares the same value the result reports.
+ */
+function avgCall(qi, col) {
+    const ref = qi.q(col);
+    return `AVG(${qi.dialect.averageArgument?.(ref, whereMod.getColumnPgType(qi, col)) ?? ref})`;
+}
 /**
  * A `_sum` / `_avg` value over a plain column: the driver's value verbatim
  * for an exact source type (see {@link isExactNumericType}), a JS number for
@@ -933,6 +1009,156 @@ function sumAvgValue(qi, col, value) {
         return value;
     return Number(value);
 }
+// ---------------------------------------------------------------------------
+// _percentile (PostgreSQL: percentile_cont / percentile_disc)
+// ---------------------------------------------------------------------------
+/** Why an engine refuses `_percentile`, keyed by dialect name. */
+const PERCENTILE_HINT = {
+    mysql: 'Percentile aggregates need PostgreSQL; MySQL has no percentile_cont/percentile_disc.',
+    sqlite: 'Percentile aggregates need PostgreSQL; SQLite has percentile functions only in builds compiled with ' +
+        'SQLITE_ENABLE_PERCENTILE, which node:sqlite cannot be assumed to have.',
+    mssql: 'Percentile aggregates are not available on SQL Server in this release: PERCENTILE_CONT is a window ' +
+        'function there, not an aggregate.',
+};
+const PERCENTILE_SPEC_KEYS = ['p', 'method'];
+const PERCENTILE_METHODS = ['cont', 'disc'];
+const PERCENTILE_NOT_ORDERABLE = 'ordering or filtering groups by _percentile is not supported yet.';
+/**
+ * Compile `_percentile` into SELECT expressions, binding each fraction (or
+ * fraction array) as a `float8` / `float8[]` parameter so the SQL text does not
+ * depend on the values or on how many there are.
+ *
+ * Refusals, all before any SQL runs: E017 on a dialect without
+ * `supportsPercentileAggregates`; E003 for a spec that is not `{ p, method? }`,
+ * a fraction outside [0, 1] or not a finite number, an empty array, an unknown
+ * method, `cont` on a date/time column (`percentile_cont` has no temporal
+ * form), a JSON-path target, and two keys naming one column. Both methods need
+ * `includePii: UNSAFE` on a PII column: `disc` returns a stored cell, and so
+ * does `cont` at p = 0 or 1 or over a one-row group.
+ */
+function planPercentiles(qi, spec, params, includePii, operation, claimResultKey) {
+    if (spec === undefined)
+        return [];
+    const where = `${operation} _percentile on table "${qi.table}"`;
+    if (typeof spec !== 'object' || spec === null || Array.isArray(spec)) {
+        throw new ValidationError(`${where} must be an object of field -> { p, method? }, e.g. { latencyMs: { p: 0.95 } }.`);
+    }
+    const entries = Object.entries(spec).filter(([, v]) => v !== undefined && v !== null);
+    if (entries.length === 0)
+        return [];
+    if (qi.dialect.supportsPercentileAggregates !== true) {
+        throw new UnsupportedFeatureError('_percentile', qi.dialect.name, PERCENTILE_HINT[qi.dialect.name] ?? 'Percentile aggregates need PostgreSQL.');
+    }
+    const meta = qi.schema.tables[qi.table];
+    const plans = [];
+    const aliases = new Set();
+    for (const [key, entry] of entries) {
+        const label = `${where}, field "${key}"`;
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+            throw new ValidationError(`${label}: expected { p, method? }, received ${describeValue(entry)}.`);
+        }
+        if ('path' in entry) {
+            throw new ValidationError(`${label}: a JSON-path target is not supported for _percentile yet.`);
+        }
+        for (const k of Object.keys(entry)) {
+            if (!PERCENTILE_SPEC_KEYS.includes(k)) {
+                const hint = suggestKey(k, PERCENTILE_SPEC_KEYS);
+                throw new ValidationError(`${label}: unknown key "${k}".${hint ? ` Did you mean "${hint}"?` : ''} Expected { p, method? }.`);
+            }
+        }
+        const { p, method = 'cont' } = entry;
+        if (!PERCENTILE_METHODS.includes(method)) {
+            throw new ValidationError(`${label}: method must be 'cont' or 'disc', received ${describeValue(method)}.`);
+        }
+        if (Array.isArray(p)) {
+            if (p.length === 0)
+                throw new ValidationError(`${label}: p is an empty array. Give at least one fraction.`);
+            for (const fraction of p)
+                assertFraction(fraction, label);
+        }
+        else {
+            assertFraction(p, label);
+        }
+        const col = qi.toColumn(key);
+        if (method === 'cont' && qi.tableMeta.dateColumns.has(col)) {
+            throw new ValidationError(`${label}: method 'cont' interpolates and needs a numeric or interval column, and "${col}" is a ` +
+                "date/time column. Use method: 'disc' for an actual stored value.");
+        }
+        assertAggregatePiiOptIn(qi.table, meta, key, col, `${operation} _percentile`, includePii);
+        const alias = `_percentile_${col}`;
+        if (aliases.has(alias)) {
+            throw new ValidationError(`${label}: column "${col}" is already named by another _percentile key.`);
+        }
+        aliases.add(alias);
+        claimResultKey?.(alias, `_percentile of column "${col}"`);
+        params.push(Array.isArray(p) ? [...p] : p);
+        const fractions = `${qi.p(params.length)}::float8${Array.isArray(p) ? '[]' : ''}`;
+        let expr = `percentile_${method}(${fractions}) WITHIN GROUP (ORDER BY ${qi.q(col)})`;
+        // numeric[] has a driver parser that returns JS numbers, which rounds an
+        // exact value the scalar form returns as text. Read the array as text too.
+        if (Array.isArray(p) && method === 'disc' && isDecimalType(whereMod.getColumnPgType(qi, col))) {
+            expr = `(${expr})::text[]`;
+        }
+        plans.push({
+            expr: `${expr} AS ${qi.q(alias)}`,
+            alias,
+            field: qi.tableMeta.reverseColumnMap[col] ?? snakeToCamel(col),
+            col,
+        });
+    }
+    return plans;
+}
+function assertFraction(value, label) {
+    if (typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1)
+        return;
+    throw new ValidationError(`${label}: p must be a fraction from 0 to 1 (0.95 for the 95th percentile), or an array of them, ` +
+        `received ${describeValue(value)}.`);
+}
+function describeValue(value) {
+    if (typeof value === 'string')
+        return `'${value}'`;
+    if (Array.isArray(value))
+        return 'an array';
+    if (value !== null && typeof value === 'object')
+        return 'an object';
+    return String(value);
+}
+function isDecimalType(pgType) {
+    const paren = pgType.indexOf('(');
+    const base = (paren === -1 ? pgType : pgType.slice(0, paren)).trim().toLowerCase();
+    return base === 'numeric' || base === 'decimal';
+}
+/** The `_percentile` block of one result row, keyed by canonical field. */
+function readPercentiles(qi, plans, row) {
+    const out = {};
+    for (const plan of plans) {
+        const value = row[plan.alias];
+        setOwn(out, plan.field, Array.isArray(value)
+            ? value.map((element) => percentileElement(qi, plan.col, element))
+            : percentileElement(qi, plan.col, value));
+    }
+    return out;
+}
+/**
+ * One percentile value, read the way the column itself reads: a date/time
+ * value through {@link temporalAggValue} (element by element in the array
+ * form, where the driver may hand back text or a bare infinity), and an int8
+ * that the array form delivers as text through the same exact-number rule the
+ * scalar int8 parser applies. `null` over zero rows.
+ */
+function percentileElement(qi, col, value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'string' && isInt8Type(whereMod.getColumnPgType(qi, col))) {
+        const n = Number(value);
+        return Number.isSafeInteger(n) ? n : value;
+    }
+    return temporalAggValue(qi, col, value);
+}
+function isInt8Type(pgType) {
+    const base = pgType.trim().toLowerCase();
+    return base === 'int8' || base === 'bigint';
+}
 export function buildAggregate(qi, args) {
     qi.currentSkip = resolveSkipGlobalFilters(args.skipGlobalFilters);
     // Resolved once, up front: see buildGroupBy.
@@ -1019,6 +1245,8 @@ export function buildAggregate(qi, args) {
             }
         }
     }
+    const percentiles = planPercentiles(qi, args._percentile, params, includePii, 'aggregate');
+    selectExprs.push(...percentiles.map((plan) => plan.expr));
     if (selectExprs.length === 0) {
         selectExprs.push(`${qi.castAgg('COUNT(*)', 'int')} AS _count`);
     }
@@ -1094,6 +1322,9 @@ export function buildAggregate(qi, args) {
                 aggResult._min = minObj;
             if (hasMaxs)
                 aggResult._max = maxObj;
+            if (percentiles.length > 0) {
+                aggResult._percentile = readPercentiles(qi, percentiles, row);
+            }
             return aggResult;
         },
         tag: `${qi.table}.aggregate`,

package/dist/query/batched-loader.d.ts

@@ -149,14 +149,23 @@ export declare function defaultProjectionFields(meta: TableMetadata, includePii:
     visible: string[];
 } | undefined;
 /**
- * Adjust a `select`/`omit` pair so that `fields` are guaranteed present in the
- * query result, returning the adjusted projection plus the list of fields that
- * were added ONLY for stitching and must be stripped from the final entities.
+ * Key under which {@link includeKeysForBatching} records the fields IT added to
+ * a `select`, as a `ReadonlySet<string>` of field names.
  *
- * Used both for the base query (parent keys) and each follow-up query (child
- * keys) so a caller's `select: { title: true }` on a relation still stitches even
- * though the FK was not requested, and the FK never appears in the output.
+ * Why it exists: naming a PII-tagged column in `select` is refused unless the
+ * query passes `includePii: UNSAFE` (see `resolveProjection`), and the loader
+ * has to project a correlation or ordering column that may itself be tagged.
+ * That column is stripped from every entity before the caller sees it, so it is
+ * the one legitimate way a PII name reaches a `select` without the caller
+ * writing it. The marker is a symbol key: `Object.keys`, `Object.entries`,
+ * spreads of a parsed body and `JSON.stringify` never see one, and
+ * `JSON.parse` cannot produce one, so request data cannot forge the exemption.
  */
+export declare const STITCH_ONLY_FIELDS: unique symbol;
+/** The fields the batched loader (not the caller) added to this `select`, if any. */
+export declare function stitchOnlyFields(select: object | undefined): ReadonlySet<string> | undefined;
+/** Record `fields` on `select` as added by an engine loader, not by the caller. Returns `select`. */
+export declare function markStitchOnly(select: Record<string, boolean>, fields: readonly string[]): Record<string, boolean>;
 /**
  * The two projection SHAPE rules from `resolveProjection`, checked on the RAW
  * caller args BEFORE `includeKeysForBatching` adjusts them. The adjustment
@@ -167,6 +176,16 @@ export declare function defaultProjectionFields(meta: TableMetadata, includePii:
  * resolver so the two strategies refuse identically, word for word.
  */
 export declare function assertProjectionShape(table: string, select: Record<string, boolean> | undefined, omit: Record<string, boolean> | undefined): void;
+/**
+ * Adjust a `select`/`omit` pair so that `fields` are guaranteed present in the
+ * query result, returning the adjusted projection plus the list of fields that
+ * were added ONLY for stitching and must be stripped from the final entities.
+ *
+ * Used both for the base query (parent keys) and each follow-up query (child
+ * keys) so a caller's `select: { title: true }` on a relation still stitches even
+ * though the FK was not requested, and the FK never appears in the output. A
+ * returned `select` carries {@link STITCH_ONLY_FIELDS} for the fields added here.
+ */
 export declare function includeKeysForBatching(
 /**
  * The table the projection is compiled against. `select` / `omit` keys are