From 189edab507d407cce6446a944b3a48c327167ec3 Mon Sep 17 00:00:00 2001 From: Amit Langote Date: Sat, 20 Dec 2025 23:09:37 +0900 Subject: [PATCH v4 3/3] Add EXPLAIN (BATCHES) option for tuple batching statistics Add a BATCHES option to EXPLAIN that reports per-node batch statistics when a node uses batch mode execution. For nodes that support batching (currently SeqScan), this shows the number of batches fetched along with average, minimum, and maximum rows per batch. Output is supported in both text and non-text formats. Add regression tests covering text output, JSON format, filtered scans, LIMIT, and disabled batching. Discussion: https://postgr.es/m/CA+HiwqFfAY_ZFqN8wcAEMw71T9hM_kA8UtyHaZZEZtuT3UyogA@mail.gmail.com --- src/backend/commands/explain.c | 30 ++++++++++++++ src/backend/commands/explain_state.c | 2 + src/backend/executor/execBatch.c | 8 +++- src/backend/executor/nodeSeqscan.c | 24 +++++------ src/include/commands/explain_state.h | 1 + src/include/executor/execBatch.h | 35 +++++++++++++++- src/include/executor/instrument.h | 1 + src/test/regress/expected/explain.out | 57 +++++++++++++++++++++++++++ src/test/regress/sql/explain.sql | 26 ++++++++++++ 9 files changed, 171 insertions(+), 13 deletions(-) diff --git a/src/backend/commands/explain.c b/src/backend/commands/explain.c index 5a6390631eb..3a639a13807 100644 --- a/src/backend/commands/explain.c +++ b/src/backend/commands/explain.c @@ -22,6 +22,7 @@ #include "commands/explain_format.h" #include "commands/explain_state.h" #include "commands/prepare.h" +#include "executor/execBatch.h" #include "foreign/fdwapi.h" #include "jit/jit.h" #include "libpq/pqformat.h" @@ -517,6 +518,8 @@ ExplainOnePlan(PlannedStmt *plannedstmt, IntoClause *into, ExplainState *es, instrument_option |= INSTRUMENT_BUFFERS; if (es->wal) instrument_option |= INSTRUMENT_WAL; + if (es->batches) + instrument_option |= INSTRUMENT_BATCHES; /* * We always collect timing for the entire statement, even when node-level @@ -2292,6 +2295,33 @@ ExplainNode(PlanState *planstate, List *ancestors, show_buffer_usage(es, &planstate->instrument->bufusage); if (es->wal && planstate->instrument) show_wal_usage(es, &planstate->instrument->walusage); + if (es->batches && planstate->ps_Batch) + { + TupleBatch *b = planstate->ps_Batch; + + if (b->stat_batches > 0) + { + if (es->format == EXPLAIN_FORMAT_TEXT) + { + ExplainIndentText(es); + appendStringInfo(es->str, + "Batches: %lld Avg Rows: %.1f Max: %d Min: %d\n", + (long long) b->stat_batches, + TupleBatchAvgRows(b), + b->stat_max_rows, + b->stat_min_rows == INT_MAX ? 0 : b->stat_min_rows); + } + else + { + ExplainPropertyInteger("Batches", NULL, b->stat_batches, es); + ExplainPropertyFloat("Average Batch Rows", NULL, + TupleBatchAvgRows(b), 1, es); + ExplainPropertyInteger("Max Batch Rows", NULL, b->stat_max_rows, es); + ExplainPropertyInteger("Min Batch Rows", NULL, + b->stat_min_rows == INT_MAX ? 0 : b->stat_min_rows, es); + } + } + } /* Prepare per-worker buffer/WAL usage */ if (es->workers_state && (es->buffers || es->wal) && es->verbose) diff --git a/src/backend/commands/explain_state.c b/src/backend/commands/explain_state.c index a6623f8fa52..6ef6055c479 100644 --- a/src/backend/commands/explain_state.c +++ b/src/backend/commands/explain_state.c @@ -159,6 +159,8 @@ ParseExplainOptionList(ExplainState *es, List *options, ParseState *pstate) "EXPLAIN", opt->defname, p), parser_errposition(pstate, opt->location))); } + else if (strcmp(opt->defname, "batches") == 0) + es->batches = defGetBoolean(opt); else if (!ApplyExtensionExplainOption(es, opt, pstate)) ereport(ERROR, (errcode(ERRCODE_SYNTAX_ERROR), diff --git a/src/backend/executor/execBatch.c b/src/backend/executor/execBatch.c index 007ae535687..93c90680d3d 100644 --- a/src/backend/executor/execBatch.c +++ b/src/backend/executor/execBatch.c @@ -19,7 +19,7 @@ * Allocate and initialize a new TupleBatch envelope. */ TupleBatch * -TupleBatchCreate(TupleDesc scandesc, int capacity) +TupleBatchCreate(TupleDesc scandesc, int capacity, bool track_stats) { TupleBatch *b; TupleTableSlot **inslots, @@ -44,6 +44,12 @@ TupleBatchCreate(TupleDesc scandesc, int capacity) b->nvalid = 0; b->next = 0; + b->track_stats = track_stats; + b->stat_batches = 0; + b->stat_rows = 0; + b->stat_max_rows = 0; + b->stat_min_rows = INT_MAX; + return b; } diff --git a/src/backend/executor/nodeSeqscan.c b/src/backend/executor/nodeSeqscan.c index a9071e32560..73eb9b6a51e 100644 --- a/src/backend/executor/nodeSeqscan.c +++ b/src/backend/executor/nodeSeqscan.c @@ -213,8 +213,9 @@ SeqNextBatch(SeqScanState *node) TableScanDesc scandesc; EState *estate; ScanDirection direction; + TupleBatch *b = node->ss.ps.ps_Batch; - Assert(node->ss.ps.ps_Batch != NULL); + Assert(b != NULL); /* * get information from the estate and scan state @@ -237,22 +238,21 @@ SeqNextBatch(SeqScanState *node) } /* Lazily create the AM batch payload. */ - if (node->ss.ps.ps_Batch->am_payload == NULL) + if (b->am_payload == NULL) { const TableAmRoutine *tam PG_USED_FOR_ASSERTS_ONLY = scandesc->rs_rd->rd_tableam; Assert(tam && tam->scan_begin_batch); - node->ss.ps.ps_Batch->am_payload = - table_scan_begin_batch(scandesc, node->ss.ps.ps_Batch->maxslots); - node->ss.ps.ps_Batch->ops = table_batch_callbacks(node->ss.ss_currentRelation); + b->am_payload = table_scan_begin_batch(scandesc, b->maxslots); + b->ops = table_batch_callbacks(node->ss.ss_currentRelation); } - node->ss.ps.ps_Batch->ntuples = - table_scan_getnextbatch(scandesc, node->ss.ps.ps_Batch->am_payload, direction); - node->ss.ps.ps_Batch->nvalid = node->ss.ps.ps_Batch->ntuples; - node->ss.ps.ps_Batch->materialized = false; + b->ntuples = table_scan_getnextbatch(scandesc, b->am_payload, direction); + b->nvalid = b->ntuples; + b->materialized = false; + TupleBatchRecordStats(b, b->ntuples); - return node->ss.ps.ps_Batch->ntuples > 0; + return b->ntuples > 0; } static inline bool @@ -340,8 +340,10 @@ SeqScanInitBatching(SeqScanState *scanstate, int eflags) { const int cap = executor_batch_rows; TupleDesc scandesc = RelationGetDescr(scanstate->ss.ss_currentRelation); + EState *estate = scanstate->ss.ps.state; + bool track_stats = estate->es_instrument && (estate->es_instrument & INSTRUMENT_BATCHES); - scanstate->ss.ps.ps_Batch = TupleBatchCreate(scandesc, cap); + scanstate->ss.ps.ps_Batch = TupleBatchCreate(scandesc, cap, track_stats); /* Choose batch variant to preserve your specialization matrix */ if (scanstate->ss.ps.qual == NULL) diff --git a/src/include/commands/explain_state.h b/src/include/commands/explain_state.h index ba073b86918..b82f7ac0829 100644 --- a/src/include/commands/explain_state.h +++ b/src/include/commands/explain_state.h @@ -55,6 +55,7 @@ typedef struct ExplainState bool memory; /* print planner's memory usage information */ bool settings; /* print modified settings */ bool generic; /* generate a generic plan */ + bool batches; /* print batch statistics */ ExplainSerializeOption serialize; /* serialize the query's output? */ ExplainFormat format; /* output format */ /* state for output formatting --- not reset for each new plan tree */ diff --git a/src/include/executor/execBatch.h b/src/include/executor/execBatch.h index 2d0066103ce..e3a4f762284 100644 --- a/src/include/executor/execBatch.h +++ b/src/include/executor/execBatch.h @@ -13,6 +13,7 @@ #ifndef EXECBATCH_H #define EXECBATCH_H +#include "limits.h" #include "executor/tuptable.h" /* @@ -45,11 +46,18 @@ typedef struct TupleBatch int nvalid; /* number of returnable tuples in outslots */ int next; /* 0-based index of next tuple to be returned */ + + /* Statistics (populated when EXPLAIN ANALYZE BATCHES) */ + bool track_stats; /* whether to collect stats */ + int64 stat_batches; /* total number of batches fetched */ + int64 stat_rows; /* total tuples across all batches */ + int stat_max_rows; /* max rows in any single batch */ + int stat_min_rows; /* min rows in any single batch (non-zero) */ } TupleBatch; /* Helpers */ -extern TupleBatch *TupleBatchCreate(TupleDesc scandesc, int capacity); +extern TupleBatch *TupleBatchCreate(TupleDesc scandesc, int capacity, bool track_stats); extern void TupleBatchReset(TupleBatch *b, bool drop_slots); extern void TupleBatchUseInput(TupleBatch *b, int nvalid); extern void TupleBatchUseOutput(TupleBatch *b, int nvalid); @@ -96,4 +104,29 @@ TupleBatchMaterializeAll(TupleBatch *b) TupleBatchUseInput(b, b->ntuples); } +/* === Batching stats. ===*/ + +static inline void +TupleBatchRecordStats(TupleBatch *b, int rows) +{ + if (!b->track_stats) + return; + + b->stat_batches++; + b->stat_rows += rows; + if (rows > b->stat_max_rows) + b->stat_max_rows = rows; + if (rows < b->stat_min_rows && rows > 0) + b->stat_min_rows = rows; +} + +static inline double +TupleBatchAvgRows(TupleBatch *b) +{ + if (b->stat_batches == 0) + return 0.0; + + return (double) b->stat_rows / b->stat_batches; +} + #endif /* EXECBATCH_H */ diff --git a/src/include/executor/instrument.h b/src/include/executor/instrument.h index ffe470f2b84..0af02db3760 100644 --- a/src/include/executor/instrument.h +++ b/src/include/executor/instrument.h @@ -64,6 +64,7 @@ typedef enum InstrumentOption INSTRUMENT_BUFFERS = 1 << 1, /* needs buffer usage */ INSTRUMENT_ROWS = 1 << 2, /* needs row count */ INSTRUMENT_WAL = 1 << 3, /* needs WAL usage */ + INSTRUMENT_BATCHES = 1 << 4, /* needs batches */ INSTRUMENT_ALL = PG_INT32_MAX } InstrumentOption; diff --git a/src/test/regress/expected/explain.out b/src/test/regress/expected/explain.out index 7c1f26b182c..fef3b4a5497 100644 --- a/src/test/regress/expected/explain.out +++ b/src/test/regress/expected/explain.out @@ -822,3 +822,60 @@ select explain_filter('explain (analyze,buffers off,costs off) select sum(n) ove (9 rows) reset work_mem; +-- Test BATCHES option +set executor_batch_rows = 64; +create table batch_test (a int, b text); +insert into batch_test select i, repeat('x', 100) from generate_series(1, 10000) i; +analyze batch_test; +-- Basic batch stats output +select explain_filter('explain (analyze, batches, buffers off, costs off) select * from batch_test'); + explain_filter +---------------------------------------------------------------- + Seq Scan on batch_test (actual time=N.N..N.N rows=N.N loops=N) + Batches: N Avg Rows: N.N Max: N Min: N + Planning Time: N.N ms + Execution Time: N.N ms +(4 rows) + +-- With filter +select explain_filter('explain (analyze, batches, buffers off, costs off) select * from batch_test where a > 5000'); + explain_filter +---------------------------------------------------------------- + Seq Scan on batch_test (actual time=N.N..N.N rows=N.N loops=N) + Filter: (a > N) + Rows Removed by Filter: N + Batches: N Avg Rows: N.N Max: N Min: N + Planning Time: N.N ms + Execution Time: N.N ms +(6 rows) + +-- With LIMIT - partial scan shows fewer batches +select explain_filter('explain (analyze, batches, buffers off, costs off) select * from batch_test limit 100'); + explain_filter +---------------------------------------------------------------------- + Limit (actual time=N.N..N.N rows=N.N loops=N) + -> Seq Scan on batch_test (actual time=N.N..N.N rows=N.N loops=N) + Batches: N Avg Rows: N.N Max: N Min: N + Planning Time: N.N ms + Execution Time: N.N ms +(5 rows) + +-- Batching disabled - no batch line +set executor_batch_rows = 0; +select explain_filter('explain (analyze, batches, buffers off, costs off) select * from batch_test'); + explain_filter +---------------------------------------------------------------- + Seq Scan on batch_test (actual time=N.N..N.N rows=N.N loops=N) + Planning Time: N.N ms + Execution Time: N.N ms +(3 rows) + +reset executor_batch_rows; +-- JSON format +select explain_filter_to_json('explain (analyze, batches, buffers off, format json) select * from batch_test where a < 1000') #> '{0,Plan,Batches}'; + ?column? +---------- + 0 +(1 row) + +drop table batch_test; diff --git a/src/test/regress/sql/explain.sql b/src/test/regress/sql/explain.sql index ebdab42604b..87bb179ced9 100644 --- a/src/test/regress/sql/explain.sql +++ b/src/test/regress/sql/explain.sql @@ -188,3 +188,29 @@ select explain_filter('explain (analyze,buffers off,costs off) select sum(n) ove -- Test tuplestore storage usage in Window aggregate (memory and disk case, final result is disk) select explain_filter('explain (analyze,buffers off,costs off) select sum(n) over(partition by m) from (SELECT n < 3 as m, n from generate_series(1,2500) a(n))'); reset work_mem; + +-- Test BATCHES option +set executor_batch_rows = 64; + +create table batch_test (a int, b text); +insert into batch_test select i, repeat('x', 100) from generate_series(1, 10000) i; +analyze batch_test; + +-- Basic batch stats output +select explain_filter('explain (analyze, batches, buffers off, costs off) select * from batch_test'); + +-- With filter +select explain_filter('explain (analyze, batches, buffers off, costs off) select * from batch_test where a > 5000'); + +-- With LIMIT - partial scan shows fewer batches +select explain_filter('explain (analyze, batches, buffers off, costs off) select * from batch_test limit 100'); + +-- Batching disabled - no batch line +set executor_batch_rows = 0; +select explain_filter('explain (analyze, batches, buffers off, costs off) select * from batch_test'); +reset executor_batch_rows; + +-- JSON format +select explain_filter_to_json('explain (analyze, batches, buffers off, format json) select * from batch_test where a < 1000') #> '{0,Plan,Batches}'; + +drop table batch_test; -- 2.47.3