WindowAgg

Description

Evaluates window functions over ordered partitions of its child output.

Core node tag

T_WindowAgg

Structured EXPLAIN Node Type

WindowAgg

Inputs

One suitably ordered child plan

Output

Tuples with window-function results

Executor initializer

ExecInitWindowAgg

Memory mechanism

tuplestore

EXPLAIN names and attributes

Structured formats use the Node Type above. Text-format spellings can also include operation, strategy, join type, scan direction or aggregation-stage attributes.

Text names recorded by this source: WindowAgg.

Parallel-aware and parallel-safe are different plan properties. A node running inside a parallel worker is not necessarily a parallel-aware node.

Memory and temporary storage

This node creates a tuplestore with work_mem. The tuplestore can move stored tuples to temporary files; this does not make work_mem a cap on every allocation made by the node.

If the tuplestore has spilled to disk, alternate reading and writing becomes quite expensive due to frequent buffer flushes. It's cheaper to force the entire partition to get spooled in one go.

Read the current row from the tuplestore, and save in ScanTupleSlot. (We can't rely on the outerplan's output slot because we may have to read beyond the current row. Also, we have to actually copy the row out of the tuplestore, since window function evaluation might cause the tuplestore to dump its state to disk.)

Window functions do not have to call this, but are encouraged to move the mark forward when possible to keep the tuplestore size down and prevent having to spill rows to disk.

Parallel execution and instrumentation

The source callbacks below can coordinate execution or collect worker instrumentation. Their presence is not a blanket claim that this node supports a shared parallel scan or shared state.

Callbacks in this build: none extracted from this node implementation.

Executor implementation notes

A WindowAgg node evaluates "window functions" across suitable partitions of the input tuple set. Any one WindowAgg works for just a single window specification, though it can evaluate multiple window functions sharing identical window specifications. The input tuples are required to be delivered in sorted order, with the PARTITION BY columns (if any) as major sort keys and the ORDER BY columns (if any) as minor sort keys. (The planner generates a stack of WindowAggs with intervening Sort nodes as needed, if a query involves more than one window specification.)

Since window functions can require access to any or all of the rows in the current partition, we accumulate rows of the partition into a tuplestore. The window functions are called using the WindowObject API so that they can access those rows as needed.

We also support using plain aggregate functions as window functions. For these, the regular Agg-node environment is emulated for each partition. As required by the SQL spec, the output represents the value of the aggregate function over all rows in the current row's window frame.

All the window function APIs are called with this object, which is passed to window functions as fcinfo->context.

We have one WindowStatePerFunc struct for each window function and window aggregate handled by this node.

EXPLAIN identity in core source

case T_WindowAgg:
			pname = sname = "WindowAgg";
			break;

Related entries

• EXPLAIN
• Using EXPLAIN
• Parallel plans
• work_mem

Documentation and source

• src/backend/commands/explain.c:1574
• src/backend/executor/execProcnode.c:345
• src/backend/executor/nodeWindowAgg.c
• src/include/nodes/plannodes.h
• src/backend/utils/sort/tuplestore.c

Compare versions

PostgreSQL 17 → 18: unchanged.

Compares recorded interfaces and attributes. Source fingerprints and build metadata are excluded; an absent sample is not proof of the introduction or removal release.

Related entries

• AggregateAgg
• GroupGroup