mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Doc: improve documentation for UNNEST().

Browse Source 
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
This commit is contained in:
Tom Lane 2021-01-27 12:50:17 -05:00
parent 2378d9232e
commit bfda0a0244
2 changed files with 27 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
doc/src/sgml/func.sgml
View File

@ -17926,7 +17926,8 @@ 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>
@ -17934,6 +17935,16 @@ SELECT NULLIF(value, '(none)') ...
<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>

17
doc/src/sgml/ref/select.sgml
View File

@ -476,9 +476,17 @@ 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>
@ -486,8 +494,7 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
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>