Clarify documentation about "peer" rows in window functions

Peer rows are matching rows when ORDER BY is specified.

Report by arnaud.mouronval@gmail.com, David G Johnston

Backpatch through 9.4

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index dafc9e3d92fd333b4c1527999d7bf0989a62b876..77920f4706f91a6a1d709748b3a3c9f4f12b639d 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -13048,7 +13048,8 @@ SELECT xmlagg(x) FROM (SELECT x FROM test ORDER BY y DESC) AS tab;
    <firstterm>Window functions</firstterm> provide the ability to perform
    calculations across sets of rows that are related to the current query
    row.  See <xref linkend="tutorial-window"> for an introduction to this
-   feature.
+   feature, and <xref linkend="syntax-window-functions"> for syntax
+   details.
   </para>
 
   <para>

diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml
index b69b63494b8afcc5385cbf0d049a7e0073076650..940d1aa5c0dd66b11bdc9f9c56c9e16e16d99de2 100644 (file)
--- a/doc/src/sgml/ref/select.sgml
+++ b/doc/src/sgml/ref/select.sgml
@@ -792,8 +792,9 @@ UNBOUNDED FOLLOWING
     The default framing option is <literal>RANGE UNBOUNDED PRECEDING</>,
     which is the same as <literal>RANGE BETWEEN UNBOUNDED PRECEDING AND
     CURRENT ROW</>; it sets the frame to be all rows from the partition start
-    up through the current row's last peer in the <literal>ORDER BY</>
-    ordering (which means all rows if there is no <literal>ORDER BY</>).
+    up through the current row's last peer (a row that <literal>ORDER
+    BY</> considers equivalent to the current row, or all rows if there
+    is no <literal>ORDER BY</>).
     In general, <literal>UNBOUNDED PRECEDING</> means that the frame
     starts with the first row of the partition, and similarly
     <literal>UNBOUNDED FOLLOWING</> means that the frame ends with the last
@@ -817,7 +818,7 @@ UNBOUNDED FOLLOWING
     results if the <literal>ORDER BY</> ordering does not order the rows
     uniquely.  The <literal>RANGE</> options are designed to ensure that
     rows that are peers in the <literal>ORDER BY</> ordering are treated
-    alike; any two peer rows will be both in or both not in the frame.
+    alike; all peer rows will be in the same frame.
    </para>
 
    <para>

diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
index 434a894157712dd1cf5560d2e672549d7aa1f69f..2f0680fd0bc0a27fb8456a6e5a10154bcd2ef722 100644 (file)
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -1877,7 +1877,7 @@ UNBOUNDED FOLLOWING
     first <firstterm>peer</> row (a row that <literal>ORDER BY</> considers
     equivalent to the current row), while a <replaceable>frame_end</> of
     <literal>CURRENT ROW</> means the frame ends with the last equivalent
-    peer.  In <literal>ROWS</> mode, <literal>CURRENT ROW</> simply means
+    <literal>ORDER BY</> peer.  In <literal>ROWS</> mode, <literal>CURRENT ROW</> simply means
     the current row.
    </para>
 
@@ -1897,7 +1897,7 @@ UNBOUNDED FOLLOWING
     which is the same as <literal>RANGE BETWEEN UNBOUNDED PRECEDING AND
     CURRENT ROW</>.  With <literal>ORDER BY</>, this sets the frame to be
     all rows from the partition start up through the current row's last
-    peer.  Without <literal>ORDER BY</>, all rows of the partition are
+    <literal>ORDER BY</> peer.  Without <literal>ORDER BY</>, all rows of the partition are
     included in the window frame, since all rows become peers of the current
     row.
    </para>