Skip to content

Sorted Merge: Eliminate coordinator Sort node for multi-shard ORDER BY queries #8529

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
neildsh wants to merge 18 commits into
base: main
Choose a base branch
from
Open

Sorted Merge: Eliminate coordinator Sort node for multi-shard ORDER BY queries #8529

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
7eb2108
Add sorted merge foundation: GUC, struct fields, and serialization
neildsh Mar 17, 2026
3e3e3b7
Add planner eligibility and worker sort pushdown for sorted merge
neildsh Mar 17, 2026
cd99710
Add per-task tuple stores and k-way merge for sorted merge
neildsh Mar 19, 2026
7bd9123
Add sorted merge foundation: GUC, struct fields, and serialization
neildsh Mar 19, 2026
1baefd6
Add more comprehensive tests for sorted merge
neildsh Mar 19, 2026
3a80aac
Minor code clean up
neildsh Mar 20, 2026
b00cc93
Added subquery tests
neildsh Mar 23, 2026
8ed417c
Put multi_orderby_pushdown in its own test group
neildsh Mar 23, 2026
0bf44ff
Replace the use of memcpy with memcpy_s and add ORDER BY to CTE test …
neildsh Mar 24, 2026
0eb923c
Emit more verbose output for EXPLAIN in sorted merge tests. Alphabeti…
neildsh Mar 27, 2026
9437018
Use explain_filter to normalize regress test output
neildsh Mar 29, 2026
49e9b93
Added more tests per feedback
neildsh Apr 10, 2026
d92b551
Incorporate code review feedback and add more test cases as well as a…
neildsh Apr 13, 2026
8b4ba36
Added test cases with volatile/stable functions
neildsh Apr 14, 2026
86f82a1
Make style checks happy
neildsh Apr 14, 2026
4bb3811
Fix the issue where EXPLAIN ANALYZE uses sorted merge for the distrib…
neildsh Apr 15, 2026
0ed36fd
Added auto explain test category
neildsh Apr 16, 2026
499e5e3
add more test cases for auto explain with duplicates
neildsh Apr 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 90 additions & 9 deletions src/backend/distributed/executor/adaptive_executor.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -171,6 +171,7 @@
#include "distributed/repartition_join_execution.h"
#include "distributed/resource_lock.h"
#include "distributed/shared_connection_stats.h"
#include "distributed/sorted_merge.h"
#include "distributed/stats/stat_counters.h"
#include "distributed/subplan_execution.h"
#include "distributed/transaction_identifier.h"
Expand Down Expand Up @@ -315,6 +316,15 @@ typedef struct DistributedExecution
* fail, such as CREATE INDEX CONCURRENTLY.
*/
bool localExecutionSupported;

/*
* Sorted merge: when useSortedMerge is true, worker results are routed
* to per-task tuple stores. After execution completes, these stores are
* k-way merged into the final scanState->tuplestorestate.
*/
bool useSortedMerge;
Tuplestorestate **perTaskStores;
int perTaskStoreCount;
Copy link
Copy Markdown
Contributor

@colm-mchugh colm-mchugh Apr 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion: keep sorted merge state in a data structure that hangs off CitusScanState. That data structure can be private to sorted_merge, and sorted_merge has something like this strawman API:

void InitSortedMerge(CitusScanState *, tasklist, sort clause, ...);
bool SortedMergeActive(CitusScanState*);
TupleTableSlot *ReturnTupleFromSortedMerge(CitusScanState*); // see 2nd comment in `sorted_merge.c`
void CleanupSortedMergeState(struct CitusScanState *scanState);

This fits into the canonical Postgres flow - for example per-task tuplestores are closed in the Cleanup function, which would be called by CitusEndScan() and CitusReScan(), as opposed to an if statement in adaptive executor, which looks a bit ad-hoc tbh.

} DistributedExecution;


