Re: [DOCS] Window function docs - Mailing list pgsql-docs

Bruce Momjian <bruce@momjian.us> writes:
> As part of writing a talk about window functions, I have done some
> cleanups of the window function docs, attached, that I would like to
> apply to head.

I think this change is just wrong:

     aggregate function, but the <literal>OVER</> clause causes it to be
-    treated as a window function and computed across an appropriate set of
-    rows.)
+    treated as a window function and computed across the entire partition.)
    </para>

avg() is going to be evaluated across the current frame, not the whole
partition.  I don't mind trying to be more precise than "appropriate set",
but it doesn't help to be apparently precise but wrong.

Not really convinced by the s/regular/normal/g changes.  That doesn't seem
to clarify much either.  Maybe it would help to define "normal" near here.
There's a definition in func.sgml (that they are not ordered-set or
hypothetical-set aggregates) but that's too far away.

In this bit:

-   definition.  Rows that are not distinct in the <literal>ORDER BY</>
-   ordering are said to be <firstterm>peers</>; the four ranking functions
-   are defined so that they give the same answer for any two peer rows.
+   definition.  Rows that are not distinct based on <literal>ORDER BY</>
+   ordering are said to be <firstterm>peers</>.  The four ranking
+   functions (includes <function>cume_dist</>) are defined so that they
+   give the same answer for any two peer rows.

"based on" seems little better than the previous wording.  Maybe it'd be
better to say "Rows that are not distinct when considering only the
<literal>ORDER BY</> columns are said to be ..."

    sometimes also <function>nth_value</>.  You can redefine the frame by
-   adding a suitable frame specification (<literal>RANGE</> or
-   <literal>ROWS</>) to the <literal>OVER</> clause.
-   See <xref linkend="syntax-window-functions"> for more information
-   about frame specifications.
+   modifying the frame specification;  see <xref
+   linkend="syntax-window-functions"> for more information about frame
+   specifications.
   </para>

Don't really like this change; it makes it vaguer for no apparent benefit.

+  <para>
+   <function>cume_dist</> computes the ratio of partition rows that
+   are less than or equal to the current row and its peers, while
+   <function>percent_rank</> computes the ratio of lesser partition rows,
+   assuming the current row is does not exist in the partition.
+  </para>

The first one probably ought to be "computes the fraction of partition
rows".  The second definition seems nonsensical --- ratio to what?  Or
probably better, fraction of what?  (And "is does not" needs help too.)

     the user.  Also, any built-in or user-defined normal aggregate function
-    can be used as a window function.  Ordered-set aggregates presently
-    cannot be used as window functions, however.
+    can be used as a window function.  However, ordered-set aggregate
+    cannot presently be used as window functions.
    </para>

Grammar (don't lose the "s" in ordered-set aggregates).

            regards, tom lane