> Here's the first doc patch for SRFs. The patch covers general

> information and SQL language specific info wrt SRFs. I've taken to
> calling this feature "Table Fuctions" to be consistent with (at least)
> one well known RDBMS.

Joe Conway

diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 9cc87965a47b9caa4189751758d1ff8bcbaa0181..6de67ebf30ef3110591c1a3f876ff843421d49a2 100644 (file)
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -1,5 +1,5 @@
 
 
  
@@ -188,6 +188,7 @@ SELECT clean_EMP();
  1
 
     
+
    
 
    
@@ -407,21 +408,53 @@ SELECT getname(new_emp());
    
 
    
-    <acronym>SQL</acronym> Functions Returning Sets
+    <acronym>SQL</acronym> Table Functions (Functions Returning Sets)
+
+    
+     A table function is one that may be used in the FROM
+     clause of a query. All SQL Language functions may be used in this manner.
+     If the function is defined to return a base type, the table function
+     produces a one column result set. If the function is defined to
+     return SETOF sometype, the table
+     function returns multiple rows. To illustrate a SQL table function,
+     consider the following, which returns SETOF a
+     composite type:
+
+
+CREATE TABLE foo (fooid int, foosubid int, fooname text, primary key(fooid,foosubid));
+INSERT INTO foo VALUES(1,1,'Joe');
+INSERT INTO foo VALUES(1,2,'Ed');
+INSERT INTO foo VALUES(2,1,'Mary');
+CREATE FUNCTION getfoo(int) RETURNS setof foo AS '
+    SELECT * FROM foo WHERE fooid = $1;
+' LANGUAGE SQL;
+SELECT * FROM getfoo(1) AS t1;
+
+
+
+ fooid | foosubid | fooname
+-------+----------+---------
+     1 |        1 | Joe
+     1 |        2 | Ed
+(2 rows)
+
+    
 
     
-     As previously mentioned, an SQL function may be declared as
-     returning SETOF sometype.
-     In this case the function's final SELECT query is executed to
-     completion, and each row it outputs is returned as an element
-     of the set.
+     When an SQL function is declared as returning SETOF
+     sometype, the function's final
+     SELECT query is executed to completion, and each row it
+     outputs is returned as an element of the set.
     
 
     
-     Functions returning sets may only be called in the target list
-     of a SELECT query.  For each row that the SELECT generates by itself,
-     the function returning set is invoked, and an output row is generated
-     for each element of the function's result set.  An example:
+     Functions returning sets may also currently be called in the target list
+     of a SELECT query.  For each row that the SELECT
+     generates by itself, the function returning set is invoked, and an output
+     row is generated for each element of the function's result set. Note,
+     however, that this capability is deprecated and may be removed in future
+     releases. The following is an example function returning a set from the
+     target list:
 
 
 CREATE FUNCTION listchildren(text) RETURNS SETOF text AS
@@ -1620,6 +1653,54 @@ CREATE FUNCTION test(int, int) RETURNS int
    
   
 
+  
+   Table Functions
+
+   function
+
+   
+    Table functions are functions that produce a set of rows, made up of
+    either base (scalar) data types, or composite (multi-column) data types.
+    They are used like a table, view, or subselect in the FROM
+    clause of a query. Columns returned by table functions may be included in
+    SELECT, JOIN, or WHERE clauses in the
+    same manner as a table, view, or subselect column.
+   
+
+   
+    If a table function returns a base data type, the single result column
+    is named for the function. If the function returns a composite type, the
+    result columns get the same names as the individual attributes of the type.
+   
+
+   
+    A table function may be aliased in the FROM clause, but it also
+    may be left unaliased. If a function is used in the FROM clause with no
+    alias, the function name is used as the relation name.
+   
+
+   
+    Table functions work wherever tables do in SELECT statements.
+    For example
+
+CREATE TABLE foo (fooid int, foosubid int, fooname text, primary key(fooid,foosubid));
+CREATE FUNCTION getfoo(int) RETURNS foo AS 'SELECT * FROM foo WHERE fooid = $1;' LANGUAGE SQL;
+SELECT * FROM getfoo(1) AS t1;
+SELECT * FROM foo where foosubid in (select foosubid from getfoo(foo.fooid) z where z.fooid = foo.fooid);
+CREATE VIEW vw_getfoo AS SELECT * FROM getfoo(1);
+SELECT * FROM vw_getfoo;
+
+    are all valid statements.
+   
+
+   
+    Currently, table functions are supported as SQL language functions
+    () and C language functions
+    (). See these individual sections for more
+    details.
+   
+
+  
 
   
    Procedural Language Handlers