Doc: improve documentation for UNNEST().

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
index aa99665e2eb79c13fa956d4b017a33768ba88cac..4342c8e74fd1fcab526f9ada6012650bb79ab44a 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -17905,7 +17905,8 @@ SELECT NULLIF(value, '(none)') ...
         setof anyelement
        
        
-        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.
        
        
         unnest(ARRAY[1,2])
@@ -17913,6 +17914,16 @@ SELECT NULLIF(value, '(none)') ...
 
  1
  2
+
+       
+       
+        unnest(ARRAY[['foo','bar'],['baz','quux']])
+        
+
+ foo
+ bar
+ baz
+ quux
 
        
       
@@ -17923,10 +17934,10 @@ SELECT NULLIF(value, '(none)') ...
         setof anyelement, anyelement [, ... ]
        
        
-        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 NULLs.  This is only allowed in a
-        query's FROM clause; see .
+        are padded with NULLs.  This form is only allowed
+        in a query's FROM clause; see .
        
        
         select * from unnest(ARRAY[1,2], ARRAY['foo','bar','baz']) as x(a,b)

diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml
index 6757033e096b8820e7ef5933f9c00b2fbcd718bc..c48ff6bc7e8ce9b3f39ca299e6ecc994a9ef83ac 100644 (file)
--- a/doc/src/sgml/ref/select.sgml
+++ b/doc/src/sgml/ref/select.sgml
@@ -476,9 +476,17 @@ TABLE [ ONLY ] table_name [ * ]
         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 SELECT command.
-        When the optional WITH ORDINALITY 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 OUT parameters), each
+        attribute becomes a separate column in the implicit table.
+       
+
+       
+        When the optional WITH ORDINALITY clause is added
+        to the function call, an additional column of type bigint
+        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 ordinality.
        
 
        
@@ -486,8 +494,7 @@ TABLE [ ONLY ] table_name [ * ]
         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 ORDINALITY
-        if present.
+        type, including the ordinality column if present.