pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedImprove "3.5. Window Functions" tutorial
3+ messages / 3 participants
[nested] [flat]
* Improve "3.5. Window Functions" tutorial
@ 2026-09-30 20:56 PG Doc comments form <noreply@postgresql.org>
0 siblings, 1 reply; 3+ messages in thread
From: PG Doc comments form @ 2026-09-30 20:56 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: matematica.a3k@gmail.com
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
^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: Improve "3.5. Window Functions" tutorial
@ 2026-10-02 06:40 David G. Johnston <david.g.johnston@gmail.com>
parent: PG Doc comments form <noreply@postgresql.org>
0 siblings, 1 reply; 3+ messages in thread
From: David G. Johnston @ 2026-10-02 06:40 UTC (permalink / raw)
To: matematica.a3k@gmail.com <matematica.a3k@gmail.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
On Wednesday, September 30, 2026, PG Doc comments form <
noreply@postgresql.org> wrote:
> 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.
>
> Wording may be improved ("scoped"), I think the added paragraph links the
> existing ones providing more meaning.
>
I’m in agreement with this page being in need of improvement. I’m not all
that comfortable with this particular proposal. It adds some of its own
concerns and doesn’t remove some existing ones.
As an aside - recent comments about the undesirability were made - and
while I’m accepting of their usage generally this one seems like a good
candidate for removal if we do update this page.
My biggest qualm is the wording that makes it sound like a window frame is
an option in lieu of looking at the partition when there is always some
default frame in place.
David J.
^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: Improve "3.5. Window Functions" tutorial
@ 2026-10-02 15:12 Matemática A3K <matematica.a3k@gmail.com>
parent: David G. Johnston <david.g.johnston@gmail.com>
0 siblings, 0 replies; 3+ messages in thread
From: Matemática A3K @ 2026-10-02 15:12 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
On Fri, Oct 2, 2026 at 3:40 AM David G. Johnston <david.g.johnston@gmail.com>
wrote:
> On Wednesday, September 30, 2026, PG Doc comments form <
> noreply@postgresql.org> wrote:
>
>> 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.
>>
>> Wording may be improved ("scoped"), I think the added paragraph links the
>> existing ones providing more meaning.
>>
>
> I’m in agreement with this page being in need of improvement. I’m not all
> that comfortable with this particular proposal. It adds some of its own
> concerns and doesn’t remove some existing ones.
>
OK
> As an aside - recent comments about the undesirability were made - and
> while I’m accepting of their usage generally this one seems like a good
> candidate for removal if we do update this page.
>
> My biggest qualm is the wording that makes it sound like a window frame is
> an option in lieu of looking at the partition when there is always some
> default frame in place.
>
"Window functions perform calculations on a subset of rows of a query for
each row of it, That subset is called the window frame, and it is
constructed on a per-row basis. The query rows are first partitioned with a
provided criteria and may be refined further if the function supports it.
After the determination of the subset (the window frame), calculations are
performed on them and the result is provided for the row."
Do you think that is an accurate definition of window function? If so (or
after the construction of it), the article should be adjusted to be built
on that.
I find the article fuzzy about it. It goes with something like "After you
define a partition, if you supply ORDER_BY, then the window is narrowed and
can be controlled with... BUT this only works if function supports it" and
after reading, I find it difficult to produce a precise idea of it.
>
> David J.
>
>
On Fri, Oct 2, 2026 at 3:40 AM David G. Johnston <david.g.johnston@gmail.com>
wrote:
> On Wednesday, September 30, 2026, PG Doc comments form <
> noreply@postgresql.org> wrote:
>
>> 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.
>>
>> Wording may be improved ("scoped"), I think the added paragraph links the
>> existing ones providing more meaning.
>>
>
> I’m in agreement with this page being in need of improvement. I’m not all
> that comfortable with this particular proposal. It adds some of its own
> concerns and doesn’t remove some existing ones.
>
> As an aside - recent comments about the undesirability were made - and
> while I’m accepting of their usage generally this one seems like a good
> candidate for removal if we do update this page.
>
> My biggest qualm is the wording that makes it sound like a window frame is
> an option in lieu of looking at the partition when there is always some
> default frame in place.
>
> David J.
>
>
^ permalink raw reply [nested|flat] 3+ messages in thread
end of thread, other threads:[~2026-10-02 15:12 UTC | newest]
Thread overview: 3+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2026-09-30 20:56 Improve "3.5. Window Functions" tutorial PG Doc comments form <noreply@postgresql.org>
2026-10-02 06:40 ` David G. Johnston <david.g.johnston@gmail.com>
2026-10-02 15:12 ` Matemática A3K <matematica.a3k@gmail.com>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox