Analytics · XB Field Notes

A window frame decides which rows one aggregate sees

Tue, 23 Feb 2027 00:00:00 +0000

A window partition determines which rows belong together; a window frame determines which of those rows feed a frame-sensitive calculation for the current row. Confusing these boundaries can turn a running total into a repeated subtotal or make last_value return the current value when the report expected the final value in the partition.

Defaults depend on ordering

In PostgreSQL, the default frame is RANGE from the partition’s beginning through the current row’s last peer. Peers have equal values for every expression in the window ORDER BY. With an order, a default running sum therefore includes all rows tied with the current row, including peers that appear later in the displayed output.

Without a window ORDER BY, all rows are peers and the default frame covers the whole partition. Thus sum(amount) OVER (PARTITION BY account) repeats an account total, while adding an order changes the calculation into an ordered cumulative result. Neither “the default is always the whole group” nor “the default adds exactly one row” describes both cases correctly.

The window order is separate from the final result order. An outer ORDER BY can arrange rows for display without changing the frame. Conversely, adding a unique identifier inside a RANGE window can split a peer group, altering the calculation rather than merely making the output prettier. Treat that change as a semantic decision.

Rows, value ranges, and peer groups

ROWS counts positions in the window ordering. A frame from two preceding rows through the current row contains at most three rows, fewer near the partition start. It does not mean three days or three minutes. If multiple events share a timestamp, include a suitable unique tie-breaker when their positional order must be deterministic.

RANGE uses ordering values and peer boundaries. With an offset, PostgreSQL requires one ordering expression and a compatible offset type; a timestamp order can use an interval. A value-based time range includes events by time difference, so its row count can grow during busy periods and shrink during quiet ones. GROUPS instead counts peer groups, allowing a frame to move by distinct ordering groups while retaining all their tied rows.

First_value, last_value, nth_value, and aggregates used as windows depend on the frame. Ranking and lag or lead have different semantics based on partition order; shrinking a frame does not make lag forget the preceding partition row. Check the function’s definition before applying one generic explanation to all window functions.

When it breaks

Last_value with an ordered default frame usually means the end of the current frame, not the end of the entire partition. With unique ordering, that is the current row. To repeat the partition’s final value, specify an ending boundary of UNBOUNDED FOLLOWING and provide an order that defines what “final” means. A chronological maximum and the value of the last chronological row are different questions.

Running totals can also surprise when tied dates receive the same cumulative number. This is expected peer behavior under the default RANGE frame. If the business wants each individual event to advance the total, use an explicit ROWS frame and deterministic event ordering. Do not eliminate genuine ties from a date-level report just to obtain a more familiar-looking curve.

Check it quickly

Save this as frames.sql and run psql -X -v ON_ERROR_STOP=1 -f frames.sql in a disposable PostgreSQL 18 database. Two events share day one, and a third belongs to day two. Temporary objects and inserted rows disappear on rollback.

\set ON_ERROR_STOP on
BEGIN;
CREATE TEMP TABLE sales (id integer, day integer, amount integer);
INSERT INTO sales VALUES (1,1,10),(2,1,20),(3,2,5);
CREATE TEMP VIEW framed AS
SELECT *,
 sum(amount) OVER (ORDER BY day) AS default_sum,
 sum(amount) OVER (ORDER BY day,id ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW) AS row_sum,
 last_value(amount) OVER (ORDER BY day,id) AS default_last,
 last_value(amount) OVER (ORDER BY day,id ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING) AS partition_last,
 sum(amount) OVER () AS whole_sum
FROM sales;
SELECT * FROM framed ORDER BY id;
DO $$ BEGIN
 IF (SELECT array_agg(default_sum ORDER BY id) FROM framed)
 IS DISTINCT FROM ARRAY[30,30,35]::bigint[] THEN RAISE EXCEPTION 'wrong peer frame'; END IF;
 IF (SELECT array_agg(row_sum ORDER BY id) FROM framed)
 IS DISTINCT FROM ARRAY[10,30,35]::bigint[] THEN RAISE EXCEPTION 'wrong row frame'; END IF;
 IF (SELECT array_agg(default_last ORDER BY id) FROM framed)
 IS DISTINCT FROM ARRAY[10,20,5] THEN RAISE EXCEPTION 'wrong current-frame end'; END IF;
 IF EXISTS (SELECT FROM framed WHERE partition_last IS DISTINCT FROM 5 OR whole_sum IS DISTINCT FROM 35) THEN
 RAISE EXCEPTION 'whole partition values wrong';
 END IF;
END $$;
ROLLBACK;

PostgreSQL 18.6 returned default sums 30, 30, 35: both first-day rows see the complete first-day peer group. The explicit ROWS sum, ordered by day and id, returned 10, 30, 35. The id deliberately defines the order between individual events; it is not included in the date-based default window.

The default last_value column returned 10, 20, 5 because its day-and-id order makes every row its own peer group. The full-partition frame returned 5 everywhere, while the unordered sum returned 35 everywhere. The assertions check these separate results and will fail if a frame is silently changed.

This small fixture establishes answer semantics, not resource costs. Frames that need future rows and large partitions can require substantial buffering or sorting. Inspect realistic execution plans and data distributions separately, preserving the tested tie and boundary behavior while tuning performance.

Sources

PostgreSQL window expressions, frame modes, offsets, and defaults, checked 2026-09-10.
PostgreSQL window functions, frame-sensitive functions and partition semantics, checked 2026-09-10.

GROUPING SETS build several aggregate views

Fri, 15 Jan 2027 00:00:00 +0000

GROUPING SETS asks one SQL statement to produce several aggregation levels. A sales report can return totals by region and product, region subtotals, and a grand total together. The result contains different kinds of rows, so identifying each row’s level is as important as calculating its amount correctly.

Declare the report’s levels

GROUPING SETS ((region,product),(region),()) specifies three groupings. The first yields one row for each observed region-product combination, the second one per region, and the empty set aggregates all selected input rows. This is a declaration of result semantics; the optimizer chooses how to execute it. It can share work across levels, but the syntax does not guarantee a particular number of physical scans or eliminate sorting and memory costs.

The shorthand ROLLUP(region,product) expands to these same prefixes, including the empty set. Reversing the columns changes the subtotal dimension. CUBE(region,product) also includes product-only totals, covering all subsets of its dimensions. Six independent dimensions mean 64 grouping sets, not merely 64 output rows: each set can contain many distinct groups, so output size may grow much more than the number of levels suggests.

All levels aggregate the population selected by FROM and WHERE. A filter restricting sales to one month also restricts the grand total to that month. If the report needs different populations at different levels, a single shared input with these sets may not express that requirement. Define the population before comparing totals with another report.

Label levels with GROUPING

Columns omitted from a grouping set appear as SQL NULL in its output rows. Real input values may also be NULL, so inspecting null columns cannot reliably identify a subtotal. GROUPING(region,product) supplies a bitmask that describes which grouping expressions are absent from the current set. The rightmost argument contributes the least significant bit.

For this report, zero means both expressions participate, one means product is omitted, and three means both are omitted. A region subtotal for an actual null region and the grand total can therefore have identical null dimension columns but different masks. Use that mask in the data contract and derive labels such as “all regions” only when the level indicates aggregation.

A grouping expression’s presence is different from its value being nonnull. GROUPING reports the former. Its arguments must match grouping expressions from the query; it is not an ordinary function for testing arbitrary values. Give downstream consumers the numeric level or another unambiguous discriminator instead of replacing every null with a subtotal label.

When it breaks

Adding every returned total together counts the same sales multiple times, once at each included level. Select a single level when computing another summary, or use the already calculated grand total. Averages and distinct counts need even more care: averaging region averages without their weights does not generally reproduce the overall average, and overlapping distinct sets cannot simply be added.

The empty grouping set still emits a row when its input is empty. Count returns zero, while sum returns NULL, so a blank amount is not evidence that the query failed to return a grand-total row. Decide how the report represents an empty population. Also avoid accidentally repeating grouping sets; duplicate level specifications can produce repeated aggregate rows rather than extra independent evidence.

Check it quickly

Save this as grouping.sql and run psql -X -v ON_ERROR_STOP=1 -f grouping.sql in a disposable PostgreSQL 18 database. The fixture deliberately includes a real null region and uses a transaction to remove its temporary objects afterward.

\set ON_ERROR_STOP on
BEGIN;
CREATE TEMP TABLE sales (region text, product text, amount integer);
INSERT INTO sales VALUES ('east','A',10),('east','B',20),(NULL,'A',5);
CREATE TEMP VIEW levels AS
SELECT region,product,sum(amount) AS total,GROUPING(region,product) AS level
FROM sales GROUP BY GROUPING SETS ((region,product),(region),());
SELECT * FROM levels ORDER BY level,region NULLS LAST,product NULLS LAST;
SELECT sum(total) AS incorrect_retotal,
 sum(total) FILTER (WHERE level=0) AS detail_total FROM levels;
CREATE TEMP VIEW empty_level AS
SELECT count(*) AS n,sum(amount) AS total FROM sales WHERE false GROUP BY GROUPING SETS (());
SELECT * FROM empty_level;
DO $$ BEGIN
 IF (SELECT count(*) FROM levels) <> 6 THEN RAISE EXCEPTION 'wrong level count'; END IF;
 IF (SELECT total FROM levels WHERE level=3) IS DISTINCT FROM 35 THEN
 RAISE EXCEPTION 'wrong grand total';
 END IF;
 IF (SELECT total FROM levels WHERE level=1 AND region IS NULL) IS DISTINCT FROM 5 THEN
 RAISE EXCEPTION 'real null region subtotal lost';
 END IF;
 IF (SELECT count(*) FROM levels WHERE region IS NULL AND product IS NULL) <> 2 THEN
 RAISE EXCEPTION 'test did not include ambiguous NULL labels';
 END IF;
 IF (SELECT n FROM empty_level) IS DISTINCT FROM 0::bigint OR
 (SELECT total FROM empty_level) IS NOT NULL THEN
 RAISE EXCEPTION 'wrong empty-input aggregate';
 END IF;
END $$;
ROLLBACK;

PostgreSQL 18.6 returned six rows: three detailed groups, two region subtotals, and one grand total. The east subtotal was 30. The null-region subtotal was 5 with mask one, while the grand total was 35 with mask three. Both latter rows had null region and product columns, proving why null-based labeling is ambiguous.

The incorrect re-total was 105, whereas summing just the detailed groups returned 35. The empty-input query returned one row with count zero and a null sum. Assertions check the level count, grand total, real-null subtotal, and empty-input behavior. Final ORDER BY controls presentation explicitly; GROUPING SETS itself does not promise that subtotals arrive next to their detail rows.

Sources

PostgreSQL table expressions, grouping sets, rollup, cube, and omitted dimensions, checked 2026-09-10.
PostgreSQL aggregate functions, GROUPING bitmasks and empty-input aggregates, checked 2026-09-10.