Gather Merge

Description

Merges ordered tuple streams from parallel workers and any participating leader execution.

Core node tag

T_GatherMerge

Structured EXPLAIN Node Type

Gather Merge

Inputs

One ordered parallel child plan

Output

Merged ordered tuples

Executor initializer

ExecInitGatherMerge

Memory mechanism

unclassified

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: Gather Merge.

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 extraction does not assign a universal memory limit or spill policy to this node. Inspect the same-build implementation and its expressions or provider.

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.

Same-version manual discussion

PostgreSQL supports parallel aggregation by aggregating in two stages. First, each process participating in the parallel portion of the query performs an aggregation step, producing a partial result for each group of which that process is aware. This is reflected in the plan as a Partial Aggregate node. Second, the partial results are transferred to the leader via Gather or Gather Merge . Finally, the leader re-aggregates the results across all workers in order to produce the final result. This is reflected in the plan as a Finalize Aggregate node.

Executor implementation notes

nodeGatherMerge.c Scan a plan in multiple workers, and do order-preserving merge.

When we read tuples from workers, it's a good idea to read several at once for efficiency when possible: this minimizes context-switching overhead. But reading too many at a time wastes memory without improving performance. We'll read up to MAX_TUPLE_STORE tuples (in addition to the first one).

Pending-tuple array for each worker. This holds additional tuples that we were able to fetch from the worker, but can't process yet. In addition, this struct holds the "done" flag indicating the worker is known to have no more tuples. (We do not use this struct for the leader; we don't keep any pending tuples for the leader, and the need_to_scan_locally flag serves as its "done" indicator.)

GatherMerge doesn't support checking a qual (it's always more efficient to do it in the child node).

Leader may access ExecProcNode result directly (if need_to_scan_locally), or from workers via tuple queue. So we can't trivially rely on the slot type being fixed for expressions evaluated within this node.

EXPLAIN identity in core source

case T_GatherMerge:
			pname = sname = "Gather Merge";
			break;

Related entries

• EXPLAIN
• Using EXPLAIN
• Parallel plans
• enable_gathermerge
• max_parallel_workers_per_gather

Documentation and source

• src/backend/commands/explain.c:1441
• src/backend/executor/execProcnode.c:360
• src/backend/executor/nodeGatherMerge.c
• src/include/nodes/plannodes.h
• PostgreSQL 18.6 · parallel-plans

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

• GatherGather