doc: show functions returning record types and use of ROWS FROM

Previously it was unclear exactly how ROWS FROM behaved and how to cast
the data types of columns returned by FROM functions.  Also document
that only non-OUT record functions can have their columns cast to data
types.

Reported-by: [email protected]
Discussion: https://postgr.es/m/158638264419.662.2482095087061084020@wrigleys.postgresql.org

Backpatch-through: 9.5

diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml
index 875a4d84de026286b32e456d0d6851afce721905..77fb1991aebd003409406e6726bbb681f81a3ff5 100644 (file)
--- a/doc/src/sgml/queries.sgml
+++ b/doc/src/sgml/queries.sgml
@@ -762,7 +762,8 @@ SELECT * FROM vw_getfoo;
      In some cases it is useful to define table functions that can
      return different column sets depending on how they are invoked.
      To support this, the table function can be declared as returning
-     the pseudo-type record.  When such a function is used in
+     the pseudo-type record with no OUT
+     parameters.  When such a function is used in
      a query, the expected row structure must be specified in the
      query itself, so that the system can know how to parse and plan
      the query.  This syntax looks like:
@@ -803,6 +804,33 @@ SELECT *
      that the parser knows, for example, what * should
      expand to.
     
+
+    
+     This example uses ROWS FROM:
+
+SELECT *
+FROM ROWS FROM
+    (
+        json_to_recordset('[{"a":40,"b":"foo"},{"a":"100","b":"bar"}]')
+            AS (a INTEGER, b TEXT),
+        generate_series(1, 3)
+    ) AS x (p, q, s)
+ORDER BY p;
+
+  p  |  q  | s
+-----+-----+---
+  40 | foo | 1
+ 100 | bar | 2
+     |     | 3
+
+     It joins two functions into a single FROM
+     target.  json_to_recordset() is instructed
+     to return two columns, the first integer
+     and the second text.  The result of
+     generate_series() is used directly.
+     The ORDER BY clause sorts the column values
+     as integers.
+