fix(api): aggregate measurements before applying the take limit

Push range-aware aggregation into Postgres via `date_trunc` so the
bucket cap applies AFTER bucketising, not before. A 1-year
`aggregate=daily` request on a minute-by-minute pulse account now
walks every row in the window and returns up to 365 daily buckets
instead of silently truncating to the first N raw rows.

Gate the aggregation branch on an explicit `aggregate` query param.
Callers that pass `from`/`to` without `aggregate` (the iOS path)
keep the raw `MeasurementWireDTO` wire shape — the v1.5 locked
contract stays byte-stable. The new `monthly` grain bounds
multi-year "All time" charts at 24 buckets per type.
This commit is contained in:
Marc-André Bombeck committed 2026-05-16 02:32:36 +02:00
1 parent b3f88026f0
commit 0d256230ef
5 files changed
+289 -58

No files matched your search

@@ -5,6 +5,8 @@ import {
rangeLengthDays,
DAILY_AGGREGATE_THRESHOLD_DAYS,
WEEKLY_AGGREGATE_THRESHOLD_DAYS,
MONTHLY_AGGREGATE_THRESHOLD_DAYS,
BUCKET_CAP,
} from "../range-aggregation";
describe("range-aggregation", () => {
@@ -23,21 +25,39 @@ describe("range-aggregation", () => {
expect(pickAggregateGrain(WEEKLY_AGGREGATE_THRESHOLD_DAYS)).toBe("daily");
});
it("returns weekly for ranges over one year", () => {
it("returns weekly for ranges over one year up to two years", () => {
expect(pickAggregateGrain(WEEKLY_AGGREGATE_THRESHOLD_DAYS + 1)).toBe(
"weekly",
);
expect(pickAggregateGrain(1000)).toBe("weekly");
expect(pickAggregateGrain(MONTHLY_AGGREGATE_THRESHOLD_DAYS)).toBe(
"weekly",
);
});
it("returns monthly for ranges over two years", () => {
expect(pickAggregateGrain(MONTHLY_AGGREGATE_THRESHOLD_DAYS + 1)).toBe(
"monthly",
);
expect(pickAggregateGrain(3650)).toBe("monthly");
});
it("honours an explicit grain override", () => {
expect(pickAggregateGrain(7, "daily")).toBe("daily");
expect(pickAggregateGrain(7, "weekly")).toBe("weekly");
expect(pickAggregateGrain(7, "monthly")).toBe("monthly");
// "raw" override falls through to the threshold ladder.
expect(pickAggregateGrain(500, "raw")).toBe("weekly");
});
});
describe("BUCKET_CAP", () => {
it("caps daily at 365 buckets and monthly at 24", () => {
expect(BUCKET_CAP.daily).toBe(365);
expect(BUCKET_CAP.monthly).toBe(24);
expect(BUCKET_CAP.weekly).toBeGreaterThan(BUCKET_CAP.monthly);
});
});
describe("rangeLengthDays", () => {
it("counts inclusive days for the same calendar window", () => {
const from = new Date("2026-05-01T00:00:00.000Z");
@@ -98,5 +118,28 @@ describe("range-aggregation", () => {
const types = new Set(out.map((r) => r.type));
expect(types).toEqual(new Set(["PULSE", "WEIGHT"]));
});
it("collapses to one row per UTC calendar month with monthly", () => {
const a = new Date("2025-01-05T10:00:00.000Z");
const b = new Date("2025-01-20T10:00:00.000Z");
const c = new Date("2025-02-10T10:00:00.000Z");
const rows = [
{ type: "WEIGHT", value: 75, measuredAt: a },
{ type: "WEIGHT", value: 76, measuredAt: b },
{ type: "WEIGHT", value: 77, measuredAt: c },
];
const out = aggregateRows(rows, "monthly");
expect(out).toHaveLength(2);
expect(out[0].count).toBe(2);
expect(out[0].avg).toBeCloseTo(75.5, 5);
expect(out[1].count).toBe(1);
expect(out[1].avg).toBe(77);
expect(out[0].bucketStart.toISOString()).toBe(
"2025-01-01T00:00:00.000Z",
);
expect(out[1].bucketStart.toISOString()).toBe(
"2025-02-01T00:00:00.000Z",
);
});
});
});
+32 -12
View File
@@ -22,26 +22,41 @@
export const DAILY_AGGREGATE_THRESHOLD_DAYS = 90;
export const WEEKLY_AGGREGATE_THRESHOLD_DAYS = 365;
export const MONTHLY_AGGREGATE_THRESHOLD_DAYS = 730;
export type AggregateGrain = "raw" | "daily" | "weekly";
export type AggregateGrain = "raw" | "daily" | "weekly" | "monthly";
/**
* Maximum bucket count per grain. Bounds the aggregated response shape
* so a multi-year window never paints more buckets than the chart can
* reasonably absorb. Applied after bucketising, NOT before — the SQL
* aggregation always sees the full row set inside the window.
*/
export const BUCKET_CAP: Record<Exclude<AggregateGrain, "raw">, number> = {
daily: 365,
weekly: 105, // ~2 years of weeks; the monthly grain kicks in past 730 d
monthly: 24,
};
/**
* Pick the bucket grain for a date window. `raw` returns the
* measurements unchanged (legacy behaviour); `daily` collapses to one
* row per UTC day per type with avg / count; `weekly` collapses to one
* row per ISO week per type.
* row per ISO week per type; `monthly` collapses to one row per UTC
* calendar month per type.
*
* The thresholds favour the user's perceived smoothness over absolute
* resolution. Charts that draw 7 / 30 / 90 days of pulse stay raw —
* the in-browser daily bucket already does the right thing. The "all
* time" range pulls daily aggregates; multi-year scopes (rare today,
* common with Apple Health backfill) pull weekly.
* the in-browser daily bucket already does the right thing. Charts
* past 90 d switch to daily, past 365 d to weekly, past 730 d to
* monthly (the "All time" chart on a multi-year account).
*/
export function pickAggregateGrain(
rangeDays: number,
explicit?: AggregateGrain,
): AggregateGrain {
if (explicit && explicit !== "raw") return explicit;
if (rangeDays > MONTHLY_AGGREGATE_THRESHOLD_DAYS) return "monthly";
if (rangeDays > WEEKLY_AGGREGATE_THRESHOLD_DAYS) return "weekly";
if (rangeDays > DAILY_AGGREGATE_THRESHOLD_DAYS) return "daily";
return "raw";
@@ -69,15 +84,14 @@ interface RawRow {
}
/**
* In-memory daily / weekly aggregation. The route uses this when the
* client requests an aggregated grain — Postgres pre-aggregates would
* be faster, but the row volume is already bounded by the from/to
* window and the per-type ceiling, so a single linear pass is enough
* for v1.4.28 and keeps the helper portable to the test harness.
* In-memory daily / weekly / monthly aggregation. Used by the route's
* fallback path and by the test harness — the production path runs the
* `aggregateRowsSql` query so the take cap never applies before
* bucketising (v1.4.28 R4-CODE-C1).
*/
export function aggregateRows(
rows: RawRow[],
grain: "daily" | "weekly",
grain: "daily" | "weekly" | "monthly",
): AggregatedRow[] {
const buckets = new Map<
string,
@@ -111,12 +125,18 @@ export function aggregateRows(
.sort((a, b) => a.bucketStart.getTime() - b.bucketStart.getTime());
}
function bucketStartFor(d: Date, grain: "daily" | "weekly"): Date {
function bucketStartFor(
d: Date,
grain: "daily" | "weekly" | "monthly",
): Date {
if (grain === "daily") {
return new Date(
Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()),
);
}
if (grain === "monthly") {
return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1));
}
// Weekly — anchor to the start of the ISO week (Monday) in UTC.
const day = d.getUTCDay() || 7; // Sunday → 7
const monday = new Date(
+4 -2
View File
@@ -254,9 +254,11 @@ export const listMeasurementsSchema = z.object({
.default("measuredAt"),
sortDir: z.enum(["asc", "desc"]).optional().default("desc"),
// v1.4.28 FB-D2 — bucket hint for range-aware queries. When set the
// GET handler downsamples server-side via `aggregateRows` and returns
// GET handler runs a server-side `date_trunc` aggregation and returns
// one row per bucket per type rather than the raw measurement rows.
aggregate: z.enum(["raw", "daily", "weekly"]).optional(),
// Omitting `aggregate` keeps the raw wire shape (iOS contract); the
// chart-data client must opt in explicitly.
aggregate: z.enum(["raw", "daily", "weekly", "monthly"]).optional(),
});
export const createBatchMeasurementSchema = z.object({