Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable
Subject: Improve "3.5. Window Functions" tutorial
To: pgsql-docs@lists.postgresql.org
From: PG Doc comments form <noreply@postgresql.org>
Cc: matematica.a3k@gmail.com
Reply-To: matematica.a3k@gmail.com, pgsql-docs@lists.postgresql.org
Date: Wed, 30 Sep 2026 20:56:45 +0000
Message-ID: 
 <179080180503.1026193.14981416435978499059@wrigleys.postgresql.org>
Auto-Submitted: auto-generated
Archived-At: 
 <https://www.postgresql.org/message-id/179080180503.1026193.14981416435978499059%40wrigleys.postgresql.org>
Precedence: bulk

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/18/tutorial-window.html
Description:

Hi! I would like to propose improvements on the "3.5. Window Functions"
tutorial.

There are two issues on the tutorial IMO:

- Paragraph structure:
Minor - yet perceivable, easy improvement on readability. Might be discussed
at last if agreed.

- Two paragraphs seems "disjointed":
"
There is another important concept associated with window functions: for
each row, there is a set of rows within its partition called its window
frame. Some window functions act only on the rows of the window frame,
rather than of the whole partition.

By default, if ORDER BY is supplied, then the frame consists of all rows
from the start of the partition up through the current row, plus any
following rows that are equal to the current row according to the ORDER BY
clause. When ORDER BY is omitted, the default frame consists of all rows in
the partition. [5]
"

which may be improved with:

"
There is another important concept associated with window functions: for
each row, there is a set of rows within its partition called its window
frame. Some window functions act only on the rows of the window frame,
rather than of the whole partition.

***
That set of rows can be "scoped" even further if an ordering is provided.
Once an ordering is provided, concepts like "start", "position" and "end"
can be defined and therefore, criterias to match them. If no ordering is
provided, the set of rows cannot be further scoped and coincide with the
partition.
***

By default, if ORDER BY is supplied, then the frame consists of all rows
from the start of the partition up through the current row, plus any
following rows that are equal to the current row according to the ORDER BY
clause. When ORDER BY is omitted, the default frame consists of all rows in
the partition. [5]
"

Wording may be improved ("scoped"), I think the added paragraph links the
existing ones providing more meaning.

Regards,
Rodrigo