Change the meaning of "tuples returned/s"
@blogh is already working on this.
Since Jul 3, 2025.
- Dominant language
- Python
- Stars
- 3k
- Forks
- 190
- PR merge metrics
- No merged PRs in 30d
Description
Hi, hoping to kickstart a discussion on a thing that's bugging me for some years :D
In short - currently the "tuples returned/s" value is not really helpful at all for the following reasons:
- It does not show the actual row counts returned to the calling applications - what most developers assume.
- In instead shows only one side of the Postgres-internal tuple reading story - namely
tup_returned, i.e. seq. scanned rows + scanned index entries, while ignoring the other side -tup_fetched, i.e. rows fetched by those scanned index entries.
Thus I think to improve the sitation would make sense to consider a combination of:
- Add "tup_fetched" to "tuples returned" the story
- Rename "tuples returned/s" to something like "tuples scanned/s"
- Start showing a new "rows returned/s" column based on
pg_stat_statements.rowsdelta instead, when pg_stat_statements is available.
In any case the current "tuples returned" is just confusing for non-Postgres-guru users - for example below is a screenshot of app doing simple key read-write transactions, but were worried as "tuples returned" was very high still - indicating maybe some unwanted seq. scans, but most likely it's just caused by internal pg_class, pg_attribute etc access on query planning.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.