Expand Down Expand Up @@ -641,7 +651,10 @@ static DistributedExecution * CreateDistributedExecution(RowModifyLevel modLevel
TransactionProperties *
xactProperties,
List *jobIdList,
bool localExecutionSupported);
bool localExecutionSupported,
bool useSortedMerge,
Tuplestorestate **perTaskStores,
int perTaskStoreCount);
static TransactionProperties DecideTaskListTransactionProperties(RowModifyLevel
modLevel,
List *taskList,
Expand Down Expand Up @@ -799,12 +812,45 @@ AdaptiveExecutor(CitusScanState *scanState)
/* Reset Task fields that are only valid for a single execution */
ResetExplainAnalyzeData(taskList);

scanState->tuplestorestate =
tuplestore_begin_heap(randomAccess, interTransactions, work_mem);

TupleDesc tupleDescriptor = ScanStateGetTupleDescriptor(scanState);
TupleDestination *defaultTupleDest =
CreateTupleStoreTupleDest(scanState->tuplestorestate, tupleDescriptor);
TupleDestination *defaultTupleDest = NULL;

/*
* When sorted merge is active, route worker results into per-task tuple
* stores. After execution completes, these stores are k-way merged into
* the final scanState->tuplestorestate.
*
* useSortedMerge is a plan-time decision — if the plan says merge, the
* executor must merge, because the combine query plan has no Sort node
* above us. Skipping the merge would produce silently unsorted output.
*
* This applies even under EXPLAIN ANALYZE: the ExplainAnalyzeDestination
* wrapper forwards data tuples (queryNumber == 0) to the per-task
* dispatch, which routes them to the correct per-task store. Plan-fetch
* tuples (queryNumber == 1) are handled entirely within
* ExplainAnalyzeDestPutTuple and never reach the per-task dispatch.
*/
Tuplestorestate **perTaskStores = NULL;
int perTaskStoreCount = 0;

if (distributedPlan->useSortedMerge)
{
TupleDestinationStats *sharedStats = palloc0(sizeof(TupleDestinationStats));
defaultTupleDest = CreatePerTaskDispatchDest(taskList, tupleDescriptor,
sharedStats,
&perTaskStores,
&perTaskStoreCount);

/* final tuplestore created after merge */
scanState->tuplestorestate = NULL;
}
else
{
scanState->tuplestorestate =
tuplestore_begin_heap(randomAccess, interTransactions, work_mem);
defaultTupleDest =
CreateTupleStoreTupleDest(scanState->tuplestorestate, tupleDescriptor);
}

bool localExecutionSupported = true;

Expand Down Expand Up @@ -865,7 +911,10 @@ AdaptiveExecutor(CitusScanState *scanState)
defaultTupleDest,
&xactProperties,
jobIdList,
localExecutionSupported);
localExecutionSupported,
distributedPlan->useSortedMerge,
perTaskStores,
perTaskStoreCount);

/*
* Make sure that we acquire the appropriate locks even if the local tasks
Expand Down Expand Up @@ -897,6 +946,30 @@ AdaptiveExecutor(CitusScanState *scanState)

FinishDistributedExecution(execution);

/*
* When sorted merge is active, k-way merge the per-task stores into
* the final tuplestore. This produces globally sorted output that the
* existing ReturnTupleFromTuplestore() path can read unchanged.
*/
if (execution->useSortedMerge && execution->perTaskStoreCount > 0)
{
scanState->tuplestorestate =
tuplestore_begin_heap(randomAccess, interTransactions, work_mem);

MergePerTaskStoresIntoFinalStore(scanState->tuplestorestate,
execution->perTaskStores,
execution->perTaskStoreCount,
distributedPlan->sortedMergeKeys,
distributedPlan->sortedMergeKeyCount,
tupleDescriptor);

/* free per-task stores — they are no longer needed */
for (int i = 0; i < execution->perTaskStoreCount; i++)
{
tuplestore_end(execution->perTaskStores[i]);
}
}

if (SortReturning && distributedPlan->expectResults && commandType != CMD_SELECT)
{
SortTupleStore(scanState);
Expand Down Expand Up @@ -1105,7 +1178,8 @@ ExecuteTaskListExtended(ExecutionParams *executionParams)
executionParams->modLevel, executionParams->taskList,
executionParams->paramListInfo, executionParams->targetPoolSize,
defaultTupleDest, &executionParams->xactProperties,
executionParams->jobIdList, executionParams->localExecutionSupported);
executionParams->jobIdList, executionParams->localExecutionSupported,
false, NULL, 0);

/*
* If current transaction accessed local placements and task list includes
Expand Down Expand Up @@ -1170,7 +1244,10 @@ CreateDistributedExecution(RowModifyLevel modLevel, List *taskList,
ParamListInfo paramListInfo,
int targetPoolSize, TupleDestination *defaultTupleDest,
TransactionProperties *xactProperties,
List *jobIdList, bool localExecutionSupported)
List *jobIdList, bool localExecutionSupported,
bool useSortedMerge,
Tuplestorestate **perTaskStores,
int perTaskStoreCount)
{
DistributedExecution *execution =
(DistributedExecution *) palloc0(sizeof(DistributedExecution));
Expand Down Expand Up @@ -1200,6 +1277,10 @@ CreateDistributedExecution(RowModifyLevel modLevel, List *taskList,

execution->localExecutionSupported = localExecutionSupported;

execution->useSortedMerge = useSortedMerge;
execution->perTaskStores = perTaskStores;
execution->perTaskStoreCount = perTaskStoreCount;

/*
* Since task can have multiple queries, we are not sure how many columns we should
* allocate for. We start with 16, and reallocate when we need more.
Expand Down
3 changes: 3 additions & 0 deletions src/backend/distributed/executor/multi_executor.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,9 @@ ParamListInfo executorBoundParams = NULL;
/* sort the returning to get consistent outputs, used only for testing */
bool SortReturning = false;

/* when true at planning time, enables coordinator sorted merge for ORDER BY */
bool EnableSortedMerge = false;

/*
* How many nested executors have we started? This can happen for SQL
* UDF calls. The outer query starts an executor, then postgres opens
Expand Down
Loading
Loading