Rename TABLE() to ROWS FROM().

nmisch · nmisch · commit 53685d79813a · 2013-12-10T09:34:37.000-05:00
SQL-standard TABLE() is a subset of UNNEST(); they deal with arrays and
other collection types.  This feature, however, deals with set-returning
functions.  Use a different syntax for this feature to keep open the
possibility of implementing the standard TABLE().
diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml
@@ -647,15 +647,15 @@ FROM (VALUES ('anne', 'smith'), ('bob', 'jones'), ('joe', 'blow'))
     </para>
 
     <para>
-     Table functions may also be combined using the <literal>TABLE</literal>
+     Table functions may also be combined using the <literal>ROWS FROM</>
      syntax, with the results returned in parallel columns; the number of
      result rows in this case is that of the largest function result, with
      smaller results padded with NULLs to match.
     </para>
 
 <synopsis>
 <replaceable>function_call</replaceable> <optional>WITH ORDINALITY</optional> <optional><optional>AS</optional> <replaceable>table_alias</replaceable> <optional>(<replaceable>column_alias</replaceable> <optional>, ... </optional>)</optional></optional>
-TABLE( <replaceable>function_call</replaceable> <optional>, ... </optional> ) <optional>WITH ORDINALITY</optional> <optional><optional>AS</optional> <replaceable>table_alias</replaceable> <optional>(<replaceable>column_alias</replaceable> <optional>, ... </optional>)</optional></optional>
+ROWS FROM( <replaceable>function_call</replaceable> <optional>, ... </optional> ) <optional>WITH ORDINALITY</optional> <optional><optional>AS</optional> <replaceable>table_alias</replaceable> <optional>(<replaceable>column_alias</replaceable> <optional>, ... </optional>)</optional></optional>
 </synopsis>
 
     <para>
@@ -674,7 +674,7 @@ TABLE( <replaceable>function_call</replaceable> <optional>, ... </optional> ) <o
      any number of array parameters, and it returns a corresponding number of
      columns, as if <literal>UNNEST</literal>
      (<xref linkend="functions-array">) had been called on each parameter
-     separately and combined using the <literal>TABLE</literal> construct.
+     separately and combined using the <literal>ROWS FROM</literal> construct.
     </para>
 
 <synopsis>
