Doc: improve documentation for UNNEST().

tglsfdc · tglsfdc · commit bfda0a02444e · 2021-01-27T12:50:17.000-05:00
Per a user question, spell out that UNNEST() returns array elements in storage order; also provide an example to clarify the behavior for multi-dimensional arrays. While here, also clarify the SELECT reference page's description of WITH ORDINALITY. These details were already given in 7.2.1.4, but a reference page should not omit details. Back-patch to v13; there's not room in the table in older versions. Discussion: https://postgr.es/m/FF1FB31F-0507-4F18-9559-2DE6E07E3B43@gmail.com
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
@@ -17926,14 +17926,25 @@ SELECT NULLIF(value, '(none)') ...
         <returnvalue>setof anyelement</returnvalue>
        </para>
        <para>
-        Expands an array to a set of rows.
+        Expands an array into a set of rows.
+        The array's elements are read out in storage order.
        </para>
        <para>
         <literal>unnest(ARRAY[1,2])</literal>
         <returnvalue></returnvalue>
 <programlisting>
  1
  2
+</programlisting>
+       </para>
+       <para>
+        <literal>unnest(ARRAY[['foo','bar'],['baz','quux']])</literal>
+        <returnvalue></returnvalue>
+<programlisting>
+ foo
+ bar
+ baz
+ quux
 </programlisting>
        </para></entry>
       </row>
@@ -17944,10 +17955,10 @@ SELECT NULLIF(value, '(none)') ...
         <returnvalue>setof anyelement, anyelement [, ... ]</returnvalue>
        </para>
        <para>
-        Expands multiple arrays (possibly of different data types) to a set of
+        Expands multiple arrays (possibly of different data types) into a set of
         rows.  If the arrays are not all the same length then the shorter ones
-        are padded with <literal>NULL</literal>s.  This is only allowed in a
-        query's FROM clause; see <xref linkend="queries-tablefunctions"/>.
+        are padded with <literal>NULL</literal>s.  This form is only allowed
+        in a query's FROM clause; see <xref linkend="queries-tablefunctions"/>.
        </para>
        <para>
         <literal>select * from unnest(ARRAY[1,2], ARRAY['foo','bar','baz']) as x(a,b)</literal>
diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml
@@ -476,18 +476,25 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
         result sets, but any function can be used.)  This acts as
         though the function's output were created as a temporary table for the
         duration of this single <command>SELECT</command> command.
-        When the optional <command>WITH ORDINALITY</command> clause is
-        added to the function call, a new column is appended after
-        all the function's output columns with numbering for each row.
+        If the function's result type is composite (including the case of a
+        function with multiple <literal>OUT</literal> parameters), each
+        attribute becomes a separate column in the implicit table.
+       </para>
+
+       <para>
+        When the optional <command>WITH ORDINALITY</command> clause is added
+        to the function call, an additional column of type <type>bigint</type>
+        will be appended to the function's result column(s).  This column
+        numbers the rows of the function's result set, starting from 1.
+        By default, this column is named <literal>ordinality</literal>.
        </para>
 
        <para>
         An alias can be provided in the same way as for a table.
         If an alias is written, a column
         alias list can also be written to provide substitute names for
         one or more attributes of the function's composite return
-        type, including the column added by <literal>ORDINALITY</literal>
-        if present.
+        type, including the ordinality column if present.
        </para>
 
        <para>