@@ -683,7 +683,7 @@ UNNEST( <replaceable>array_expression</replaceable> <optional>, ... </optional>
 
     <para>
      If no <replaceable>table_alias</replaceable> is specified, the function
-     name is used as the table name; in the case of a <literal>TABLE()</>
+     name is used as the table name; in the case of a <literal>ROWS FROM()</>
      construct, the first function's name is used.
     </para>
 
@@ -731,20 +731,20 @@ SELECT * FROM vw_getfoo;
 <synopsis>
 <replaceable>function_call</replaceable> <optional>AS</optional> <replaceable>alias</replaceable> (<replaceable>column_definition</replaceable> <optional>, ... </optional>)
 <replaceable>function_call</replaceable> AS <optional><replaceable>alias</replaceable></optional> (<replaceable>column_definition</replaceable> <optional>, ... </optional>)
-TABLE( ... <replaceable>function_call</replaceable> AS (<replaceable>column_definition</replaceable> <optional>, ... </optional>) <optional>, ... </optional> )
+ROWS FROM( ... <replaceable>function_call</replaceable> AS (<replaceable>column_definition</replaceable> <optional>, ... </optional>) <optional>, ... </optional> )
 </synopsis>
 
     <para>
-     When not using the <literal>TABLE()</> syntax,
+     When not using the <literal>ROWS FROM()</> syntax,
      the <replaceable>column_definition</replaceable> list replaces the column
      alias list that could otherwise be attached to the <literal>FROM</>
      item; the names in the column definitions serve as column aliases.
-     When using the <literal>TABLE()</> syntax,
+     When using the <literal>ROWS FROM()</> syntax,
      a <replaceable>column_definition</replaceable> list can be attached to
      each member function separately; or if there is only one member function
      and no <literal>WITH ORDINALITY</> clause,
      a <replaceable>column_definition</replaceable> list can be written in
-     place of a column alias list following <literal>TABLE()</>.
+     place of a column alias list following <literal>ROWS FROM()</>.
     </para>
 
     <para>
diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml
@@ -56,7 +56,7 @@ SELECT [ ALL | DISTINCT [ ON ( <replaceable class="parameter">expression</replac
                 [ WITH ORDINALITY ] [ [ AS ] <replaceable class="parameter">alias</replaceable> [ ( <replaceable class="parameter">column_alias</replaceable> [, ...] ) ] ]
     [ LATERAL ] <replaceable class="parameter">function_name</replaceable> ( [ <replaceable class="parameter">argument</replaceable> [, ...] ] ) [ AS ] <replaceable class="parameter">alias</replaceable> ( <replaceable class="parameter">column_definition</replaceable> [, ...] )
     [ LATERAL ] <replaceable class="parameter">function_name</replaceable> ( [ <replaceable class="parameter">argument</replaceable> [, ...] ] ) AS ( <replaceable class="parameter">column_definition</replaceable> [, ...] )
-    [ LATERAL ] TABLE( <replaceable class="parameter">function_name</replaceable> ( [ <replaceable class="parameter">argument</replaceable> [, ...] ] ) [ AS ( <replaceable class="parameter">column_definition</replaceable> [, ...] ) ] [, ...] )
+    [ LATERAL ] ROWS FROM( <replaceable class="parameter">function_name</replaceable> ( [ <replaceable class="parameter">argument</replaceable> [, ...] ] ) [ AS ( <replaceable class="parameter">column_definition</replaceable> [, ...] ) ] [, ...] )
                 [ WITH ORDINALITY ] [ [ AS ] <replaceable class="parameter">alias</replaceable> [ ( <replaceable class="parameter">column_alias</replaceable> [, ...] ) ] ]
     <replaceable class="parameter">from_item</replaceable> [ NATURAL ] <replaceable class="parameter">join_type</replaceable> <replaceable class="parameter">from_item</replaceable> [ ON <replaceable class="parameter">join_condition</replaceable> | USING ( <replaceable class="parameter">join_column</replaceable> [, ...] ) ]
 
@@ -390,7 +390,7 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
        <para>
         Multiple function calls can be combined into a
         single <literal>FROM</>-clause item by surrounding them
-        with <literal>TABLE( ... )</>.  The output of such an item is the
+        with <literal>ROWS FROM( ... )</>.  The output of such an item is the
         concatenation of the first row from each function, then the second
         row from each function, etc.  If some of the functions produce fewer
         rows than others, NULLs are substituted for the missing data, so
@@ -410,18 +410,18 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
        </para>
 
        <para>
-        When using the <literal>TABLE( ... )</> syntax, if one of the
+        When using the <literal>ROWS FROM( ... )</> syntax, if one of the
         functions requires a column definition list, it's preferred to put
         the column definition list after the function call inside
-        <literal>TABLE( ... )</>.  A column definition list can be placed
-        after the <literal>TABLE( ... )</> construct only if there's just a
-        single function and no <literal>WITH ORDINALITY</> clause.
+        <literal>ROWS FROM( ... )</>.  A column definition list can be placed
+        after the <literal>ROWS FROM( ... )</> construct only if there's just
+        a single function and no <literal>WITH ORDINALITY</> clause.
        </para>
 
        <para>
         To use <literal>ORDINALITY</literal> together with a column definition
-        list, you must use the <literal>TABLE( ... )</> syntax and put the
-        column definition list inside <literal>TABLE( ... )</>.
+        list, you must use the <literal>ROWS FROM( ... )</> syntax and put the
+        column definition list inside <literal>ROWS FROM( ... )</>.
        </para>
       </listitem>
      </varlistentry>
@@ -1811,8 +1811,7 @@ SELECT distributors.* WHERE distributors.name = 'Westward';
    </para>
 
    <para>
-    Placing multiple function calls inside <literal>TABLE( ... )</> syntax is
-    also an extension of the SQL standard.
+    <literal>ROWS FROM( ... )</> is an extension of the SQL standard.
    </para>
   </refsect2>
 
diff --git a/src/backend/nodes/copyfuncs.c b/src/backend/nodes/copyfuncs.c
@@ -2310,7 +2310,7 @@ _copyRangeFunction(const RangeFunction *from)
 
 	COPY_SCALAR_FIELD(lateral);
 	COPY_SCALAR_FIELD(ordinality);
-	COPY_SCALAR_FIELD(is_table);
+	COPY_SCALAR_FIELD(is_rowsfrom);
 	COPY_NODE_FIELD(functions);
 	COPY_NODE_FIELD(alias);
 	COPY_NODE_FIELD(coldeflist);
diff --git a/src/backend/nodes/equalfuncs.c b/src/backend/nodes/equalfuncs.c
@@ -2142,7 +2142,7 @@ _equalRangeFunction(const RangeFunction *a, const RangeFunction *b)
 {
 	COMPARE_SCALAR_FIELD(lateral);
 	COMPARE_SCALAR_FIELD(ordinality);
-	COMPARE_SCALAR_FIELD(is_table);
+	COMPARE_SCALAR_FIELD(is_rowsfrom);
 	COMPARE_NODE_FIELD(functions);
 	COMPARE_NODE_FIELD(alias);
 	COMPARE_NODE_FIELD(coldeflist);
diff --git a/src/backend/nodes/outfuncs.c b/src/backend/nodes/outfuncs.c
@@ -2629,7 +2629,7 @@ _outRangeFunction(StringInfo str, const RangeFunction *node)
 
 	WRITE_BOOL_FIELD(lateral);
 	WRITE_BOOL_FIELD(ordinality);
-	WRITE_BOOL_FIELD(is_table);
+	WRITE_BOOL_FIELD(is_rowsfrom);
 	WRITE_NODE_FIELD(functions);
 	WRITE_NODE_FIELD(alias);
 	WRITE_NODE_FIELD(coldeflist);
diff --git a/src/backend/parser/gram.y b/src/backend/parser/gram.y
@@ -406,7 +406,7 @@ static Node *makeRecursiveViewSelect(char *relname, List *aliases, Node *query);
 				a_expr b_expr c_expr AexprConst indirection_el
 				columnref in_expr having_clause func_table array_expr
 				ExclusionWhereClause
-%type <list>	func_table_item func_table_list opt_col_def_list
+%type <list>	rowsfrom_item rowsfrom_list opt_col_def_list
 %type <boolean> opt_ordinality
 %type <list>	ExclusionConstraintList ExclusionConstraintElem
 %type <list>	func_arg_list
@@ -9980,13 +9980,13 @@ relation_expr_opt_alias: relation_expr					%prec UMINUS
 
 /*
  * func_table represents a function invocation in a FROM list. It can be
- * a plain function call, like "foo(...)", or a TABLE expression with
- * one or more function calls, "TABLE (foo(...), bar(...))",
+ * a plain function call, like "foo(...)", or a ROWS FROM expression with
+ * one or more function calls, "ROWS FROM (foo(...), bar(...))",
  * optionally with WITH ORDINALITY attached.
- * In the TABLE syntax, a column definition list can be given for each
+ * In the ROWS FROM syntax, a column definition list can be given for each
  * function, for example:
- *     TABLE (foo() AS (foo_res_a text, foo_res_b text),
- *            bar() AS (bar_res_a text, bar_res_b text))
+ *     ROWS FROM (foo() AS (foo_res_a text, foo_res_b text),
+ *                bar() AS (bar_res_a text, bar_res_b text))
  * It's also possible to attach a column definition list to the RangeFunction
  * as a whole, but that's handled by the table_ref production.
  */
@@ -9995,29 +9995,30 @@ func_table: func_expr_windowless opt_ordinality
 					RangeFunction *n = makeNode(RangeFunction);
 					n->lateral = false;
 					n->ordinality = $2;
-					n->is_table = false;
+					n->is_rowsfrom = false;
 					n->functions = list_make1(list_make2($1, NIL));
 					/* alias and coldeflist are set by table_ref production */
 					$$ = (Node *) n;
 				}
-			| TABLE '(' func_table_list ')' opt_ordinality
+			| ROWS FROM '(' rowsfrom_list ')' opt_ordinality
 				{
 					RangeFunction *n = makeNode(RangeFunction);
 					n->lateral = false;
-					n->ordinality = $5;
-					n->is_table = true;
-					n->functions = $3;
+					n->ordinality = $6;
+					n->is_rowsfrom = true;
+					n->functions = $4;
 					/* alias and coldeflist are set by table_ref production */
 					$$ = (Node *) n;
 				}
 		;
 
-func_table_item: func_expr_windowless opt_col_def_list
+rowsfrom_item: func_expr_windowless opt_col_def_list
 				{ $$ = list_make2($1, $2); }
 		;
 
-func_table_list: func_table_item					{ $$ = list_make1($1); }
-			| func_table_list ',' func_table_item	{ $$ = lappend($1, $3); }
+rowsfrom_list:
+			rowsfrom_item						{ $$ = list_make1($1); }
+			| rowsfrom_list ',' rowsfrom_item	{ $$ = lappend($1, $3); }
 		;
 
 opt_col_def_list: AS '(' TableFuncElementList ')'	{ $$ = $3; }
diff --git a/src/backend/parser/parse_clause.c b/src/backend/parser/parse_clause.c
@@ -655,33 +655,33 @@ transformRangeFunction(ParseState *pstate, RangeFunction *r)
 	 * expansion) and no WITH ORDINALITY.  The reason for the latter
 	 * restriction is that it's not real clear whether the ordinality column
 	 * should be in the coldeflist, and users are too likely to make mistakes
-	 * in one direction or the other.  Putting the coldeflist inside TABLE()
-	 * is much clearer in this case.
+	 * in one direction or the other.  Putting the coldeflist inside ROWS
+	 * FROM() is much clearer in this case.
 	 */
 	if (r->coldeflist)
 	{
 		if (list_length(funcexprs) != 1)
 		{
-			if (r->is_table)
+			if (r->is_rowsfrom)
 				ereport(ERROR,
 						(errcode(ERRCODE_SYNTAX_ERROR),
-						 errmsg("TABLE() with multiple functions cannot have a column definition list"),
-						 errhint("Put a separate column definition list for each function inside TABLE()."),
+						 errmsg("ROWS FROM() with multiple functions cannot have a column definition list"),
+						 errhint("Put a separate column definition list for each function inside ROWS FROM()."),
 						 parser_errposition(pstate,
 									 exprLocation((Node *) r->coldeflist))));
 			else
 				ereport(ERROR,
 						(errcode(ERRCODE_SYNTAX_ERROR),
 						 errmsg("UNNEST() with multiple arguments cannot have a column definition list"),
-						 errhint("Use separate UNNEST() calls inside TABLE(), and attach a column definition list to each one."),
+						 errhint("Use separate UNNEST() calls inside ROWS FROM(), and attach a column definition list to each one."),
 						 parser_errposition(pstate,
 									 exprLocation((Node *) r->coldeflist))));
 		}
 		if (r->ordinality)
 			ereport(ERROR,
 					(errcode(ERRCODE_SYNTAX_ERROR),
 					 errmsg("WITH ORDINALITY cannot be used with a column definition list"),
-				   errhint("Put the column definition list inside TABLE()."),
+				   errhint("Put the column definition list inside ROWS FROM()."),
 					 parser_errposition(pstate,
 									 exprLocation((Node *) r->coldeflist))));
 
diff --git a/src/backend/utils/adt/ruleutils.c b/src/backend/utils/adt/ruleutils.c
@@ -8125,10 +8125,10 @@ get_from_clause_item(Node *jtnode, Query *query, deparse_context *context)
 				rtfunc1 = (RangeTblFunction *) linitial(rte->functions);
 
 				/*
-				 * Omit TABLE() syntax if there's just one function, unless it
+				 * Omit ROWS FROM() syntax for just one function, unless it
 				 * has both a coldeflist and WITH ORDINALITY. If it has both,
-				 * we must use TABLE() syntax to avoid ambiguity about whether
-				 * the coldeflist includes the ordinality column.
+				 * we must use ROWS FROM() syntax to avoid ambiguity about
+				 * whether the coldeflist includes the ordinality column.
 				 */
 				if (list_length(rte->functions) == 1 &&
 					(rtfunc1->funccolnames == NIL || !rte->funcordinality))
@@ -8151,8 +8151,8 @@ get_from_clause_item(Node *jtnode, Query *query, deparse_context *context)
 					 * XXX This is pretty ugly, since it makes not-terribly-
 					 * future-proof assumptions about what the parser would do
 					 * with the output; but the alternative is to emit our
-					 * nonstandard extended TABLE() notation for what might
-					 * have been a perfectly spec-compliant multi-argument
+					 * nonstandard ROWS FROM() notation for what might have
+					 * been a perfectly spec-compliant multi-argument
 					 * UNNEST().
 					 */
 					all_unnest = true;
@@ -8189,7 +8189,7 @@ get_from_clause_item(Node *jtnode, Query *query, deparse_context *context)
 					{
 						int			funcno = 0;
 
-						appendStringInfoString(buf, "TABLE(");
+						appendStringInfoString(buf, "ROWS FROM(");
 						foreach(lc, rte->functions)
 						{
 							RangeTblFunction *rtfunc = (RangeTblFunction *) lfirst(lc);
@@ -8422,7 +8422,7 @@ get_column_alias_list(deparse_columns *colinfo, deparse_context *context)
  *
  * When printing a top-level coldeflist (which is syntactically also the
  * relation's column alias list), use column names from colinfo.  But when
- * printing a coldeflist embedded inside TABLE(), we prefer to use the
+ * printing a coldeflist embedded inside ROWS FROM(), we prefer to use the
  * original coldeflist's names, which are available in rtfunc->funccolnames.
  * Pass NULL for colinfo to select the latter behavior.
  *
diff --git a/src/include/nodes/parsenodes.h b/src/include/nodes/parsenodes.h
@@ -466,11 +466,11 @@ typedef struct RangeSubselect
  * RangeFunction - function call appearing in a FROM clause
  *
  * functions is a List because we use this to represent the construct
- * TABLE(func1(...), func2(...), ...).	Each element of this list is a
+ * ROWS FROM(func1(...), func2(...), ...).	Each element of this list is a
  * two-element sublist, the first element being the untransformed function
  * call tree, and the second element being a possibly-empty list of ColumnDef
  * nodes representing any columndef list attached to that function within the
- * TABLE() syntax.
+ * ROWS FROM() syntax.
  *
  * alias and coldeflist represent any alias and/or columndef list attached
  * at the top level.  (We disallow coldeflist appearing both here and
@@ -481,7 +481,7 @@ typedef struct RangeFunction
 	NodeTag		type;
 	bool		lateral;		/* does it have LATERAL prefix? */
 	bool		ordinality;		/* does it have WITH ORDINALITY suffix? */
-	bool		is_table;		/* is result of TABLE() syntax? */
+	bool		is_rowsfrom;	/* is result of ROWS FROM() syntax? */
 	List	   *functions;		/* per-function information, see above */
 	Alias	   *alias;			/* table alias & optional column aliases */
 	List	   *coldeflist;		/* list of ColumnDef nodes to describe result
diff --git a/src/test/regress/expected/rangefuncs.out b/src/test/regress/expected/rangefuncs.out
diff --git a/src/test/regress/sql/rangefuncs.sql b/src/test/regress/sql/rangefuncs.sql

Original file line number	Diff line number	Diff line change
`@@ -2142,7 +2142,7 @@ _equalRangeFunction(const RangeFunction a, const RangeFunction b)`
`2142`	`2142`	`{`
`2143`	`2143`	`COMPARE_SCALAR_FIELD(lateral);`
`2144`	`2144`	`COMPARE_SCALAR_FIELD(ordinality);`
`2145`		`- COMPARE_SCALAR_FIELD(is_table);`
	`2145`	`+ COMPARE_SCALAR_FIELD(is_rowsfrom);`
`2146`	`2146`	`COMPARE_NODE_FIELD(functions);`
`2147`	`2147`	`COMPARE_NODE_FIELD(alias);`
`2148`	`2148`	`COMPARE_NODE_FIELD(coldeflist);`